NAME
    App::Config - Perl5 extension for managing global application
    configuration information.

SYNOPSIS
        use App::Config;
        my $cfg = new App::Config;

        $cfg->define("foo");            # very simple variable definition

        $cfg->set("foo", 123);          # trivial set/get examples
        $fval = $cfg->get("foo");      
        
        $cfg->foo(456);                 # direct variable access 

        $cfg->cfg_file(".myconfigrc");  # read config file
        $cfg->cmd_line(\@ARGV);         # process command line

OVERVIEW
    App::Config is a Perl5 module to handle global configuration
    variables for perl programs. The advantages of using such a
    module over the standard "global variables" approach include:

    *   Reduction of clutter in the main namespace.

    *   Default values can be specified.

    *   Multiple names (aliases) can refer to the same variable.

    *   Configuration values can be set directly from config files
        and/or command line arguments.

    *   Data values can be automatically validated by pattern matching
        (e.g. "\d+" to accept digits only) or through user-supplied
        routines.

    *   User-defined routines can be called automatically when
        configuration values are changed.

PREREQUISITES
    App::Config requires Perl version 5.004 or later. If you have an
    older version of Perl, please upgrade to latest version. Perl
    5.004 is known to be stable and includes new features and bug
    fixes over previous versions. Perl itself is available from your
    nearest CPAN site (see http://www.perl.com/CPAN).

INSTALLATION
    To install this module type the following:

        perl Makefile.PL
        make
        make install

    The 'make install' will install the module on your system. You
    may need root access to perform this task. If you install the
    module in a local directory (for example, by executing "perl
    Makefile.PL LIB=~/lib" in the above - see `perldoc MakeMaker'
    for full details), you will need to ensure that the PERL5LIB
    environment variable is set to include the location, or add a
    line to your scripts explicitly naming the library location: use
    lib '/local/path/to/lib';

DESCRIPTION
  USING THE App::Config MODULE

    To import and use the App::COnfig module the following line
    should appear in your Perl script: use App::Config; App::Config
    is implemented using object-oriented methods. A new App::Config
    object is created and initialised using the App::Config->new()
    method. This returns a reference to a new App::Config object. my
    $cfg = App::Config->new();

    This will create a reference to a new App::Config with all
    configuration options set to their default values. You can
    initialise the object by passing a hash array reference
    containing configuration options:

        $cfg = App::Config->new( {
            CASE      => 1,
            FILEPARSE => \&my_parser,
            ERROR     => \&my_error,
        } );

    The following configuration options may be specified. Some of
    these use default values as may be specified in the GLOBAL
    configuration option.

    CASE
        Determines if the variable names are treated case
        sensitively. Any non-zero value makes case significant when
        naming variables. By default, CASE is set to 0 and thus
        "Variable", "VARIABLE" and "VaRiAbLe" are all treated as
        "variable".

    ERROR
        Specifies a user-defined error handling routine. A format
        string is passed as the first parameter, followed by any
        additional values, as per printf(3C).

    FILEPARSE
        Specifies a user-defined routine for parsing a configuration
        file. The function is called by `cfg_file()' and is passed a
        reference to the App::Config object and the name of the file
        to parse. The routine should update any variable values
        directly. The return value is expected to be 1 to indicate
        success or 0 to indicate failure. This value is returned
        directly from `cfg_file()';

        Pseudo-Code Example:

            $cfg = App::Config->new( { FILEPARSE => \&my_parser } );

            sub my_parser {
                my $cfg  = shift;
                my $file = shift;

                # open file, read lines, etc.
                # ...
                $cfg->set($variable, $value);  # set variable value 
                # close file, etc.

                return 1;
            }

    LINEPARSE
        Instead of providing a routine to parse the entire config
        file, LINEPARSE can be used to define a function to handle
        each line of the config file. The `cfg_file()' routine reads
        the file and passes each line to the LINEPARSE function,
        where defined.

        Four parameters are passed to the LINEPARSE function; a
        reference to the App::Config object, the config filename,
        the current line within the file and the line of text itself
        (the filename and line number are useful for reporting
        errors). Note that `cfg_file()' does some elementary pre-
        processing before calling the LINEPARSE function. See the
        section on "READING A CONFIGURATION FILE" for more details.

        The function should return 1 to indicate that the line has
        been successfully parsed, or 0 to indicate that no action
        was taken and the default line parser should now be used for
        this line.

    CMDPARSE
        Specifies a user-defined routine for parsing the command
        line. The function is called by cmd_line() and is passed a
        reference to the App::Config object and a reference to a
        list of command line arguments (usually @ARGV).

        The function is required to set variable values directly and
        return 1 or 0 to indicate success or failure, as is
        described in the FILEPARSE section above.

    ARGPARSE
        Just as a LINEPARSE routine can be defined to parse each
        line of a config file, an ARGPARSE routine can also be
        specified to parse each command line argument. The function
        is called from cmd_line() and is passed a reference to the
        App::Config object through which variable values can be
        manipulated. Other parameters passed are the command line
        argument in question (e.g. `"-v"'), the name of the variable
        to which it corresponds (e.g. `"verbose"') and a reference
        to the remaining argument list. The function is expected to
        modify the argument list if necessary, shifting off
        additional parameters where required.

        A pseudo-code example is shown:

            my $cfg = App::Config->new( { ARGPARSE => \&my_arg_parse, } );

            sub my_arg_parse {
                my $cfg     = shift;
                my $arg     = shift;
                my $var     = shift;
                my $argvref = shift;

                VAR: {
                    $var eq 'verbose' && do {  
                        $cfg->set($var, 1);
                        last VAR;
                    };

                    # this time, look at $arg instead of $var
                    $arg eq '-f' && do {
                        $cfg->set($var, shift(@$argvref));  # should error check
                        last VAR;
                    };

                    # not interested in anything else
                    # (let default parser have a go)
                    return 0;
                }

                # we processed it so return 1
                return 1;
            }
                        
        =item CMDENV

        The CMDENV option is used to specify the name of an
        environment variable which may contain default command line
        options. If defined, the variable is examined by the
        cmd_line() routine where it is split into whitespace
        separated tokens and parsed along with the rest of the
        command line options. Environment variable options are
        processed before any real command line options.

        Note that the variable is split on whitespace and does not
        take into account quoted whitespace. Thus 'foo "bar baz"
        qux' will be split into the tokens 'foo', '"bar', 'baz"' and
        'qux'. This will be fixed in a future release.

        From the Unix shell:

            $ SPLATOPTS="-z -f foobar"

        Perl App::Config usage:

            my $cfg = App::Config->new( { CMDENV => "SPLATOPTS" } );

            $cfg->cmd_line(\@ARGV);   # parses ("-z", "-f", "foobar", @ARGV)

    ENDOFARGS
        The ENDOFARGS option can be used to specify the marker that
        signifies the end of the command line argument list.
        Typically, and by default, this is '--'. Any arguments
        appearing in the command line after this token will be
        ignored.

            my $cfg = App::Config->new( { ENDOFARGS => "STOP" } );

            @args = qw(-f -g -h STOP -i -am -ignored);
            $cfg->cmd_line(\@args);

            # @args now contains qw(-i -am -ignored) 

    GLOBAL
        The GLOBAL option allows default values to be set for the
        ARGCOUNT, EXPAND, CMDARG and VALIDATE options for all
        variables. the section on "DEFINING VARIABLES" below
        describes these options in detail.

        The CMDARG global option, when set to any true value,
        specifies that the command line option for any variable
        should be of the form "-variable". Any aliases specified for
        a variable can also be used in this way. e.g.

            my $cfg = App::Config->new({
                    GLOBAL => { ARGCOUNT => 1, CMDARG => 1 }
                });

            $cfg->define("foo", { 
                    ALIAS  => 'bar' 
                });

        The GLOBAL ARGCOUNT parameter specifies that the foo
        variable expects an argument. An ARGCOUNT option specified
        in the `define()' method call would override this default.
        The GLOBAL CMDARG option specifies that the 'foo' variable
        should be specified on the command line as '-foo'. The ALIAS
        name for foo can also be specified as such: '-bar'.

  DEFINING VARIABLES

    The `define()' function is used to pre-declare a variable and
    specify its configuration.

        $cfg->define("foo");

    In the simple example above, a new variable called "foo" is
    defined. A reference to a hash array may also be passed to
    specify configuration information for the variable:

        $cfg->define("foo", {
                DEFAULT   => 99,
                ALIAS     => 'metavar1',
            });

    The following configuration options may be specified

    DEFAULT
        The DEFAULT value is used to initialise the variable. The
        variable remains set to this value unless otherwise changed
        via `set()', `cfg_file()' or `cmd_line()'.

    ALIAS
        The ALIAS option allows a number of alternative names to be
        specified for this variable. A single alias should be
        specified as a string, multiple aliases as a reference to an
        array. e.g.:

            $cfg->define("foo", {
                    ALIAS  => 'metavar1',
                });

        or

            $cfg->define("bar", {
                    ALIAS => [ 'metavar2', 'metalrod', 'boozer' ],
                });

        In the first example, `$cfg->set("metavar1")' (or any other
        variable-related function) is equivalent to `$cfg-
        >set("foo")'. Likewise for the second example, with all 3
        aliases defined.

    CMDARG
        When processing a list of command line arguments, flags may
        be used to refer to certain variable values. For example, `-
        v' is a common flag indicating verbose mode. The 'verbose'
        variable might be defined as such:

            $cfg->define("verbose", {
                    CMDARG => '-v',
                });

        If the `cmd_line()' function detects `-v' in the command
        line arguments, it will update the 'verbose' value. See also
        the ARGCOUNT option below which influences the variable
        values that are set by the command line processing function.

        A variable may have more than one related command line
        argument. These can be specified by passing a reference to
        an array of arguments:

            $cfg->define("verbose", {
                    CMDARG => [ '-v', '-V' ],
                });

        If the GLOBAL CMDARG variable is set (the GLOBAL manpage
        above) then the default CMDARG for each variable will be its
        name (and any aliases) prefixed by a dash, e.g. '-verbose'.
        Any CMADRG value specifically set will override this
        default.

    ARGCOUNT
        Some variables are intended to be simple flags that have a
        false/true (zero/non-zero) value (e.g. the 'verbose' example
        above) while others may require mandatory arguments (e.g.
        specifying a file: `"-f filename"'). The ARGCOUNT value is
        used to determine if an additional argument is expected
        (`ARGCOUNT => 1') or not (`ARGCOUNT => 0').

        When ARGCOUNT is 1, `cfg_file()' passes the rest of the
        config line (after the opening variable name has been
        removed) as the argument value and `cmd_line()' passes the
        next argument from the command line argument list (usually
        @ARGV). When ARGCOUNT is 0, both functions pass the value 1
        to set the variable to a true state. The default ARGCOUNT
        value is 0.

        If the GLOBAL ARGCOUNT variable is set (the GLOBAL manpage
        above) then this value will be used as the default ARGCOUNT
        for each variable unless otherwise specified.

        NOTE: Although any non-zero value can be used to indicate
        the presence of an additional argument, this option may be
        extended in the future to handle multiple arguments. The
        behaviour associated with any value other than 1 or 0 may
        change in subsequent versions.

    EXPAND
        Variable values specified in a configuration file (see the
        section on "READING A CONFIGURATION FILE") may contain
        environment variables, other App::Config variables and/or
        users' home directories specified in tilde notation (e.g.
        ~abw). The EXPAND option specifies if these variables should
        be replaced with their relevant values. By default EXPAND is
        set to 1 (expansion) but can be set to 0 to disable the
        feature.

        If the GLOBAL EXPAND variable is set (the GLOBAL manpage
        above) then this value will be used as the default EXPAND
        for each variable unless otherwise specified.

        Items are expanded according to the following rules:

    *       A directory element specified in tilde notation is expanded
            to the full directory path it represents (e.g. ~abw/lib
            => /user/abw/lib). A tilde by itself expands to the home
            directory of the current user (e.g. ~/lib =>
            /users/abw/lib). If a non-existant user is specified or
            it is not possible to determine the home directory of
            the user, the tilde notation is left unexpanded (e.g.
            ~nosuchuser/lib).

    *       A variable enclosed in braces and prefixed with a dollar
            symbol (e.g. ${HOME}) is assumed to be an environment
            variable and is expanded as such. A non-existant
            variable will be replaced by an empty string, as is
            typical in UNIX shell expansion (e.g. ${DUD}/lib =>
            /lib).

    *       A variable enclosed in parenthesis and prefixed with a
            dollar symbol (e.g. $(ROOT)) is assumed to refer to
            another variable defined in the current App::Config
            object. Case sensitivity is applied as per the current
            CASE setting and non-existant variables are replaced by
            an empty string as per environment variables (e.g.
            $(mipspelt)/lib => /lib).

    *       A variable prefixed with a dollar and with no enclosing
            braces or parenthesis (e.g. $root/lib) is first
            interpreted as an App::Config variable and if not
            resolved, as an environment variable. If the variable
            cannot be evaluated in either context it is ignored and
            the original text is left unmodified.

    VALIDATE
        Each variable may have a sub-routine or regular expression
        defined which is used to validate the intended value that is
        set by `cfg_file()' and `cmd_line()'.

        If VALIDATE is defined as a simple string, it is applied as
        a regular expression to the value read from the config file
        or command line. If the regex matches, the value is set. If
        not, a warning message is generated.

        VALIDATE may also be defined as a reference to a sub-routine
        which takes as its arguments the name of the variable and
        its intended value. The sub-routine should return 1 or 0 to
        indicate that the value is valid or invalid, respectively.
        An invalid value will cause a warning error message to be
        generated.

        If the GLOBAL VALIDATE variable is set (the GLOBAL manpage
        above) then this value will be used as the default VALIDATE
        for each variable unless otherwise specified.

    ACTION
        The ACTION option allows a sub-routine to be bound to a
        variable that is executed whenever the variable is set. The
        ACTION is passed a reference to the App::Config object, the
        name of the variable and the value of the variable.

        The ACTION routine may be used, for example, to post-process
        variable data, update the value of some other dependant
        variable, generate a warning message, etc.

        Example:

            sub my_notify {
                my $cfg = shift;
                my $var = shift;
                my $val = shift;

                print "$variable set to $value\n";
            }

        Be aware that calling `$cfg->set()' to update the variable
        from within the ACTION function will cause a recursive loop
        as the ACTION function is repeatedly called. This is
        probably a bug, certainly a limitation.

      READING AND MODIFYING VARIABLE VALUES

    App::Config defines two methods to manipulate variable values:

        set($variable, $value);
        get($variable);

    Both functions take the variable name as the first parameter and
    `set()' takes an additional parameter which is the new value for
    the variable. `set()' returns 1 or 0 to indicate successful or
    unsuccessful update of the variable value. If there is an ACTION
    routine associated with the named variable, the value returned
    will be passed back from `set()'. The `get()' function returns
    the current value of the variable.

    Once defined, variables may be accessed directly as object
    methods where the method name is the same as the variable name.
    i.e.

        $cfg->set("verbose", 1);

    is equivalent to

        $cfg->verbose(1); 

    Without parameters, the current value of the variable is
    returned. If a parameter is specified, the variable is set to
    that value and the original value (before modification) is
    returned.

        $cfg->age(28);  
        $cfg->age(29);  # sets 'age' to 29, returns 28

  READING A CONFIGURATION FILE

    App::Config can be used to read configuration files and
    automatically update variable values based on the contents of
    the file.

        $cfg->cfg_file("$HOME/.myapprc");

    The `cfg_file()' function reads each line of the specified
    configuration file and processes them according to the following
    rules:

    *   Any lines ending with a backslash '\' are treated as
        continuation lines. The following line is appended to the
        current line (and any subsequent continuation lines) before
        any further processing.

    *   Any blank lines or lines starting with a '#' (i.e. comments) are
        ignored.

    *   Leading and trailing whitespace is ignored.

    *   The line is separated at the first whitespace character or at
        the first `'='' character (surrounding whitespace is
        ignored).

    *   A variable by itself with no corresponding value will be treated
        as a simple flag if it's ARGCOUNT is 0. In this case, the
        value for the variable will be set to 1.

    The following example demonstrates a typical configuration file:

        # simple flag (same as " verbose 1" or "verbose = 1")
        verbose

        # the following lines are all equivalent
        file     /tmp/foobar
        file  =  /tmp/foobar
        file=/tmp/foo

  PARSING THE COMMAND LINE

    By specify CMDARG values for defined variables, the `cmd_line()'
    function can be used to read the command line parameters and
    automatically set variables.

    When an command line argument matches a CMDARG value, the
    variable it relates to is updated. If the variable has an
    ARGCOUNT of 0, it will be assigned the value 1 (i.e. the flag is
    set). A variable with an ARGCOUNT of 1 will be set with the next
    value in the arguments. Users familiar with getopt(3C) will
    recognise this as equivalent to adding a colon after an option
    letter (e.g. `"f:"'). An error is generated if the argument
    starts with a '-'. The special option "--" may be used to
    delimit the end of the options. `cmd_line()' stops processing if
    it finds this option.

    Example variable definition:

        $cfg->define("verbose", {
                CMDARG   => '-v',
                ARGCOUNT => 0,      # default anyway
            });
        $cfg->define("file", {
                CMDARG   => '-f',
                ARGCOUNT => 1,      # expects an argument
            });

    Command-line options:

        -v -f foobar

    Variable values after calling `cmd_line(\@ARGV)':

        verbose: 1
        file:    foobar

