Craig Manley > SMS-Ringtone-RTTTL-Parser-0.07 > SMS::Ringtone::RTTTL::Parser

Download:
SMS-Ringtone-RTTTL-Parser-0.07.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.07   Source  

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.

syntax highlighting: