Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Data::Phrasebook::LoadUserYContributed Perl DData::Phrasebook::Loader::YAML(3)

NAME
       Data::Phrasebook::Loader::YAML -	Absract	your phrases with YAML.

SYNOPSIS
	   use Data::Phrasebook;

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

	   $q->delimiters( qr{ \[% \s* (\w+) \s* %\] }x	);
	   my $phrase =	$q->fetch($keyword);

DESCRIPTION
       This class loader implements phrasebook patterns	using YAML.

       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.

       An example YAML file:

	 ---
	 foo: >
	   Welcome to [% my %] world.
	   It is a nice	[%place	%].

       Within the phrase text placeholders can be used,	which are then
       replaced	with the appropriate values once the get() method is called.
       The default style of placeholders can be	altered	using the delimiters()
       method.

INHERITANCE
       Data::Phrasebook::Loader::YAML 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 a YAML map.

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

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

       It must take a "file" (be it a scalar, or something more	complex) and
       return a	handle.	The "dict" is optional,	should you wish	to use the
       dictionary support.

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

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

       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 "key" will be returned, otherwise "undef" is returned.

   dicts
       Returns the list	of dictionaries	available.

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

       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.

   keywords
       Returns the list	of keywords available. List is lexically sorted.

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

       If one or more named dictionaries have been previously selected,	they
       will be farmed for keywords, followed by	the default dictionary.

       The "dict" 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.

       To find all available keywords in all available dictionaries, use the
       following:

	$loader->keywords( [ $loader->dicts ] );

   set_default
       If a requested phrase is	not found in the named dictionary an attempt
       is made to find it in the default dictionary. Data::Phrasebook loaders
       normally	use the	first dictionary in the	phrasebook as the default, but
       as mentioned in "DICTIONARY SUPPORT" this does not make sense because
       the dictionaries	in YAML	phrasebooks are	not ordered.

       To override the automatically selected default dictionary use this
       method, and pass	it a "default_dictionary_name".	This value is only
       reset at	phrasebook load	time, so you'll	probably need to trigger a
       reload:

	$q->loader->set_default( $default_dictionary_name );
	$q->loader->load( $file	);

       To reset	the loader's behaviour to automatic default dictionary
       selection, pass this method an undefined	value, and then	reload.

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.

       Source data format for a	single unnamed dictionary is a YAML stream
       that has	as its root node an anonymous hash, like so:

	---
	first_key: first_value
	second_key: second_value

       In this case, specifying	one or more named dictionaries will have no
       effect.	The single dictionary that comprises the YAML file will	take
       the place of your default dictionary, so	will always be searched. To
       override	this behaviour use the "set_default" object method.

       Multiple	dictionaries must be specified using a two-level hash system,
       where the root node of your YAML	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:

	---
	dict_one:
	   first_key: first_value
	   second_key: second_value
	dict_two:
	   first_key: first_value
	   second_key: second_value

       If you use any other structure for your YAML dictionary files, the
       result is uncertain, and	this loader module is very likely to crash
       your program.

       If a requested phrase is	not found in the named dictionary an attempt
       is made to find it in the default dictionary. Data::Phrasebook loaders
       normally	use the	first dictionary in the	phrasebook as the default, but
       this does not make sense	because	YAML phrasebook	files contain an
       unordered hash of dictionaries.

       This loader will	therefore select the first dictionary from the list of
       lexically sorted	dictionary names to be the default. To override	this
       behaviour use the "set_default" object method. Alternatively, just
       include a dictionary that is guaranteed to be selected for the default
       (e.g.  "0000default"); it need not contain any keys.

SEE ALSO
       Data::Phrasebook, Data::Phrasebook::Loader.

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

COPYRIGHT AND LICENSE
	 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.

perl v5.32.1			  2014-08-23 Data::Phrasebook::Loader::YAML(3)

NAME | SYNOPSIS | DESCRIPTION | INHERITANCE | METHODS | DICTIONARY SUPPORT | SEE ALSO | BUGS, PATCHES & FIXES | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Data::Phrasebook::Loader::YAML&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help