Data-Phrasebook-0.34/0000755000175000017500000000000012150627201013632 5ustar barbiebarbieData-Phrasebook-0.34/README0000644000175000017500000000363112150627177014531 0ustar barbiebarbieData::Phrasebook ================ DESCRIPTION Abstract your queries! This distribution enables the framework for abstracting common or locale data out of your code into a datastore. The default is within a plain text file, but more complex datastores can be intrigrated via the use of other Data::Pharsebook::Loader distributions (eg YAML, XML, INI, DBI). DEPENDENCIES The distribution requires the following modules: Module::Pluggable >= 2.5 For debugging purposes, the following modules are required: Data::Dumper For testing purposes, the following modules are required: Test::More >= 0.47 For testing purposes, the following modules are desireable, but not essential: Test::Pod >= 1.00 Test::Pod::Coverage >= 0.08 Pod::Coverage Test::CPAN::Meta >= 0.12 INSTALLATION To install this module type the following: perl Makefile.PL make make test make install For more detailed installation instructions, see INSTALL. USAGE Read the pod documentation in the distrubtion files. CHANGES For a complete list of changes, see the Changes file. SUPPORT If you spot a bug or are experiencing difficulties that are not explained within the POD documentation, please send an email to barbie@cpan.org or submit a bug to the RT system (http://rt.cpan.org/). It would help greatly if you are able to pinpoint problems or even supply a patch. Fixes are dependent upon their severity and my availability. Should a fix not be forthcoming, please feel free to (politely) remind me. AUTHOR Original author: Iain Campbell Truskett (16.07.1979 - 29.12.2003) Maintainer: Barbie for Miss Barbell Productions http://www.missbarbell.co.uk. COPYRIGHT AND LICENSE Copyright (C) 2004-2013 Barbie for Miss Barbell Productions. Copyright (C) 2003 Iain Truskett. This distribution is free software; you can redistribute it and/or modify it under the Artistic Licence v2. Data-Phrasebook-0.34/lib/0000755000175000017500000000000012150627201014400 5ustar barbiebarbieData-Phrasebook-0.34/lib/Data/0000755000175000017500000000000012150627201015251 5ustar barbiebarbieData-Phrasebook-0.34/lib/Data/Phrasebook.pm0000644000175000017500000001747212150627177017733 0ustar barbiebarbiepackage Data::Phrasebook; use strict; use warnings FATAL => 'all'; use base qw( Data::Phrasebook::Debug ); use Carp qw( croak ); use vars qw($VERSION); $VERSION = '0.34'; =head1 NAME Data::Phrasebook - Abstract your queries! =head1 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'}); =head1 DESCRIPTION Data::Phrasebook is a collection of modules for accessing phrasebooks from various data sources. =head1 PHRASEBOOKS To explain what phrasebooks are it is worth reading Rani Pinchuk's (author of L) article on Perl.com: L 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. =head1 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. =head1 CONSTRUCTOR =head2 new The arguments to new depend upon the exact class you're creating. The default class is C and only requires the Loader arguments. The C class requires a database handle as well as the Loader arguments. The C argument defines the object class of the phrasebook and the behaviours that can be associated with it. Using C as a fake class, the class module is searched for in the following order: =over 4 =item 1 If you've subclassed C, for example as C, then C is tried. =item 2 If that failed, C is tried. =item 3 If B failed, C is tried. =item 4 If all the above failed, we croak. =back 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 C method of the specified class is called with the remaining arguments. =cut sub new { my $class = shift; my %args = @_; my $debug = delete $args{debug} || 0; $class->debug($debug); if($debug) { $class->store(3,"$class->new IN"); $class->store(4,"$class->new args=[".$class->dumper(\%args).']'); } my $sub = delete $args{class} || 'Plain'; if (eval "require ${class}::$sub") { $sub = $class."::$sub"; } elsif (eval "require Data::Phrasebook::$sub") { $sub = "Data::Phrasebook::$sub"; } elsif (eval "require $sub") { # it's a module by itself } else { croak "Could not find appropriate class for '$sub': [$@]"; } $class->store(4,"$class->new sub=[$sub]") if($class->debug); return $sub->new( %args ); } 1; __END__ =head1 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 ); =head1 DICTIONARIES =head2 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. =head2 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. =head1 DEDICATION Much of the code for the original class framework is from Iain's original code. My code was much 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) =head1 SEE ALSO L, L, L, L, L, L, L, L. =head1 SUPPORT Please see the README file. =head1 AUTHOR Original author: Iain Campbell Truskett (16.07.1979 - 29.12.2003) Maintainer: Barbie since January 2004. for Miss Barbell Productions . =head1 COPYRIGHT AND LICENSE Copyright (C) 2003 Iain Truskett. Copyright (C) 2004-2013 Barbie for Miss Barbell Productions. This distribution is free software; you can redistribute it and/or modify it under the Artistic License v2. =cut Data-Phrasebook-0.34/lib/Data/Phrasebook/0000755000175000017500000000000012150627201017346 5ustar barbiebarbieData-Phrasebook-0.34/lib/Data/Phrasebook/Plain.pm0000644000175000017500000000462112150627177020766 0ustar barbiebarbiepackage Data::Phrasebook::Plain; use strict; use warnings FATAL => 'all'; use base qw( Data::Phrasebook::Generic Data::Phrasebook::Debug ); use Carp qw( croak ); use vars qw($VERSION); $VERSION = '0.34'; =head1 NAME Data::Phrasebook::Plain - The Simple Phrasebook Model. =head1 SYNOPSIS use Data::Phrasebook; my $q = Data::Phrasebook->new( class => 'Plain', loader => 'Text', file => 'phrases.txt', ); my $r = Data::Phrasebook->new( 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'}); =head1 DESCRIPTION This module is the fallback or default phrasebook class. It doesn't do much except act as a very simple templating facility. =head1 METHODS =head2 fetch Retrieves the specified C