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.

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.