Perl API

The facade is deliberately small: build one converter and use it for as many scores as you have. The stages underneath it are public too, and can be driven one at a time when something needs inspecting between them.

A complete program

use strict;
use warnings;

use Music::NWC2MusicXML;

my $converter = Music::NWC2MusicXML->new(log_level => 'normal');

for my $input (@ARGV) {
	my $out = $converter->convert(input => $input, overwrite => 1);
	if (defined $out) {
		print "converted $input -> $out\n";
	} else {
		warn "could not convert $input\n";
	}
}

exit($converter->diagnostics->has_warnings ? 1 : 0);

new

Builds a converter and the decoder, parser and generator it will use, so they are constructed once rather than per file.

my $c = Music::NWC2MusicXML->new(log_level => 'verbose', validate => 1);

Returns the blessed converter. It emits no messages of its own.

convert

The single-file entry point: decode, parse, generate, write. Fatal problems croak; everything that can be survived is a warning and the conversion continues.

my $out = $c->convert(
	input     => 'Pilgrim.nwc',
	output    => 'out/Pilgrim.musicxml',
	overwrite => 1,
);

Returns the output path on success and undef on failure, with the reason on the diagnostics object. It writes the output file and updates the diagnostic counters as side effects.

batch_convert

Converts a list of files in sequence. A file that fails is caught and counted; the rest of the list is still converted, and a summary is printed at the end.

my $counts = $c->batch_convert(
	inputs     => [ glob('scores/**/*.nwc') ],
	output_dir => 'musicxml',
	recursive  => 1,
	base_dir   => 'scores',
	overwrite  => 1,
);

# { processed => 12, successful => 11, warnings => 3, failed => 1 }
printf "%d of %d converted, %d failed\n",
	$counts->{successful}, $counts->{processed}, $counts->{failed};

Returns a hash reference of counts: processed, successful, warnings and failed. It does not croak because one score was bad.

diagnostics

Returns the Music::NWC2MusicXML::Diagnostics object the converter has been using. It carries the warning count, and every message the pipeline produces goes through its catalogue, so warnings read the same way whether they came from the decoder, the parser or the generator.

my $diag = $c->diagnostics;
if ($diag->has_warnings) {
	print "converted with warnings\n";
}

Class-level defaults

The converter uses Object::Configure, so defaults can be set once for the whole process instead of being repeated at each new:

use Music::NWC2MusicXML;

Music::NWC2MusicXML->configure(log_level => 'verbose');

my $c = Music::NWC2MusicXML->new;   # already verbose

That is convenient in a long-running program, and worth knowing about in one that is not yours: a module or a configuration file that has called configure changes the behaviour of every later new. An explicit argument still wins.

The stages on their own

The facade chains three objects, and nothing stops you chaining them yourself. That is how a score can be inspected between decoding and generation — and it is what the golden-file regression test does:

use Music::NWC2MusicXML::NWC;
use Music::NWC2MusicXML::Parser;
use Music::NWC2MusicXML::MusicXML;

my $score = Music::NWC2MusicXML::Parser->new->parse(
	Music::NWC2MusicXML::NWC->read('t/input/my_score.nwc')
);

my $xml = Music::NWC2MusicXML::MusicXML->new->generate($score);

open my $fh, '>', 't/input/my_score.musicxml' or die $!;
print {$fh} $xml;
close $fh;

The score model is plain data with accessors, so a program that needs to know what a file contains — the staves, their instruments, the number of measures — can stop after parsing and ask, without producing XML at all.