Package 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)
The number zero(0) is treated like the missing number and is not entered into the event set name. See events set "m={i,k}" in the example above.

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.

  • Field Details

    • lenientNesting

      boolean lenientNesting
      Whether overlapping (non-hierarchcal) groups are allowed.

    • 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. If the caller provides null, then this is set to Translet.FAIL().

    • 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 Details

    • GroupCollector

      public GroupCollector(MessageReceiver<SimpleMessage<eu.bandm.tools.util.xml.XMLDocumentIdentifier>> mmsg, @Opt @Opt String singletonLeadIn, Map<String,String> open2close, @Opt @Opt Translet.Parser<String> identParser, @Opt @Opt Translet.Parser<String> additionalTextParser, boolean lenientNesting, boolean sameNameNestingAllowed, boolean sameNameMeansSameSet, boolean openCloseImmediateAllowed, boolean shortcutClose)
      Only constructor, setting all configuration parameters.
      Parameters:
      mmsg - receiver for messages in initialization.
      singletonLeadIn - parser for the symbol to separate event set names without an opening parenthesis
      open2close - pairs of opening and closing parenthesis, must be an injective map
      identParser - for the name (preceding a possible number). May be ==null if no names (bexond the implicit numbers) are allowed.
      additionalTextParser - parser for an additional text for the start AND for the end of a group (e.g. "molto legato" at a beginning). May be ==null if no such text is allowed.
      lenientNesting - whether non-well-nested sequences of groups are permitted.
      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 Details

    • 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<eu.bandm.tools.util.xml.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.
      Parameters:
      msg - receiver for consistency errors
      evs - the list of events, in the same sequence as in the preceding parsing process
      result - gets the resulting event sets by their name

    • checkDoubleMentioned

      protected void checkDoubleMentioned(MessageReceiver<SimpleMessage<eu.bandm.tools.util.xml.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.