NAME
       # TODO AppConfig - Perl5 module for managing application
       configuration information.

SYNOPSIS
           use AppConfig;

           # create a new AppConfig
           my $config = AppConfig->new(\%cfg, @vardefs);

           # define a new variable
           $config->define($varname, \%varopts);

           # set/get the value
           $config->set($varname, $value);
           $config->get($varname);

           # shortcut form
           $config->varname($value);
           $config->varname();

           # read configuration file
           $config->file($file);

           # parse command line options
           $config->args(\@ARGV);


OVERVIEW
       AppConfig is a Perl5 module to handle global configuration
       variables for perl programs.

       It maintains the state of any number of variables,
       handling default values, aliasing, validation, update
       callbacks and option arguments for use by AppConfig::*
       modules.

       The module handles the parsing of configuration files and
       command line arguments.

PREREQUISITES
       AppConfig requires Perl 5.004 or later.

OBTAINING AND INSTALLING THE AppConfig MODULE BUNDLE
       The AppConfig module bundle is available from CPAN.  As
       the 'perlmod' manual page explains:

           CPAN stands for the Comprehensive Perl Archive Network.
           This is a globally replicated collection of all known Perl
           materials, including hundreds of unbunded modules.

           [...]

           For an up-to-date listing of CPAN sites, see
           http://www.perl.com/perl/ or ftp://ftp.perl.com/perl/ .

       Within the CPAN archive, AppConfig is in the category:

         *) TODO: what's the name of this category?

       The module is available in the following directories:

       # TODO: check this

           /modules/by-module/AppConfig-<version>.tar.gz
           /authors/id/ABW/AppConfig-<version>.tar.gz

       AppConfig is distributed as a single gzipped tar archive
       file:

           AppConfig-<version>.tar.gz

       Note that "<version>" represents the current AppConfig
       Revision number, of the form "2.00".  See the REVISION
       manpage below to determine the current version number for
       AppConfig.

       Unpack the archive to create a AppConfig installation
       directory:

           gunzip AppConfig-<version>.tar.gz
           tar xvf AppConfig-<version>.tar

       'cd' into that directory, make, test and install the
       modules:

           cd AppConfig-<version>
           perl Makefile.PL
           make
           make test
           make install

       The 't' sub-directory contains a number of small sample
       files which are processed by the test script (called by
       'make test').  See the README file in that directory for
       more information.

       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';

       The 'examples' sub-directory contains some simple examples
       of using the AppConfig modules.

DESCRIPTION
       USING THE AppConfig MODULE

       To import and use the AppConfig module the following line
       should appear in your Perl script:

            use AppConfig;

       AppConfig is implemented using object-oriented methods.  A
       new AppConfig object is created and initialised using the
       new() method.  This returns a reference to a new AppConfig
       object.

           my $config = AppConfig->new();

       This will create and return a reference to a new AppConfig
       object.

       In doing so, the AppConfig object also creates an internal
       reference to an App::State object in which to store
       variable state.  All arguments passed into the AppConfig
       constructor are passed directly to the App::State
       constructor.

       See the App::State manpage for full details of the
       configuration options available.

       Note that any unresolved method calls to AppConfig are
       automatically delegated to the AppConfig::State object.
       In practice, it means that it is possible to treat the
       AppConfig object as if it were an AppConfig::State object:

           # create AppConfig
           my $config = AppConfig->new('foo', 'bar');

           # methods get passed through to internal AppConfig::State
           $config->foo(100);
           $config->set('bar', 200);
           $config->define('baz');
           $config->baz(300);



       DEFINING VARIABLES

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

           $config->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:

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

       See L<AppConfig::State) for further details of the
       configuration options available when defining variables.

       READING AND MODIFYING VARIABLE VALUES

       AppConfig defines two methods to manipulate variable
       values:

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

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

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

       is equivalent to

           $config->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.

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


       READING CONFIGURATION FILES

       The AppConfig module provides a streamlined interface for
       reading configuration files with the AppConfig::File
       module.  The file() method automatically loads the
       AppConfig::File module and creates an object to process
       the configuration file(s).  Variables stored in the
       internal AppConfig::State are automatically updated with
       values specified in the configuration file.

           $config->file($file);

       Multiple files may be passed to file() and should indicate
       the file name or be a reference to an open file handle or
       glob.

           $config->file($file, $filehandle, \*STDIN, ...);

       The configuration file should contain lines of the form:

           variable = value

       The separating '=' is optional.

       Variables that are simple flags and do not expect an
       argument (ARGS = 0) can be specified without any value.
       They will be set with the value 1.

       Variable values may contain references to other AppConfig
       variables, environment variables and/or users' home
       directories.  These will be expanded depending on the
       EXPAND value set in the AppConfig::State.  Three different
       expansion types may be applied:

           bin = ~/bin          # expand '~' to home dir if EXPAND_UID
           tmp = ~abw/tmp       # as above, but home dir for user 'abw'

           perl = $bin/perl     # expand value of 'bin' variable if EXPAND_VAR
           ripl = $(bin)/ripl   # as above with explicit parens

           home = ${HOME}       # expand HOME environment var if EXPAND_ENV

       See the AppConfig::File manpage for further details on
       reading configuration files and expanding variable values.

       PARSING COMMAND LINE OPTIONS

       The args() method is used to parse command line options.
       It automatically loads the AppConfig::Args module and
       creates an object to process the command line arguments.
       Variables stored in the internal AppConfig::State are
       automatically updated with values specified in the
       arguments:

           $config->args(\@ARGV);

       Variables should be prefixed by a '-' or '--'.

           myprog -verbose --debug

       Variables that expect an additional argument (ARGS != 0)
       will be set to the value of the argument following it.  If
       the next argument starts with a '-' then a warning will be
       raised and the value will not be set.

           myprog --verbose -f /tmp/myfile

       Variables that do not expect a value (ARGS = 0) will be set to 1.

       Any arguments remaining at the end of the list that do not
       start with a '-' will not be processed.  These arguments
       will remain in the list when args() returns.  Valid
       arguments and value will be removed from the list.

       See the AppConfig::Args manpage for further details on
       parsing command line arguments.

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

       Web Technology Group, Canon Research Centre Europe Ltd.

REVISION
       $Revision: 0.1 $

COPYRIGHT
       Copyright (C) 1998 Canon Research Centre Europe Ltd.  All
       Rights Reserved.

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

SEE ALSO
       AppConfig::State, AppConfig::File, AppConfig::Args


