eu.bandm.tscore.base

Class GroupCollector

java.lang.Object

eu.bandm.tscore.base.GroupCollector

public class GroupCollector
extends Object

Collects sets of adjacent events from one single voice.

Usage:

1. Construct an instance (thereby specifying all input parsers and operation modes).
2. Apply the parser returned by getParser() to one or more parameter tracks of one or more voices. (All parsed start and stop symbols are stored to internal maps.)
3. Call reify(MessageReceiver,Iterable,Multimap) (specifiying as second argument basically the same sequence of Events) which converts the parsed information into the final result, a collection of EventSets.

This feature can be used for legato slurs, for beam grouping, for spanning expression marks over more than one event, for additional analytic comments, etc.
All subsequent events of the same voice between the corresponding parentheses are collected into one single(1) EventSet of the raw model. The Events are entered in their sequential order into ".orderedEvents", the only voice is entered into ".voices" and parsed "additional Text" is entered into ".startText" and ".endText".

Alternatively, events can be collected into an event set pointwise.

The name of the generated event sets is the concatenation of the parenthesis symbol, the explicit identifier and an explicit number. All of these components except one may be missing.

Example:

    T         1.0                       2.0
     VOX v    a  b c  d e   f   g   h   i     j   k    l  
      P p     e    [m   e]m             +m        m0+e
                   (    (1  )   )1 
                        {"Siegfriedmotiv"              }
              (2"legatissimo possibile"           )
 

