Proposal: Support Interleaved Words and Symbols in `mx::api` Directions

[rpatters1]

(Sorry for the LLM-written issue. It was easier than thinking. 🙄)

Need

MusicXML allows a <direction-type> to contain an ordered sequence of <words> and <symbol> children. mx::api should be able to preserve and write these mixed direction
markings.

The immediate need is expressive dynamics and performance text, for example:

<direction-type>
  <words>più</words>
  <symbol>dynamicForte</symbol>
</direction-type>

or:

<direction-type>
  <symbol>dynamicPP</symbol>
  <words>subito</words>
</direction-type>

These are visually and semantically ordered. Splitting them into separate directions, or preserving only the words, loses useful notation intent.

Current Gap

mx::core already supports this shape: DirectionTypeChoiceChoice can be either words or symbol.

mx::api currently exposes direction words, but does not expose a corresponding ordered item for this mixed sequence. The reader also skips symbols in this group, and the
writer batches words rather than emitting an interleaved word/symbol run.

Desired Capability

mx::api should be able to read, represent, modify, and write ordered word/symbol sequences such as:

  <direction-type>
    <words>più</words>
    <symbol>dynamicForte</symbol>
  </direction-type>

without losing the symbol or the ordering during an API round trip.

[rpatters1]

In looking further at this with my own two eyes, I am realizing that DirectionData may need a major refactor. It seems like a perfect use-case for std::variant. You could have

using DirectionTypeData = std::variant <
    TempoData,
    MarkData,
    WedgeStart,
    WedgeStop,
    OttavaStart,
    SpannerStart,
    SpannerStop,
    WordsData,
    ChordData,
    FiguredBassData,
    SegnoData,
    CodaData,
    RehearsalData,
    SymbolData, // added by me for this issue ;-p
>;

Then all you would need is one vector.

std::vector<DirectionTypeData> directionTypes;

And you could dispense with DirectionComponent and orderedComponents which look risky to me no matter how you slice it. The directionTypes would encode the order directly, so there would be no need for trickery to round-trip.

I certainly would not undertake a refactor like this myself without your blessing. I don't know what the ramifications might be both in-repo and for other clients.

[webern]

Symbol

I agree with the need to support <symbol> interleaved with words.

Semantics Nit

Although, I have a nit for the files you are authoring:

<direction-type>
  <words>più</words>
  <symbol>dynamicForte</symbol>
</direction-type>

The spec says this:

The symbol element specifies a musical symbol using a canonical SMuFL glyph name. It is used when an occasional musical symbol is interspersed into text. It should not be used in place of semantic markup, such as metronome marks that mix text and symbols.

And, I agree, you should use the common-MusicXML-language-semantics when available:

<direction placement="below">
  <direction-type><words>più</words></direction-type>
  <direction-type><dynamics><f/></dynamics></direction-type>
</direction>

Ordered Direction Components

I agree that mx::api has a gap here. The ordering workaround was sufficient for some basic cases, but it falls short of more complex directions. Here some examples of what is and is not supported.

Example A (supported):

<direction placement="below">
  <direction-type><words>più</words></direction-type>
  <direction-type><dynamics><f/></dynamics></direction-type>
</direction>

Example B (supported):

<direction placement="below">
  <direction-type><words>più</words></direction-type>
</direction>
<direction>
  <direction-type><dynamics><f/></dynamics></direction-type>
</direction>

Example C (supported with the buggy ordering knob):

<direction placement="below">
  <direction-type><words>più</words></direction-type>
  <direction-type><dynamics><f/></dynamics></direction-type>
</direction>

orderedComponents = { {words, 0}, {mark, 0} } → words emit before the
mark. Works, but only because there's a single words element.

Example D (impossible: words split around another kind, e.g. "più 𝆑 ma non troppo"):

<direction placement="below">
  <direction-type><words>più</words></direction-type>
  <direction-type><dynamics><f/></dynamics></direction-type>
  <direction-type><words>ma non troppo</words></direction-type>
</direction>

{words,0}, {mark,0}, {words,1} doesn't work — the writer dumps all words
at the first words entry (DirectionWriter.cpp:792), yielding "più ma non
troppo 𝆑". Also impossible: anything containing <symbol> (no api type;
reader drops it).

Proposal

I think your proposal is solid except for one nit. I'm aesthetically influenced by Rust (I wish I had algebraic enums) and I don't like std::variant's undefined behavior and access methods very much, so I started adding "choice" classes in the mx::api to hide the std::variant. Thus I suggest something more like this:

class DirectionChoice
{
  public:
    enum class Kind { tempo, mark, wedgeStart, /* ..., */ wordsRun };

