view release on metacpan or  search on metacpan

lib/Config/YAML/Tiny.pm  view on Meta::CPAN

=head1 DESCRIPTION

Config::YAML is a somewhat object-oriented wrapper around
the YAML 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.

=head1 METHODS

=head2 new

Creates a new Config::YAML::Tiny object.

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

The C<config> 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>,
then it is used to specify the file to which configuration
data will later be written out.  This positional dependancy
makes it possible to have parameters named "config" and/or
"output" in config files.

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

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

=cut

=head2 get_*/set_*

If you'd prefer not to directly molest the object to store
and retrieve configuration data (something I B<highly
recommend>, autoloading methods of the forms C<get_[param]>
and C<set_[param]> 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

=cut

=head2 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)

=cut

=head2 read

Imports a YAML-formatted config file.

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

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

=cut

=head2 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> method documentation for details.

=cut

=head1 DEPRECATED METHODS

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

=head2 get

Returns the value of a parameter.

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

=cut

=head2 set

Sets the value of a parameter:

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

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

=cut

=head1 COMPATABILITY WITH CONFIG::YAML

This module should be able to work as a drop in replacement
of L<Config::YAML>.

This code began as a quick post of the L<Config::YAML> 1.42
code changing as little as possible to get YAML::Tiny