NAME

Config::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.bar");

# Get a config value, return 'eek' if not found
my $value = $config->get("foo.bar", "eek");

# Set a value
$config->set("foo.bar", "wizz");

my $record = $config->record();

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....    "

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"
}

METHODS

my $config = Config::Record->new([file => $file]);

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 not supplied then an empty configuration record is created.

$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. 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.

$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->param($key[, $default]);

This method is a (deprecated) alias for $config->get($key[, $default]). It will be removed in a future release.

$config->set($key, $value);

Sets the value of a configuration parameter corresponding to the name key.

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.

BUGS

Config::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

* It is not possible to have a value continue across multiple lines

* When getting a parameter value it is not possible to specify an
  index into an array reference, eg $cfg->get('foo.bar[3].wizz');

It is planned to fix all these problems in a future release.

AUTHORS

Daniel Berrange <dan@berrange.com>

COPYRIGHT

Copyright (C) 2000-2004 Daniel P. Berrange <dan@berrange.com>

SEE ALSO

perl(1)