/ 
Class-Phrasebook-0.88
River stage one • 1 direct dependent • 1 total dependent
/ Class::Phrasebook

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.

The dictionaries that are loaded by object of this class, are cached in a class member. This means that if you use this class within other class, and you produce many objects of that other class, you will not have in memory many copies of the loaded dictionaries of those objects. Actually you will have one copy in memory for each dictionary that is loaded, no matter how many objects load it. This copy will be deleted when all the objects that refer to it go out of scope (like the Perl references). You can fix that any loaded dictionary will never go out of scope (till the process ends). You do that by calling the class method clean_out_of_scope_dictionaries with 0 as its argument.

Beside being happy with the fact that you can use the Class::Phrasebook within other objects without poluting the memory, you should know about one possible flow in that caching - if the dictionary is changed but its name and the name of the XML file that holds it remain the same, the new dictionary will not be loaded even if the load method is called.

Because it is not the intention to have this kind of situation (changing the dictionary while the program is already running), the one that is crazy enough to have this kind of need, invited to email the author, and a force_load method might be added to this class.

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.

CLASS METHODS

clean_out_of_scope_dictionaries( BOOLEAN )

This method takes one argument. If it is 1 (TRUE), dictionaries will be deleted from the cache when they go out of scope. If it is 0 (FALSE), the dictionaries will stay in the cache (till the program ends). The default behaviour is that the dictionaries are deleted when they go out of scope (so 1).

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 1 (TRUE), then new lines will be removed from the phrase that a is returned by the method get. Unset by default. Returns the value of the data member REMOVE_NEW_LINES flag.

as_is_between_tags ( BOOLEAN )

Access method to the data member AS_IS_BETWEEN_TAGS flag. Set by default. In the past releases, the class did not deal correctly with spaces and new lines. When this flag is unset, the class will continue in its old behavior. So if the new - correct - behavior breaks your code, you can go back to the old behavior. See also the environment variable PHRASEBOOK_AS_IS_BETWEEN_TAGS. Returns the value of the data member AS_IS_BETWEEN_TAGS 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.

PHRASEBOOK_AS_IS_BETWEEN_TAGS

This environment variable control the default setting of the data member AS_IS_BETWEEN_TAGS. If it is unset, that data member is 1 by default. See the method as_is_between_tags for more information.

AUTHOR

Rani Pinchuk, rani@cpan.org

COPYRIGHT

Copyright (c) 2001-2002 Ockham Technology N.V. & 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