NWC2MusicXML/Staff.pm

filter: Statementstmt 100% 76 / 76 Branchbran 75.0% 6 / 8 Conditioncond 80.0% 4 / 5 MC/DCmcdc 66.6% 2 / 3 Subroutinesub 100% 27 / 27 Podpod 94.1% 16 / 17 totaltotal 96.3% 131 / 136 CC 8 SCAR 5.0
CC
8
Cov
97%
add_event
4.0
has_notes
3.0
_fmt_msg
2.0
CRAP 1.7
« NWC2MusicXML/Diagnostics.pm ↑ Summary
1 package Music::NWC2MusicXML::Staff;
2  
3 15 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 15 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5  
6 15 ▶use version; our $VERSION = version->declare('0.003.0');
Subroutine BEGIN: called CC=1 SCAR=0.0
7  
8 15 ▶use Carp qw(croak carp);
Subroutine BEGIN: called CC=1 SCAR=0.0
9 15 ▶use Readonly;
Subroutine BEGIN: called CC=1 SCAR=0.0
10 15 ▶use Scalar::Util qw(blessed);
Subroutine BEGIN: called CC=1 SCAR=0.0
11 15 ▶use Params::Validate::Strict qw(validate_strict);
Subroutine BEGIN: called CC=1 SCAR=0.0
12 15 ▶use Params::Get;
Subroutine BEGIN: called CC=1 SCAR=0.0
13 15 ▶use Music::NWC2MusicXML::Event;
Subroutine BEGIN: called CC=1 SCAR=0.0
14  
15 15 Readonly::Hash my %MESSAGES => (
16 error_bad_event => 'add_event: argument must be a Music::NWC2MusicXML::Event, got: %s',
17 error_internal => 'Internal error: %s',
18 );
19  
20 # Event types that constitute a sounding (or structurally significant) event
21 # for the purpose of has_notes(). Hash lookup is O(1); avoids regex in a loop.
22 15 Readonly::Hash my %SOUNDING_EVENT_TYPES => map { $_ => 1 } qw(Note Rest Chord Bar);
23  
24 =head1 NAME
25  
26 Music::NWC2MusicXML::Staff - Internal representation of a single NWC staff.
27  
28 =head1 VERSION
29  
30 0.003.0
31  
32 =head1 SYNOPSIS
33  
34 use Music::NWC2MusicXML::Staff;
35  
36 my $staff = Music::NWC2MusicXML::Staff->new(
37 name => 'Violin I',
38 group => 'Standard',
39 instrument => { name => 'String Ensemble 1', patch => 48 },
40 );
41  
42 $staff->add_event($note_event);
43 my $events = $staff->events;
44  
45 =head1 DESCRIPTION
46  
47 C<Music::NWC2MusicXML::Staff> holds all information about one NWC staff: its
48 properties (name, visibility, number of lines), instrument data, and the
49 ordered sequence of C<Music::NWC2MusicXML::Event> objects that constitute its
50 musical content.
51  
52 The event list is in parse order. MusicXML generation iterates over it
53 to produce C<< <measure> >> elements.
54  
55 =cut
56  
57 423 ▶sub new {
Subroutine new: called CC=2 SCAR=7.0
Pod undocumented
58 423 my ($class, %input) = @_;
59 423 my $args = validate_strict(
60 schema => {
61 name => { type => 'scalar', optional => 1, default => 'Staff' },
62 group => { type => 'scalar', optional => 1, default => 'Standard' },
63 lines => { type => 'scalar', optional => 1, default => 5 },
64 visible => { type => 'scalar', optional => 1, default => 1 },
65 ending_bar => { type => 'scalar', optional => 1 },
66 instrument => { type => 'hashref', optional => 1, default => {} },
67 initial_clef => { type => 'scalar', optional => 1 },
68 initial_key => { type => 'hashref', optional => 1 },
69 initial_timesig => { type => 'hashref', optional => 1 },
70 },
71 input => \%input,
72 );
73 423 ▶ croak $@ unless defined $args;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $args 0 423 423
74  
75 my $self = bless {
76 _name => $args->{name},
77 _group => $args->{group},
78 _lines => $args->{lines},
79 _visible => $args->{visible},
80 _ending_bar => $args->{ending_bar},
81 _instrument => $args->{instrument},
82 _initial_clef => $args->{initial_clef},
83 _initial_key => $args->{initial_key},
84 _initial_timesig => $args->{initial_timesig},
85 423 _events => [],
86 }, $class;
87  
88 423 return $self;
89 }
90  
91 # ---------------------------------------------------------------------------
92 # Accessors
93 # ---------------------------------------------------------------------------
94  
95 =head2 name
96  
97 Return the staff name string.
98  
99 =cut
100  
101 301 ▶sub name { return $_[0]->{_name} }
Subroutine name: called CC=1 SCAR=0.0
Pod documented
102  
103 =head2 group
104  
105 Return the group name string.
106  
107 =cut
108  
109 5 ▶sub group { return $_[0]->{_group} }
Subroutine group: called CC=1 SCAR=0.0
Pod documented
110  
111 =head2 lines
112  
113 Return the number of staff lines (usually 5).
114  
115 =cut
116  
117 6 ▶sub lines { return $_[0]->{_lines} }
Subroutine lines: called CC=1 SCAR=0.0
Pod documented
118  
119 =head2 visible
120  
121 Return 1 if the staff is visible, 0 otherwise.
122  
123 =cut
124  
125 6 ▶sub visible { return $_[0]->{_visible} }
Subroutine visible: called CC=1 SCAR=0.0
Pod documented
126  
127 =head2 instrument
128  
129 Return the instrument information hashref.
130  
131 Keys: C<name> (string), C<patch> (MIDI patch number 0-127).
132  
133 =cut
134  
135 632 ▶sub instrument { return $_[0]->{_instrument} }
Subroutine instrument: called CC=1 SCAR=0.0
Pod documented
136  
137 =head2 initial_clef
138  
139 Return the initial clef string (e.g. C<Treble>), or undef if none recorded.
140  
141 =cut
142  
143 525 ▶sub initial_clef { return $_[0]->{_initial_clef} }
Subroutine initial_clef: called CC=1 SCAR=0.0
Pod documented
144  
145 =head2 set_initial_clef
146  
147 Set the initial clef.
148  
149 =cut
150  
151 273 ▶sub set_initial_clef {
Subroutine set_initial_clef: called CC=1 SCAR=0.0
Pod documented
152 273 my ($self, $clef) = @_;
153 273 $self->{_initial_clef} = $clef;
154 273 return $self;
155 }
156  
157 =head2 initial_key
158  
159 Return the initial key hashref (C<signature>, C<tonic>, C<mode>), or undef.
160  
161 =cut
162  
163 524 ▶sub initial_key { return $_[0]->{_initial_key} }
Subroutine initial_key: called CC=1 SCAR=0.0
Pod documented
164  
165 =head2 set_initial_key
166  
167 Set the initial key.
168  
169 =cut
170  
171 235 ▶sub set_initial_key {
Subroutine set_initial_key: called CC=1 SCAR=0.0
Pod documented
172 235 my ($self, $key) = @_;
173 235 $self->{_initial_key} = $key;
174 235 return $self;
175 }
176  
177 =head2 initial_timesig
178  
179 Return the initial time-signature hashref (C<beats>, C<beat_type>), or undef.
180  
181 =cut
182  
183 689 ▶sub initial_timesig { return $_[0]->{_initial_timesig} }
Subroutine initial_timesig: called CC=1 SCAR=0.0
Pod documented
184  
185 =head2 set_initial_timesig
186  
187 Set the initial time signature.
188  
189 =cut
190  
191 238 ▶sub set_initial_timesig {
Subroutine set_initial_timesig: called CC=1 SCAR=0.0
Pod documented
192 238 my ($self, $ts) = @_;
193 238 $self->{_initial_timesig} = $ts;
194 238 return $self;
195 }
196  
197 # ---------------------------------------------------------------------------
198 # Event management
199 # ---------------------------------------------------------------------------
200  
201 =head2 add_event
202  
203 Append a C<Music::NWC2MusicXML::Event> to this staff's event list.
204  
205 =head3 Purpose
206  
207 Used by the parser to build the ordered event sequence as it processes NWCTXT
208 records belonging to this staff.
209  
210 =head3 Arguments
211  
212 =over 4
213  
214 =item C<$event> -- a blessed C<Music::NWC2MusicXML::Event> object (required).
215  
216 =back
217  
218 =head3 Returns
219  
220 C<$self> (for chaining).
221  
222 =head3 Side Effects
223  
224 Appends to C<_events> array.
225  
226 =head3 Usage Example
227  
228 $staff->add_event(
229 Music::NWC2MusicXML::Event->new(type => 'Note', ...)
230 );
231  
232 =head3 API SPECIFICATION
233  
234 =head4 Input
235  
236 $event : Music::NWC2MusicXML::Event (required)
237  
238 =head4 Output
239  
240 $self (Music::NWC2MusicXML::Staff)
241  
242 =head3 MESSAGES
243  
244 | Code | Meaning | Resolution |
245 |----------------|----------------------------------------|---------------------------------|
246 | error_bad_event| Argument is not a Music::NWC2MusicXML::Event | Construct event before adding |
247  
248 =head3 FORMAL SPECIFICATION
249  
250 [AddEvent]
251 DeltaStaff
252 event? : Event
253 ---------
254 events' = events ^ <event?>
255  
256 (placeholder)
257  
258 =cut
259  
260 181155 ▶sub add_event {
Subroutine add_event: called CC=4 SCAR=13.9
Pod documented
261 181155 my ($self, $event) = @_;
262 181155 ▶ croak _fmt_msg('error_bad_event', ref($event) // 'SCALAR')
Branch: 1 branch
BranchTrueFalseTotal
unless builtin::blessed($event) and $event->isa("Music::NWC2MusicXML::Event") 10 181145 181155
Condition80%4/5
builtin::blessed($event) and $event->isa("Music::NWC2MusicXML::Event")
!ll&&!rl&&r
82181145
ref $event // "SCALAR"
l!l
100
MC/DC100%2/2
builtin::blessed($event) and $event->isa("Music::NWC2MusicXML::Event")
builtin::blessed($event) $event->isa("Music::NWC2MusicXML::Event")
MC/DC0%0/1
ref $event // "SCALAR"
ref $event
Truth table100%3/3
A and B
A= builtin::blessed($event)B= $event->isa("Music::NWC2MusicXML::Event")
ABresult
0X0
100
111
Truth table50%1/2
A
A= ref $event
Aresult
11
00
263 unless blessed($event) && $event->isa('Music::NWC2MusicXML::Event');
264 181145 push @{ $self->{_events} }, $event;
265 181145 return $self;
266 }
267  
268 =head2 events
269  
270 Return an arrayref of all C<Music::NWC2MusicXML::Event> objects in parse order.
271  
272 =head3 Returns
273  
274 Arrayref of C<Music::NWC2MusicXML::Event>.
275  
276 =head3 API SPECIFICATION
277  
278 =head4 Input
279  
280 (none)
281  
282 =head4 Output
283  
284 ARRAYREF of Music::NWC2MusicXML::Event
285  
286 =cut
287  
288 1958 ▶sub events {
Subroutine events: called CC=1 SCAR=0.0
Pod documented
289 1958 my ($self) = @_;
290 1958 return $self->{_events};
291 }
292  
293 =head2 musical_events
294  
295 Return an arrayref containing only the events where C<is_musical_event> is
296 true. Metadata records are excluded.
297  
298 =cut
299  
300 5 ▶sub musical_events {
Subroutine musical_events: called CC=1 SCAR=0.0
Pod documented
301 5 my ($self) = @_;
302 5 return [ grep { $_->is_musical_event } @{ $self->{_events} } ];
303 }
304  
305 =head2 event_count
306  
307 Return the total number of events (musical + metadata).
308  
309 =cut
310  
311 38 ▶sub event_count {
Subroutine event_count: called CC=1 SCAR=0.0
Pod documented
312 38 my ($self) = @_;
313 38 return scalar @{ $self->{_events} };
314 }
315  
316 =head2 has_notes
317  
318 Return true if any note, rest, chord, or bar event has been added to this
319 staff. Used by the parser to distinguish staff-header records (before any
320 sounding content) from mid-staff change records.
321  
322 =cut
323  
324 3233 ▶sub has_notes {
Subroutine has_notes: called CC=3 SCAR=11.0
Pod documented
325 3233 my ($self) = @_;
326 3233 for my $ev (@{ $self->{_events} }) {
327 4029 ▶ return 1 if $SOUNDING_EVENT_TYPES{ $ev->type };
Branch: 1 branch
BranchTrueFalseTotal
if $SOUNDING_EVENT_TYPES{$ev->type} 2696 1333 4029
328 }
329 537 return 0;
330 }
331  
332 # ---------------------------------------------------------------------------
333 # Private
334 # ---------------------------------------------------------------------------
335  
336 10 ▶sub _fmt_msg {
Subroutine _fmt_msg: called CC=2 SCAR=7.1
337 10 my ($key, @args) = @_;
338 10 ▶ croak "Unknown message key: $key" unless exists $MESSAGES{$key};
Branch: 1 branch
BranchTrueFalseTotal
unless exists $MESSAGES{$key} 0 10 10
339 10 return sprintf $MESSAGES{$key}, @args;
340 }
341  
342 15 1;
343  
344 __END__
« NWC2MusicXML/Diagnostics.pm ↑ Summary