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);

# 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)

Returns a new SMS::Ringtone::RTTTL::Parser object. The only parameter passed must be a a RTTTL string. The RTTTL string is parsed and validated by this constructor.

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.

AUTHOR

Craig Manley c.manley@skybound.nl

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.