Config::Record(3) User Contributed Perl Documentation Config::Record(3)NAMEConfig::Record - Configuration file access
SYNOPSIS
use Config::Record;
# Create an empty record & then load from file
my $config = Config::Record->new();
$config->load("/etc/myapp.cfg");
# Create & load, then save to filename
my $config = Config::Record->new(file => "/etc/myapp.cfg");
$config->save("/etc/myapp.cfg");
# Load / save from filehandle
my $fh = IO::File->new("/etc/myapp.cfg");
my $config = Config::Record->new(file => $fh);
$config->save($fh);
# Get a config value, throw error if not found
my $value = $config->get("foo");
# Get a config value, return 'eek' if not found
my $value = $config->get("foo", "eek");
# Set a value
$config->set("foobar", "wizz");
# Get a deep config value (ie nested hash)
my $value = $config->get("foo/bar", "eek");
# Get first element of an array param
my $value = $config->get("people/[0]/forename");
# Get the raw hash reference forming the record
my $record = $config->record();
# Get a new config object rooted at a sub-hash
my $config = $config->view("foo");
DESCRIPTION
This module provides an API for loading and saving of simple
configuration file records. Entries in the configuration file are
essentially key,value pairs, with the key and values separated by a
single equals symbol. The "key" consists only of alphanumeric
characters. There are three types of values, scalar values can contain
anything except newlines. Trailing whitespace will be trimmed unless
the value is surrounded in double quotes. eg
foo = Wizz
foo = "Wizz.... "
Long lines can be split with a backslash character, without introducing
newlines. Without double quotes, whitespace at beginning and end of
lines will be trimmed eg
foo = This is a long \
line of text
foo = "This is a long " \
"line of text"
Multi-line strings can be provided as 'HERE' documents, eg
foo = <<EOF
This is a multiple paragraph
block of text with newlines
preserved
EOF
Array values consist of a single right round bracket, following by one
"value" per line, terminated by a single left round bracket. eg
foo = (
Wizz
"Wizz... "
)
Hash values consist of a single right curly bracket, followed by one
key,value pair per line, terminated by a single left curly bracket. eg
foo = {
one = Wizz
two = "Wizz.... "
}
Arrays and hashes can be nested to arbitrary depth.
EXAMPLE
name = Foo
title = "Wizz bang wallop"
eek = (
OOhh
Aahhh
Wizz
)
people = (
{
forename = John
surnamne = Doe
}
{
forename = Some
surname = One
}
)
wizz = {
foo = "Elk"
ooh = "fds"
}
EXTRA PARSER FEATURES
The syntax described thus far is classed as the base feature set. By
passing the "features" parameter when creating an instance of the
"Config::Record" class, it is posible to turn on certain extra features
QUOTED NON-ALPHANUMERIC KEYS
The keys for configuration parameters are normally restricted to only
contain the characters 'a-Z', '0-9', '_', '-' and '.'. Sometimes it is
desirable to allow arbitrary characters for keys. If this capability is
required then the "quotedkeys" parameter can be set.
EXAMPLE
name = Foo
title = "Wizz bang wallop"
" some parameter " = (
foo
bar
}
"an embeded \" quote" = bar
"an embeded \\ backslash" = wizz
EXTERNAL INCLUDE FILES
With large configuration files it can be desirable to split them into a
number of smaller files. If this capability is required, then the
"includes" feature can be requested. Each included file must follow the
syntax rules already described.
EXAMPLE
In the main file
name = Foo
title = "Wizz bang wallop"
foo = @include(somefile.cfg)
And in somefile.cfg
firstname = Joe
lastname = Blogs
Is equivalent to
name = Foo
title = "Wizz bang wallop"
foo = {
firstname = Joe
lastname = Blogs
}
METHODS
my $config = Config::Record->new([file => $file], [features =>
\%features]);
Creates a new config object, loading parameters from the file
specified by the "file" parameter. The "file" parameter can either
be a string representing a fully qualified filename, or a
IO::Handle object. If the "file" parameter is a string, this
filename will be saved and future calls to "load" or "save" are
permitted to omit the filename. If the "file" parameter is not
supplied then an empty configuration record is created.
The "features" parameter allows extra parser features to be
enabled. The two valid keys for the associated hash as "includes"
and "quotedkeys" as described earlier in this document.
$config->load([$file]);
Loads and parses a configuration record. The "file" parameter can
either be a string representing a fully qualified filename, or an
IO::Handle object. The $file parameter may be omitted, if a
filename was specified in the constructor, or in previous calls to
"load" or "save". Prior to loading the record, the current contents
of this configuration are cleared.
$config->save([$file]);
Saves the configuration record to a file. The "file" parameter can
either be a string representing a fully qualified filename, or an
IO::Handle object opened for writing. The $file parameter may be
omitted, if a filename was specified in the constructor, or in
previous calls to "load" or "save".
my $value = $config->get($key[, $default]);
Gets the value of a configuration parameter corresponding to the
name "key". If there is no value in the record, then the optional
"default" is returned.
$config->set($key, $value);
Sets the value of a configuration parameter corresponding to the
name "key".
$config->view($key)
Return a new Config::Record object, rooted at the specified key.
If the key doesn't resolve to a hash reference an error will be
raised.
my $record = $config->record();
Retrieves a hash reference for the entire configuration record.
Currently this is the actual internal storage record, so changes
will modify the configuration. In the next release this will be
changed to be a deep clone of the internal storage record.
BUGSConfig::Record has the following limitations
· If you load and then save a configuration file all comments are
removed & whitespace normalized.
· Ordering of elements in hash ref are not preserved across load and
save sequence
These limitations may be fixed in a future release if there is demand
from users...
AUTHORS
Daniel Berrange <dan@berrange.com>
COPYRIGHT
Copyright (C) 2000-2007 Daniel P. Berrange <dan@berrange.com>
SEE ALSOperl(1)perl v5.14.1 2007-12-12 Config::Record(3)