This creates the following groups:

     name     contents                               startText  endText
     ------------------------------------------------------------------
              a,b,c,d,e,f,g,h,i,j,k,l
     e        a,      e,          k                  ""         ""
     [m           c,d,e,                             ""         ""
     m                        i,  k                  ""         ""
     (            c,d,e,f                            ""         ""
     (1               e,f,g                          ""         ""
     {                e,f,g,h,i,j,k,l                "Siegfriedmotiv"  ""
     (2       a,b,c,d,e,f,g,h,i,j,k                  "legatissimo possibile" ""

 

The input syntax rules are

        param = (cont|point)*
        cont = (parenthopen|parenthclose)  (ident)?  (number)?
        point = (pointwiseleadin)? ( ident  (number)? | number) 
 

Semantics are kind of "imperative", that means, open and close "commands" are "executed" from left to right.

    T         1.0                      
     VOX v    a     b           c
      P p           ]m[m  // Closes a currently open group and opens a new group, 
                          // Both are distict, but both are named "[m"
                          // Event "b" is member of both groups

      P q           (m)m  // starts a new group and closes it immediately, 
                          // Event "b" is its only member
 

All direct neighbour events which go to the same group form one single event set. The identifier of this set is the concatenation of all front-end symbols. This includes the open parenthesis. It does not include the "point lead in", which is only required in the front end text when more than one group identifier must be referred to, like in "(a(b+e".
All created event sets are entered into one single multi-map, indexed by that name.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected class	GroupCollector.GroupEvent Represents the translation of a group start, group end or singleton additon parameter text.
protected static class	GroupCollector.Kind Kind of group commands, to be stored in GroupCollector.GroupEvent.

Field Summary

Fields

Modifier and Type	Field and Description
(package private) Translet.Parser<String>	additionalTextParser The parser for the additional opening and closing text.
(package private) Map<String,GroupCollector.GroupEvent>	byName Currently collecting event sets while visiting the events in source order.
(package private) Map<String,GroupCollector.GroupEvent>	byParenthesis Currently collecting event sets while visiting the events in source order.
(package private) Map<String,String>	close2open The map from closing parenthesis text back to the corresponding opening parenthesis symbol.
protected int	globalCounter Used to assign increasing GroupCollector.GroupEvent.localLevel to each GroupEvent on construction.
(package private) Multimap<Event,GroupCollector.GroupEvent>	groupEvents Maps an event to all decoded group start, end, and singleton commands.
(package private) Translet.Parser<String>	identParser The parser for the groups name.
(package private) Map<String,GroupCollector.GroupEvent>	onlySets The last event set created with this name.
(package private) Map<String,String>	open2close The map from open parenthesis text to the corresponding closing parenthesis symbol.
(package private) boolean	openCloseImmediateAllowed Whether a set just opened may be closed on the very same event.
(package private) boolean	sameNameMeansSameSet Whether two different sets with the same name are not allowed, but unified into one set.
(package private) boolean	sameNameNestingAllowed Whether two different sets with the same name may nest.
(package private) boolean	shortcutClose Whether a parenthesis without any identification relates to the latest corresponding opening parenthesis.
(package private) String	singletonLeadIn The string to separate/lead-in a text meaning single membership.
protected Comparator<GroupCollector.GroupEvent>	sourceOrder Cmpares to GroupEvents according to increasing time of creation.

Constructor Summary

Constructors

Constructor and Description

GroupCollector(MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> mmsg, @Opt String singletonLeadIn, Map<String,String> open2close, @Opt Translet.Parser<String> identParser, @Opt Translet.Parser<String> additionalTextParser, boolean sameNameNestingAllowed, boolean sameNameMeansSameSet, boolean openCloseImmediateAllowed, boolean shortcutClose) Only constructor, setting all configuration parameters.

Method Summary

Modifier and Type	Method and Description
protected void	addToAllOpen(Event ev, Set<String> mentioned) Add the event to all event sets which are currently (when visiting event in source order) active in collecting, but not explicitly opened or closed at the current event.
protected void	checkDoubleMentioned(MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msg, Event ev, Set<String> mentioned, String s) Generate an error or only a warning whenever a group name appears more than once for the same event.
protected void	closeSet(GroupCollector.GroupEvent ge, String name, String para) Close a GroupEvent representing a set.
Translet.Parser<?>	getParser() Get the parser which accepts open group, close group, and singleton add parameter texts, converts these into group events and stores these.
protected void	openSet(GroupCollector.GroupEvent ge, String name, String para) Open a GroupEvent representing a set.
void	reify(MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msg, Iterable<Event> evs, Multimap<String,EventSet> result) Analyses the collected parameter text, and creates EventSets accordingly.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

sameNameNestingAllowed

boolean sameNameNestingAllowed

Whether two different sets with the same name may nest.

sameNameMeansSameSet

boolean sameNameMeansSameSet

Whether two different sets with the same name are not allowed, but unified into one set.

openCloseImmediateAllowed

boolean openCloseImmediateAllowed

Whether a set just opened may be closed on the very same event.

shortcutClose

boolean shortcutClose

Whether a parenthesis without any identification relates to the latest corresponding opening parenthesis.

singletonLeadIn

final String singletonLeadIn

The string to separate/lead-in a text meaning single membership.

open2close

final Map<String,String> open2close

The map from open parenthesis text to the corresponding closing parenthesis symbol. Is given by the caller. Must be injective.

close2open

final Map<String,String> close2open

The map from closing parenthesis text back to the corresponding opening parenthesis symbol. Is built locally from open2close.

identParser

final Translet.Parser<String> identParser

The parser for the groups name. Is provided by the caller.

additionalTextParser

final Translet.Parser<String> additionalTextParser

The parser for the additional opening and closing text. Is provided by the caller.

groupEvents

final Multimap<Event,GroupCollector.GroupEvent> groupEvents

Maps an event to all decoded group start, end, and singleton commands.

globalCounter

protected int globalCounter

Used to assign increasing GroupCollector.GroupEvent.localLevel to each GroupEvent on construction.

sourceOrder

protected Comparator<GroupCollector.GroupEvent> sourceOrder

Cmpares to GroupEvents according to increasing time of creation.

byName

Map<String,GroupCollector.GroupEvent> byName

Currently collecting event sets while visiting the events in source order. (=current event is between the sets opening and closing parenthesis, both inclusive.) For each name, a stack of GroupEvents is maintained, because sets with the same name are not always forbidden to overlap, as in m[ m[ ]m ]m. The very first opened group event (in case of re-opening) represents and carries the generated EventSet.

byParenthesis

Map<String,GroupCollector.GroupEvent> byParenthesis

Currently collecting event sets while visiting the events in source order. (=current event is between the sets opening and closing parenthesis, both inclusive.) For open parenthesis, a stack of different event sets is maintained, to realise the shortcutClose mode.

onlySets

Map<String,GroupCollector.GroupEvent> onlySets

The last event set created with this name. Needed in mode sameNameMeansSameSet for re-opening (and for point-wise fill). (Otherwise only the key set of this map is relevant, holding all used identifiers.)

Constructor Detail

GroupCollector

public GroupCollector(MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> mmsg,
                      @Opt
                      @Opt String singletonLeadIn,
                      Map<String,String> open2close,
                      @Opt
                      @Opt Translet.Parser<String> identParser,
                      @Opt
                      @Opt Translet.Parser<String> additionalTextParser,
                      boolean sameNameNestingAllowed,
                      boolean sameNameMeansSameSet,
                      boolean openCloseImmediateAllowed,
                      boolean shortcutClose)

Only constructor, setting all configuration parameters.

Parameters:

sameNameNestingAllowed - whether more than one group (>1) with same name+num may be growing at the same time. (Only this requires stacks for analysis).

sameNameMeansSameSet - whether a set can be re-opened, i.e. the same name+num continues collections of an already closed set of the same name

openCloseImmediateAllowed - whether an open command can be followed by a close command at the same event (effect is similar to that of a singleton add) Only this requires respecting the source order of the events.

shortcutClose - whether a closing parenthesis without any identification is treated as a shortcut for the source order last group with the corresponding opening parenthesis.

Method Detail

getParser

public Translet.Parser<?> getParser()

Get the parser which accepts open group, close group, and singleton add parameter texts, converts these into group events and stores these.

reify

public void reify(MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msg,
                  Iterable<Event> evs,
                  Multimap<String,EventSet> result)

Analyses the collected parameter text, and creates EventSets accordingly. The parameter texts are encoded as GroupCollector.GroupEvent instances, linked to the events in groupEvents. This method steps throught the events in source order and creates the event sets. Enters them into the result MultiMap and enters the Events into the EventSets.

checkDoubleMentioned

protected void checkDoubleMentioned(MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msg,
                                    Event ev,
                                    Set<String> mentioned,
                                    String s)

Generate an error or only a warning whenever a group name appears more than once for the same event.

addToAllOpen

protected void addToAllOpen(Event ev,
                            Set<String> mentioned)

Add the event to all event sets which are currently (when visiting event in source order) active in collecting, but not explicitly opened or closed at the current event. If currently more than one group with the same name are active, add only to the top-most = latest opened in source order.

openSet

protected void openSet(GroupCollector.GroupEvent ge,
                       String name,
                       String para)

Open a GroupEvent representing a set.

closeSet

protected void closeSet(GroupCollector.GroupEvent ge,
                        String name,
                        String para)

Close a GroupEvent representing a set.