NAME

Data::Phrasebook::Loader::XML - Absract your phrases with XML.

SYNOPSIS

    use Data::Phrasebook;

    my $q = Data::Phrasebook->new(
        class  => 'Fnerk',
        loader => 'XML',
        file   => 'phrases.xml',
        dict   => 'Dictionary',     # optional
    );

  OR

    my $q = Data::Phrasebook->new(
        class  => 'Fnerk',
        loader => 'XML',
        file   => {
            file => 'phrases.xml',
            ignore_whitespace => 1,
        }
    );

    # 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

This class loader implements phrasebook patterns using XML.

Phrases can be contained within one or more dictionaries, with each phrase accessible via a unique key. Phrases may contain placeholders, please see Data::Phrasebook for an explanation of how to use these. Groups of phrases are kept in a dictionary. The first dictionary is used as the default, unless a specific dictionary is requested.

In this implementation, the dictionaries and phrases are implemented with an XML document. This document is the same as implement by Class::Phrasebook.

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>
 ]>

An example 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>
   <phrase name="THE_AUTHOR">Barbie</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>
   <phrase name="THE_AUTHOR">Barbie</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>
   <phrase name="THE_AUTHOR">Barbie</phrase>
 </dictionary>
 </phrasebook>

Note that, unlike Class::Phrasebook, this implementation does not search the default dictionary if a phrase is not found in the specified dictionary. This may change in the future.

Each phrase should have a unique name within a dictionary, which is then used as a reference key. Within the phrase text placeholders can be used, which are then replaced with the appropriate values once the get() method is called.

The parameter 'ignore_whitespace', will remove any extra whitespace from the phrase. This includes leading and trailing whitespace. Whitespace around a newline, including the newline, is replace with a single space.

If you need to use the '<' symbol in your XML, you'll need to use '&lt;' instead.

    # <phrase name="TEST">$a &lt; $b</phrase>

    my $q = Data::Phrasebook->new(
        class  => 'Fnerk',
        loader => 'XML',
        file   => 'phrases.xml',
    );

    my $phrase = $q->fetch('TEST');    # returns '$a < $b'

INHERITANCE

Data::Phrasebook::Loader::XML inherits from the base class Data::Phrasebook::Loader::Base. See that module for other available methods and documentation.

METHODS

load

Given a file, load it. file must contain valid XML.

   $loader->load( $file, $dict );

This method is used internally by Data::Phrasebook::Generic's data method, to initialise the data store.

get

Returns the phrase stored in the phrasebook, for a given keyword.

   my $value = $loader->get( $key );

dicts

Returns the list of dictionaries available.

   my @dicts = $loader->dicts();

keywords

Returns the list of keywords available.

   my @keywords = $loader->keywords();

CONTINUATION LINES

As a configuration option (default is off), continuation lines can be used via the use of the 'ignore_whitespace' or 'ignore_newlines' options as follows:

    my $q = Data::Phrasebook->new(
        class  => 'Fnerk',
        loader => 'XML',
        file   => {
            file => 'phrases.xml',
            ignore_whitespace => 1,
        }
    );

Using 'ignore_whitespace', all whitespace (including newlines) will be collapsed into a single space character, with leading and trailing whitespace characters removed.

    my $q = Data::Phrasebook->new(
        class  => 'Fnerk',
        loader => 'XML',
        file   => {
            file => 'phrases.xml',
            ignore_newlines => 1,
        }
    );

Using 'ignore_newlines', all newlines are removed, preserving whitespace around them, should this be required.

SEE ALSO

Data::Phrasebook.

BUGS, PATCHES & FIXES

There are no known bugs at the time of this release. However, if you spot a bug or are experiencing difficulties, that is 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/). However, 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

  Barbie, <barbie@cpan.org>
  for Miss Barbell Productions <http://www.missbarbell.co.uk>.

COPYRIGHT AND LICENSE

  Copyright (C) 2004-2014 Barbie for Miss Barbell Productions.

  This distribution is free software; you can redistribute it and/or
  modify it under the Artistic License 2.0.

cpanm Data::Phrasebook::Loader::XML

perl -MCPAN -e shell
install Data::Phrasebook::Loader::XML