Daniel P. Berrangé > Config-Record-1.1.2 > Config::Record

Download:
Config-Record-1.1.2.tar.gz

Dependencies

Annotate this POD

Website

View/Report Bugs
Module Version: 1.1.2   Source  

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

BUGS ^

Config::Record has the following limitations

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)

syntax highlighting: