The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Config-Wild-1.4
River stage zero No dependents
++
/ Config::Wild

NAME

Config::Wild - parse an application configuration file with wildcard keywords

SYNOPSIS

  use Config::Wild;
  $cfg = Config::Wild->new();
  $cfg = Config::Wild->new( $configfile, \%attr );

DESCRIPTION

This is a simple package to parse and present to an application configuration information read from a configuration file. Configuration information in the file has the form

  keyword = value

where keyword is a token which may contain Perl regular expressions surrounded by curly brackets, i.e.

  foobar.{\d+}.name = goo

and value is the remainder of the line after any whitespace following the = character is removed.

Keywords which contain regular expressions are termed wildcard keywords; those without are called absolute keywords. Wildcard keywords serve as templates to allow grouping of keywords which have the same value. For instance, say you've got a set of keywords which normally have the same value, but where on occaision you'd like to override the default:

  p.{\d+}.foo = goo
  p.99.foo = flabber

value may reference environmental variables or other Config::Wild variables via the following expressions:

  • Environment variables may be accessed via ${var}:

      foo = ${HOME}/foo

    If the variable doesn't exist, the expression is replaced with an empty string.

  • Other Config::Wild variables may be accessed via $(var).

      root = ${HOME}
  foo = $(root)/foo

    If the variable doesn't exist, the expression is replaced with an empty string. Variable expansions can be nested, as in

      root = /root
  branch = $(root)/branch
  tree = $(branch)/tree

    tree will evaluate to /root/branch/tree.

  • Either type of variable may be accessed via $var. In this case, if var is not a Config::Wild variable, it is assumed to be an environmental variable. If the variable doesn't exist, the expression is left as is.

Substitutions are made when the value method is called, not when the values are first read in.

Lines which begin with the # character are ignored. There is also a set of directives which alter the where and how Config::Wild reads configuration information. Each directive begins with the % character and appears alone on a line in the config file:

%include file

Temporarily interrupt parsing of the current input file, and switch the input stream to the specified file.

METHODS

new
  $cfg = Config::Wild->new( \%attr );
  $cfg = Config::Wild->new( $config_file, \%attr );

Create a new Config::Wild object, optionally loading configuration information from a file. It returns the new object, or undef upon error.

Additional attributes which modify the behavior of the object may be specified in the passed %attr hash. They may also be specifed or modified after object creation using the set_attr method.

The following attributes are available:

UNDEF = function

This defines a function to be called when the value of an undefined keyword is requested. The function is passed the name of the keyword. It should return a value, which will be returned as the value of the keyword.

For example,

  $cfg = Config::Wild->new( "foo.cnf", { UNDEF => \&undefined_keyword } );

  sub undefined_keyword
  {
    my $keyword = shift;
    return 33;
  }

You may also use this to centralize error messages:

  sub undefined_keyword
  {
    my $keyword = shift;
    die("undefined keyword requested: $keyword\n");
  }

To reset this to the default behavior, set UNDEF to undef:

  $cfg->set_attr( UNDEF => undef );
PrintError = boolean

If true, all errors will result in a call to warn(). If it is set to a reference to a function, that function will be called instead.

dir = directory

If specified the current working directory will be changed to the specified directory before a configuration file is loaded.

load
  $cfg->load( $file );

Load information from a configuration file into the current object. New configuration values will supersede previous ones, in the following complicated fashion. Absolutely specified keywords will overwrite previously absolutely specified values. Since it is difficult to determine whether the set of keywords matched by two regular expressions overlap, wildcard keywords are pushed onto a last-in first-out (LIFO) list, so that when the application requests a value, it will use search the wildcard keywords in reverse order that they were specified.

It returns 1 upon success, undef if an error ocurred. The error message may be retrieved with the errmsg method.

load_cmd
  $cfg->load_cmd( \@ARGV );
  $cfg->load_cmd( \@ARGV,\%attr );

Parse an array of keyword-value pairs (possibly command line arguments), and insert them into the list of keywords. It can take an optional hash of attributes with the following values:

Exists

If true, the keywords must already exist. An error will be returned if the keyword isn't in the absolute list, or doesn't match against the wildcards.

Upon success, it returns 1, upon error it returns undef and sets the object's error message (see errmsg()).

For example,

  $cfg->load_cmd( \@ARGV, { Exists => 1} )
    || die( $cfg->errmsg, "\n" );
set
  $cfg->set( $keyword, $value );

Explicitly set a keyword to a value. Useful to specify keywords that should be available before parsing the configuration file.

get
  $value = $cfg->get( $keyword );

Return the value associated with a given keyword. $keyword is first matched against the absolute keywords, then agains the wildcards. If no match is made, undef is returned.

delete
  $cfg->delete( $keyword );

Delete $keyword from the list of keywords (either absolute or wild) stored in the object. The keyword must be an exact match. It is not an error to delete a keyword which doesn't exist.

exists
  $exists = $cfg->exists( $keyword );

Returns non-zero if the given keyword matches against the list of keywords in the object, undef if not.

set_attr
  $cfg->set_attr( \%attr );

Set internal configuration parameters. It returns undef and sets the object's error message upon error. The available parameters are:

errmsg

Returns the last error message stored in the object;

There are also "hidden" methods which allow more natural access to keywords. You may access a keyword's value by specifying the keyword as the method, instead of using value. The following are equivalent:

   $foo = $cfg->get( 'keyword' );
   $foo = $cfg->keyword;

If keyword doesn't exist, it returns undef.

Similarly, you can set a keyword's value using a similar syntax. The following are equivalent, if the keyword already exists:

   $cfg->set( 'keyword', $value );
   $cfg->keyword( $value );

If the keyword doesn't exist, the second statement does nothing.

It is a bit more time consuming to use these methods rather than using set and value.

COPYRIGHT & LICENSE

Copyright 1998-2011 Smithsonian Astrophysical Observatory

This software is released under the GNU General Public License. You may find a copy at

   http://www.fsf.org/copyleft/gpl.html

SEE ALSO

AppConfig, an early version of which was the inspiration for this module.

AUTHOR

Diab Jerius, <djerius@cpan.org>