feat: expose musicxml id attributes in mx::api

src/include/mx/api/ApiCommon.h

@@ -32,6 +32,17 @@ constexpr int NUMBER_LEVEL_UNSPECIFIED = -1; // MusicXML 'number' attributes, e.
 constexpr int VALUE_UNSPECIFIED = -1;        // other absent-able ints, e.g. DirectionData::voice
 constexpr Double DOUBLE_UNSPECIFIED = -1.0;  // absent-able doubles, e.g. StaffData::staffSize
 
+// MusicXML lets most elements carry an optional id attribute, a name that identifies that one
+// element within the document. Software uses it to point at a particular note, measure, or
+// marking -- to line playback up with the score, to hang an annotation on a note, or to link one
+// file to another. Every mx::api type that models such an element has an `id` member. Leave it
+// empty and no id attribute is written.
+//
+// An id must be unique within the document and must follow the XML name rules: a letter or an
+// underscore first, then letters, digits, dots, hyphens, or underscores. mx repairs an id that
+// breaks the name rules when it writes the file, but it does not check uniqueness, so an id you
+// invent must not collide with one already in the score.
+
 // Intentional ternary: absent-able bools use Bool::unspecified, not std::optional<bool>.
 // See "mx::api conventions" in AGENTS.md.
 enum class Bool

src/include/mx/api/BarlineData.h

@@ -116,10 +116,13 @@ class BarlineData
     RepeatWinged repeatWinged;
     HorizontalAlignment location;
 
+    // The <barline> element's id attribute (see ApiCommon.h).
+    std::optional<std::string> id;
+
     BarlineData()
         : tickTimePosition{0}, barlineType{BarlineType::normal}, ending{}, repeat{false}, repeatTimes{0},
           repeatDirection{RepeatDirection::unspecified}, repeatAfterJump{Bool::unspecified},
-          repeatWinged{RepeatWinged::unspecified}, location{HorizontalAlignment::unspecified}
+          repeatWinged{RepeatWinged::unspecified}, location{HorizontalAlignment::unspecified}, id{}
     {
     }
 };
@@ -134,6 +137,7 @@ MXAPI_EQUALS_MEMBER(repeatDirection)
 MXAPI_EQUALS_MEMBER(repeatAfterJump)
 MXAPI_EQUALS_MEMBER(repeatWinged)
 MXAPI_EQUALS_MEMBER(location)
+MXAPI_EQUALS_MEMBER(id)
 MXAPI_EQUALS_END;
 MXAPI_NOT_EQUALS_AND_VECTORS(BarlineData);
 } // namespace api

src/include/mx/api/ClefData.h

@@ -6,6 +6,9 @@
 
 #include "mx/api/ApiCommon.h"
 
+#include <optional>
+#include <string>
+
 namespace mx
 {
 namespace api
@@ -67,6 +70,10 @@ class ClefData
     // Visibility of the clef via the MusicXML print-object attribute.
     // unspecified -> omit the attribute, yes/no -> write print-object verbatim.
     Bool printObject;
+
+    // The <clef> element's id attribute (see ApiCommon.h).
+    std::optional<std::string> id;
+
     std::string toString() const;
 
     // convenience - set symbol, line and octave for common clefs
@@ -99,6 +106,7 @@ MXAPI_EQUALS_MEMBER(tickTimePosition)
 MXAPI_EQUALS_MEMBER(location)
 MXAPI_EQUALS_MEMBER(additional)
 MXAPI_EQUALS_MEMBER(printObject)
+MXAPI_EQUALS_MEMBER(id)
 MXAPI_EQUALS_END;
 MXAPI_NOT_EQUALS_AND_VECTORS(ClefData);
 } // namespace api

src/include/mx/api/CurveData.h

@@ -10,6 +10,9 @@
 #include "mx/api/PositionData.h"
 #include "mx/api/SpannerNumber.h"
 
+#include <optional>
+#include <string>
+
 // MusicXML Documentation for Bezier Attributes Group
 // The bezier attribute group is used to indicate the curvature of slurs
 // and ties, representing the control points for a cubic bezier curve.
@@ -100,9 +103,13 @@ struct CurveStart
     bool isColorSpecified;
     ColorData colorData;
 
+    // The id attribute of the element this curve end is written as -- <slur> for a slur,
+    // <tied> for a tie (see ApiCommon.h).
+    std::optional<std::string> id;
+
     CurveStart(CurveType inCurveType)
         : curveType{inCurveType}, number{}, curvePoints{}, curveOrientation{CurveOrientation::unspecified},
-          placement{Placement::unspecified}, lineData{}, isColorSpecified{false}, colorData{}
+          placement{Placement::unspecified}, lineData{}, isColorSpecified{false}, colorData{}, id{}
     {
     }
 };