    DirectionChoice();                       // tempo, default-constructed
    explicit DirectionChoice(TempoData);
    explicit DirectionChoice(MarkData);
    explicit DirectionChoice(WedgeStart);
    // ...
    explicit DirectionChoice(std::vector<WordsChoice>);  // one <direction-type> (words|symbol)+ run

    Kind kind() const;
    bool isTempo() const;   // etc.

    // Wrong-kind access returns a default-constructed copy.
    TempoData tempo() const;
    MarkData mark() const;
    // ...
    std::vector<WordsChoice> wordsRun() const;

  private:
    std::variant<TempoData, MarkData, WedgeStart, /* ..., */ std::vector<WordsChoice>> myValue;
};

And

class WordsChoice
{
  public:
    enum class Kind { words, symbol };

    WordsChoice();                        // words, empty
    WordsChoice(WordsData);
    WordsChoice(SymbolData);

    Kind kind() const;
    bool isWords() const;
    bool isSymbol() const;

    // Wrong-kind access returns a default-constructed copy.
    WordsData words() const;
    SymbolData symbol() const;

  private:
    std::variant<WordsData, SymbolData> myValue;
};

Conclusion

I think we can go ahead with this change. I'm happy to do it if you want, or you can give it a shot. If you do, there may be some back-and-forth in review, but if you follow patterns established in:

• TimeChoice — TimeSignatureData | ComplexTimeSignature; simple-equivalent complex collapses to simple.
• ComplexTimeSignature — (MeteredTimeSignature | senza-misura string)
• MarkDataChoice — monostate | TremoloMarkData | ArpeggiateMarkData | NonArpeggiateMarkData; monostate = "none".

Where MarkDataChoice is perhaps the closest template for WordsChoice / DirectionChoice (Kind enum, copy accessors, default-copy on wrong-kind). And have your agent read /mx-api-doctrine, it should probably go pretty smoothly.

[webern]

This might serve as a reasonable stress-test file to add to the corpus under synthetic/:

<?xml version="1.0" encoding="UTF-8"?>
<score-partwise version="4.0">
  <part-list>
    <score-part id="P1">
      <part-name>MusicXML Part</part-name>
    </score-part>
  </part-list>
  <part id="P1">
    <measure number="1">
      <attributes>
        <divisions>1</divisions>
        <time>
          <beats>4</beats>
          <beat-type>4</beat-type>
        </time>
        <clef>
          <sign>G</sign>
          <line>2</line>
        </clef>
      </attributes>
      <direction placement="below">
        <direction-type>
          <words>più</words>
        </direction-type>
        <direction-type>
          <dynamics>
            <f/>
          </dynamics>
        </direction-type>
      </direction>
      <note>
        <pitch>
          <step>C</step>
          <octave>4</octave>
        </pitch>
        <duration>1</duration>
        <type>quarter</type>
      </note>
      <direction placement="below">
        <direction-type>
          <words>dolce</words>
        </direction-type>
      </direction>
      <direction>
        <direction-type>
          <dynamics>
            <p/>
          </dynamics>
        </direction-type>
      </direction>
      <note>
        <pitch>
          <step>D</step>
          <octave>4</octave>
        </pitch>
        <duration>1</duration>
        <type>quarter</type>
      </note>
      <direction placement="below">
        <direction-type>
          <words>meno</words>
        </direction-type>
        <direction-type>
          <dynamics>
            <mf/>
          </dynamics>
        </direction-type>
      </direction>
      <note>
        <pitch>
          <step>E</step>
          <octave>4</octave>
        </pitch>
        <duration>1</duration>
        <type>quarter</type>
      </note>
      <direction placement="below">
        <direction-type>
          <words>gliss. </words>
          <symbol>arrowBlackUp</symbol>
        </direction-type>
        <direction-type>
          <dynamics>
            <ff/>
          </dynamics>
        </direction-type>
        <direction-type>
          <words> al niente</words>
        </direction-type>
      </direction>
      <note>
        <pitch>
          <step>F</step>
          <octave>4</octave>
        </pitch>
        <duration>1</duration>
        <type>quarter</type>
      </note>
    </measure>
  </part>
</score-partwise>

[rpatters1]

I am traveling at the moment so won't be in front of a devbox computer before next week. FWIW: i have list of gaps in mx::api I was going to work through then, where I will just submit PRs for the easy ones and open issues for ones that require refactoring or other complications. So I might get around to this in a couple of weeks if you haven't already tackled it.

I ended up using what was available for encoding dynamics (as you suggested: semantically) after I posted this issue.