NWC2MusicXML/Diagnostics.pm

filter: Statementstmt 98.9% 94 / 95 Branchbran 76.9% 20 / 26 Conditioncond 100% 4 / 4 MC/DCmcdc 100% 2 / 2 Subroutinesub 100% 19 / 19 Podpod 100% 10 / 10 totaltotal 95.5% 149 / 156 CC 16 SCAR 8.6
CC
16
Cov
94%
new
5.0
_record_warning
3.0
count
3.0
CRAP 2.4
« NWC2MusicXML/Event.pm ↑ Summary NWC2MusicXML/Staff.pm »
1 package Music::NWC2MusicXML::Diagnostics;
2  
3 9 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 9 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 9 ▶use autodie qw(:all);
Subroutine BEGIN: called CC=1 SCAR=0.0
6  
7 9 our $VERSION = '0.003.0';
8  
9 9 ▶use Carp qw(croak carp);
Subroutine BEGIN: called CC=1 SCAR=0.0
10 9 ▶use Readonly;
Subroutine BEGIN: called CC=1 SCAR=0.0
11 9 ▶use Params::Validate::Strict qw(validate_strict);
Subroutine BEGIN: called CC=1 SCAR=0.0
12 9 ▶use Params::Get;
Subroutine BEGIN: called CC=1 SCAR=0.0
13  
14 # ---------------------------------------------------------------------------
15 # Log-level constants -- higher value = more output
16 # ---------------------------------------------------------------------------
17 9 Readonly::Scalar my $LOG_QUIET => 0;
18 9 Readonly::Scalar my $LOG_NORMAL => 1;
19 9 Readonly::Scalar my $LOG_VERBOSE => 2;
20 9 Readonly::Scalar my $LOG_DEBUG => 3;
21  
22 9 Readonly::Hash my %LOG_LEVEL_MAP => (
23 quiet => $LOG_QUIET,
24 normal => $LOG_NORMAL,
25 verbose => $LOG_VERBOSE,
26 debug => $LOG_DEBUG,
27 );
28  
29 # ---------------------------------------------------------------------------
30 # Exit-code constants (mirrored from main spec section 2)
31 # ---------------------------------------------------------------------------
32 9 Readonly::Scalar our $EXIT_OK => 0;
33 9 Readonly::Scalar our $EXIT_WARNINGS => 1;
34 9 Readonly::Scalar our $EXIT_BAD_INPUT => 2;
35 9 Readonly::Scalar our $EXIT_OUTPUT => 3;
36 9 Readonly::Scalar our $EXIT_INTERNAL => 4;
37  
38 # ---------------------------------------------------------------------------
39 # i18n message dictionary -- all user-visible strings live here
40 # ---------------------------------------------------------------------------
41 9 Readonly::Hash my %MESSAGES => (
42 error_internal => 'Internal error: %s',
43 error_open_warn_file => 'Cannot open warnings file %s for writing: %s',
44 warn_unsupported_obj => '[%s] Staff %s at %s: unsupported NWC object %s (%s)',
45 warn_approx_feature => '[%s] Staff %s at %s: %s approximated as %s',
46 warn_no_equivalent => '[%s] Staff %s at %s: %s has no MusicXML equivalent -- preserved in diagnostics',
47 info_file_start => 'Converting: %s',
48 info_file_done => 'Done: %s -> %s',
49 info_file_failed => 'FAILED: %s (%s)',
50 info_summary => 'Files processed: %d Successful: %d Warnings: %d Failed: %d',
51 debug_decode_step => '[DEBUG] NWC decode: %s',
52 debug_parse_step => '[DEBUG] Parser: %s',
53 debug_gen_step => '[DEBUG] MusicXML gen: %s',
54 );
55  
56 # ---------------------------------------------------------------------------
57 # new
58 # ---------------------------------------------------------------------------
59  
60 =head1 NAME
61  
62 Music::NWC2MusicXML::Diagnostics - Warning collection, logging, and reporting for
63 the Music::NWC2MusicXML conversion pipeline.
64  
65 =head1 VERSION
66  
67 0.003.0
68  
69 =head1 SYNOPSIS
70  
71 use Music::NWC2MusicXML::Diagnostics;
72  
73 my $diag = Music::NWC2MusicXML::Diagnostics->new(
74 level => 'verbose',
75 warnings_fh => \*STDERR,
76 );
77  
78 $diag->warn_unsupported(
79 file => 'Pilgrim.nwc',
80 staff => 'Staff 1',
81 pos => '4:2',
82 object => 'UserTool',
83 reason => 'No MusicXML equivalent',
84 );
85  
86 $diag->summary;
87  
88 =head1 DESCRIPTION
89  
90 Centralises all diagnostic output for the Music::NWC2MusicXML pipeline. No
91 module should print warnings or debug traces directly; instead each module
92 receives a C<Diagnostics> instance and routes output through it.
93  
94 Supports four severity levels: quiet, normal (default), verbose, debug.
95 Warnings can be written to an optional file handle (C<--warnings FILE>).
96 A summary count (processed / successful / warnings / failed) is maintained
97 and can be printed at batch completion.
98  
99 =cut
100  
101 =head2 new
102  
103 Construct a Diagnostics instance.
104  
105 =head3 Arguments
106  
107 Named parameters:
108  
109 =over 4
110  
111 =item C<level> -- log verbosity (optional, default C<'normal'>).
112  
113 =item C<warnings_fh> -- writable filehandle for per-warning output (optional).
114  
115 =back
116  
117 =head3 Returns
118  
119 Blessed C<Music::NWC2MusicXML::Diagnostics> object.
120  
121 =head3 API SPECIFICATION
122  
123 =head4 Input
124  
125 level : SCALAR (optional, default 'normal')
126 -- Valid domain (4 values only, case-sensitive):
127 -- 'quiet', 'normal', 'verbose', 'debug'
128 -- Invalid: undef, '' (empty), wrong-case ('QUIET', 'Normal'),
129 -- numeric (0, 1, 2, 3), or any other string -> croak
130 -- error_internal 'Unknown log level: ...'
131 warnings_fh : filehandle (optional)
132 -- Valid: any writable filehandle, or undef/absent (no file output)
133 -- The caller retains ownership; this module never closes it
134  
135 =head4 Output
136  
137 Music::NWC2MusicXML::Diagnostics object
138  
139 =cut
140  
141 115 ▶sub new {
Subroutine new: called CC=5 SCAR=16.1
Pod documented
142 115 my ($class, %input) = @_;
143 115 my $warnings_fh = delete $input{warnings_fh}; # glob refs can't be typed
144 115 my $args = validate_strict(
145 schema => {
146 level => { type => 'scalar', optional => 1, default => 'normal' },
147 },
148 input => \%input,
149 );
150 115 ▶ croak $@ unless defined $args;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $args 0 115 115
151  
152 115 ▶ my $level_key = $args->{level} // '';
Condition100%2/2
$args->{"level"} // ""
l!l
1141
MC/DC100%1/1
$args->{"level"} // ""
$args->{"level"}
Truth table100%2/2
A
A= $args->{"level"}
Aresult
11
00
153 croak _fmt_msg('error_internal', 'Unknown log level: ' . ($level_key || '(undef)'))
154 115 ▶ unless exists $LOG_LEVEL_MAP{$level_key};
Branch: 1 branch
BranchTrueFalseTotal
unless exists $LOG_LEVEL_MAP{$level_key} 11 104 115
Condition100%2/2
$level_key || '(undef)'
l!l
65
MC/DC100%1/1
$level_key || '(undef)'
$level_key
Truth table100%2/2
A
A= $level_key
Aresult
11
00
155  
156 my $self = bless {
157 104 _level => $LOG_LEVEL_MAP{$level_key},
158 _warnings_fh => $warnings_fh,
159 _warnings => [],
160 _counts => { processed => 0, successful => 0, warnings => 0, failed => 0 },
161 }, $class;
162  
163 104 return $self;
164 }
165  
166 # ---------------------------------------------------------------------------
167 # Public: logging methods
168 # ---------------------------------------------------------------------------
169  
170 =head2 info
171  
172 Log an informational message (suppressed at C<quiet> level).
173  
174 =head3 Purpose
175  
176 Emit progress / status information to STDERR.
177  
178 =head3 Arguments
179  
180 =over 4
181  
182 =item C<message> -- the text to emit.
183  
184 =back
185  
186 =head3 Returns
187  
188 C<$self> (for chaining).
189  
190 =head3 API SPECIFICATION
191  
192 =head4 Input
193  
194 message : SCALAR (required)
195  
196 =head4 Output
197  
198 $self (Music::NWC2MusicXML::Diagnostics)
199  
200 =head3 FORMAL SPECIFICATION
201  
202 [DiagInfo]
203 DiagInfo == message : String
204  
205 (placeholder -- populate with Z calculus as implementation matures)
206  
207 =cut
208  
209 64 ▶sub info {
Subroutine info: called CC=2 SCAR=6.9
Pod documented
210 64 my ($self, $message) = @_;
211 64 ▶ return $self if $self->{_level} < $LOG_NORMAL;
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"_level"} < $LOG_NORMAL 63 1 64
212 1 print STDERR $message, "\n";
213 1 return $self;
214 }
215  
216 =head2 verbose
217  
218 Log a verbose message (emitted only at C<verbose> or C<debug> level).
219  
220 =head3 Purpose
221  
222 Emit per-file detail that is too chatty for normal output but useful when
223 diagnosing conversion issues.
224  
225 =head3 Arguments
226  
227 =over 4
228  
229 =item C<message> -- the text to emit.
230  
231 =back
232  
233 =head3 Returns
234  
235 C<$self>.
236  
237 =head3 API SPECIFICATION
238  
239 =head4 Input
240  
241 message : SCALAR (required)
242  
243 =head4 Output
244  
245 $self (Music::NWC2MusicXML::Diagnostics)
246  
247 =head3 FORMAL SPECIFICATION
248  
249 (placeholder)
250  
251 =cut
252  
253 5 ▶sub verbose {
Subroutine verbose: called CC=2 SCAR=6.9
Pod documented
254 5 my ($self, $message) = @_;
255 5 ▶ return $self if $self->{_level} < $LOG_VERBOSE;
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"_level"} < $LOG_VERBOSE 4 1 5
256 1 print STDERR $message, "\n";
257 1 return $self;
258 }
259  
260 =head2 debug
261  
262 Log a debug trace (emitted only at C<debug> level).
263  
264 =head3 Purpose
265  
266 Emit low-level pipeline tracing for developer use.
267  
268 =head3 Arguments
269  
270 =over 4
271  
272 =item C<message> -- the text to emit.
273  
274 =back
275  
276 =head3 Returns
277  
278 C<$self>.
279  
280 =head3 API SPECIFICATION
281  
282 =head4 Input
283  
284 message : SCALAR (required)
285  
286 =head4 Output
287  
288 $self (Music::NWC2MusicXML::Diagnostics)
289  
290 =head3 FORMAL SPECIFICATION
291  
292 (placeholder)
293  
294 =cut
295  
296 89 ▶sub debug {
Subroutine debug: called CC=2 SCAR=6.9
Pod documented
297 89 my ($self, $message) = @_;
298 89 ▶ return $self if $self->{_level} < $LOG_DEBUG;
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"_level"} < $LOG_DEBUG 88 1 89
299 1 print STDERR '[DEBUG] ', $message, "\n";
300 1 return $self;
301 }
302  
303 =head2 warn_unsupported
304  
305 Record a warning for an unsupported NWC object.
306  
307 =head3 Purpose
308  
309 Called when the parser or generator encounters an NWC object it cannot
310 represent in MusicXML. The warning is added to the internal list and, if
311 a C<warnings_fh> was supplied, written immediately to that handle.
312  
313 =head3 Arguments
314  
315 Named parameters (hashref or flat list):
316  
317 =over 4
318  
319 =item C<file> -- input filename (string, required).
320  
321 =item C<staff> -- staff name or number (string, required).
322  
323 =item C<pos> -- measure:beat position string (string, optional).
324  
325 =item C<object> -- NWC object type name (string, required).
326  
327 =item C<reason> -- human-readable reason (string, optional).
328  
329 =back
330  
331 =head3 Returns
332  
333 C<$self>.
334  
335 =head3 Side Effects
336  
337 Increments the internal warning counter. Writes to C<warnings_fh> if set.
338  
339 =head3 Usage Example
340  
341 $diag->warn_unsupported(
342 file => 'Pilgrim.nwc',
343 staff => 'Violin I',
344 pos => '12:1',
345 object => 'UserTool',
346 reason => 'No MusicXML equivalent',
347 );
348  
349 =head3 API SPECIFICATION
350  
351 =head4 Input
352  
353 file : SCALAR (required)
354 staff : SCALAR (required)
355 pos : SCALAR (optional, default => '?')
356 object : SCALAR (required)
357 reason : SCALAR (optional, default => 'unknown')
358  
359 =head4 Output
360  
361 $self (Music::NWC2MusicXML::Diagnostics)
362  
363 =head3 MESSAGES
364  
365 | Code | Resolution |
366 |-------------------------|------------------------------------|
367 | warn_unsupported_obj | NWC object has no MusicXML mapping |
368  
369 =head3 FORMAL SPECIFICATION
370  
371 (placeholder)
372  
373 =cut
374  
375 21 ▶sub warn_unsupported {
Subroutine warn_unsupported: called CC=2 SCAR=7.0
Pod documented
376 21 my ($self, %input) = @_;
377 21 my $args = validate_strict(
378 schema => {
379 file => { type => 'scalar' },
380 staff => { type => 'scalar' },
381 pos => { type => 'scalar', optional => 1, default => '?' },
382 object => { type => 'scalar' },
383 reason => { type => 'scalar', optional => 1, default => 'unknown' },
384 },
385 input => \%input,
386 );
387 20 ▶ croak $@ unless defined $args;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $args 0 20 20
388  
389 my $msg = _fmt_msg('warn_unsupported_obj',
390 20 $args->{file}, $args->{staff}, $args->{pos}, $args->{object}, $args->{reason});
391  
392 20 $self->_record_warning($msg);
393 20 return $self;
394 }
395  
396 =head2 warn_approximate
397  
398 Record a warning that an NWC feature was approximated.
399  
400 =head3 Purpose
401  
402 Called when an NWC feature maps only approximately to a MusicXML construct.
403  
404 =head3 Arguments
405  
406 Named parameters: C<file>, C<staff>, C<pos>, C<feature>, C<approximation>.
407  
408 =head3 Returns
409  
410 C<$self>.
411  
412 =head3 API SPECIFICATION
413  
414 =head4 Input
415  
416 file : SCALAR (required)
417 staff : SCALAR (required)
418 pos : SCALAR (optional)
419 feature : SCALAR (required)
420 approximation : SCALAR (required)
421  
422 =head4 Output
423  
424 $self
425  
426 =head3 FORMAL SPECIFICATION
427  
428 (placeholder)
429  
430 =cut
431  
432 4 ▶sub warn_approximate {
Subroutine warn_approximate: called CC=2 SCAR=7.0
Pod documented
433 4 my ($self, %input) = @_;
434 4 my $args = validate_strict(
435 schema => {
436 file => { type => 'scalar' },
437 staff => { type => 'scalar' },
438 pos => { type => 'scalar', optional => 1, default => '?' },
439 feature => { type => 'scalar' },
440 approximation => { type => 'scalar' },
441 },
442 input => \%input,
443 );
444 4 ▶ croak $@ unless defined $args;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $args 0 4 4
445  
446 my $msg = _fmt_msg('warn_approx_feature',
447 $args->{file}, $args->{staff}, $args->{pos},
448 4 $args->{feature}, $args->{approximation});
449  
450 4 $self->_record_warning($msg);
451 4 return $self;
452 }
453  
454 =head2 count
455  
456 Update the batch summary counters.
457  
458 =head3 Purpose
459  
460 Called by the top-level converter to track per-file outcomes.
461  
462 =head3 Arguments
463  
464 Named parameter: C<outcome> -- one of C<processed>, C<successful>,
465 C<warnings>, C<failed>.
466  
467 =head3 Returns
468  
469 C<$self>.
470  
471 =head3 API SPECIFICATION
472  
473 =head4 Input
474  
475 outcome : SCALAR (required)
476 -- Valid domain (4 values only, case-sensitive):
477 -- 'processed', 'successful', 'warnings', 'failed'
478 -- Invalid: undef, '' (empty), wrong-case ('Processed'), any other
479 -- string -> croak error_internal 'Unknown counter: ...'
480  
481 =head4 Output
482  
483 $self
484  
485 =head3 FORMAL SPECIFICATION
486  
487 (placeholder)
488  
489 =cut
490  
491 1111 ▶sub count {
Subroutine count: called CC=3 SCAR=11.0
Pod documented
492 1111 my ($self, %input) = @_;
493 1111 my $args = validate_strict(
494 schema => { outcome => { type => 'scalar' } },
495 input => \%input,
496 );
497 1111 ▶ croak $@ unless defined $args;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $args 0 1111 1111
498  
499 croak _fmt_msg('error_internal', 'Unknown counter: ' . $args->{outcome})
500 1111 ▶ unless exists $self->{_counts}{ $args->{outcome} };
Branch: 1 branch
BranchTrueFalseTotal
unless exists $self->{"_counts"}{$args->{"outcome"}} 6 1105 1111
501  
502 1105 $self->{_counts}{ $args->{outcome} }++;
503 1105 return $self;
504 }
505  
506 =head2 summary
507  
508 Print the batch processing summary.
509  
510 =head3 Purpose
511  
512 Emits the Files processed / Successful / Warnings / Failed summary to STDERR
513 at the end of a batch run.
514  
515 =head3 Returns
516  
517 C<$self>.
518  
519 =head3 API SPECIFICATION
520  
521 =head4 Input
522  
523 (none)
524  
525 =head4 Output
526  
527 $self
528  
529 =head3 FORMAL SPECIFICATION
530  
531 (placeholder)
532  
533 =cut
534  
535 15 ▶sub summary {
Subroutine summary: called CC=2 SCAR=6.9
Pod documented
536 15 my ($self) = @_;
537 15 ▶ return $self if $self->{_level} < $LOG_NORMAL;
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"_level"} < $LOG_NORMAL 14 1 15
538 1 my $c = $self->{_counts};
539 print STDERR _fmt_msg('info_summary',
540 1 $c->{processed}, $c->{successful}, $c->{warnings}, $c->{failed}), "\n";
541 1 return $self;
542 }
543  
544 =head2 warnings
545  
546 Return an arrayref of all collected warning strings.
547  
548 =head3 Returns
549  
550 Arrayref of strings.
551  
552 =head3 API SPECIFICATION
553  
554 =head4 Input
555  
556 (none)
557  
558 =head4 Output
559  
560 arrayref of SCALAR
561  
562 =cut
563  
564 38 ▶sub warnings {
Subroutine warnings: called CC=1 SCAR=0.0
Pod documented
565 38 my ($self) = @_;
566 38 return $self->{_warnings};
567 }
568  
569 =head2 has_warnings
570  
571 Return true if any warnings have been collected.
572  
573 =cut
574  
575 12 ▶sub has_warnings {
Subroutine has_warnings: called CC=1 SCAR=0.0
Pod documented
576 12 my ($self) = @_;
577 12 return scalar @{ $self->{_warnings} } > 0;
578 }
579  
580 # ---------------------------------------------------------------------------
581 # Private helpers
582 # ---------------------------------------------------------------------------
583  
584 24 ▶sub _record_warning {
Subroutine _record_warning: called CC=3 SCAR=11.1
585 24 my ($self, $msg) = @_;
586 24 push @{ $self->{_warnings} }, $msg;
587 24 $self->{_counts}{warnings}++;
588 24 ▶ if (defined $self->{_warnings_fh}) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $self->{"_warnings_fh"}) 3 21 24
589 3 print { $self->{_warnings_fh} } 'WARNING: ', $msg, "\n";
590 }
591 24 ▶ if ($self->{_level} >= $LOG_NORMAL) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{"_level"} >= $LOG_NORMAL) 0 24 24
592 0 print STDERR 'WARNING: ', $msg, "\n";
593 }
594 24 return;
595 }
596  
597 # Class-level helper; not a method so it can be called before construction.
598 42 ▶sub _fmt_msg {
Subroutine _fmt_msg: called CC=2 SCAR=7.1
599 42 my ($key, @args) = @_;
600 42 ▶ croak "Unknown message key: $key" unless exists $MESSAGES{$key};
Branch: 1 branch
BranchTrueFalseTotal
unless exists $MESSAGES{$key} 0 42 42
601 42 return sprintf $MESSAGES{$key}, @args;
602 }
603  
604 9 1;
605  
606 __END__
« NWC2MusicXML/Event.pm ↑ Summary NWC2MusicXML/Staff.pm »