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 the store_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 the yamlfile 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 standard new 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 specialist unpack 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 specialist pack 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

Moose, MooseX::Storage

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.