File Coverage

blib/lib/Data/Phrasebook.pm

Criterion	Covered	Total	%
statement	29	29	100.0
branch	10	10	100.0
condition	4	4	100.0
subroutine	6	6	100.0
pod	1	1	100.0
total	50	50	100.0

package Data::Phrasebook;
use strict;
use warnings FATAL => 'all';
use base qw( Data::Phrasebook::Debug );
use Carp qw( croak );

use vars qw($VERSION);
$VERSION = '0.35';

=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__