Package eu.bandm.music.entities

Class MTreeSpec

java.lang.Object
eu.bandm.music.entities.MTree_<MTreeSpec>
eu.bandm.music.entities.MTreeSpec
All Implemented Interfaces:
MetrumIndication
public class MTreeSpec extends MTree_<MTreeSpec>
A specification for an MTree, as constructed by a user. The fields defining the duration values need not be completely filled, but must be free of conflicts and allow un-ambiguous completion.
A tscore parser is provided; for its syntax see the user doc.
A user constructs an MTreeSpec and then calls MTree.install(MTreeSpec,MTree.Parameters) to expand it to an MTree. ATTENTION: In its very first life span, the mere specification has *algebraic* semantics and the parsers heavily make use of *sharing*. Fields like "parent", "position" etc. are thus inapplicable. The opposite is true for any MTree.

  • Field Details

  • Constructor Details

    • MTreeSpec

      public MTreeSpec(List<MTreeSpec> args)
      Create one node with arg nodes as sub-nodes. Set context fields ".parent" and ".pos"

    • MTreeSpec

      public MTreeSpec(MTreeSpec... args)
      Create one node with arg nodes as sub-nodes.

    • MTreeSpec

      public MTreeSpec(Rational rat, List<MTreeSpec> args)
      Create one node with arg nodes as sub-nodes, and an explicit duration.

    • MTreeSpec

      public MTreeSpec(int num, int den, MTreeSpec... args)
      Create one node with arg nodes as sub-nodes, and an explicit duration.

    • MTreeSpec

      public MTreeSpec(Rational rat, MTreeSpec... args)
      Create one node with arg nodes as sub-nodes, and an explicit duration.

  • Method Details

    • self

      protected MTreeSpec self()
      Necessary to avoid "unchecked cast" warning when returning "this" instance in the parameterized superclass MTree_.
      Specified by:
      self in class MTree_<MTreeSpec>

    • REP

      public static MTreeSpec REP(int cnt, MTreeSpec sub)
      Create and return one node which contains n times the given subnode as its childs. Corresponds to the parsing result of an input like "3*<sub>".

    • REP

      public static MTreeSpec REP(Rational rat, int cnt, MTreeSpec sub)
      Create and return one node which contains n times the given subnode as its childs and has the explicitly given duration. Corresponds only roughly to the parsing results of an input like "3/4(3*<sub>)". (Repetion count and explict duration are not combinable when parsing.)

    • REP

      public static MTreeSpec REP(int num, int den, int cnt, MTreeSpec sub)

    • ALTS

      public static MTreeSpec ALTS(List<MTreeSpec> alts)
      Set every element in the list (but the very first) as the alternative of its predecssor.

    • ALTS

      public static MTreeSpec ALTS(MTreeSpec... args)
      See Also:

    • initialize

      public MTreeSpec initialize(Modifiers.Reaction redundantDuration, MessageReceiver<SimpleMessage<?>> msg)
      May only be called for the topmost node, representing a complete metric tree/ measure. Assumes that initially only a few MTree_.duration fields are set. The durations of the children of such a node are calculated by equidistant division. The duration of a node where all childern have a duration is by summing them up. After all durations have been set, the start positions are defined by summing up the preceding siblings. The user is free to define durations at very different positions of a fresh MTreeSpec, before calling the method. This may result in inconsistencies, which are signalled as exceptions. Esp. when tuplets shall be combined, durations must be inserted explicitly. 
         new MTreeSpec(new MTreeSpec (3,4, new MTreeSpec(),
                                     new MTreeSpec(),
                                     new MTreeSpec()),
                 new MTreeSpec (2,4, new MTreeSpec(),
                                     new MTreeSpec(),
                                     new MTreeSpec())
                 ):
      ... defines a measure with three(3) quarter notes (1/4) in its first part, and three(3) quarter triplets(1/6) in its second part.
      The following combinations are possible of nodes not yet carrying a duration: 
              p=dp            p=dp               p=?      
      /  \   \        /  \   \           /  \   \     
     x=?  y=? z=?   x=dx y=? z=dz      x=dx y=dy z=dz
      Parameters:
      redundantDuration - how to react when the duration of a particular node is defined by more than one(>1) sources to the same value.

    • initialize

      public MTreeSpec initialize(MessageReceiver<SimpleMessage<?>> msg)
      Calls initialize(Modifiers.Reaction, MessageReceiver) with Modifiers.Reaction.silentlyAllow.

    • initialize

      @Deprecated(forRemoval=true) public MTreeSpec initialize(Modifiers.Reaction redundantDuration)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use initialize(Reaction, MessageReceiver) instead.

    • initialize

      @Deprecated(forRemoval=true) public MTreeSpec initialize()
      Deprecated, for removal: This API element is subject to removal in a future version.
      use initialize(Reaction, MessageReceiver) instead.

    • react

      protected void react(Modifiers.Reaction react, MessageReceiver<SimpleMessage<?>> msg, String txt, Object... args)
      Generates maybe a message with the given text and arguments, either as error or as warning, depending on "react". This allows to choose between "silently allow", "warning", and "error".

    • propagateUp

      @Opt protected @Opt Rational propagateUp(Set<MTreeSpec> contributors)
      If this has no duration, then induce it from its childs. Visit depth-first and sum-up the durations of children, as long as (recursively) possible and necessary, and return the result.

    • propagateToAlts

      protected void propagateToAlts(Rational dura, Set<MTreeSpec> visited, Modifiers.Reaction redundantDuration, MessageReceiver<SimpleMessage<?>> msg)
      Distribute found duration to all alternatives,

    • propagateToChilds

      protected void propagateToChilds(Set<MTreeSpec> visited, Modifiers.Reaction redundantDuration, MessageReceiver<SimpleMessage<?>> msg)
      Either all children do not have a duration, then the duration is distributed equally among them, or only one child does not have a duration and gets the rest. If all have a duration, then the sum must match the parent's one.

    • parseAndInitialize

      @Opt public static @Opt MTreeSpec parseAndInitialize(MessageReceiver<SimpleMessage<eu.bandm.tools.util.xml.XMLDocumentIdentifier>> msg, String s)
      Create one top node and all described sub nodes by parsing a specification text.

    • parser

      public static Translet.Parser<MTreeSpec> parser()