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");

         # 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
       possible 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 embedded \" quote" = bar
         "an embedded \\ 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.

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

       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 ALSO

       perl(1)