Package eu.bandm.tscore.base

Class TendencyCollector<E extends Entity>

java.lang.Object
eu.bandm.tscore.base.TendencyCollector<E>
public class TendencyCollector<E extends Entity> extends Object
Processes a parameter track which contains tendencies spanning more than one Event.

Usage: construct an instance (specifying all input formats) and then call reify(MessageReceiver, Iterable,Map, Map, Map, Map, Map, Map, Map, Map) (specifiying a sequence of Events and all maps where to store the results.

Tendencies span (in nearly all cases) more than one event and are employed in musical scores mostly for changes of loudness, but also of tempo, and in other types of scores for continuous increase/decrease processes of any scalar parameter ("Entity") like brightness, voltage, etc. The entity and its parser, given as attribute to this class, can appear in tendency contexts, spanning the process between two(2) values over a non-empty sequence of events, and in singleton mode, i.e. only one(1) value related to only one(1) event (and mostly inherited by the successor events).

Tendency Context

Each tendency, as constructed by this algorithm, is contained in one(1) particular parameter track, and is defined atop of one(1) particular domain. For the values of this domain a lexical representation must exist which is non-ambigue in the parsing context. This context is built by the configuration of the dedicated input symbols mentioned in the following parsing rules.

Each recognized tendency, which correspond to exactly one(1) appearance of a tendency symbol in the source text, one(1) instance of EventSet is constructed. All information (contained events, kind and number, start and end value, start and end text) is collected into fields of this instance, or into maps indexed by this instance.
The startpoint of each tendency group is denotated by

  • a tendency start symbol for increasng and decreasing tendencies These default to < and >. A sensible alternative, e.g. in a more technical type of notation, could be / and \ or ^ and v.
  • These may be predecessed by a value of the domain, serving as the start point of the tendency.
Additionally there may follow
  • some group numbering to support nested tendencies in the same parameter track (example from CWN: many short diminuendos in one large crescendo)
  • some additional textstring, either further specifying the process (like in (diminuendo) "molto") or even redundantly repeating the meaning, for determining same later rendering completely ("poco a poco meno forte")
Esp. in case of tempo, but sometimes also for intensity, a typical usage would be to let the tendency symbol control the generation of technical sound data, and the string value the appearance of a printed score intended for the human reader.
Attention:
In most cases there will not be an automated correlation check, so that contradictory input like ">"cresc. sempre"" is not detected automatically on this level of processing and may lead to severe confusion!

The tendency extends up to its end point symbol. This is given by

  • either a concrete value of the parameter domain, given by its lexical representation,
  • or the special "fin" symbol, which denotates an un-specified end of the tendency (defaults to "!").
The end point symbol may follow
  • directly after the tendency symbol in the same parameter text fragment. This defines a group with only one member, and means eg. a crescendo extending only over the duration of this single note.
  • or in the same param track, but at some later event in the same voice. In this case, start and end of the tendency must be explicitly related by using the same number code (possibly epsilon). Whether the ending event is included in the generated EventSet is controlled by the global flag lastEventIncluded. (Please not that the meaning, whether the process ends at the beginning or the end of that event's sounding duration is independent, and decided in later processing steps.)
In the second case, the end point symbol is the start point of a new tendency, iff it is followed by a new tendency symbol.
(In this case the "fin" symbol may be ommitted.) There are 15 combinations of the lexical components (not considering number and additional text) Some have identic structure, and some are not sensible. Combination number 8 is only sensible as an end symbole of a tendency. All others operate as singleton or start tendency, and at the same time as end points of tendency: 
 
 Combination works as...
 ..singleton
 | ..tendency start
 | | ..end
 | | |       Event[n]         Event[n+1]  [n+2]     Event[n+k]
 | | |       1  2  4  8 
 | | |      (^binary encoding)
 | | |      (example:)
         0   
 I   E   1   p                  (p           p      )  !   (inherit) 
   S E   2      <        ----------------------------- !/f create tendency Group
   S E   3   p  <        ----------------------------- !/f create tendency Group
         4         f     (parsed as 1)  
         5   p     f     (NOT ALLOWED)
 I  (e)  6      <  f            (f           f      )  !   (inherit) 
 I  (e)  7   p  <  f            (f           f      )  !   (inherit) 
     E   8            !  (sensible only as END OF TENDENCY)
 I   E   9   p        !              (no inheritance, no process)
 I   E  10      <     !  (create singleton tendency)
 I   E  11   p  <     !  (create singleton tendency)
        12         f  !  (parsed as 9)
        13   p     f  !  (NOT ALLOWED)
 I   E  14      <  f  !  (create singleton tendency)
 I   E  15   p  <  f  !  (create singleton tendency)

So if the last syntactic element is (1) an entity value, then inheritance is started, if it is (2) a tendency sign, a tendency EventSet is started. The parser grammar could be described by 

   tendency ::=  domainValue?  tendencySymbol  domainValue?
                 endSymbol? number? additionalText?

Singleton Usage

Beside the apperance in a tendency, as described above, the source text of a domain value can appear in a stand-alone syntax, without tendency symbol.

  • As in case of CWN intensity, the single appearance of a domain value (like "f" or "pp") is meant the current event and for all its successors, until the next explicit value indication ("sticky" semantics).
  • But some others (classically: "sfz") are only valid for a single event. This is denotated by appending the "fin" symbol = case 9 above.
  • Also these non-tendency values may be qualified by a number (for not interfering with tendencies they are contained in),
  • and they can be attributed by text (like "molto").
  • This text may even be related to the question of validity of their extension ("sempre", "von nun an", "al segno"), but this is not considered on this level of processing.
The recognized spontanuous values are returned in the two Multimaps Event <-> D called singleton_explicit and singleton_inherited.

This is realized by a parser accepting ... 

   singleton ::= domainValue  endSymbol? number? additionalText?

Remark 1

Currently we support the groups numbers "0" to "9", while "no number" defaults to "0"

Remark 2

According to the general tscore discipline, all components belonging to the same event must be written without intervening blanks. 

           c              cis  d    dis   e      %
           p<1"molto">2   >2   >2   >2    ff1>2  !2

Remark 3

In the context of music, the predominant application will be with loudness/intensity. But in modern music there will be other applications, e.g. between articulations: 

           c      cis  d    dis   e      f    g   h 
           v<               .-<          -<       (
           "Tonform jedesmal verlängern"

Remark 4

In classical notation dim/cresc annotations are only for one single (instrumental) voice. But in contemporary notations it may be notated in some over-all directives' (pseudo) voice, and valid for (a subset of) an ensemble: 

                dim sempre
           >----------------------------->
 Instr a      x                x
 Instr b            o                o
 Instr c        o      x   x      o
To use this algorithm with such a data structure, the events must in a preparatory step be collected into a pseudo (possibly overlapping, non-monodic) "sum"-voice, i.e. List of Events.

  • Field Details

    • tendencySymbols

      final String[] tendencySymbols
      The symbols for increase and decrease, set on construction.

    • endSymbol

      final String endSymbol
      The symbol for "end of tendency", set on construction.

    • domainParser

      final Translet.Parser<E extends Entity> domainParser
      Parser for the parameter values.

    • additionalTextParser

      final Translet.Parser<String> additionalTextParser
      Parser for the additional text.

    • lastEventIncluded

      final boolean lastEventIncluded
      Whether the last event is included in the event set built for a tendency. (Please note that even if it is included, all higher/later steps of processing are free to realize the tendency only up to its beginning.)

    • singletonTendencyAllowed

      final boolean singletonTendencyAllowed
      Whether a tendency (created by attaching a tendency symbol to an event) may be terminated immediately, by an endSymbol or a parameter value at the very same event. If this value is false, the parser will simply reject the corresponding input combinations.

    • default_tendencySymolbs

      static final String[] default_tendencySymolbs
      The default signs for increase and decrease.

    • default_endSymbol

      public static final String default_endSymbol
      The default end sign.
      See Also:

    • tendencyCtrls

      final Multimap<Event,TendencyCollector<E extends Entity>.TendencyCtrl> tendencyCtrls
      Intermediate storage for the tendency information, by events. The parser obtained by getParser() must be integrated into the whole parsing process of the voice. It will fill this storage. After completion, a call to reify(MessageReceiver, Iterable,Map, Map, Map, Map, Map, Map, Map, Map) will analyse this storage and construct event sets.

    • packTendencyCtrl

      protected Function6<E extends Entity,String,E extends Entity,Boolean,Integer,String,TendencyCollector<E extends Entity>.TendencyCtrl> packTendencyCtrl

    • runningTendencies

      EventSet[] runningTendencies
      Set of all currently collecting tendencies, when visiting the analysed events in source order. Different tendencies running in parallel are identified by one decimal digit.

    • runningFlats

      E extends Entity[] runningFlats
      Running/inherited simple parameter values, when visiting the analysed events in source order. Like different tendencies, parallel runs are possible and are identified by one decimal digit.

  • Constructor Details

    • TendencyCollector

      public TendencyCollector(String[] tendencySymbols, String endSymbol, Translet.Parser<E> domainParser, Translet.Parser<String> additionalTextParser, boolean lastEventIncluded, boolean singletonTendencyAllowed)
      Only constructor. Seta all configuration parameters.
      Parameters:
      tendencySymbols - an array of two strings, for increase and decrease.
      endSymbol - the input string for "end of tendency"
      domainParser - the parser for the values of the parameter domain
      additionalTextParser - the parser for additional text to the start and/or the end of tendency groups
      lastEventIncluded - whether the event carrying the "end of tendency" sign is included in the EventSet
      singletonTendencyAllowed - whether an "end of tendency" input will be accepted on the event which has just started this tendency group.

  • Method Details

    • getParser

      public Translet.Parser<?> getParser()
      Returns the parser which realizes the combination of parameters set when constructing this instance.

    • reify

      public void reify(MessageReceiver<SimpleMessage<eu.bandm.tools.util.xml.XMLDocumentIdentifier>> msg, Iterable<Event> evs, Map<String,EventSet> tendencies, Map<EventSet,@Opt E> startValues, Map<EventSet,@Opt E> endValues, Map<EventSet,@Opt String> startTexts, Map<EventSet,@Opt String> endTexts, Map<Event,E> singleton_explicit, Map<Event,E> singleton_inherited, Map<Event,String> singleton_text)
      Analyses the parameter text of the events by visiting them in the given order. This is in nearly all cases the sequential (lexical) order of the input score. Creates EventSets accordingly, enters them into the result MultiMap and enters the Events into the EventSets.
      Parameters:
      msg - the target of warnings
      evs - input parameter: the set of events to analyse, in the sequential order
      tendencies - all tendency groups by name FIXME name synthetisch ????
      startValues - maps a recognized tendency group (=member in the range of "tendencies") to its start value.
      endValues - maps a recognized tendency group (=member in the range of "tendencies") to its start value.
      startTexts - maps a recognized tendency group (=member in the range of "tendencies") to its start text.
      endTexts - maps a recognized tendency group (=member in the range of "tendencies") to its start text.
      singleton_explicit - maps all events which carry an explicit paramter value
      singleton_inherited - maps all events which inherti the parameter value from some predecessor.
      singleton_text - maps all events which carry an additional "start_text", which is also an "end_text" in case of a singleton tendency group.

    • startsTendency

      protected boolean startsTendency(TendencyCollector<E>.TendencyCtrl tc)
      Whether this intermediate object carries a tendency symbol.