@@ -119,9 +126,13 @@ struct CurveContinue
     bool isBezierOffset2Specified;
     double bezierOffset2;
 
+    // The id attribute of the element this curve end is written as -- <slur> for a slur,
+    // <tied> for a tie (see ApiCommon.h).
+    std::optional<std::string> id;
+
     CurveContinue(CurveType inCurveType)
         : curveType{inCurveType}, number{}, curvePoints{}, isBezierX2Specified{false}, bezierX2{0.0},
-          isBezierY2Specified{false}, bezierY2{0.0}, isBezierOffset2Specified{false}, bezierOffset2{0.0}
+          isBezierY2Specified{false}, bezierY2{0.0}, isBezierOffset2Specified{false}, bezierOffset2{0.0}, id{}
     {
     }
 };
@@ -132,7 +143,11 @@ struct CurveStop
     SpannerNumber number;
     CurvePoints curvePoints;
 
-    CurveStop(CurveType inCurveType) : curveType{inCurveType}, number{}, curvePoints{}
+    // The id attribute of the element this curve end is written as -- <slur> for a slur,
+    // <tied> for a tie (see ApiCommon.h).
+    std::optional<std::string> id;
+
+    CurveStop(CurveType inCurveType) : curveType{inCurveType}, number{}, curvePoints{}, id{}
     {
     }
 };
@@ -157,6 +172,7 @@ MXAPI_EQUALS_MEMBER(placement)
 MXAPI_EQUALS_MEMBER(lineData)
 MXAPI_EQUALS_MEMBER(isColorSpecified)
 MXAPI_EQUALS_MEMBER(colorData)
+MXAPI_EQUALS_MEMBER(id)
 MXAPI_EQUALS_END;
 MXAPI_NOT_EQUALS_AND_VECTORS(CurveStart);
 
@@ -170,13 +186,15 @@ MXAPI_EQUALS_MEMBER(isBezierY2Specified)
 MXAPI_EQUALS_MEMBER(bezierY2)
 MXAPI_EQUALS_MEMBER(isBezierOffset2Specified)
 MXAPI_EQUALS_MEMBER(bezierOffset2)
+MXAPI_EQUALS_MEMBER(id)
 MXAPI_EQUALS_END;
 MXAPI_NOT_EQUALS_AND_VECTORS(CurveContinue);
 
 MXAPI_EQUALS_BEGIN(CurveStop)
 MXAPI_EQUALS_MEMBER(curveType)
 MXAPI_EQUALS_MEMBER(number)
 MXAPI_EQUALS_MEMBER(curvePoints)
+MXAPI_EQUALS_MEMBER(id)
 MXAPI_EQUALS_END;
 MXAPI_NOT_EQUALS_AND_VECTORS(CurveStop);
 } // namespace api

src/include/mx/api/DirectionData.h

@@ -11,6 +11,7 @@
 #include "mx/api/SoundData.h"
 
 #include <optional>
+#include <string>
 
 namespace mx
 {
@@ -80,10 +81,13 @@ struct DirectionData
     // serialize as their own <figured-bass> elements, not as direction-type content.
     std::vector<FiguredBassData> figuredBasses;
 
+    // The <direction> element's id attribute (see ApiCommon.h).
+    std::optional<std::string> id;
+
     DirectionData()
         : tickTimePosition{0}, placement{Placement::unspecified}, systemRelation{SystemRelation::unspecified}, offset{},
           voice{VALUE_UNSPECIFIED}, isStaffValueSpecified{true}, isSoundDataSpecified{false}, soundData{},
-          directionTypes{}, chords{}, figuredBasses{}
+          directionTypes{}, chords{}, figuredBasses{}, id{}
     {
     }
 };
@@ -106,6 +110,7 @@ MXAPI_EQUALS_MEMBER(soundData)
 MXAPI_EQUALS_MEMBER(directionTypes)
 MXAPI_EQUALS_MEMBER(chords)
 MXAPI_EQUALS_MEMBER(figuredBasses)
+MXAPI_EQUALS_MEMBER(id)
 MXAPI_EQUALS_END;
 MXAPI_NOT_EQUALS_AND_VECTORS(DirectionData);
 } // namespace api

src/include/mx/api/FiguredBassData.h

@@ -6,6 +6,7 @@
 
 #include "mx/api/ApiCommon.h"
 
+#include <optional>
 #include <string>
 #include <vector>
 
@@ -48,7 +49,10 @@ class FiguredBassData
     // The optional <duration>, in ticks. A value less than 0 means 'unspecified' (no duration child).
     int durationTimeTicks;
 
