/ 
Music-NWC2MusicXML-0.001.1
/ Music::NWC2MusicXML::Diagnostics

NAME

Music::NWC2MusicXML::Diagnostics - Warning collection, logging, and reporting for the Music::NWC2MusicXML conversion pipeline.

VERSION

0.001.1

SYNOPSIS

use Music::NWC2MusicXML::Diagnostics;

my $diag = Music::NWC2MusicXML::Diagnostics->new(
    level        => 'verbose',
    warnings_fh  => \*STDERR,
);

$diag->warn_unsupported(
    file   => 'Pilgrim.nwc',
    staff  => 'Staff 1',
    pos    => '4:2',
    object => 'UserTool',
    reason => 'No MusicXML equivalent',
);

$diag->summary;

DESCRIPTION

Centralises all diagnostic output for the Music::NWC2MusicXML pipeline. No module should print warnings or debug traces directly; instead each module receives a Diagnostics instance and routes output through it.

Supports four severity levels: quiet, normal (default), verbose, debug. Warnings can be written to an optional file handle (--warnings FILE). A summary count (processed / successful / warnings / failed) is maintained and can be printed at batch completion.

new

Construct a Diagnostics instance.

Arguments

Named parameters:

level -- log verbosity (optional, default 'normal').
warnings_fh -- writable filehandle for per-warning output (optional).

Returns

Blessed Music::NWC2MusicXML::Diagnostics object.

API SPECIFICATION

Input

level        : SCALAR (optional, default 'normal')
                 -- Valid domain (4 values only, case-sensitive):
                 --   'quiet', 'normal', 'verbose', 'debug'
                 -- Invalid: undef, '' (empty), wrong-case ('QUIET', 'Normal'),
                 --   numeric (0, 1, 2, 3), or any other string -> croak
                 --   error_internal 'Unknown log level: ...'
warnings_fh  : filehandle (optional)
                 -- Valid: any writable filehandle, or undef/absent (no file output)
                 -- The caller retains ownership; this module never closes it

Output

Music::NWC2MusicXML::Diagnostics object

info

Log an informational message (suppressed at quiet level).

Purpose

Emit progress / status information to STDERR.

Arguments

message -- the text to emit.

Returns

$self (for chaining).

API SPECIFICATION

Input

message : SCALAR (required)

Output

$self (Music::NWC2MusicXML::Diagnostics)

FORMAL SPECIFICATION

[DiagInfo]
  DiagInfo == message : String

(placeholder -- populate with Z calculus as implementation matures)

verbose

Log a verbose message (emitted only at verbose or debug level).

Purpose

Emit per-file detail that is too chatty for normal output but useful when diagnosing conversion issues.

Arguments

message -- the text to emit.

Returns

$self.

API SPECIFICATION

Input

message : SCALAR (required)

Output

$self (Music::NWC2MusicXML::Diagnostics)

FORMAL SPECIFICATION

(placeholder)

debug

Log a debug trace (emitted only at debug level).

Purpose

Emit low-level pipeline tracing for developer use.

Arguments

message -- the text to emit.

Returns

$self.

API SPECIFICATION

Input

message : SCALAR (required)

Output

$self (Music::NWC2MusicXML::Diagnostics)

FORMAL SPECIFICATION

(placeholder)

warn_unsupported

Record a warning for an unsupported NWC object.

Purpose

Called when the parser or generator encounters an NWC object it cannot represent in MusicXML. The warning is added to the internal list and, if a warnings_fh was supplied, written immediately to that handle.

Arguments

Named parameters (hashref or flat list):

file -- input filename (string, required).
staff -- staff name or number (string, required).
pos -- measure:beat position string (string, optional).
object -- NWC object type name (string, required).
reason -- human-readable reason (string, optional).

Returns

$self.

Side Effects

Increments the internal warning counter. Writes to warnings_fh if set.

Usage Example

$diag->warn_unsupported(
    file   => 'Pilgrim.nwc',
    staff  => 'Violin I',
    pos    => '12:1',
    object => 'UserTool',
    reason => 'No MusicXML equivalent',
);

API SPECIFICATION

Input

file   : SCALAR (required)
staff  : SCALAR (required)
pos    : SCALAR (optional, default => '?')
object : SCALAR (required)
reason : SCALAR (optional, default => 'unknown')

Output

$self (Music::NWC2MusicXML::Diagnostics)

MESSAGES

| Code | Resolution | |-------------------------|------------------------------------| | warn_unsupported_obj | NWC object has no MusicXML mapping |

FORMAL SPECIFICATION

(placeholder)

warn_approximate

Record a warning that an NWC feature was approximated.

Purpose

Called when an NWC feature maps only approximately to a MusicXML construct.

Arguments

Named parameters: file, staff, pos, feature, approximation.

Returns

$self.

API SPECIFICATION

Input

file          : SCALAR (required)
staff         : SCALAR (required)
pos           : SCALAR (optional)
feature       : SCALAR (required)
approximation : SCALAR (required)

Output

$self

FORMAL SPECIFICATION

(placeholder)

count

Update the batch summary counters.

Purpose

Called by the top-level converter to track per-file outcomes.

Arguments

Named parameter: outcome -- one of processed, successful, warnings, failed.

Returns

$self.

API SPECIFICATION

Input

outcome : SCALAR (required)
            -- Valid domain (4 values only, case-sensitive):
            --   'processed', 'successful', 'warnings', 'failed'
            -- Invalid: undef, '' (empty), wrong-case ('Processed'), any other
            --   string -> croak error_internal 'Unknown counter: ...'

Output

$self

FORMAL SPECIFICATION

(placeholder)

summary

Print the batch processing summary.

Purpose

Emits the Files processed / Successful / Warnings / Failed summary to STDERR at the end of a batch run.

Returns

$self.

API SPECIFICATION

Input

(none)

Output

$self

FORMAL SPECIFICATION

(placeholder)

warnings

Return an arrayref of all collected warning strings.

Returns

Arrayref of strings.

API SPECIFICATION

Input

(none)

Output

arrayref of SCALAR

has_warnings

Return true if any warnings have been collected.

DIAGNOSTICS

See %MESSAGES hash in source for all message keys and their sprintf-compatible format strings.

LIMITATIONS

  • Warning file is opened externally; this module does not open files itself.

  • Thread safety is not guaranteed.

AUTHOR

Nigel Horne <nigel.horne@gmail.com>

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.