NAME

Music::LilyPond::Scale::Chromatic - methods to parse and alter LilyPond notes

SYNOPSIS

  my $note = Music::LilyPond::Scale::Chromatic->new('b');
  
  $note->transpose(1);
  my $value = $note->get_value;
  
  print $note->as_string;
  
  $note->invert();

DESCRIPTION

This module contains methods for parsing and applying musical operations such as transposition on notes parsed from the LilyPond notation.

The module will throw an error in various conditions. These should be caught with eval blocks if necessary.

CLASS METHODS

new optional note

Constructor method. Optionally accepts a string such as ces that represents a LilyPond note.

set_default_accidental accidental

Use this method to set a class-wide default on what accidental should be used for output. The accidental can be specified as es or is as is the default in LilyPond, or as sharp or flat.

By default, the sign (or sharp for neutral) of the original note will be used, so that notes that were sharp remain sharp, and flats remain flat, if necessary after transposition or inversion.

The default accidental setting (if any) is only considered during the as_string method call, and does not affect instance specific accidental calls for particular notes.

get_default_accidental

Returns the current class accidental setting, either -1 for flat, 0 for neutral, though sharps will be used if necessary, or 1 for sharp.

unset_default_accidental

Clears any custom accidental setting.

INSTANCE METHODS

Most instance methods, with the notable exception of the get_* and as_string, return the instance, allowing method call chains:

  $note->parse('c')->transpose(-6)->invert('d')->as_string;

as_string

Returns the note as a string value LilyPond expects, such as cis. The module tries to preserve sharps or flats from the original note should the note have been transposed or otherwise changed, though this behavior can be changed via a number of class or instance methods.

parse note

Parses a note like new, except that a note is required.

transpose degrees

Adjusts the note by the specified number of degrees (semitones):

  $note->parse('c');
  $note->transposition(1);  # note is now 'cis'
  $note->transposition(-6); # note is now 'g'

invert optional note axis

Inverts the note, by default via modulus math, or with a note axis supplied, mirrored around that note. Check eg/inversions under the module source for an illustration of how this works, as it may be different from inversions in Music Theory.

clone

Clones the object to create a new one.

get_accidental

Returns the accidental setting for the note: -1, 0, or 1 for flats, neutrals, or sharps, respectively.

set_accidental

Sets the accidental style for the note. The accidental can be specified as es or is as is the default in LilyPond, or as sharp or flat.

set_value

Sets the internal numeric value for the note. Does not specify the accidental of the note, so an accidental method call may be necessary if the note should be a flat:

  # hard way to say ->parse('des')
  $note->set_value(1)->set_accidental('flat');

get_value

Returns the internal numeric value for the note.

BUGS

No known bugs.

Reporting Bugs

Newer versions of this module may be available from CPAN.

If the bug is in the latest version, send a report to the author. Patches that fix problems or add new features are welcome.

Known Issues

Only the LilyPond note names and whether the note is flat or sharp is supported. Note durations or other ornaments are not supported. Check eg/transpose under the module source for a primitive lexer that can parse notes out of simple LilyPond files.

SEE ALSO

• http://www.lilypond.org/

• MIDI::Praxis::Variation

• The eg directory of this module distribution for sample scripts.

AUTHOR

Jeremy Mates, <jmates@sial.org>

COPYRIGHT

Copyright 2010 by Jeremy Mates.

This program is free software; you can redistribute it and/or modify it under the Artistic license.