File Coverage

=head1 NAME

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

=head1 VERSION

0.002.4

=head1 SYNOPSIS

    use Music::NWC2MusicXML::Parser;

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

=head1 DESCRIPTION

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

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

=head2 NWCTXT record structure

Each record occupies one line and begins with C<|>:

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

Fields are pipe-delimited.  Values may be:

=over 4

=item * unquoted single tokens

=item * double-quoted strings (which may contain C<|> and C<:>)

=item * comma-separated lists

=back

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

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

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

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

=cut

=head2 new

Construct a parser.

=head3 Arguments

Named parameters:

=over 4

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

=back

=head3 Returns

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

=head3 API SPECIFICATION

=head4 Input

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

=head4 Output

    Music::NWC2MusicXML::Parser object

=head3 FORMAL SPECIFICATION

 [ParserInit]
   diagnostics : Diagnostics

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

=cut

=head2 parse

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

=head3 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.

=head3 Arguments

=over 4

=item C<$nwctxt> -- scalar string containing the full NWCTXT representation
(required).

=back

=head3 Returns

A C<Music::NWC2MusicXML::Score> object.

=head3 Side Effects

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

=head3 Usage Example

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

=head3 API SPECIFICATION

=head4 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

=head4 Output

    Music::NWC2MusicXML::Score

=head3 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 |

=head3 FORMAL SPECIFICATION

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

 (placeholder)

=cut