NAME

Music::NWC2MusicXML::Parser - NWCTXT text parser producing an internal score representation.

VERSION

0.003.0

SYNOPSIS

use Music::NWC2MusicXML::Parser;

my $parser = Music::NWC2MusicXML::Parser->new;
my $score  = $parser->parse($nwctxt);

DESCRIPTION

Music::NWC2MusicXML::Parser accepts the NWCTXT string produced by Music::NWC2MusicXML::NWC and returns a Music::NWC2MusicXML::Score object.

The internal representation is completely independent of MusicXML so that parsing and MusicXML generation can be tested separately.

NWCTXT record structure

Each record occupies one line and begins with |:

|RecordType|Field1:Value1|Field2:Value2|...

Fields are pipe-delimited. Values may be:

  • unquoted single tokens

  • double-quoted strings (which may contain | and :)

  • comma-separated lists

The parser does not use split(/[|]/) because quoted values and escape sequences require a proper tokeniser.

Record type aliases: some NWC versions export DynamicVariance where others write the abbreviated DynVariance; the parser accepts both and emits the same DynVariance event in either case.

Text event placement: Text records carry an optional Placement: field. When it is absent the vertical position is inferred from the Pos: field: a non-negative Pos value sets placement to 'Above'; a negative value sets it to 'Below'. This handles common NWC files where performance directions such as "Slightly faster" are positioned above the staff via a positive Pos number with no explicit Placement: field.

EndingBar normalisation: NWC StaffProperties stores the ending barline style as a multi-word string (e.g. "Section Close"). The parser strips internal spaces on ingestion so the value matches the compact style tokens used by Music::NWC2MusicXML::MusicXML (e.g. 'SectionClose'). When NWC emits two StaffProperties records for a staff (the second carrying channel and volume data), only the record that actually contains an EndingBar: field updates _ending_bar; the second record is not allowed to clobber the value set by the first.

new

Construct a parser.

Arguments

Named parameters:

diagnostics -- a Music::NWC2MusicXML::Diagnostics instance (optional).

Returns

Blessed Music::NWC2MusicXML::Parser object.

API SPECIFICATION

Input

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

Output

Music::NWC2MusicXML::Parser object

FORMAL SPECIFICATION

[ParserInit]
  diagnostics : Diagnostics

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

parse

Parse a complete NWCTXT string and return the corresponding Music::NWC2MusicXML::Score.

Purpose

This is the primary entry point. It iterates over each line of the NWCTXT, dispatches to a type-specific handler, and accumulates the results into a Score object.

Arguments

$nwctxt -- scalar string containing the full NWCTXT representation (required).

Returns

A Music::NWC2MusicXML::Score object.

Side Effects

Croaks on fatal structural errors (e.g. missing header). Issues warnings via diagnostics for non-fatal issues (e.g. unknown records).

Usage Example

my $score = Music::NWC2MusicXML::Parser->new->parse($nwctxt);

API SPECIFICATION

Input

$nwctxt : SCALAR (UTF-8, required)
            -- Valid domain: non-empty string beginning with the line
            --   '!NoteWorthyComposer(<version>)' followed by pipe-delimited records
            -- Invalid partitions:
            --   undef or '' -> croaks error_empty_input
            --   non-empty but missing header -> croaks error_no_header
            -- Boundary: MAX_RECORDS = 1,000,000 pipe-delimited records
            --   At exactly 1,000,000 records: accepted
            --   At 1,000,001+ records: croaks error_too_many_records

Output

Music::NWC2MusicXML::Score

MESSAGES

| Code | Meaning | Resolution | |-----------------------|------------------------------------------|-------------------------------| | error_empty_input | Input is undef or zero-length | Check NWC decoder output | | error_no_header | Header line not found | Verify NWC binary decoder | | error_too_many_records| Record count exceeds MAX_RECORDS | Input may be malicious/corrupt| | error_bad_record | Record cannot be tokenised | File may be corrupt | | error_no_staff | Event seen before first AddStaff | NWCTXT may be truncated | | warn_unknown_record | Unknown record type stored as Unsupported| New NWC version may add types |

FORMAL SPECIFICATION

[Parse]
  nwctxt? : NWCTXT
  ----------
  score!  : Score

(placeholder)

DIAGNOSTICS

MESSAGES

| Code | Meaning | Resolution | |------------------------|------------------------------------------|-----------------------------------| | error_empty_input | NWCTXT string is empty or undef | Check NWC decoder | | error_no_header | Header line absent | Verify NWCTXT output from decoder | | error_too_many_records | Record count exceeds MAX_RECORDS (1M) | Probable corrupt input | | error_bad_record | Record fails tokenisation | File may be corrupt | | error_no_staff | Musical event before any AddStaff | NWCTXT may be truncated | | warn_unknown_record | Unknown record type | New NWC version; file as UnsupportedEvent | | warn_bad_value | Field value not in recognised set | NWC file may use newer syntax |

LIMITATIONS

  • Note and Rest pitch/duration sub-field parsing is stubbed (Phase 2).

  • Tuplet time-modification is not yet applied to affected events (Phase 4).

  • The parser does not yet validate measure duration totals (Phase 3 / --validate).

  • Multi-voice detection within a single staff is deferred to the MusicXML generator.

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.