Data::Phrasebook(3pm)					User Contributed Perl Documentation				     Data::Phrasebook(3pm)

NAME

       Data::Phrasebook - Abstract your queries!

ABSTRACT

       A collection of modules for accessing phrasebooks from various data sources.

SYNOPSIS

	   use Data::Phrasebook;

	   my $q = Data::Phrasebook->new(
	       class  => 'Plain',
	       loader => 'Text',
	       file   => 'phrases.txt',
	   );

	   # simple keyword to phrase mapping
	   my $phrase = $q->fetch($keyword);

	   # keyword to phrase mapping with parameters
	   $q->delimiters( qr{ [% s* (w+) s* %] }x );
	   my $phrase = $q->fetch($keyword,{this => 'that'});

DESCRIPTION

       Data::Phrasebook is a collection of modules for accessing phrasebooks from various data sources.

PHRASEBOOKS

       To explain what phrasebooks are it is worth reading Rani Pinchuk's (author of Class::Phrasebook) article on Perl.com:

       <http://www.perl.com/pub/a/2002/10/22/phrasebook.html>

       Common uses of phrasebooks are in handling error codes, accessing databases via SQL queries and written language phrases. Examples are the
       mime.types file and the hosts file, both of which use a simple phrasebook design.

       Unfortunately Class::Phrasebook is a complete work and not a true class based framework. If you can't install XML libraries, you cannot use
       it.  This distribution is a collaboration between Iain Truskett and myself to create an extendable and class based framework for
       implementing phrasebooks.

CLASSES

       In creating a phrasebook object, a class type is required. This class defines the nature of the phrasebook or the behaviours associated
       with it. Currently there are two classes, Plain and SQL.

       The Plain class is the default class, and allows retrieval of phrases via the fetch() method. The fetch() simply returns the phrase that
       maps to the given keyword.

       The SQL class allows specific database handling. Phrases are retrieved via the query() method. The query() method internally retrieves the
       SQL phrase, then returns the statement handler object, which the user can then perform a prepare/execute/fetch/finish sequence on. For more
       details see Data::Phrasebook::SQL.

CONSTRUCTOR

   new
       The arguments to new depend upon the exact class you're creating.

       The default class is "Plain" and only requires the Loader arguments. The "SQL" class requires a database handle as well as the Loader
       arguments.

       The "class" argument defines the object class of the phrasebook and the behaviours that can be associated with it. Using "Foobar" as a fake
       class, the class module is searched for in the following order:

       1.  If you've subclassed "Data::Phrasebook", for example as "Dictionary", then "Dictionary::Foobar" is tried.

       2.  If that failed, "Data::Phrasebook::Foobar" is tried.

       3.  If that failed, "Foobar" is tried.

       4.  If all the above failed, we croak.

       This should allow you some flexibility in what sort of classes you use while not having you type too much.

       For other parameters, see the specific class you wish to instantiate.  The class argument is removed from the arguments list and the "new"
       method of the specified class is called with the remaining arguments.

DELIMITERS

       Delimiters allow for variable substitution in the phrase. The default style is ':variable', which would be passed as:

	   $q->delimiters( qr{ :(w+) }x );

       As an alternative, a Template Toolkit style would be passed as:

	   $q->delimiters( qr{ [% s* (w+) s* %] }x );

DICTIONARIES

   Simple Dictionaries
       Data::Phrasebook supports the use of dictionaries. See the specific Loader module to see how to implement the dictionary within your
       phrasebook. Using Data::Phrasebook::Loader::Ini as an example, the dictionary might be laid out as:

	 [Stuff]
	 language=Perl
	 platform=Linux

	 [Nonsense]
	 platform=Windows

       The phrasebook object is then created and used as:

	 my $q = Data::Phrasebook->new(
	   class  => 'Plain',
	   loader => 'Ini',
	   file   => 'phrases.ini',
	   dict   => 'Nonsense',
	 );

	 my $language = $q->fetch('language'); # retrieves 'Perl'
	 my $platform = $q->fetch('platform'); # retrieves 'Windows'

       The former is from the default (first) dictionary, and the second is from the named dictionary ('Nonsense'). If a phrase is not found in
       the named dictionary an attempt is made to find it in the default dictionary. Otherwise undef will be returned.

       Once a dictionary or file is specified, changing either requires reloading. As this is done at the loader stage, we need to let it know
       what it needs to reload. This can be done with the either (or both) of the following:

	 $q->file('phrases2.ini');
	 $q->dict('Stuff');

       A subsequent fetch() will then reload the file and dictionary, before retrieving the phrase required. However, a reload only takes place if
       both the file and the dictionary passed are not the ones currently loaded.

   Multiple Dictionaries
       As of version 0.25, the ability to provide prescendence over multiple dictionaries for the same phrasebook. Using
       Data::Phrasebook::Loader::Ini again as an example, the phrasebook might be laid out as:

	 [AndTheOther]
	 language=Perl
	 platform=Linux
	 network=LAN

	 [That]
	 platform=Solaris
	 network=WLAN

	 [This]
	 platform=Windows

       The phrasebook object is then created and used as:

	 my $q = Data::Phrasebook->new(
	   class  => 'Plain',
	   loader => 'Ini',
	   file   => 'phrases.ini',
	   dict   => ['This','That','AndTheOther'],
	 );

	 my $language = $q->fetch('language'); # retrieves 'Perl'
	 my $platform = $q->fetch('platform'); # retrieves 'Windows'
	 my $network  = $q->fetch('nework');   # retrieves 'WLAN'

       The first dictionary, if not specified and supported by the Loader module, is still used as the default dictionary.

       The dictionaries can be specified, or reordered, using the object method:

	 $q->dict('That','AndTheOther','This');

       A subsequent reload will occur with the next fetch call.

DEDICATION

       Much of the original class framework work is from Iain's original code. My code was a lot simpler and was tied to using just an INI data
       source. Merging all the ideas and code together we came up with this distribution.

       Unfortunately Iain died in December 2003, so he never got to see or play with the final working version. I can only thank him for his
       thoughts and ideas in getting this distribution into a state worthy of release.

	 Iain Campbell Truskett (16.07.1979 - 29.12.2003)

SEE ALSO

       Data::Phrasebook::Plain, Data::Phrasebook::SQL, Data::Phrasebook::SQL::Query, Data::Phrasebook::Debug, Data::Phrasebook::Generic,
       Data::Phrasebook::Loader, Data::Phrasebook::Loader::Text, Data::Phrasebook::Loader::Base.

SUPPORT

       Please see the README file.

DSLIP

	 b - Beta testing
	 d - Developer
	 p - Perl-only
	 O - Object oriented
	 p - Standard-Perl: user may choose between GPL and Artistic

AUTHOR

	 Original author: Iain Campbell Truskett (16.07.1979 - 29.12.2003)
	 Maintainer: Barbie <barbie@cpan.org> since January 2004.
	 for Miss Barbell Productions <http://www.missbarbell.co.uk>.

COPYRIGHT AND LICENSE

	 Copyright (C) 2003 Iain Truskett.
	 Copyright (C) 2004-2010 Barbie for Miss Barbell Productions.

	 This module is free software; you can redistribute it and/or
	 modify it under the Artistic Licence v2.

perl v5.10.1							    2010-10-15						     Data::Phrasebook(3pm)