NAME
PkgForge::YAMLStorage - A Moose role for serialising objects into YAML
VERSION
This documentation refers to PkgForge::YAMLStorage version 1.4.8
SYNOPSIS
package My::App;
use Moose;
with 'PkgForge::YAMLStorage';
has 'foobar' => (
is => 'ro',
isa => 'Str',
traits => ['PkgForge::Serialise'],
);
# ... rest of the class here
my $obj = My::App->new();
$obj->store_in_yamlfile('/tmp/store.yml');
my $obj2 = My::App->new_from_yamlfile('/tmp/store.yml');
DESCRIPTION
This is a Moose role for serialising objects into YAML files. This module is designed to only serialise specific attributes. It is intended to be simple and lightweight and deliberately only supports a single format. For much more comprehensive support there are already more heavy-weight solutions available, such as MooseX::Storage. In general, YAML can cope very well with serialising most data but this role also provides support for attributes having their own specialist methods for packing and unpacking of data.
Only attributes in a class which have the PkgForge::Serialise
trait will be serialised to a YAML file or loaded from a YAML file. In general YAML can be used to serialise pretty much any data structure. However, where necessary, any attribute which has the PkgForge::Serialise
trait can specify that it has specialist pack
and/or unpack
helper methods. These helper methods can be used to mangle the attribute data before serialisation or after deserialisation but prior to the data being loaded as part of the new object.
ATTRIBUTES
There is one attribute which is gained by any Moose class which implements this role.
- yamlfile
-
This is a simple string which holds the path to the YAML file. When a filename is passed into the
new_from_yamlfile
method the value is automatically set for this attribute. If no filename is passed into thestore_in_yamlfile
method then the value of this attribute will be used. There is no default value for this attribute and it does not have to be specified. A class implementing this role may override the attribute to have a default value if necessary.
SUBROUTINES/METHODS
- new_from_yamlfile([$filename|$hashref|%hash])
-
This method creates a new object for the class with the values of certain attributes being taken from the YAML file. The method takes either a single string as a file name, a hash or a reference to a hash of attributes and their values. If passing a hash or hashref the YAML file name should be specified using the
yamlfile
hash key. If no file name is given then the method will look for a default value for theyamlfile
attribute.Once the path to the YAML file has been found the data is loaded from the file using the
load_data_from_yamlfile
method. Any data passed in as a hash or reference to a hash will be passed into that method. The final results hash populated by that method will be passed to the standardnew
method for the class and the generated object is returned. - load_data_from_yamlfile( $filename, $results )
-
This is a class method which takes the name of the YAML file from which the data should be loaded and a reference to a hash into which the values of the required attributes should be inserted.
The YAML file must exist and the data in the YAML file must be loadable as a reference to a hash. Only attributes which have the
PkgForge::Serialise
trait will have their values loaded from the YAML file. Any attribute which already has a value in the results hash will be ignored. It will not be checked and no data will be unpacked.Any attribute with the
PkgForge::Serialise
trait can specify that a specialistunpack
helper method should be used to handle the unpacking of the data. The unpacking method will be passed a scalar variable which is either the data or a reference to the data found for the attribute in the YAML file. The data can be mangled in anyway required as long as the method returns a single scalar variable (which may, of course, be a reference to another object or a complex data structure). - store_in_yamlfile($file)
-
If no file name is specified then the value of the
yamlfile
attribute will be used. If no file name is found then an exception will be thrown.This method will serialise, into the specified YAML file, a hash of the attributes, and their values, for the object which have the
PkgForge::Serialise
trait. The hash keys will be sorted before serialisation so that the content of the generated files should always be reproducible and comparable with a simple text diff tool.Any attribute with the
PkgForge::Serialise
trait can specify that a specialistpack
helper method should be used to handle the packing of the data. The packing method will be passed the value of the attribute. The data can be mangled in anyway required as long as the method returns a single scalar variable (which may, of course, be a reference to a complex data structure).
DEPENDENCIES
This module is powered by Moose. It also requires YAML::Syck for reading and writing YAML files and Try::Tiny for exception handling. It also works fine with YAML::XS but the output files generated are slightly different. This breaks some expectations in other parts of the PkgForge code and test-suite so that module, although better, is being avoided for now.
SEE ALSO
PLATFORMS
This is the list of platforms on which we have tested this software. We expect this software to work on any Unix-like platform which is supported by Perl.
ScientificLinux5, Fedora13
BUGS AND LIMITATIONS
Please report any bugs or problems (or praise!) to bugs@lcfg.org, feedback and patches are also always very welcome.
AUTHOR
Stephen Quinney <squinney@inf.ed.ac.uk>
LICENSE AND COPYRIGHT
Copyright (C) 2011 University of Edinburgh. All rights reserved.
This library is free software; you can redistribute it and/or modify it under the terms of the GPL, version 2 or later.
1 POD Error
The following errors were encountered while parsing the POD:
- Around line 295:
You forgot a '=back' before '=head1'