/ 
Data-Phrasebook-Loader-XML-0.16
River stage zero No dependents
/ Data::Phrasebook::Loader::XML

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.