File: lib/Music/NWC2MusicXML/Event.pm

lib/Music/NWC2MusicXML/Event.pm

Structural Coverage (Approximate)

TER1 (Statement): 100.00%
TER2 (Branch): 81.25%
TER3 (LCSAJ): 100.0% (2/2)
Approximate LCSAJ segments: 17

LCSAJ Legend

● Covered — this LCSAJ path was executed during testing.

● Not covered — this LCSAJ path was never executed. These are the paths to focus on.

Multiple dots on a line indicate that multiple control-flow paths begin at that line. Hovering over any dot shows:

        start → end → jump

start – first line of the linear sequence
end – last line before control flow changes
jump – line execution jumps to next

Uncovered paths show [NOT COVERED] in the tooltip.

Mutant Testing Legend

Survived (tests missed this) Killed (tests detected this) No mutation

1: package Music::NWC2MusicXML::Event; 2: 3: use strict; 4: use warnings; 5: 6: our $VERSION = '0.001.1'; 7: 8: use Carp qw(croak carp); 9: use Readonly; 10: use Params::Validate::Strict qw(validate_strict); 11: use Params::Get; 12: 13: # --------------------------------------------------------------------------- 14: # Valid event types (both musical events and score/staff metadata markers) 15: # --------------------------------------------------------------------------- 16: Readonly::Hash my %MUSICAL_EVENT_TYPES => map { $_ => 1 } qw( 17: Note 18: Rest 19: Chord 20: Clef 21: Key 22: TimeSig 23: Tempo 24: Dynamic 25: DynVariance 26: TempoVariance 27: Text 28: Lyric 29: Bar 30: Tie 31: Slur 32: Beam 33: Tuplet 34: Instrument 35: FlowControl 36: UnsupportedEvent 37: ); 38: 39: Readonly::Hash my %METADATA_EVENT_TYPES => map { $_ => 1 } qw( 40: SongInfo 41: PgSetup 42: AddStaff 43: StaffProperties 44: StaffInstrument 45: ); 46: 47: # --------------------------------------------------------------------------- 48: # Duration map: NWC duration name -> rational denominator (quarter = 1/1) 49: # Using [numerator, denominator] pairs where the base unit is one quarter note. 50: # --------------------------------------------------------------------------- 51: Readonly::Hash my %DURATION_RATIONALS => ( 52: 'Whole' => [ 4, 1 ], 53: 'Half' => [ 2, 1 ], 54: '4th' => [ 1, 1 ], 55: '8th' => [ 1, 2 ], 56: '16th' => [ 1, 4 ], 57: '32nd' => [ 1, 8 ], 58: '64th' => [ 1, 16 ], 59: ); 60: 61: # Dotted note: multiply by 3/2; double-dotted: 7/4 62: Readonly::Scalar my $DOT_NUMERATOR => 3; 63: Readonly::Scalar my $DOT_DENOMINATOR => 2; 64: 65: Readonly::Hash my %MESSAGES => ( 66: error_unknown_type => 'Unknown event type: %s', 67: error_bad_duration => 'Unrecognised NWC duration: %s', 68: error_bad_rational => 'Rational arguments must be positive integers', 69: error_internal => 'Internal error: %s', 70: ); 71: 72: =head1 NAME 73: 74: Music::NWC2MusicXML::Event - Internal representation of a single NWC musical event 75: or score metadata record. 76: 77: =head1 VERSION 78: 79: 0.001.1 80: 81: =head1 SYNOPSIS 82: 83: use Music::NWC2MusicXML::Event; 84: 85: # Musical event 86: my $note = Music::NWC2MusicXML::Event->new( 87: type => 'Note', 88: start_time => [0, 1], # rational: 0 quarter-notes from measure start 89: duration => [1, 1], # rational: one quarter note 90: data => { 91: pitch => 'C', 92: octave => 4, 93: accidental => 0, 94: }, 95: ); 96: 97: # Unsupported / unknown object 98: my $unknown = Music::NWC2MusicXML::Event->new( 99: type => 'UnsupportedEvent', 100: nwc_label => 'SomeFutureObject', 101: data => { raw => '|SomeFutureObject|...' }, 102: ); 103: 104: =head1 DESCRIPTION 105: 106: C<Music::NWC2MusicXML::Event> is the internal representation of one NWC record. 107: It covers both musical events (notes, rests, bars, dynamics, ...) and 108: score/staff metadata (SongInfo, StaffProperties, ...). 109: 110: Musical timing is represented using exact rational numbers stored as 111: two-element arrayrefs C<[$numerator, $denominator]>. Floating-point 112: arithmetic is never used for musical durations; this avoids cumulative 113: rounding errors when dividing a beat into complex tuplet groupings. 114: 115: Unknown NWC object types are stored as C<UnsupportedEvent> records so 116: that conversion can continue rather than aborting. 117: 118: =cut 119: 120: # --------------------------------------------------------------------------- 121: # new 122: # --------------------------------------------------------------------------- 123: 124: =head2 new 125: 126: Construct a new Event. 127: 128: =head3 Purpose 129: 130: Factory constructor used by the parser to wrap each parsed NWC record into a 131: typed, time-stamped object suitable for later MusicXML generation. 132: 133: =head3 Arguments 134: 135: Named parameters: 136: 137: =over 4 138: 139: =item C<type> (string, required) -- one of the recognised event type names 140: listed in C<%MUSICAL_EVENT_TYPES> or C<%METADATA_EVENT_TYPES>, or 141: C<UnsupportedEvent>. 142: 143: =item C<nwc_label> (string, optional) -- the original NWC record label, useful 144: when C<type> is C<UnsupportedEvent>. 145: 146: =item C<start_time> (arrayref [$num,$den], optional) -- rational offset from 147: the beginning of the current measure. Default C<[0,1]>. 148: 149: =item C<duration> (arrayref [$num,$den], optional) -- rational duration in 150: quarter-note units. Default C<[0,1]> for non-durational events. 151: 152: =item C<data> (hashref, optional) -- type-specific payload (see below). 153: 154: =back 155: 156: =head3 Data payloads by type 157: 158: =over 4 159: 160: =item B<Note> -- C<pitch>, C<octave>, C<accidental>, C<tie_start>, C<tie_stop>, 161: C<slur_start>, C<slur_stop>, C<articulations> (arrayref), C<stem_direction>, 162: C<grace>. 163: 164: =item B<Rest> -- (no pitch fields). 165: 166: =item B<Chord> -- C<notes> (arrayref of Note-like hashrefs). 167: 168: =item B<Clef> -- C<nwc_clef> (e.g. C<Treble>). 169: 170: =item B<Key> -- C<nwc_signature> (e.g. C<Bb>), C<tonic>, C<mode>. 171: 172: =item B<TimeSig> -- C<beats>, C<beat_type>. 173: 174: =item B<Tempo> -- C<bpm>. 175: 176: =item B<Dynamic> -- C<marking> (e.g. C<mf>). 177: 178: =item B<Lyric> -- C<text>, C<verse>, C<syllabic> (C<begin>|C<middle>|C<end>|C<single>). 179: 180: =item B<Bar> -- C<style> (C<normal>|C<double>|C<final>|C<repeat_start>|C<repeat_end>|C<section>). 181: 182: =item B<FlowControl> -- C<directive> (e.g. C<Coda>, C<Segno>, C<DaCapo>). 183: 184: =item B<UnsupportedEvent> -- C<raw> (original NWC text line). 185: 186: =back 187: 188: =head3 Returns 189: 190: A blessed C<Music::NWC2MusicXML::Event> object. 191: 192: =head3 Side Effects 193: 194: None. 195: 196: =head3 Usage Example 197: 198: my $rest = Music::NWC2MusicXML::Event->new( 199: type => 'Rest', 200: start_time => [1, 1], 201: duration => [1, 2], # eighth rest 202: ); 203: 204: =head3 API SPECIFICATION 205: 206: =head4 Input 207: 208: type : SCALAR (required) 209: -- Valid domain: any string registered in %MUSICAL_EVENT_TYPES 210: -- or %METADATA_EVENT_TYPES (see Event.pm constants) 211: -- Invalid partition: unknown/unregistered string, undef, or '' 212: -- -> stored as UnsupportedEvent (carp), not croak 213: nwc_label : SCALAR (optional) 214: start_time : ARRAYREF [int>=0, int>0] (optional, default [0,1]) 215: -- Valid domain: exactly-2-element arrayref [numerator, denominator] 216: -- where denominator > 0. Numerator >= 0. 217: -- Invalid: non-arrayref, 1-element, 3+-element, or denominator=0 218: -- -> croak error_bad_rational 219: duration : ARRAYREF [int>=0, int>0] (optional, default [0,1]) 220: -- Same constraints as start_time 221: data : HASHREF (optional, default {}) 222: 223: =head4 Output 224: 225: Music::NWC2MusicXML::Event object 226: 227: =head3 MESSAGES 228: 229: | Code | Meaning | Resolution | 230: |---------------------|-----------------------------------------|------------------------| 231: | error_unknown_type | Type string not in recognised set | Check NWC record label | 232: | error_bad_rational | start_time or duration malformed | Use [$num,$den] form | 233: 234: =head3 FORMAL SPECIFICATION 235: 236: [EventInit] 237: type : EventType 238: start_time : Q+ (non-negative rational) 239: duration : Q+ (non-negative rational) 240: data : DATA 241: 242: (placeholder -- populate with Z calculus as implementation matures) 243: 244: =cut 245: 246: sub new { ●247 → 263 → 273 247: my ($class, %input) = @_; 248: my $args = validate_strict( 249: schema => { 250: type => { type => 'scalar' }, 251: nwc_label => { type => 'scalar', optional => 1 }, 252: start_time => { type => 'arrayref', optional => 1, default => [0, 1] }, 253: duration => { type => 'arrayref', optional => 1, default => [0, 1] }, 254: data => { type => 'hashref', optional => 1, default => {} }, 255: }, 256: input => \%input, 257: ); 258: croak $@ unless defined $args; 259: 260: # Normalise unknown types to UnsupportedEvent rather than croaking; 261: # this preserves conversion continuity when new NWC versions add objects. 262: my $type_key = $args->{type} // '';

Mutants (Total: 1, Killed: 1, Survived: 0)

264: exists $MUSICAL_EVENT_TYPES{$type_key} 265: || exists $METADATA_EVENT_TYPES{$type_key} 266: ) { 267: carp _fmt_msg('error_unknown_type', $type_key || '(undef)') 268: . ' -- storing as UnsupportedEvent'; 269: $args->{nwc_label} //= $args->{type}; 270: $args->{type} = 'UnsupportedEvent'; 271: } 272: 273: _validate_rational($args->{start_time}); 274: _validate_rational($args->{duration}); 275: 276: my $self = bless { 277: _type => $args->{type}, 278: _nwc_label => $args->{nwc_label} // $args->{type}, 279: _start_time => _reduce_rational($args->{start_time}), 280: _duration => _reduce_rational($args->{duration}), 281: _data => $args->{data}, 282: }, $class; 283: 284: return $self;