Config::YAML (3pm)

Version 1.42

Config::YAML is a somewhat object-oriented wrapper around the \s-1YAML\s0 module which makes reading and writing configuration files simple. Handling multiple config files (e.g. system and per-user configuration, or a gallery app with per-directory configuration) is a snap.

    use Config::YAML;

    # create Config::YAML object with any desired initial options
    # parameters; load system config; set alternate output file
    my $c = Config::YAML->new( config => "/usr/share/foo/globalconf",
                               output => "~/.foorc",
                               param1 => value1,
                               param2 => value2,
                               ...
                               paramN => valueN,
                             );

    # integrate user's own config
    $c->read("~/.foorc");

    # integrate command line args using Getopt::Long
    $rc = GetOptions ( $c,
                       'param1|p!',
                       'param2|P',
                       'paramN|n',
                     );

    # Write configuration state to disk
    $c->write;

    # simply get params back for use...
    do_something() unless $c->{param1};
    # or get them more OO-ly if that makes you feel better
    my $value = $c->get_param2;

new

Creates a new Config::YAML object.

my $c = Config::YAML->new( config => initial_config, output => output_config );

The \*(C`config\*(C' parameter specifies the file to be read in during object creation. It is required, and must be the first parameter given. If the second parameter is \*(C`output\*(C', then it is used to specify the file to which configuration data will later be written out. This positional dependency makes it possible to have parameters named \*(L"config\*(R" and/or \*(L"output\*(R" in config files.

Initial configuration values can be passed as subsequent parameters to the constructor:

my $c = Config::YAML->new( config => "~/.foorc", foo => "abc", bar => "xyz", baz => [ 1, 2, 3 ], );

get_*/set_*

If you'd prefer not to directly molest the object to store and retrieve configuration data, autoloading methods of the forms \*(C`get_[param]\*(C' and \*(C`set_[param]\*(C' are provided. Continuing from the previous example:

print $c->get_foo; # prints "abc" my $val = $c->get_quux; # $c->{quux} doesn't exist; returns undef

$c->set_bar(30); # $c->{bar} now equals 30, not "xyz" my @list = qw(alpha beta gamma); $c->set_baz(\@list); # $c->{baz} now a reference to @list

fold

Convenience method for folding multiple values into the config object at once. Requires a hashref as its argument.

$prefs{theme} = param(theme); $prefs{format} = param(format); $prefs{sortby} = param(order);

$c->fold(\%prefs);

my $format = $c->get_format; # value matches that of param(format)

read

Imports a YAML-formatted config file.

$c->read('/usr/share/fooapp/fooconf');

\*(C`read()\*(C' is called at object creation and imports the file specified by \*(C`new(config=>)\*(C', so there is no need to call it manually unless multiple config files exist.

write

Dump current configuration state to a YAML-formatted flat file.

$c->write;

The file to be written is specified in the constructor call. See the \*(C`new\*(C' method documentation for details.

These methods have been superceded and will likely be removed in the next release.

get

Returns the value of a parameter.

print $c->get('foo');

set

Sets the value of a parameter:

$c->set('foo',1);

my @paints = qw( oil acrylic tempera ); $c->set('paints', \@paints);

Shawn Boyette (\*(C`<[email protected]>\*(C')

Original implementation by Kirrily \*(L"Skud\*(R" Robert (as \*(C`YAML::ConfigFile\*(C').

• Config::YAML ignores the \s-1YAML\s0 document separation string (\*(C`---\*(C') because it has no concept of multiple targets for the data coming from a config file.

Please report any bugs or feature requests to \*(C`[email protected]\*(C', or through the web interface at <http://rt.cpan.org>. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

Copyright 2004 Shawn Boyette, All Rights Reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.