NAME

App::ConfigWild - parse an application configuration file

SYNOPSIS

  use App::ConfigWild;
  $cfg = new ConfigWild;
  $cfg = new ConfigWild "configfile";

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 ConfigWild 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 ConfigWild 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 ConfigWild variable, it is assumed to be and 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 ConfigWild 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 ConfigWild ([$config_file])

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

load( $file )

Load information from a configuration file into the current object. New configuration values will supersede previous ones, in a 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( \@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 list of attributes:

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 objects error message (see errmsg()).

For example,

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

set( $keyword, $value )

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

value( $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( $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( $keyword )

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

set_attr( \%attr )

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

UNDEF

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 = new ConfigWild "foo.cnf";
  $cfg->set_attr( { 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.

PrintError

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.

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->value( '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.

AUTHOR

Diab Jerius ( djerius@cfa.harvard.edu )

This package was heavily influenced by App::Config by Andy Wardley.

REVISION

$Revision: 1.7 $