/ 
Config-Easy-0.3
River stage zero No dependents
/ Config::Easy

NAME

Config::Easy - Access to a simple key-value configuration file.

SYNOPSIS

Typical usage:

conf.txt contains:
-------
# vital information
name       Harriet
city       San Francisco

# options
verbose    1        # 0 or 1
-------

use Config::Easy 'conf.txt';

print "$C{name}\n" if $C{verbose};

Or for an object oriented approach:

use Config::Easy();

my $c = Config::Easy->new('conf.txt');

print $c->get('name'), "\n"
  if  $c->get('verbose');

For more details see the section OBJECT.

DESCRIPTION

The statement:

use Config::Easy "conf.txt";

will take the file named "conf.txt" in the current directory as the default configuration file.

Lines from the file have leading and trailing blanks trimmed. Comments begin with # and continue to the end of the line. Entirely blank lines are ignored.

Lines are divided into key and value at the first white space on the line. These key-value pairs are inserted into the %C hash which is then exported into the current package.

# personal information
empname     Harold
ssn         123-45-6789
phone       876-555-1212

print "$C{empname} - $C{ssn}\n";

The name is the minimal %C to visually emphasize the key name.

The file 'conf.txt' can be overridden with a -F command line option.

% prog -F newconf

It can also be -Fnewconf, if you wish.

To use a configuration file in the same directory as the perl script itself you can use the core module FindBin:

use FindBin;
use Config::Easy "$FindBin::Bin/conf.txt";

COMMAND LINE ARGUMENTS

Command line arguments are scanned looking for any with an equals sign in them.

% prog name=Mathilda status=okay

These arguments are extracted (removed from @ARGV), parsed into key=value and inserted into the %C hash. They will override any values in the configuration file. A warning is emitted if the key did not appear in the file.

This parsing of arguments will stop at an argument of '--'.

% prog name=Mary -- num=3

'-- num=3' can be processed by 'prog' itself.

ACCESS ELSEWHERE

If you want access to the configuration hash from other files simply put:

use Config::Easy;

at the top of those files; the %C hash will again be exported into the current package. You need to have:

use Config::Easy 'conf.txt';

only once in the main file before anyone needs to look at the %C hash.

STRICT

Installing the module Tie::StrictHash will protect against the common problem of misspelling of a key name:

use Config::Easy 'conf';
use Tie::StrictHash;
strict_hash %C;

print "name is $C{emplname}\n";

% prog
key 'emplname' does not exist at prog line 5
%

If there is access from other files you need the strict_hash call only in the main file.

CONTINUATION LINES

Lines ending with backslash are continued onto the next line. This allows:

ids   45 \
      67 \    # middle value
      89

instead of:

ids    45 67 89

Leading blanks on continuation lines are trimmed. Any blanks before the backslash are converted to a single blank.

STRING SUBSTITUTION

For a simple string substitution mechanism:

name        Harold
place       here
phrase      I'm $name and I'm $place.

This would yield:

$C{phrase} = "I'm Harold and I'm here.";

You can escape an actual dollar sign with a backslash '\'.

There is also a way to interpolate your (or rather our) variables into a configuration value.

In the configuration file:

path        /a/b/c.\$date.gz      # the dollar sign is escaped

In the code:

print $C{path};       #   /a/b/c.$date.gz
our $date = "20040102";
config_eval;
print $C{path};       #   /a/b/c.20040102.gz

The exported function 'config_eval' will interpolate 'our' (not 'my') variables from the main package into the %C values. You can give config_eval a list of which keys to evaluate, if you wish.

config_eval qw/path trigger/;

QUOTED VALUES

Leading and trailing blanks in the value are normally trimmed. If you do want such things quote the value field with single or double quotes. The quotes will be trimmed off for you.

foo     "   big one   "
bar     ' yeah '

If you want an actual # in the value escape it with a backslash.

title   The \# of hits.

MULTIPLE VALUES

Multiple valued values are possible by using references to anonymous arrays and hashes. This syntax in the configuration file:

colors [ red yellow blue green ]

will effectively do this:

$C{colors}  = [ qw(red yellow blue green) ];

In your program you can have:

for my $c (@{$C{colors}}) {
    ...
}

or

print $C{colors}[2];

Similarily:

ages  { joe   45 \
        betty 47 \
        mary  13 \       # their daughter
      }

does this:

$C{ages} = { joe   => 45,
             betty => 47
             mary  => 13,
           };

In both cases neither the values nor the keys can have internal blanks. If you need this you could use underscores for this purpose and replace them with blanks later.

If a value begins with ', ", [, or { and does not end with the matching delimiter then further lines will be read until such a line is found. This makes the syntax cleaner and more maintainable:

ages {
    joe   45
    betty 47
    mary  13       # their daughter
}

MULTI-LINE VALUES

If you wish a single value to span multiple lines:

story -
Once upon  a time
there was a fellow named
$name who lived peacefully
in the town of $city.
.

If the value is '-' alone, it indicates that the real value is all following lines up until a period '.' is seen on a line by itself. String substitution will still take place. $C{story} from above will have 4 embedded newlines.

OBJECT

Some may object to their namespace being 'polluted' with the %C hash or find the name %C too cryptic. They also may not like command line arguments being parsed and extracted by any module except those named Getopt::*.

For these users there is a pure object oriented interface:

use Config::Easy();    # the () is required so that
                       # nothing is done at import() time.
my $c = Config::Easy->new('conf.txt');

$c->args;        # parse command line arguments (optional)

#
# the get method can be called in several ways
#
print "name is ", $c->get('name'), "\n";          #  the key 'name'

my ($age, $status) = $c->get(qw/ age status /);   # two at once

my %config = $c->get;                             # gets entire hash
print $config{name};

You can have multiple instances of the Config::Easy object.

The get method enforces 'strict' behavior. If you use a key name that does not occur in the configuration file it will die with an error message.

print $c->get("oops");

% prog
key 'oops' does not exist at prog line 10.

Methods 'strict' and 'no_strict' turn this behavior on and off.

'config_eval' is a method to interpolate 'our' variables. See STRING SUBSTITUTION above.

SEE ALSO

Tie::StrictHash protects against misspelling of key names.

Getopt::Easy is a clear and simple alternative to Getopt::Std and Getopt::Long.

Date::Simple is an elegant way of dealing with dates.

AUTHOR

Jon Bjornstad <jonb@logicalpoetry.com>