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.