/ 
YAML-AppConfig-0.14
River stage one • 3 direct dependents • 3 total dependents
/ YAML::AppConfig

NAME

YAML::AppConfig - Manage configuration files with YAML and variable reference.

SYNOPSIS

use YAML::AppConfig;

my $string = <<'YAML';
---
etc_dir: /opt/etc
foo_dir: $etc_dir/foo
bar_dir : ${foo_dir}bar
some_array:
    - $foo_dir/place
YAML

# Can also load form a file or other YAML::AppConfig object.  
# Just use file => or object => instead of string =>
my $conf = YAML::AppConfig->new(string => $string);

# Get variables in two different ways, both equivalent.
$conf->get("etc_dir");    # returns /opt/etc
$conf->get_foo_dir;       # returns /opt/etc/foo

# Get at the raw, uninterpolated values, in three equivalent ways:
$conf->get("etc_dir", 1); # returns '$etc_dir/foo'
$conf->get_etc_dir(1);    # returns '$etc_dir/foo'
$conf->config->{foo_dir}; # returns '$etc_dir/foo'

# Set etc_dir in three different ways, all equivalent.
$conf->set("etc_dir", "/usr/local/etc");
$conf->set_etc_dir("/usr/local/etc");
$conf->config->{etc_dir} = "/usr/local/etc";

# Notice that changed variables affect other variables:
$config->get_foo_dir;          # now returns /usr/local/etc/foo
$config->get_some_array->[0];  # returns /usr/local/etc/foo/place

# You can escape variables for concatenation purposes:
$config->get_bar_dir;  # Returns '/usr/local/etc/foobar'

DESCRIPTION

YAML::AppConfig extends the work done in Config::YAML and YAML::ConfigFile to allow variable reference between settings. Essentialy your configuration file is a hash serialized to YAML. Scalar values that have $foo_var type values in them will have interpolation done on them. If $foo_var is a key in the configuration file it will be substituted, otherwise it will be left alone. $foo_var must be a reference to a scalar value and not a hash or array, otherwise it won't be interpolated.

Either YAML or YAML::Syck is used underneath. You can also specify your own YAML parser by using the yaml_class attribute to new(). By default the value of the yaml_class attribute is preferred over everything. Failing that, we check to see if YAML::Syck or YAML is loaded, and if so use that (prefering Syck). If nothing is loaded and the yaml_class attribute was not given then we try to load a YAML parser, starting with YAML::Syck and then trying YAML. If this is Too AI for you and bites your ass then you can force behavior using yaml_class, which is really why it exists.

USING VARIABLES

Variable names refer to items at the top of the YAML configuration. There is currently no way to refer to items nested inside the configuration. If a variable is not known, because it doesn't match the name of a top level configuration key, then no substitution is done on it and it is left verbatim in the value.

Variables names must match one of /\$\w+/ or /\${\w+}/. Just like in Perl the ${foo} form is to let you have values of the form ${foo}bar and have the variable be treated as $foo instead of $foobar.

You can escape a variable by using a backslash before the dollar sign. For example \$foo will result in a literal $foo being used, and thus no interpolation will be done on it. If you should want a literal \$foo then use two slashes, \\$foo. Should you want a literal \\$foo then use three slashes, and so on. Escaping can be used with ${foo} style variables too.

Variables can be references to more complex data structures. So it's possible to define a list and assign it to a top level configuration key and then reuse that list anywhere else in the configuration file. Just like in Perl, if a variable refering to a reference is used in a string the raw memory address will be its value, so be warned.

METHODS

new(%args)

Creates a new YAML::AppConfig object and returns it. new() accepts the following key values pairs:

file

The name of the file which contains your YAML configuration.

string

A string containing your YAML configuration.

object

A YAML::AppConfig object which will be deep copied into your object.

no_resolve

If true no attempt at variable resolution is done on calls to get().

yaml_class

The name of the class we should use to find our LoadFile and Load functions for parsing YAML files and strings, respectively. The named class should provide both LoadFile and Load as functions and should be loadable via require.

get(key, [no_resolve])

Given $key the value of that setting is returned, same as get_$key. If $no_resolve is passed in then the raw value associated with $key is returned, no variable interpolation is done.

set(key, value)

Similar to get() except you can also provide a value for the setting.

get_*([no_resolve])

Convenience methods to retrieve values using a method, see get. For example if foo_bar is a configuration value in your YAML file then get_foo_bar retrieves its value. These methods are curried versions of get. These functions all take a single optional argument, $no_resolve, which is the same as get()'s $no_resolve.

set_*(value)

A convience method to set values using a method, see set and get_*. These methods are curried versions of set.

config

Returns the hash reference to the raw config hash. None of the values are interpolated, this is just the raw data.

config_keys

Returns the keys in config() sorted from first to last.

merge(%args)

Merge takes another YAML configuration and merges it into this one. %args are the same as those passed to new(), so the configuration can come from a file, string, or existing YAML::AppConfig object.

AUTHORS

Matthew O'Connor <matthew@canonical.org>

Original implementations by Kirrily "Skud" Robert (as YAML::ConfigFile) and Shawn Boyette (as Config::YAML).

SEE ALSO

YAML, YAML::Syck, Config::YAML, YAML::ConfigFile

COPYRIGHT

Copyright 2006 Matthew O'Connor, All Rights Reserved.

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