/ 
YAML-Accessor-0.45
River stage zero No dependents
/ YAML::Accessor

NAME

YAML::Accessor

ABSTRACT

Syntactic sugar for YAML::XS using Class::Accessor with sub-accessors.

SYNOPSIS

package YConfig;
use base qw{ YAML::Accessor };

# Load by filename
my $yc = YConfig->new(
  file => 'config.yml',  # Can be a filehandle.
  readonly   => 1,       # This is a default. Can be 1 (true).
  damian     => 1,       # See below. Can be 0 (false).

  # Implemented, but probably buggy and not tested.
  autocommit => 0,       # This is a default. Can be 1 (true).
)
or die "failed to load 'config.yml' [$!]";

DESCRIPTION

YAML::Accessor aims to create a "gettr/settr" interface for YAML objects/files and allow the user to both manipulate their structure and to read and write from the (specified) file(s).

It doesn't use the simple YAML::XS call LoadFile and this may seem unituitive for users of YAML::XS. The point is not to reinvent YAML::XS, but rather to create intuitive, easily-constructed objects with proper accessor/mutator methods.

There are lots of things one could do with this; the obvious use case is a config file.

PARAMETERS

file is not optional. It's got to be a filehandle or a scalar that (hopefully) refers to a file you can read. If not, new() barfs and properly sets $! for you.

autocommit is optional. If you set this to true, your file will be written to each time a mutator is called.

readonly is optional. It defaults to true. This means you get no mutators ("settrs") and you won't munge your file accidentally. If you set readonly and autocommit both to true, new explodes and you deserve what you get. But you still get $!.

damian refers to the Class::Accessor method "follow_best_practice", which is defined in Damian Conway's book on "Perl Best Practices" on ORA. If you set this to true, your methods will be

$obj->get_foo();     # gets the value of foo
$obj->set_foo(100);  # sets foo to 100

If you don't like this, set damian to false (that is, 0 or undef or ''), and your methods will be:

$foo = $obj->foo();  # returns value of foo
$obj->foo(100);      # sets foo to 100

damian defaults to true.

ACCESSORS

get_foo() accessors will return whatever the value of foo is (note use of "Damianized" accessor here). In the event there's a list of things, you need to read the code to the get() method in this module.

set_foo() mutators will set the value of whatever field is specified (in this case, "foo" -- noting again the "Damianized" mutator). Mutators return one of two things. If you've set autocommit to true, the mutator will return the value of the latest attempt to "commit" (write) your file. In the event you have not turned on autocommit during the constructor, the mutator will simply return the value(s) supplied. For more detail, have a look at the code. But really, it's not too complicated.

METHODS

commit() allows you to force the current yaml to be flushed to disk. Note that YAML::Accessor calls this method internally when you use mutators.

SUB-ACCESSORS

When calling an accessor method, the object will try to determine whether the value you are requesting is itself an accessor (or rather, should be made an accessor). Therefore you may use a construct such as:

$obj->get_foo()->get_bar();

and it should Just Work. Note that this only works for hash values. If you request an accessor that has an array or scalar (or anything else), you'll simply get what you asked for.

Note that this is not standard Class::Accessor behavior. The reason for this is that YAML allows us to have deeply-nested structures, and having to refer to their hash keys after a single layer of accessors, like such:

$obj->get_foo()->{bar};

is tedious and misses the point of this package.

SEE ALSO

YAML::XS
Class::Accessor

Perl Best Practices
Damian Conway
O'Reilly & Associates
ISBN-13: 978-0596001735
ASIN: 0596001738

BUGS

The implementation actually doesn't allow this module to internally use Class::Accessor and instead overrides its get() and set() functions to refer to your shiny YAML object. That's kind of inconsistent, but you wanted YAML, not an object that referred to YAML. If you can come up with a way to fix it, awesome. This way is simpler.

Also, it looks like doing something like

use base qw{ Class::Accessor };
use base qw{ YAML::Accessor  };

is fraught with peril. Don't do that.

While not exactly a bug, this package uses YAML::XS instead of YAML in the interest of speed and ingy's preference.

AUTHOR

Jane A. Avriette, <jane@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2011 by Jane A. Avriette

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.0 or, at your option, any later version of Perl 5 you may have available.