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
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_dr} = "/usr/local/etc";

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

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. If YAML::Syck is found it will be used over YAML.

USING VARIABLES

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.

If a variable is not recognized it will be left as is in the value, it won't be interpolated away or cause a warning. Unknown variables are not recognized, as are variables that refer to references (e.g. hashes or arrays). Currently variables can only address items in the top-most level of the YAML configuration file (i.e. the top most level of the hash the conf file represents).

There is currently no way to escape a variable. For simple cases this is not a problem because unrecongnized variables are left as is. However, if you have a setting named foo in the top of your YAML file and you want to use a literal value of '$foo' then you are, in a way, out of luck. As a work around, you can access the raw values from the Perl side by passing in $no_resolve to get(). I realize this is not ideal and there are still cases were you are SOL, but I haven't hit this problem yet and so I have not been inclined to solve it.

METHODS

new

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().

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_*

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_*

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.

AUTHORS

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

Matthew O'Connor <matthew@canonical.org>

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.