File Coverage

=head1 NAME

Music::NWC2MusicXML - Convert NoteWorthy Composer 2 C<.nwc> score files to MusicXML.

=head1 VERSION

0.002.4

=head1 SYNOPSIS

    # Simple conversion
    use Music::NWC2MusicXML;

    my $converter = Music::NWC2MusicXML->new;
    $converter->convert(
        input  => 'Pilgrim.nwc',
        output => 'Pilgrim.musicxml',
    );

    # Batch conversion
    $converter->batch_convert(
        inputs     => [ glob('*.nwc') ],
        output_dir => 'musicxml',
        overwrite  => 1,
    );

=head1 DESCRIPTION

C<Music::NWC2MusicXML> is the top-level facade for the NWC-to-MusicXML conversion
pipeline.  It coordinates three independent stages:

=over 4

=item 1. B<NWC binary decoding> (C<Music::NWC2MusicXML::NWC>) -- reads the C<.nwc>
binary container, verifies the magic signature, decompresses the zlib payload,
and extracts the NWCTXT text representation.

=item 2. B<NWCTXT parsing> (C<Music::NWC2MusicXML::Parser>) -- parses the NWCTXT into
an internal representation (C<Music::NWC2MusicXML::Score>).

=item 3. B<MusicXML generation> (C<Music::NWC2MusicXML::MusicXML>) -- serialises the
internal representation to a well-formed UTF-8 MusicXML document.

=back

Each stage is independently testable.  The facade wires them together,
handles batch processing, and routes all diagnostics through a single
C<Music::NWC2MusicXML::Diagnostics> instance.

=head1 PRESERVATION PRINCIPLE

The guiding principle of the conversion is:

I<Preserve musical meaning rather than graphical appearance.>

Priority order: notes and rhythm > voices > measures > articulations >
dynamics > lyrics > structural markings > instrument info > graphical layout.

=cut

=head2 new

Construct a converter.

=head3 Purpose

Creates a configured converter instance that can be reused for multiple
conversions without reconstructing the pipeline components each time.

=head3 Arguments

Named parameters:

=over 4

=item C<log_level>    -- C<quiet>, C<normal> (default), C<verbose>, C<debug>.

=item C<warnings_fh> -- filehandle for warning output (optional; defaults to
STDERR in the C<Diagnostics> object).

=item C<validate>    -- perform extended consistency checks (boolean, default 0).

=back

=head3 Returns

Blessed C<Music::NWC2MusicXML> object.

=head3 Usage Example

    my $c = Music::NWC2MusicXML->new(log_level => 'verbose', validate => 1);

=head3 API SPECIFICATION

=head4 Input

    log_level    : SCALAR  (optional, default 'normal')
    warnings_fh  : (filehandle, optional)
    validate     : SCALAR  (optional, default 0)

=head4 Output

    Music::NWC2MusicXML object

=head3 MESSAGES

None.

=cut

=head2 convert

Convert a single C<.nwc> file to MusicXML.

=head3 Purpose

Main single-file conversion entry point.  Chains decoder -> parser ->
generator, writes the output file, and updates the internal diagnostic counters.

=head3 Arguments

Named parameters:

=over 4

=item C<input>     -- path to the C<.nwc> input file (required).

=item C<output>    -- path for the C<.musicxml> output file (optional).
Defaults to the input path with the extension replaced by C<.musicxml>.

=item C<overwrite> -- if false (default), skip conversion when the output file
already exists.

=back

=head3 Returns

Scalar string -- the output file path if conversion succeeded, or undef on
failure.

=head3 Side Effects

Writes the output file.  Updates diagnostic counters.
Croaks on fatal errors; non-fatal issues are issued as warnings.

=head3 Usage Example

    my $out = $c->convert(input => 'Pilgrim.nwc', overwrite => 1);

=head3 API SPECIFICATION

=head4 Input

    input     : SCALAR (path, required)
    output    : SCALAR (path, optional)
    overwrite : boolean (optional, default false)

=head4 Output

    SCALAR (output path) or undef

=head3 MESSAGES

| Code               | Meaning                              | Resolution                    |
|--------------------|--------------------------------------|-------------------------------|
| error_no_input     | C<input> parameter missing           | Provide input path            |
| error_file_not_found| Input file does not exist           | Check path                    |
| error_decode       | NWC decoding stage failed            | See error detail              |
| error_parse        | NWCTXT parsing stage failed          | See error detail              |
| error_generate     | MusicXML generation failed           | See error detail              |
| error_write        | Cannot write output file             | Check permissions / disk space|

=cut

=head2 batch_convert

Convert multiple C<.nwc> files, optionally into a separate output directory.

=head3 Purpose

Processes a list of input files in sequence.  Failures on individual files
are caught and counted; conversion continues with remaining files.
A summary is printed at the end.

=head3 Arguments

Named parameters:

=over 4

=item C<inputs>     -- arrayref of input file paths (required).

=item C<output_dir> -- directory for output files (optional; defaults to each
file's own directory).

=item C<overwrite>  -- overwrite existing output files (boolean, default 0).

=item C<recursive>  -- preserve relative directory structure under
C<output_dir> (boolean, default 0).

=item C<base_dir>   -- base directory stripped when computing relative paths
for recursive mode (optional).

=back

=head3 Returns

Hashref: C<< { processed => N, successful => N, warnings => N, failed => N } >>.

=head3 Side Effects

Writes output files.  Prints a summary to STDERR.
Does not croak on per-file failures.

=head3 Usage Example

    $c->batch_convert(
        inputs     => [ glob('scores/**/*.nwc') ],
        output_dir => 'musicxml',
        recursive  => 1,
        base_dir   => 'scores',
        overwrite  => 1,
    );

=head3 API SPECIFICATION

=head4 Input

    inputs     : ARRAYREF of SCALAR paths (required)
    output_dir : SCALAR (optional)
    overwrite  : SCALAR bool (optional, default 0)
    recursive  : SCALAR bool (optional, default 0)
    base_dir   : SCALAR (optional)

=head4 Output

    HASHREF { processed:int, successful:int, warnings:int, failed:int }

=cut

=head2 diagnostics

Return the C<Music::NWC2MusicXML::Diagnostics> instance.

=cut