| 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
| |||||||||||||||||||||
| 151 | |||||||||||||||||||||
| 152 | 115 | ▶ | my $level_key = $args->{level} // ''; | ||||||||||||||||||
|
Condition100%2/2
$args->{"level"} // ""
MC/DC100%1/1
$args->{"level"} // ""
$args->{"level"}
Truth table100%2/2
A
A= $args->{"level"}
| |||||||||||||||||||||
| 153 | croak _fmt_msg('error_internal', 'Unknown log level: ' . ($level_key || '(undef)')) | ||||||||||||||||||||
| 154 | 115 | ▶ | unless exists $LOG_LEVEL_MAP{$level_key}; | ||||||||||||||||||
|
Branch: 1 branch
Condition100%2/2
$level_key || '(undef)'
MC/DC100%1/1
$level_key || '(undef)'
$level_key
Truth table100%2/2
A
A= $level_key
| |||||||||||||||||||||
| 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
| |||||||||||||||||||||
| 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
| |||||||||||||||||||||
| 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
| |||||||||||||||||||||
| 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
| |||||||||||||||||||||
| 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
| |||||||||||||||||||||
| 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
| |||||||||||||||||||||
| 498 | |||||||||||||||||||||
| 499 | croak _fmt_msg('error_internal', 'Unknown counter: ' . $args->{outcome}) | ||||||||||||||||||||
| 500 | 1111 | ▶ | unless exists $self->{_counts}{ $args->{outcome} }; | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 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
| |||||||||||||||||||||
| 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
| |||||||||||||||||||||
| 589 | 3 | print { $self->{_warnings_fh} } 'WARNING: ', $msg, "\n"; | |||||||||||||||||||
| 590 | } | ||||||||||||||||||||
| 591 | 24 | ▶ | if ($self->{_level} >= $LOG_NORMAL) { | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 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
| |||||||||||||||||||||
| 601 | 42 | return sprintf $MESSAGES{$key}, @args; | |||||||||||||||||||
| 602 | } | ||||||||||||||||||||
| 603 | |||||||||||||||||||||
| 604 | 9 | 1; | |||||||||||||||||||
| 605 | |||||||||||||||||||||
| 606 | __END__ | ||||||||||||||||||||