File Coverage

=head1 NAME

Music::NWC2MusicXML::NWC - Binary NWC container decoder.

=head1 VERSION

0.001.1

=head1 SYNOPSIS

    use Music::NWC2MusicXML::NWC;

    # From a file
    my $nwctxt = Music::NWC2MusicXML::NWC->read('Pilgrim.nwc');

    # From an in-memory buffer (e.g. read from a database blob)
    my $nwctxt = Music::NWC2MusicXML::NWC->decode($binary_data);

    print $nwctxt;   # prints the NWCTXT representation

=head1 DESCRIPTION

Converts a NoteWorthy Composer 2 binary C<.nwc> file into its NWCTXT text
representation.  The NWCTXT string is then passed to
C<Music::NWC2MusicXML::Parser>.

The conversion pipeline implemented here is:

    NWC binary container
          |
          v  (verify magic + locate zlib stream)
    compressed score data
          |
          v  (Compress::Zlib inflate)
    raw decompressed bytes
          |
          v  (locate !NoteWorthyComposer( marker)
    NWCTXT representation (UTF-8 string)

No NoteWorthy Composer installation is required.

=cut

=head2 new

Construct a decoder object.  Optionally binds diagnostic output to a
C<Music::NWC2MusicXML::Diagnostics> instance.

=head3 Arguments

Named parameters:

=over 4

=item C<diagnostics> -- a C<Music::NWC2MusicXML::Diagnostics> instance (optional).

=back

=head3 Returns

Blessed C<Music::NWC2MusicXML::NWC> object.

=head3 API SPECIFICATION

=head4 Input

    diagnostics : Music::NWC2MusicXML::Diagnostics  (optional)

=head4 Output

    Music::NWC2MusicXML::NWC object

=cut

=head2 read

Read a C<.nwc> binary file from disk and return its NWCTXT representation.

Can be called as a class method (C<< Music::NWC2MusicXML::NWC->read($file) >>)
or as an instance method.

=head3 Purpose

Encapsulates file-I/O so that C<decode> can be tested independently with
in-memory data.

=head3 Arguments

=over 4

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

=back

=head3 Returns

Scalar string containing the NWCTXT representation (UTF-8).

=head3 Side Effects

Reads from disk.  Croaks on any I/O or format error.

=head3 Usage Example

    my $nwctxt = Music::NWC2MusicXML::NWC->read('Pilgrim.nwc');

=head3 API SPECIFICATION

=head4 Input

    $filename : SCALAR  path (required)
                  -- Valid domain: defined, non-empty string naming a regular,
                  --   readable file in NWC 2.x binary format
                  -- Invalid partitions: undef, '' (empty), directory, non-existent,
                  --   unreadable, or wrong format -> all croak error_not_a_file
                  --   or error_not_nwc / error_truncated depending on failure point

=head4 Output

    SCALAR (UTF-8 string)

=head3 MESSAGES

| Code                | Meaning                             | Resolution                     |
|---------------------|-------------------------------------|--------------------------------|
| error_not_a_file    | File cannot be opened               | Check path and permissions     |
| error_not_nwc       | File does not begin with NWC magic  | Verify file is a real .nwc     |
| error_truncated     | File too short to be valid          | File may be corrupt            |

=cut

=head2 decode

Decode a binary NWC payload (already loaded into a scalar) and return its
NWCTXT representation.

Can be called as a class method or instance method.

Separates decompression logic from file I/O; enables unit testing with
in-memory test vectors.

=head3 Arguments

=over 4

=item C<$data>     -- binary scalar containing the full file content (required).

=item C<$filename> -- source filename for diagnostic messages (optional, default C<< <buffer> >>).

=back

=head3 Returns

Scalar string containing the NWCTXT representation (UTF-8).

=head3 Side Effects

None (no I/O).  Croaks on any format or decompression error.

=head3 Usage Example

    my $nwctxt = Music::NWC2MusicXML::NWC->decode($binary_blob);

=head3 API SPECIFICATION

=head4 Input

    $data     : SCALAR (binary, required)
                  -- Valid domain: length >= MIN_FILE_BYTES (9 bytes)
                  --   Minimum: 5-byte magic '[NWZ]' + 4 bytes = 9 bytes (MIN_FILE_BYTES)
                  --   Below min (length 0..8): croaks error_truncated
                  --   At min (length 9) with wrong magic: croaks error_not_nwc
                  --   MAX decompressed size: 268,435,456 bytes (MAX_DECOMP_BYTES = 256 MB)
    $filename : SCALAR (optional, default '<buffer>')
                  -- Any string; used only in diagnostic messages

=head4 Output

    SCALAR (UTF-8 string)

=head3 MESSAGES

| Code                   | Meaning                                 | Resolution                        |
|------------------------|-----------------------------------------|-----------------------------------|
| error_not_nwc          | Magic signature absent                  | Confirm file is an NWC 2.x binary |
| error_truncated        | Data too short                          | File may be truncated             |
| error_no_zlib_stream   | zlib stream not found in binary         | File may be corrupt               |
| error_decompress_fail  | zlib inflation failed                   | Payload is corrupt                |
| error_decomp_too_large | Decompressed size exceeds safety limit  | Reject; may be a zip bomb         |
| error_no_nwctxt_marker | NWCTXT marker absent after decompression| File structure unexpected         |
| error_bad_utf8         | Decompressed text is not valid UTF-8    | NWC file may use a legacy encoding|

=cut