-    FiguredBassData() : figures{}, parentheses{Bool::unspecified}, durationTimeTicks{VALUE_UNSPECIFIED}
+    // The <figured-bass> element's id attribute (see ApiCommon.h).
+    std::optional<std::string> id;
+
+    FiguredBassData() : figures{}, parentheses{Bool::unspecified}, durationTimeTicks{VALUE_UNSPECIFIED}, id{}
     {
     }
 };
@@ -57,6 +61,7 @@ MXAPI_EQUALS_BEGIN(FiguredBassData)
 MXAPI_EQUALS_MEMBER(figures)
 MXAPI_EQUALS_MEMBER(parentheses)
 MXAPI_EQUALS_MEMBER(durationTimeTicks)
+MXAPI_EQUALS_MEMBER(id)
 MXAPI_EQUALS_END;
 MXAPI_NOT_EQUALS_AND_VECTORS(FiguredBassData);
 

src/include/mx/api/KeyData.h

@@ -6,6 +6,9 @@
 #include "mx/api/ApiCommon.h"
 #include "mx/api/KeyComponent.h"
 
+#include <optional>
+#include <string>
+
 namespace mx
 {
 namespace api
@@ -121,9 +124,12 @@ struct KeyData
     // alterations. When custom is non-empty, then fifths and mode are ignored.
     std::vector<KeyComponent> nonTraditional;
 
+    // The <key> element's id attribute (see ApiCommon.h).
+    std::optional<std::string> id;
+
     KeyData()
         : fifths{0}, cancel{0}, cancelLocation{CancelLocation::unspecified}, mode{KeyMode::unspecified},
-          tickTimePosition{0}, staffIndex{INDEX_UNSPECIFIED}, nonTraditional{}
+          tickTimePosition{0}, staffIndex{INDEX_UNSPECIFIED}, nonTraditional{}, id{}
     {
     }
 };
@@ -136,6 +142,7 @@ MXAPI_EQUALS_MEMBER(mode)
 MXAPI_EQUALS_MEMBER(tickTimePosition)
 MXAPI_EQUALS_MEMBER(staffIndex)
 MXAPI_EQUALS_MEMBER(nonTraditional)
+MXAPI_EQUALS_MEMBER(id)
 MXAPI_EQUALS_END;
 
 MXAPI_NOT_EQUALS_AND_VECTORS(KeyData);

src/include/mx/api/LyricData.h

@@ -8,6 +8,9 @@
 #include "mx/api/PositionData.h"
 #include "mx/api/PrintData.h"
 
+#include <optional>
+#include <string>
+
 namespace mx
 {
 namespace api
@@ -38,7 +41,7 @@ class LyricData
   public:
     LyricData()
         : text{}, verseNumber{}, verseName{}, syllabic{LyricSyllabic::unspecified}, hasExtend{false},
-          extendType{LyricExtendType::unspecified}, positionData{}, printData{}
+          extendType{LyricExtendType::unspecified}, positionData{}, printData{}, id{}
     {
     }
 
@@ -50,6 +53,9 @@ class LyricData
     LyricExtendType extendType;
     PositionData positionData;
     PrintData printData;
+
+    // The <lyric> element's id attribute (see ApiCommon.h).
+    std::optional<std::string> id;
 };
 
 MXAPI_EQUALS_BEGIN(LyricData)
@@ -61,6 +67,7 @@ MXAPI_EQUALS_MEMBER(hasExtend)
 MXAPI_EQUALS_MEMBER(extendType)
 MXAPI_EQUALS_MEMBER(positionData)
 MXAPI_EQUALS_MEMBER(printData)
+MXAPI_EQUALS_MEMBER(id)
 MXAPI_EQUALS_END;
 MXAPI_NOT_EQUALS_AND_VECTORS(LyricData);
 } // namespace api

src/include/mx/api/MeasureData.h

@@ -111,6 +111,9 @@ class MeasureData
     // before this field existed.
     std::vector<TransposeData> transpositions;
 
+    // The <measure> element's id attribute (see ApiCommon.h).
+    std::optional<std::string> id;
+
     MeasureData()
         : staves{}, timeSignature{}, number{}, measureNumbering{MeasureNumbering::unspecified},
           measureNumberingMultipleRestAlways{Bool::unspecified}, measureNumberingMultipleRestRange{Bool::unspecified},
@@ -141,6 +144,7 @@ MXAPI_EQUALS_MEMBER(keys)
 MXAPI_EQUALS_MEMBER(barlines)
 MXAPI_EQUALS_MEMBER(partSymbol)
 MXAPI_EQUALS_MEMBER(transpositions)
+MXAPI_EQUALS_MEMBER(id)
 MXAPI_EQUALS_END;
 MXAPI_NOT_EQUALS_AND_VECTORS(MeasureData);
 } // namespace api

