YAML::Accessor
Syntactic sugar for YAML::XS using Class::Accessor with sub-accessors.
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' [$!]";
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.
YAML::XS
LoadFile
There are lots of things one could do with this; the obvious use case is a config file.
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.
file
new()
$!
autocommit is optional. If you set this to true, your file will be written to each time a mutator is called.
autocommit
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 $!.
readonly
new
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
damian
$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.
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.
get_foo()
foo
get()
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.
set_foo()
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.
commit()
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.
YAML::XS Class::Accessor Perl Best Practices Damian Conway O'Reilly & Associates ISBN-13: 978-0596001735 ASIN: 0596001738
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.
set()
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.
Alex J. Avriette, <alex@cpan.org>
Copyright (C) 2011 by Alex J. 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.
To install YAML::Accessor, copy and paste the appropriate command in to your terminal.
cpanm
cpanm YAML::Accessor
CPAN shell
perl -MCPAN -e shell install YAML::Accessor
For more information on module installation, please visit the detailed CPAN module installation guide.