/ 
Music-NWC2MusicXML-0.001.0
/ Music::NWC2MusicXML::Score

NAME

Music::NWC2MusicXML::Score - Internal representation of a complete NWC score.

VERSION

0.001.0

SYNOPSIS

use Music::NWC2MusicXML::Score;

my $score = Music::NWC2MusicXML::Score->new(
    metadata   => { Title => 'To a Pilgrim', Author => 'Trad, Arr Nigel Horne' },
    page_setup => { StaffSize => 16, Zoom => 3 },
);

$score->add_staff($staff_object);
my $staves = $score->staves;

DESCRIPTION

Music::NWC2MusicXML::Score is the root of the internal representation tree. It holds:

  • metadata -- SongInfo fields (Title, Author, Lyricist, Copyright, Comments).

  • page_setup -- PgSetup fields, retained but largely informational.

  • properties -- additional score-level NWC properties.

  • staves -- ordered list of Music::NWC2MusicXML::Staff objects.

This class is MusicXML-agnostic; it describes the musical content in NWC terms. The Music::NWC2MusicXML::MusicXML generator translates it to XML.

metadata

Return the metadata hashref.

Keys correspond to NWC SongInfo field names: Title, Author, Lyricist, Copyright, Comments.

Returns

Hashref.

page_setup

Return the page-setup hashref (NWC PgSetup fields).

properties

Return additional score-level properties hashref.

nwc_version

Return the NWC version string extracted from the NWCTXT header (e.g. 2.751), or undef if not available.

fonts

Return the arrayref of font descriptors parsed from NWC Font records. Each entry is a hashref with keys: style, typeface, size, bold, italic.

set_metadata_field

Set a single metadata field.

Arguments

$key -- field name (e.g. Title).
$value -- string value.

Returns

$self.

add_staff

Append a Music::NWC2MusicXML::Staff to the score's staff list.

Purpose

Called by the parser each time it encounters an AddStaff record; the staff object is populated with subsequent per-staff records and then stays in the list for MusicXML generation.

Arguments

$staff -- a blessed Music::NWC2MusicXML::Staff object (required).

Returns

$self (for chaining).

Side Effects

Appends to _staves.

Usage Example

$score->add_staff(
    Music::NWC2MusicXML::Staff->new(name => 'Violin I')
);

API SPECIFICATION

Input

$staff : Music::NWC2MusicXML::Staff (required)

Output

$self (Music::NWC2MusicXML::Score)

MESSAGES

| Code | Meaning | Resolution | |----------------|----------------------------------|------------------------------| | error_bad_staff| Argument is not a Staff object | Construct Staff before adding |

FORMAL SPECIFICATION

[AddStaff]
  DeltaScore
  staff? : Staff
  ---------
  staves' = staves ^ <staff?>

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

staves

Return an arrayref of all Music::NWC2MusicXML::Staff objects in score order.

Returns

Arrayref of Music::NWC2MusicXML::Staff.

API SPECIFICATION

Input

(none)

Output

ARRAYREF of Music::NWC2MusicXML::Staff

current_staff

Return the last staff appended (the one currently being populated by the parser), or undef if no staves have been added.

staff_count

Return the number of staves.

validate

Perform consistency checks on the score structure. Called when --validate is passed on the command line.

Purpose

Checks that every staff has at least one event, that tie/slur relationships are consistent, and that measure durations match the current time signature.

Returns

Arrayref of diagnostic strings (empty on success).

API SPECIFICATION

Input

(none)

Output

ARRAYREF of SCALAR (diagnostic messages)

FORMAL SPECIFICATION

[Validate]
  score : Score
  ---------
  forall s : staves @ valid_staff(s)

(placeholder)

DIAGNOSTICS

MESSAGES

| Code | Meaning | Resolution | |-----------------|--------------------------|------------------------------------| | error_bad_staff | Non-Staff passed to add | Construct a proper Staff first | | error_no_staves | Score has no staves | Ensure NWCTXT contains AddStaff |

LIMITATIONS

  • validate is a stub; full validation implemented in Phase 3.

  • Page-layout and graphical properties are stored but not used in MusicXML generation.

AUTHOR

Nigel Horne <nigel.horne@gmail.com>

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.