NAME
Music::NWC2MusicXML::NWC - Binary NWC container decoder.
VERSION
0.001.0
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 representationDESCRIPTION
Converts a NoteWorthy Composer 2 binary .nwc file into its NWCTXT text representation. The NWCTXT string is then passed to 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.
new
Construct a decoder object. Optionally binds diagnostic output to a Music::NWC2MusicXML::Diagnostics instance.
Arguments
Named parameters:
Returns
Blessed Music::NWC2MusicXML::NWC object.
API SPECIFICATION
Input
diagnostics : Music::NWC2MusicXML::Diagnostics (optional)Output
Music::NWC2MusicXML::NWC objectread
Read a .nwc binary file from disk and return its NWCTXT representation.
Can be called as a class method (Music::NWC2MusicXML::NWC->read($file)) or as an instance method.
Purpose
Encapsulates file-I/O so that decode can be tested independently with in-memory data.
Arguments
Returns
Scalar string containing the NWCTXT representation (UTF-8).
Side Effects
Reads from disk. Croaks on any I/O or format error.
Usage Example
my $nwctxt = Music::NWC2MusicXML::NWC->read('Pilgrim.nwc');API SPECIFICATION
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 pointOutput
SCALAR (UTF-8 string)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 |
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.
Arguments
$data-- binary scalar containing the full file content (required).$filename-- source filename for diagnostic messages (optional, default<buffer>).
Returns
Scalar string containing the NWCTXT representation (UTF-8).
Side Effects
None (no I/O). Croaks on any format or decompression error.
Usage Example
my $nwctxt = Music::NWC2MusicXML::NWC->decode($binary_blob);API SPECIFICATION
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 messagesOutput
SCALAR (UTF-8 string)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|
DIAGNOSTICS
MESSAGES
| Code | Meaning | Resolution | |------------------------|----------------------------------------|-----------------------------------| | error_not_a_file | Cannot open/read input file | Check path and permissions | | error_not_nwc | Magic signature absent | Confirm file is NWC 2.x | | error_truncated | File too short | File may be corrupt or incomplete | | error_no_zlib_stream | No valid zlib header found | Binary may be from unknown version| | error_decompress_fail | zlib inflate failed | Payload corrupt | | error_decomp_too_large | Decompressed size exceeds 256 MB | Possible zip-bomb; reject | | error_no_nwctxt_marker | NWCTXT marker absent | Unexpected binary structure | | error_bad_utf8 | Text not valid UTF-8 | Latin-1 fallback applied |
LIMITATIONS
Only NWC 2.x binary format (
[NWZ]magic) is supported. NWC 1.x files use a different structure and will be rejected.Files larger than 256 MB when decompressed will be rejected for safety. Legitimate scores should not approach this limit.
Latin-1 fallback for non-UTF-8 NWCTXT is a best-effort heuristic.
FORMAL SPECIFICATION
new
[NWCDecoderInit]
diagnostics : Diagnostics
(placeholder -- populate with Z calculus as implementation matures)read
[ReadFile]
filename? : FileName
----------
result! : NWCTXT
(placeholder)decode
[Decode]
data? : BinaryData
filename? : FileName
----------
nwctxt! : NWCTXT
(placeholder)AUTHOR
Nigel Horne <njh@nigelhorne.com>
LICENSE
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.