src/include/mx/api/NoteData.h

@@ -82,7 +82,11 @@ struct TieLetRing
     bool isColorSpecified;
     ColorData colorData;
 
-    TieLetRing() : positionData{}, curveOrientation{CurveOrientation::unspecified}, isColorSpecified{false}, colorData{}
+    // The <tied> element's id attribute (see ApiCommon.h).
+    std::optional<std::string> id;
+
+    TieLetRing()
+        : positionData{}, curveOrientation{CurveOrientation::unspecified}, isColorSpecified{false}, colorData{}, id{}
     {
     }
 };
@@ -92,6 +96,7 @@ MXAPI_EQUALS_MEMBER(positionData)
 MXAPI_EQUALS_MEMBER(curveOrientation)
 MXAPI_EQUALS_MEMBER(isColorSpecified)
 MXAPI_EQUALS_MEMBER(colorData)
+MXAPI_EQUALS_MEMBER(id)
 MXAPI_EQUALS_END;
 MXAPI_NOT_EQUALS_AND_VECTORS(TieLetRing);
 
@@ -202,6 +207,9 @@ class NoteData
     // similarly when parsing if we see ##misc-data## in this element, it
     // will be parsed into these strings. do not use commas in your misc
     // data strings as these are the delimiter
+
+    // The <note> element's id attribute (see ApiCommon.h).
+    std::optional<std::string> id;
     std::vector<std::string> miscData;
 };
 
@@ -234,6 +242,7 @@ MXAPI_EQUALS_MEMBER(printData)
 MXAPI_EQUALS_MEMBER(noteAttachmentData)
 MXAPI_EQUALS_MEMBER(lyrics)
 MXAPI_EQUALS_MEMBER(miscData)
+MXAPI_EQUALS_MEMBER(id)
 MXAPI_EQUALS_END;
 MXAPI_NOT_EQUALS_AND_VECTORS(NoteData);
 } // namespace api

src/include/mx/api/PedalLineData.h

@@ -7,6 +7,9 @@
 #include "mx/api/ApiCommon.h"
 #include "mx/api/PositionData.h"
 
+#include <optional>
+#include <string>
+
 namespace mx
 {
 namespace api
@@ -50,11 +53,14 @@ struct PedalLineData
     int tickTimePosition;
     PositionData positionData;
 
-    PedalLineData() : kind{PedalLineKind::unspecified}, tickTimePosition{0}, positionData{}
+    // The <pedal> element's id attribute (see ApiCommon.h).
+    std::optional<std::string> id;
+
+    PedalLineData() : kind{PedalLineKind::unspecified}, tickTimePosition{0}, positionData{}, id{}
     {
     }
 
-    PedalLineData(PedalLineKind inKind) : kind{inKind}, tickTimePosition{0}, positionData{}
+    PedalLineData(PedalLineKind inKind) : kind{inKind}, tickTimePosition{0}, positionData{}, id{}
     {
     }
 };
@@ -63,6 +69,7 @@ MXAPI_EQUALS_BEGIN(PedalLineData)
 MXAPI_EQUALS_MEMBER(kind)
 MXAPI_EQUALS_MEMBER(tickTimePosition)
 MXAPI_EQUALS_MEMBER(positionData)
+MXAPI_EQUALS_MEMBER(id)
 MXAPI_EQUALS_END;
 MXAPI_NOT_EQUALS_AND_VECTORS(PedalLineData);
 } // namespace api

src/include/mx/api/RehearsalData.h

@@ -9,6 +9,9 @@
 #include "mx/api/FontData.h"
 #include "mx/api/PositionData.h"
 
+#include <optional>
+#include <string>
+
 namespace mx
 {
 namespace api
@@ -32,9 +35,12 @@ class RehearsalData
     // and says which edge of the text the position refers to; MusicXML defines both.
     HorizontalAlignment justify;
 
+    // The <rehearsal> element's id attribute (see ApiCommon.h).
+    std::optional<std::string> id;
+
     RehearsalData()
         : text{}, positionData{}, isColorSpecified{false}, colorData{}, fontData{}, enclosure{Enclosure::unspecified},
-          justify{HorizontalAlignment::unspecified}
+          justify{HorizontalAlignment::unspecified}, id{}
     {
     }
 };
@@ -47,6 +53,7 @@ MXAPI_EQUALS_MEMBER(colorData)
 MXAPI_EQUALS_MEMBER(fontData)
 MXAPI_EQUALS_MEMBER(enclosure)
 MXAPI_EQUALS_MEMBER(justify)
+MXAPI_EQUALS_MEMBER(id)
 MXAPI_EQUALS_END;
 MXAPI_NOT_EQUALS_AND_VECTORS(RehearsalData);
 } // namespace api