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.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected class	TendencyCollector.TendencyCtrl Intermediate storage, one instance for each tendency control command attached to an event.

Field Summary

Fields

Modifier and Type	Field and Description
(package private) Translet.Parser<String>	additionalTextParser Parser for the additional text.
static String	default_endSymbol The default end sign.
(package private) static String[]	default_tendencySymolbs The default signs for increase and decrease.
(package private) Translet.Parser<E>	domainParser Parser for the parameter values.
(package private) String	endSymbol The symbol for "end of tendency", set on construction.
(package private) boolean	lastEventIncluded Whether the last event is included in the event set built for a tendency.
protected Function6<E,String,E,Boolean,Integer,String,TendencyCollector.TendencyCtrl>	packTendencyCtrl
(package private) E[]	runningFlats Running/inherited simple parameter values, when visiting the analysed events in source order.
(package private) EventSet[]	runningTendencies Set of all currently collecting tendencies, when visiting the analysed events in source order.
(package private) 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.
(package private) Multimap<Event,TendencyCollector.TendencyCtrl>	tendencyCtrls Intermediate storage for the tendency information, by events.
(package private) String[]	tendencySymbols The symbols for increase and decrease, set on construction.

Constructor Summary

Constructors

Constructor and Description
TendencyCollector(String[] tendencySymbols, String endSymbol, Translet.Parser<E> domainParser, Translet.Parser<String> additionalTextParser, boolean lastEventIncluded, boolean singletonTendencyAllowed) Only constructor.

Method Summary

Modifier and Type	Method and Description
Translet.Parser<?>	getParser() Returns the parser which realizes the combination of parameters set when constructing this instance.
void	reify(MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msg, Iterable<Event> evs, Map<String,EventSet> tendencies, Map<EventSet,E> startValues, Map<EventSet,E> endValues, Map<EventSet,String> startTexts, Map<EventSet,String> endTexts, Map<Event,E> singleton_explict, Map<Event,E> singleton_inherited, Map<Event,String> singleton_text) Analyses the parameter text of the events by visiting them in the given order.
protected boolean	startsTendency(TendencyCollector.TendencyCtrl tc) Whether this intermediate object carries a tendency symbol.

Methods inherited from class java.lang.Object

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

Field Detail

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:

Constant Field Values

tendencyCtrls

final Multimap<Event,TendencyCollector.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.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 Detail

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 Detail

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<XMLDocumentIdentifier>> msg,
                  Iterable<Event> evs,
                  Map<String,EventSet> tendencies,
                  Map<EventSet,E> startValues,
                  Map<EventSet,E> endValues,
                  Map<EventSet,String> startTexts,
                  Map<EventSet,String> endTexts,
                  Map<Event,E> singleton_explict,
                  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

eve - 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.TendencyCtrl tc)

Whether this intermediate object carries a tendency symbol.