NAME

Class::Phrasebook - Implements the Phrasebook pattern

SYNOPSIS

  use Class::Phrasebook;
  my $pb = new Class::Phrasebook($log, "test.xml");
  $pb->load("NL"); # using Dutch as the language
  $phrase = $pb->get("ADDRESS", 
		     { street => "Chaim Levanon",
		       number => 88,
		       city   => "Tel Aviv" } );

DESCRIPTION

This class implements the Phrasebook pattern. It lets us create dictionaries of phrases. Each phrase can be accessed by a unique key. Each phrase may have placeholders. Group of phrases are kept in a dictionary. The first dictionary is the default one - which means that it will always be read. One of the dictionaries might be used to override the default one. The phrases are kept in an XML document.

The XML document type definition is as followed:

 <?xml version="1.0"?>
 <!DOCTYPE phrasebook [
	       <!ELEMENT phrasebook (dictionary)*>              
	       <!ELEMENT dictionary (phrase)*>
               <!ATTLIST dictionary name CDATA #REQUIRED>
               <!ELEMENT phrase (#PCDATA)>
               <!ATTLIST phrase name CDATA #REQUIRED>
 ]>

Example for XML file:

 <?xml version="1.0"?>
 <!DOCTYPE phrasebook [
	       <!ELEMENT phrasebook (dictionary)*>              
	       <!ELEMENT dictionary (phrase)*>
               <!ATTLIST dictionary name CDATA #REQUIRED>
               <!ELEMENT phrase (#PCDATA)>
               <!ATTLIST phrase name CDATA #REQUIRED>
 ]>
 <phrasebook>
 <dictionary name="EN">

 <phrase name="HELLO_WORLD">
            Hello World!!!
 </phrase>

 <phrase name="THE_HOUR">
            The time now is $hour. 
 </phrase>

 <phrase name="ADDITION">
            add $a and $b and you get $c
 </phrase>


 <!-- my name is the same in English Dutch and French. -->
 <phrase name="THE_AUTHOR">
            Rani Pinchuk
 </phrase>
 </dictionary>

 <dictionary name="FR">
 <phrase name="HELLO_WORLD">
            Bonjour le Monde!!!
 </phrase>

 <phrase name="THE_HOUR">
            Il est maintenant $hour. 
 </phrase>

 <phrase name="ADDITION">
            $a + $b = $c
 </phrase>

 </dictionary>

 <dictionary name="NL">
 <phrase name="HELLO_WORLD">
            Hallo Werld!!!
 </phrase>

 <phrase name="THE_HOUR">
            Het is nu $hour. 
 </phrase>

 <phrase name="ADDITION">
            $a + $b = $c
 </phrase>

 </dictionary>

 </phrasebook>

Each phrase should have a unique name. Within the phrase text we can place placeholders. When get method is called, those placeholders will be replaced by their value.

CONSTRUCTOR

new ( [ LOG ], FILEPATH )

The constructor. FILEPATH can be the absolute path of the XML file. But it can be also just a name of the file, or relative path to the file. In that case, that file will be searched in the following places: * The current directory. * The directory ./lib in the current directory. * The directory ../lib in the current directory. * The directories that are in @INC.

LOG is a Log object. If LOG is undef, NullLog object will be used. If it is provided, the class will use the Log facilities to log unusual events. Returns the new object, or undef on failure.

METHODS

load( DICTIONARY_NAME )

Will load the phrases of certain dictionary from the file. If the dictionary that is requested is not the first one (in the XML file), the first dictionary will be loaded first, and then the requested dictionary phrases will be loaded. That way, the first dictionary play the role of the default dictionary.

The DICTIONARY_NAME data member will be set to the parameter that is sent to this method. Yet, if nothing is sent to the method, the method will use the value of the DICTIONARY_NAME data member to load the right dictionary. If the data member is not defined as well, the default dictionary will be loaded.

Returns 1 on success, 0 on failure.

get(KEY [, REFERENCE_TO_ANONYMOUS_HASH ]) Will return the phrase that fits to the KEY. If a reference to anonymous has is sent, it will be used to define the parameters in the phrase.

dictionary_name( DICTIONARY_NAME )

Access method to the DICTIONARY_NAME data member. See load method above.

remove_new_lines ( BOOLEAN )

Access method to the data member REMOVE_NEW_LINES flag. If this data member is true (1), then new lines will be removed from the phrase that a is returned by the method get. Returns the value of the data member REMOVE_NEW_LINES flag.

ACCESS METHODS

get_xml_path ( FILE )

Will return the path of the xml file with that name. It will look for this file in the current directory, in ./lib ../lib and in all the directories in @INC. If it is not found, NULL will be returned.

file_path( FILEPATH )

Access method to the FILE_PATH data member. FILEPATH can be the absolute path of the XML file. But it can be also just a name of the file, or relative path to the file. In that case, that file will be searched in the following places: * The current directory. * The directory ./lib below the current directory. * The directory ../lib below the current directory. * The directories that are in @INC.

log( LOG )

Access method to the LOG data member.

ENVIRONMENTS

PHRASEBOOK_DEBUG_PRINTS

If this environment is set to "COLOR", the get method will print the phrases it gets, with some extra information in color screen output using ANSI escape sequences. If the environment is set to "HTML", the information will be printed in HTML format. If the environment is set to "TEXT" - the information will be printed as simple text. If the environment is not set, or empty - nothing will be printed. This feature comes to help debugging the phrases that we get from the object of this class.

AUTHOR

Rani Pinchuk, rani@cpan.org

COPYRIGHT

Copyright (c) 2001 EM-TECH (www.em-tech.net) & Rani Pinchuk. All rights reserved. This package is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

XML::Parser(3), Log::LogLite(3), Log::NullLogLite(3), The Phrasebook Pattern - Yonat Sharon & Rani Pinchuk - PLoP2K - http://jerry.cs.uiuc.edu/~plop/plop2k/proceedings/Pinchuk/Pinchuk.pdf