NAME

SMS::Ringtone::RTTTL::Parser - parse and validate RTTTL strings.

SYNOPSIS

use SMS::Ringtone::RTTTL::Parser;

my $rtttl = 'Flntstn:d=4,o=5,b=200:g#,c#,8p,c#6,8a#,g#,c#,' .
            '8p,g#,8f#,8f,8f,8f#,8g#,c#,d#,2f,2p,g#,c#,8p,' .
            'c#6,8a#,g#,c#,8p,g#,8f#,8f,8f,8f#,8g#,c#,d#,2c#';

my $r = new SMS::Ringtone::RTTTL::Parser($rtttl);
....or....
my $r = new SMS::Ringtone::RTTTL::Parser($rtttl,{'STRICT_NOTE_PART_ORDER' => 0});


# Check for errors
if ($r->has_errors()) {
 print "The following RTTTL errors were found:\n";
 foreach (@{$r->get_errors()}) {
  print "$_\n";
 }
 exit;
}

# Dump parse results to STDOUT
$r->puke();

DESCRIPTION

SMS::Ringtone::RTTTL::Parser is a RTTTL string parser and validator. See http://members.tripod.lycos.nl/jupp/linux/soft/rtttl_player/EBNF.txt for RTTTL syntax in BNF.

CLASS METHODS

new ($rtttl_string,$hash_ref_of_options)

Returns a new SMS::Ringtone::RTTTL::Parser object. The 1st parameter passed must be a a RTTTL string. The RTTTL string is parsed and validated by this constructor. The second parameter is optional and must be a hash ref. The only currently supported option is STRICT_NOTE_PART_ORDER of which the default value is true (1). Setting this option to false (0), will allow RTTTL::Parser to accept RTTTL strings in which the notes have a format of "<note> := [<duration>] <note> [<special-duration>] [<scale>] <delimiter>" instead of "<note> := [<duration>] <note> [<scale>] [<special-duration>] <delimiter>". This option was added because some RTTTL generators don't follow the smart messaging specifications strictly.

OBJECT METHODS

get_bpm()

Returns the effective BPM setting.

get_part_defaults()

Returns defaults part of RTTTL string.

get_part_name()

Returns name part of RTTTL string.

get_part_notes()

Returns notes part of RTTTL string.

get_errors()

Returns (a reference to) an array of parse errors. See has_errors.

get_note_count()

Returns number of notes in RTTTL string.

get_notes()

Returns (a reference to) an array of array references, each containing the 4 elements: duration, note, octave, dots.

duration is the effective note duration.
note is the note letter and optional sharp symbol (examples: F# C B P G#).
octave is the effective octave.
dots is the number of dots.

get_repeat()

Returns the effective repeat length setting.

get_rtttl()

Recontructs and returns an optimized version of the RTTTL string.

get_style()

Returns the effective style setting.

get_volume()

Returns the effective volume setting.

get_warnings()

Returns (a reference to) an array of parse warnings. See has_warnings.

has_errors()

Returns 0 if no parsing errors occured, else the number of errors. See get_errors.

has_warnings()

Returns 0 if no parsing warnings occured, else the number of warnings. Warnings occur whenever a RTTTL string does not strictly follow the RTTTL syntax specifications, but nevertheless is likely to be parseable by a SMS gateway or mobile phone. Warnings often occur due to incorrect BPM settings or name lengths that exceed 10 characters. See get_warnings.

is_name_valid()

Indicates if name part of RTTTL string is valid.

is_defaults_valid()

Indicates if defaults part of RTTTL string is valid.

is_notes_valid()

Indicates if notes part of RTTTL string is valid.

puke()

Dumps parse results to STDOUT. Useful for debugging.

FUNCTIONS

These are subroutines that aren't methods and don't affect anything (i.e., don't have ``side effects'') -- they just take input and/or give output.

is_valid_bpm($bpm)

Returns a boolean indicating if the $bpm parameter is a valid RTTTL BPM value.

is_valid_duration($dur)

Returns a boolean indicating if the $dur parameter is a valid RTTTL duration value.

is_valid_octave($octave)

Returns a boolean indicating if the $octave parameter is a valid RTTTL octave value.

is_valid_repeat($len)

Returns a boolean indicating if the $len parameter is a valid RTTTL repeat length value.

is_valid_volume($volume)

Returns a boolean indicating if the $volume parameter is a valid RTTTL volume value.

nearest_bpm($bpm)

Returns the nearest valid RTTTL BPM setting to the parameter $bpm.

nearest_duration($dur)

Returns the nearest valid RTTTL duration setting to the parameter $dur.

nearest_octave($octave)

Returns the nearest valid RTTTL octave setting to the parameter $octave.

HISTORY

Version 0.01 2001-11-03

Initial version.

Version 0.02 2001-11-05

Fixed minor bugs in error messages.

Version 0.03 2001-11-06

get_rtttl() now returns RTTTL with valid defaults part if original RTTTL defaults part contains invalid values. Name part is also limited to length of 20 characters.

Version 0.04 2001-12-26

Maximum name length is now 15 instead of 10. Larger lengths only create warnings and not errors. Added support for RTTTL 1.1. Added get_repeat(), get_style(), and get_volume() methods. Notes parsing follows specs more strictly. get_rtttl() now returns a reconstructed and optimized RTTTL string.

Version 0.05 2002-01-02

Fixed CRLF bug in test script. Warnings about whitespace in defaults section removed. Any whitespace found there or in notes section now results in an error.

Version 0.06 2002-03-21

Patched by Igor Ivoilov. Added support for new() constructor option STRICT_NOTE_PART_ORDER because there are a lot of RTTTL generators that generate rtttl that doesn't strictly follow the specification but have a note form like: <note> := [<duration>] <note> [<special-duration>] [<scale>] <delimiter> instead of: <note> := [<duration>] <note> [<scale>] [<special-duration>] <delimiter>

Version 0.07 2002-08-01

Fixed length($4) check in _parse_notes() so that undefined values don't emmit warnings anymore.

AUTHOR

Craig Manley	c.manley@skybound.nl

ACKNOWLEDGMENTS

Thanks to the following for finding bugs and/or offering suggestions:

Igor Ivoilov	igor@francoudi.com

COPYRIGHT

Copyright (C) 2001 Craig Manley <c.manley@skybound.nl>. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.