NAME

Config::Cascade - simple configuration file framework for managing multi-level configurations, with regexp validation.

VERSION

Version 0.02

SYNOPSIS

Config::Cascade is intended to allow the use of global configurations in combination with more specific configs, with the added benefit of overriding all of these settings from the command line. This benefit allows the use of a standard base config, with a simple format, while allowing custom configs for multiple programs utilizing the same resources or configurations. Validated configuration options will function in both global and specific configuration files, and may also be referenced from the command line using Getopt::Long and getopt style notation: --<option>=<value> or -<alias>=<value>

Example:

    use Config::Cascade;
    my %config = Config::Cascade->new(  
                                        configDir => '/etc/Frood', 
                                        globalConfig => 'global.cfg', 
                                        configFile => 'example.cfg',
                                        validate => {
                                                host => {type => 'fqdn'},
                                                port => {type => 'regexp', args=> 'RE::num::int'},
                                                url => {type => 'regexp', args => '^http:'},
                                                },
                                     );

    print $config{host};

Validation File format

A validation file follows a simple format, one entry per line:

<Config variable name> <data type> <optional arguments>

Config variable names are arbitrary, but must be single strings, sans white space. The following is a list of valid data types.

alias - Declares this entry to be an alias for another. Alias requires an optional argument referring to the parent option.

bool - Sets the value to '1' if present.

int - Matches the equiv of $RE{num}{int}

fqdn - Matches fully qualified domain names for formatting, using $RE{net}{domain}

regexp - Matches a free form regular expression, or refers to an entry in Regexp::Common. This requires an optional argument of a valid regular expression, or RE reference. Specifying 'RE::' informs the parser a Regexp::Common regexp is being invoked, with subsequent delimited entries corresponding to Regexp::Common's multi-level hash syntax. Otherwise, the contents of args will be precompiled as-is and matched accordingly.

string - Matches the equiv of /\w+/

Config File format

A configuration file follows a simple format, one entry per line: <Config variable name> <value>

FUNCTIONS

new

        Performs start-up sanity checks and functions. The module will at first attempt to load a 
global configuration file, if available. After that, a more specific configuration file (if available),
is loaded, overriding any settings in the global configuration that collide. After that, command line
options then override any loaded settings that collide.

        Valid options:
                configDir - Specifies a directory containing configuration files.
                        - If not specified, will use the current working directory.
                configFile - Specifies a specific configuration file to be read.
                        - If not specifed, will be ignored.
                debug - enables debug output.
                globalConfig - Specifies a global config shared between multiple programs.
                        - If not specified, global.cfg will be looked for in the specified configDir.
                noCommandLine - Skips parsing of @ARGV.
                noConfig - Skips reading of configuration files. Command line options will be used.
                noValidation - Skips use of validation functions entirely. 
                validate - Optional hash structure containing validation instructions.
                validationFile - Specifies a file containing configuration validation instructions.
                        - If not specified, global.validation will be looked for in the specified configDir.

AUTHOR

Bill Nash, <billn@billn.net>

ACKNOWLEDGEMENTS

Thanks go to bline, dngor, Somni, the letter P, and the number 2.

COPYRIGHT & LICENSE

Copyright 2005 Bill Nash, All Rights Reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.