KNOWN BUGS AND LIMITATIONS
    The following list represents known limitations or bugs in
    App::Config or ways in which it may be improved in the future.
    Please contact the author if you have any suggestions or
    comments.

    *   An ACTION sub-routine may not update its variable via the $cfg-
        >set() method. This causes the ACTION function to be re-
        executed, starting a recursive loop.

    *   More extensive variable validation (not using user-defined
        functions), perhaps by defining standard classes (e.g.
        numeric, filename, list, etc). Variable validation may be
        also extended to allow manipulation of the data as well
        (e.g. splitting a string into a list).

    *   Further extend command line parsing. Maybe allow regexes to be
        specified for matches (e.g. `"-v(erbose)"') and handle
        different command line characters other than `'-'' (e.g.
        `+flag @file'). This may also tie in with long (--) and
        short (-) options and defining recognised 'classes' of
        options.

    *   ARGCOUNT should be able to indicate nargs > 1 and have cmd_line
        extract them accordingly. Perhaps have types, e.g. boolean,
        single, multiple. The validate function could additionally
        take an array ref which contains code refs or regex's to
        match each arg. Should also be able to handle multiple
        options that can be specified separately, e.g. `-
        I/usr/include' `-I/user/abw/include'.

    *   An ACCESS parameter could specify which actions may update a
        variable: set(), cfg_file() and/or cmd_line().

    *   Allow variables to have related environment variables which are
        parsed by an env_vars() function.

AUTHOR
    Andy Wardley, `<abw@cre.canon.co.uk>'

    Web Technology Group, Canon Research Centre Europe Ltd.

    App::Config is based in part on the ConfigReader module, v0.5,
    by Andrew Wilcox (currently untraceable).

    Thanks to all the people who have reported bugs and made
    suggestions. Extra special thanks to those who sent patches:

        Mik Firestone <fireston@lexmark.com>
            * GLOBAL arguments

        Blair Zajac <blair@gps.caltech.edu>
            * getpw*() check for Win32 compatibility

REVISION
    $Revision: 1.7 $

COPYRIGHT
    Copyright (C) 1997,98 Canon Research Centre Europe Ltd. All
    Rights Reserved.

    This module is free software; you can redistribute it and/or
    modify it under the term of the Perl Artistic License.

SEE ALSO
    Andy Wardley's Home Page
        http://www.kfs.org/~abw/

    Canon Research Centre Europe
        http://www.cre.canon.co.uk/perl/

    The ConfigReader module.
        The module which provided inspiration and ideas for the
        development of App::Config.