.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Data::Phrasebook::Loader::YAML 3pm"
.TH Data::Phrasebook::Loader::YAML 3pm "2022-06-12" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Data::Phrasebook::Loader::YAML \- Absract your phrases with YAML.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Data::Phrasebook;
\&
\&    my $q = Data::Phrasebook\->new(
\&        class  => \*(AqFnerk\*(Aq,
\&        loader => \*(AqYAML\*(Aq,
\&        file   => \*(Aqphrases.yaml\*(Aq,
\&    );
\&
\&    $q\->delimiters( qr{ \e[% \es* (\ew+) \es* %\e] }x );
\&    my $phrase = $q\->fetch($keyword);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This class loader implements phrasebook patterns using \s-1YAML.\s0
.PP
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. In this implementation a single file is one
complete dictionary.
.PP
An example \s-1YAML\s0 file:
.PP
.Vb 4
\&  \-\-\-
\&  foo: >
\&    Welcome to [% my %] world.
\&    It is a nice [%place %].
.Ve
.PP
Within the phrase text placeholders can be used, which are then replaced with
the appropriate values once the \fBget()\fR method is called. The default style of
placeholders can be altered using the \fBdelimiters()\fR method.
.SH "INHERITANCE"
.IX Header "INHERITANCE"
Data::Phrasebook::Loader::YAML inherits from the base class
Data::Phrasebook::Loader::Base.
See that module for other available methods and documentation.
.SH "METHODS"
.IX Header "METHODS"
.SS "load"
.IX Subsection "load"
Given a \f(CW\*(C`file\*(C'\fR, load it. \f(CW\*(C`file\*(C'\fR must contain a \s-1YAML\s0 map.
.PP
.Vb 1
\&   $loader\->load( $file, @dict );
.Ve
.PP
This method is used internally by Data::Phrasebook::Generic's
\&\f(CW\*(C`data\*(C'\fR method, to initialise the data store.
.PP
It must take a \f(CW\*(C`file\*(C'\fR (be it a scalar, or something more complex)
and return a handle. The \f(CW\*(C`dict\*(C'\fR is optional, should you wish to use the
dictionary support.
.SS "get"
.IX Subsection "get"
Returns the phrase stored in the phrasebook, for a given keyword.
.PP
.Vb 1
\&   my $value = $loader\->get( $key );
.Ve
.PP
If one or more named dictionaries have been previously selected, they will be
searched in order, followed by the default dictionary. The first hit on
\&\f(CW\*(C`key\*(C'\fR will be returned, otherwise \f(CW\*(C`undef\*(C'\fR is returned.
.SS "dicts"
.IX Subsection "dicts"
Returns the list of dictionaries available.
.PP
.Vb 1
\&   my @dicts = $loader\->dicts();
.Ve
.PP
This is the list of all dictionaries available in the source file. If multiple
dictionaries are not being used, then an empty list will be returned.
.SS "keywords"
.IX Subsection "keywords"
Returns the list of keywords available. List is lexically sorted.
.PP
.Vb 1
\& my @keywords = $loader\->keywords( $dict );
.Ve
.PP
If one or more named dictionaries have been previously selected, they will be
farmed for keywords, followed by the default dictionary.
.PP
The \f(CW\*(C`dict\*(C'\fR argument is optional, and may be used to override the search to a
single named dictionary, or a list of dictionaries if passed by reference,
plus the default dictionary of course.
.PP
To find all available keywords in all available dictionaries, use the
following:
.PP
.Vb 1
\& $loader\->keywords( [ $loader\->dicts ] );
.Ve
.SS "set_default"
.IX Subsection "set_default"
If a requested phrase is not found in the named dictionary an attempt is made
to find it in the \fIdefault\fR dictionary. Data::Phrasebook loaders normally
use the first dictionary in the phrasebook as the default, but as mentioned in
\&\*(L"\s-1DICTIONARY SUPPORT\*(R"\s0 this does not make sense because the dictionaries in
\&\s-1YAML\s0 phrasebooks are not ordered.
.PP
To override the automatically selected default dictionary use this method, and
pass it a \f(CW\*(C`default_dictionary_name\*(C'\fR. This value is only reset at phrasebook
load time, so you'll probably need to trigger a reload:
.PP
.Vb 2
\& $q\->loader\->set_default( $default_dictionary_name );
\& $q\->loader\->load( $file );
.Ve
.PP
To reset the loader's behaviour to automatic default dictionary selection,
pass this method an undefined value, and then reload.
.SH "DICTIONARY SUPPORT"
.IX Header "DICTIONARY SUPPORT"
This loader supports the use of dictionaries, as well as multiple dictionaries
with a search order. If you are unfamiliar with these features, see
Data::Phrasebook for more information.
.PP
Source data format for a single unnamed dictionary is a \s-1YAML\s0 stream that has
as its \fIroot node\fR an anonymous hash, like so:
.PP
.Vb 3
\& \-\-\-
\& first_key: first_value
\& second_key: second_value
.Ve
.PP
In this case, specifying one or more named dictionaries will have no effect.
The single dictionary that comprises the \s-1YAML\s0 file will take the place of your
\&\fIdefault\fR dictionary, so will always be searched. To override this behaviour
use the \f(CW\*(C`set_default\*(C'\fR object method.
.PP
Multiple dictionaries \fBmust\fR be specified using a two-level hash system,
where the root node of your \s-1YAML\s0 file is an anonymous hash containing
dictionary names, and the values of those hash keys are further anonymous
hashes containing the dictionary contents. Here is an example:
.PP
.Vb 7
\& \-\-\-
\& dict_one:
\&    first_key: first_value
\&    second_key: second_value
\& dict_two:
\&    first_key: first_value
\&    second_key: second_value
.Ve
.PP
If you use any other structure for your \s-1YAML\s0 dictionary files, the result is
uncertain, and this loader module is very likely to crash your program.
.PP
If a requested phrase is not found in the named dictionary an attempt is made
to find it in the \fIdefault\fR dictionary. Data::Phrasebook loaders normally
use the first dictionary in the phrasebook as the default, but this does not
make sense because \s-1YAML\s0 phrasebook files contain an unordered hash of
dictionaries.
.PP
This loader will therefore select the first dictionary from the list of
\&\fIlexically sorted\fR dictionary names to be the default. To override this
behaviour use the \f(CW\*(C`set_default\*(C'\fR object method. Alternatively, just include a
dictionary that is guaranteed to be selected for the default (e.g.
\&\f(CW\*(C`0000default\*(C'\fR); it need not contain any keys.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Data::Phrasebook,
Data::Phrasebook::Loader.
.SH "BUGS, PATCHES & FIXES"
.IX Header "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 \s-1POD\s0
documentation, please send an email to barbie@cpan.org or submit a bug to the
\&\s-1RT\s0 system (http://rt.cpan.org/). However, it would help greatly if you are
able to pinpoint problems or even supply a patch.
.PP
Fixes are dependent upon their severity and my availability. Should a fix not
be forthcoming, please feel free to (politely) remind me.
.SH "AUTHOR"
.IX Header "AUTHOR"
.Vb 3
\&  Original author: Iain Campbell Truskett (16.07.1979 \- 29.12.2003)
\&  Maintainer: Barbie <barbie@cpan.org> since January 2004.
\&  for Miss Barbell Productions <http://www.missbarbell.co.uk>.
.Ve
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
.Vb 2
\&  Copyright (C) 2003 Iain Truskett.
\&  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.
.Ve