--- /dev/null
+.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sh \" Subsection heading
+.br
+.if t .Sp
+.ne 5
+.PP
+\fB\\$1\fR
+.PP
+..
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings. \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote. | will give a
+.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
+.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
+.\" expand to `' in nroff, nothing in troff, for use with C<>.
+.tr \(*W-|\(bv\*(Tr
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+. ds -- \(*W-
+. ds PI pi
+. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
+. ds L" ""
+. ds R" ""
+. ds C` ""
+. ds C' ""
+'br\}
+.el\{\
+. ds -- \|\(em\|
+. ds PI \(*p
+. ds L" ``
+. ds R" ''
+'br\}
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
+.\" entries marked with X<> in POD. Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.if \nF \{\
+. de IX
+. tm Index:\\$1\t\\n%\t"\\$2"
+..
+. nr % 0
+. rr F
+.\}
+.\"
+.\" For nroff, turn off justification. Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.hy 0
+.if n .na
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear. Run. Save yourself. No user-serviceable parts.
+. \" fudge factors for nroff and troff
+.if n \{\
+. ds #H 0
+. ds #V .8m
+. ds #F .3m
+. ds #[ \f1
+. ds #] \fP
+.\}
+.if t \{\
+. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+. ds #V .6m
+. ds #F 0
+. ds #[ \&
+. ds #] \&
+.\}
+. \" simple accents for nroff and troff
+.if n \{\
+. ds ' \&
+. ds ` \&
+. ds ^ \&
+. ds , \&
+. ds ~ ~
+. ds /
+.\}
+.if t \{\
+. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+. \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+. \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+. \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+. ds : e
+. ds 8 ss
+. ds o a
+. ds d- d\h'-1'\(ga
+. ds D- D\h'-1'\(hy
+. ds th \o'bp'
+. ds Th \o'LP'
+. ds ae ae
+. ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "AppConfig 3"
+.TH AppConfig 3 "2007-07-06" "perl v5.8.7" "User Contributed Perl Documentation"
+.SH "NAME"
+AppConfig \- Perl5 module for reading configuration files and parsing command line arguments.
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+.Vb 1
+\& use AppConfig;
+.Ve
+.PP
+.Vb 2
+\& # create a new AppConfig object
+\& my $config = AppConfig\->new( \e%cfg );
+.Ve
+.PP
+.Vb 2
+\& # define a new variable
+\& $config\->define( $varname => \e%varopts );
+.Ve
+.PP
+.Vb 6
+\& # create/define combined
+\& my $config = AppConfig\->new( \e%cfg,
+\& $varname => \e%varopts,
+\& $varname => \e%varopts,
+\& ...
+\& );
+.Ve
+.PP
+.Vb 3
+\& # set/get the value
+\& $config\->set( $varname, $value );
+\& $config\->get($varname);
+.Ve
+.PP
+.Vb 3
+\& # shortcut form
+\& $config\->varname($value);
+\& $config\->varname;
+.Ve
+.PP
+.Vb 2
+\& # read configuration file
+\& $config\->file($file);
+.Ve
+.PP
+.Vb 2
+\& # parse command line options
+\& $config\->args(\e@args); # default to \e@ARGV
+.Ve
+.PP
+.Vb 2
+\& # advanced command line options with Getopt::Long
+\& $config\->getopt(\e@args); # default to \e@ARGV
+.Ve
+.PP
+.Vb 2
+\& # parse CGI parameters (GET method)
+\& $config\->cgi($query); # default to $ENV{ QUERY_STRING }
+.Ve
+.SH "OVERVIEW"
+.IX Header "OVERVIEW"
+AppConfig is a Perl5 module for managing application configuration
+information. It maintains the state of any number of variables and
+provides methods for parsing configuration files, command line
+arguments and \s-1CGI\s0 script parameters.
+.PP
+Variables values may be set via configuration files. Variables may be
+flags (On/Off), take a single value, or take multiple values stored as a
+list or hash. The number of arguments a variable expects is determined
+by its configuration when defined.
+.PP
+.Vb 4
+\& # flags
+\& verbose
+\& nohelp
+\& debug = On
+.Ve
+.PP
+.Vb 2
+\& # single value
+\& home = /home/abw/
+.Ve
+.PP
+.Vb 3
+\& # multiple list value
+\& file = /tmp/file1
+\& file = /tmp/file2
+.Ve
+.PP
+.Vb 3
+\& # multiple hash value
+\& book camel = Programming Perl
+\& book llama = Learning Perl
+.Ve
+.PP
+The '\-' prefix can be used to reset a variable to its default value and
+the '+' prefix can be used to set it to 1
+.PP
+.Vb 2
+\& \-verbose
+\& +debug
+.Ve
+.PP
+Variable, environment variable and tilde (home directory) expansions
+can be applied (selectively, if necessary) to the values read from
+configuration files:
+.PP
+.Vb 4
+\& home = ~ # home directory
+\& nntp = ${NNTPSERVER} # environment variable
+\& html = $home/html # internal variables
+\& img = $html/images
+.Ve
+.PP
+Configuration files may be arranged in blocks as per the style of Win32
+\&\*(L"\s-1INI\s0\*(R" files.
+.PP
+.Vb 5
+\& [file]
+\& site = kfs
+\& src = ~/websrc/docs/$site
+\& lib = ~/websrc/lib
+\& dest = ~/public_html/$site
+.Ve
+.PP
+.Vb 3
+\& [page]
+\& header = $lib/header
+\& footer = $lib/footer
+.Ve
+.PP
+You can also use Perl's \*(L"heredoc\*(R" syntax to define a large block of
+text in a configuration file.
+.PP
+.Vb 4
+\& multiline = <<FOOBAR
+\& line 1
+\& line 2
+\& FOOBAR
+.Ve
+.PP
+.Vb 4
+\& paths exe = "${PATH}:${HOME}/.bin"
+\& paths link = <<'FOO'
+\& ${LD_LIBARRAY_PATH}:${HOME}/lib
+\& FOO
+.Ve
+.PP
+Variables may also be set by parsing command line arguments.
+.PP
+.Vb 1
+\& myapp \-verbose \-site kfs \-file f1 \-file f2
+.Ve
+.PP
+AppConfig provides a simple method (\fIargs()\fR) for parsing command line
+arguments. A second method (\fIgetopt()\fR) allows more complex argument
+processing by delegation to Johan Vroman's Getopt::Long module.
+.PP
+AppConfig also allows variables to be set by parameters passed to a
+\&\s-1CGI\s0 script via the \s-1URL\s0 (\s-1GET\s0 method).
+.PP
+.Vb 1
+\& http://www.nowhere.com/cgi\-bin/myapp?verbose&site=kfs
+.Ve
+.SH "PREREQUISITES"
+.IX Header "PREREQUISITES"
+AppConfig requires Perl 5.005 or later.
+.PP
+The Getopt::Long and Test::More modules should be installed.
+If you are using a recent version of Perl (e.g. 5.8.0) then these
+should already be installed.
+.SH "OBTAINING AND INSTALLING THE AppConfig MODULE BUNDLE"
+.IX Header "OBTAINING AND INSTALLING THE AppConfig MODULE BUNDLE"
+The AppConfig module bundle is available from \s-1CPAN\s0. As the 'perlmod'
+manual page explains:
+.PP
+.Vb 3
+\& CPAN stands for the Comprehensive Perl Archive Network.
+\& This is a globally replicated collection of all known Perl
+\& materials, including hundreds of unbundled modules.
+.Ve
+.PP
+.Vb 1
+\& [...]
+.Ve
+.PP
+.Vb 2
+\& For an up\-to\-date listing of CPAN sites, see
+\& http://www.perl.com/perl/ or ftp://ftp.perl.com/perl/ .
+.Ve
+.PP
+Within the \s-1CPAN\s0 archive, AppConfig is in the category:
+.PP
+.Vb 1
+\& 12) Option, Argument, Parameter and Configuration File Processing
+.Ve
+.PP
+The module is available in the following directories:
+.PP
+.Vb 2
+\& /modules/by\-module/AppConfig/AppConfig\-<version>.tar.gz
+\& /authors/id/ABW/AppConfig\-<version>.tar.gz
+.Ve
+.PP
+AppConfig is distributed as a single gzipped tar archive file:
+.PP
+.Vb 1
+\& AppConfig\-<version>.tar.gz
+.Ve
+.PP
+Note that \*(L"<version>\*(R" represents the current AppConfig version
+number, of the form \*(L"n.nn\*(R", e.g. \*(L"3.14\*(R". See the \s-1REVISION\s0 section
+below to determine the current version number for AppConfig.
+.PP
+Unpack the archive to create a AppConfig installation directory:
+.PP
+.Vb 2
+\& gunzip AppConfig\-<version>.tar.gz
+\& tar xvf AppConfig\-<version>.tar
+.Ve
+.PP
+\&'cd' into that directory, make, test and install the modules:
+.PP
+.Vb 5
+\& cd AppConfig\-<version>
+\& perl Makefile.PL
+\& make
+\& make test
+\& make install
+.Ve
+.PP
+The 't' sub-directory contains a number of test scripts that are run when
+a 'make test' is run.
+.PP
+The 'make install' will install the module on your system. You may need
+administrator privileges to perform this task. If you install the module
+in a local directory (for example, by executing \*(L"perl Makefile.PL
+LIB=~/lib\*(R" in the above \- see \f(CW\*(C`perldoc MakeMaker\*(C'\fR for full details), you
+will need to ensure that the \s-1PERL5LIB\s0 environment variable is set to
+include the location, or add a line to your scripts explicitly naming the
+library location:
+.PP
+.Vb 1
+\& use lib '/local/path/to/lib';
+.Ve
+.PP
+The 'examples' sub-directory contains some simple examples of using the
+AppConfig modules.
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+.Sh "\s-1USING\s0 \s-1THE\s0 AppConfig \s-1MODULE\s0"
+.IX Subsection "USING THE AppConfig MODULE"
+To import and use the AppConfig module the following line should
+appear in your Perl script:
+.PP
+.Vb 1
+\& use AppConfig;
+.Ve
+.PP
+To import constants defined by the AppConfig module, specify the name of
+one or more of the constant or tag sets as parameters to \f(CW\*(C`use\*(C'\fR:
+.PP
+.Vb 1
+\& use AppConfig qw(:expand :argcount);
+.Ve
+.PP
+See \*(L"\s-1CONSTANT\s0 \s-1DEFINITIONS\s0\*(R" below for more information on the constant
+tagsets defined by AppConfig.
+.PP
+AppConfig is implemented using object-oriented methods. A
+new AppConfig object is created and initialised using the
+\&\fInew()\fR method. This returns a reference to a new AppConfig
+object.
+.PP
+.Vb 1
+\& my $config = AppConfig\->new();
+.Ve
+.PP
+This will create and return a reference to a new AppConfig object.
+.PP
+In doing so, the AppConfig object also creates an internal reference
+to an AppConfig::State object in which to store variable state. All
+arguments passed into the AppConfig constructor are passed directly
+to the AppConfig::State constructor.
+.PP
+The first (optional) parameter may be a reference to a hash array
+containing configuration information.
+.PP
+.Vb 8
+\& my $config = AppConfig\->new( {
+\& CASE => 1,
+\& ERROR => \e&my_error,
+\& GLOBAL => {
+\& DEFAULT => "<unset>",
+\& ARGCOUNT => ARGCOUNT_ONE,
+\& },
+\& } );
+.Ve
+.PP
+See AppConfig::State for full details of the configuration options
+available. These are, in brief:
+.IP "\s-1CASE\s0" 4
+.IX Item "CASE"
+Used to set case sensitivity for variable names (default: off).
+.IP "\s-1CREATE\s0" 4
+.IX Item "CREATE"
+Used to indicate that undefined variables should be created automatically
+(default: off).
+.IP "\s-1GLOBAL\s0" 4
+.IX Item "GLOBAL"
+Reference to a hash array of global values used by default when defining
+variables. Valid global values are \s-1DEFAULT\s0, \s-1ARGCOUNT\s0, \s-1EXPAND\s0, \s-1VALIDATE\s0
+and \s-1ACTION\s0.
+.IP "\s-1PEDANTIC\s0" 4
+.IX Item "PEDANTIC"
+Used to indicate that command line and configuration file parsing routines
+should return immediately on encountering an error.
+.IP "\s-1ERROR\s0" 4
+.IX Item "ERROR"
+Used to provide a error handling routine. Arguments as per \fIprintf()\fR.
+.PP
+Subsequent parameters may be variable definitions. These are passed
+to the \fIdefine()\fR method, described below in \*(L"\s-1DEFINING\s0 \s-1VARIABLES\s0\*(R".
+.PP
+.Vb 2
+\& my $config = AppConfig\->new("foo", "bar", "baz");
+\& my $config = AppConfig\->new( { CASE => 1 }, qw(foo bar baz) );
+.Ve
+.PP
+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:
+.PP
+.Vb 2
+\& # create AppConfig
+\& my $config = AppConfig\->new('foo', 'bar');
+.Ve
+.PP
+.Vb 5
+\& # methods get passed through to internal AppConfig::State
+\& $config\->foo(100);
+\& $config\->set('bar', 200);
+\& $config\->define('baz');
+\& $config\->baz(300);
+.Ve
+.Sh "\s-1DEFINING\s0 \s-1VARIABLES\s0"
+.IX Subsection "DEFINING VARIABLES"
+The \f(CW\*(C`define()\*(C'\fR method (delegated to AppConfig::State) is used to
+pre-declare a variable and specify its configuration.
+.PP
+.Vb 1
+\& $config\->define("foo");
+.Ve
+.PP
+Variables may also be defined directly from the AppConfig \fInew()\fR
+constructor.
+.PP
+.Vb 1
+\& my $config = AppConfig\->new("foo");
+.Ve
+.PP
+In both simple examples above, a new variable called \*(L"foo\*(R" is defined. A
+reference to a hash array may also be passed to specify configuration
+information for the variable:
+.PP
+.Vb 4
+\& $config\->define("foo", {
+\& DEFAULT => 99,
+\& ALIAS => 'metavar1',
+\& });
+.Ve
+.PP
+Configuration items specified in the \s-1GLOBAL\s0 option to the module
+constructor are applied by default when variables are created. e.g.
+.PP
+.Vb 6
+\& my $config = AppConfig\->new( {
+\& GLOBAL => {
+\& DEFAULT => "<undef>",
+\& ARGCOUNT => ARGCOUNT_ONE,
+\& }
+\& } );
+.Ve
+.PP
+.Vb 2
+\& $config\->define("foo");
+\& $config\->define("bar", { ARGCOUNT => ARGCOUNT_NONE } );
+.Ve
+.PP
+is equivalent to:
+.PP
+.Vb 1
+\& my $config = AppConfig\->new();
+.Ve
+.PP
+.Vb 4
+\& $config\->define( "foo", {
+\& DEFAULT => "<undef>",
+\& ARGCOUNT => ARGCOUNT_ONE,
+\& } );
+.Ve
+.PP
+.Vb 4
+\& $config\->define( "bar",
+\& DEFAULT => "<undef>",
+\& ARGCOUNT => ARGCOUNT_NONE,
+\& } );
+.Ve
+.PP
+Multiple variables may be defined in the same call to \fIdefine()\fR.
+Configuration hashes for variables can be omitted.
+.PP
+.Vb 1
+\& $config\->define("foo", "bar" => { ALIAS = "boozer" }, "baz");
+.Ve
+.PP
+See AppConfig::State for full details of the configuration options
+available when defining variables. These are, in brief:
+.IP "\s-1DEFAULT\s0" 4
+.IX Item "DEFAULT"
+The default value for the variable (default: undef).
+.IP "\s-1ALIAS\s0" 4
+.IX Item "ALIAS"
+One or more (list reference or \*(L"list|like|this\*(R") alternative names for the
+variable.
+.IP "\s-1ARGCOUNT\s0" 4
+.IX Item "ARGCOUNT"
+Specifies the number and type of arguments that the variable expects.
+Constants in \f(CW\*(C`:expand\*(C'\fR tag set define \s-1ARGCOUNT_NONE\s0 \- simple on/off flag
+(default), \s-1ARGCOUNT_ONE\s0 \- single value, \s-1ARGCOUNT_LIST\s0 \- multiple values
+accessed via list reference, \s-1ARGCOUNT_HASH\s0 \- hash table, \*(L"key=value\*(R",
+accessed via hash reference.
+.IP "\s-1ARGS\s0" 4
+.IX Item "ARGS"
+Used to provide an argument specification string to pass to Getopt::Long
+via AppConfig::Getopt. E.g. \*(L"=i\*(R", \*(L":s\*(R", \*(L"=s@\*(R". This can also be used to
+implicitly set the \s-1ARGCOUNT\s0 value (\f(CW\*(C`/^!/\*(C'\fR = \s-1ARGCOUNT_NONE\s0, \f(CW\*(C`/@/\*(C'\fR =
+\&\s-1ARGCOUNT_LIST\s0, \f(CW\*(C`/%/\*(C'\fR = \s-1ARGCOUNT_HASH\s0, \f(CW\*(C`/[=:].*/\*(C'\fR = \s-1ARGCOUNT_ONE\s0)
+.IP "\s-1EXPAND\s0" 4
+.IX Item "EXPAND"
+Specifies which variable expansion policies should be used when parsing
+configuration files. Constants in \f(CW\*(C`:expand\*(C'\fR tag set define:
+.Sp
+.Vb 5
+\& EXPAND_NONE \- no expansion (default)
+\& EXPAND_VAR \- expand C<$var> or C<$(var)> as other variables
+\& EXPAND_UID \- expand C<~> and C<~uid> as user's home directory
+\& EXPAND_ENV \- expand C<${var}> as environment variable
+\& EXPAND_ALL \- do all expansions.
+.Ve
+.IP "\s-1VALIDATE\s0" 4
+.IX Item "VALIDATE"
+Regex which the intended variable value should match or code reference
+which returns 1 to indicate successful validaton (variable may now be set).
+.IP "\s-1ACTION\s0" 4
+.IX Item "ACTION"
+Code reference to be called whenever variable value changes.
+.Sh "\s-1COMPACT\s0 \s-1FORMAT\s0 \s-1DEFINITION\s0"
+.IX Subsection "COMPACT FORMAT DEFINITION"
+Variables can be specified using a compact format. This is identical to
+the specification format of Getopt::Long and is of the form:
+.PP
+.Vb 1
+\& "name|alias|alias<argopts>"
+.Ve
+.PP
+The first element indicates the variable name and subsequent \s-1ALIAS\s0
+values may be added, each separated by a vertical bar '|'.
+.PP
+The <argopts> element indicates the \s-1ARGCOUNT\s0 value and may be one of
+the following;
+.PP
+.Vb 4
+\& ! ARGCOUNT_NONE
+\& =s ARGCOUNT_ONE
+\& =s@ ARGCOUNT_LIST
+\& =s% ARGCOUNT_HASH
+.Ve
+.PP
+Additional constructs supported by Getopt::Long may be specified instead
+of the \*(L"=s\*(R" element (e.g. \*(L"=f\*(R"). The entire <argopts> element
+is stored in the \s-1ARGS\s0 parameter for the variable and is passed intact to
+Getopt::Long when the \fIgetopt()\fR method is called.
+.PP
+The following examples demonstrate use of the comapct format, with their
+equivalent full specifications:
+.PP
+.Vb 1
+\& $config\->define("foo|bar|baz!");
+.Ve
+.PP
+.Vb 5
+\& $config\->define(
+\& "foo" => {
+\& ALIAS => "bar|baz",
+\& ARGCOUNT => ARGCOUNT_NONE,
+\& });
+.Ve
+.PP
+.Vb 1
+\& $config\->define("name=s");
+.Ve
+.PP
+.Vb 4
+\& $config\->define(
+\& "name" => {
+\& ARGCOUNT => ARGCOUNT_ONE,
+\& });
+.Ve
+.PP
+.Vb 1
+\& $config\->define("file|filelist|f=s@");
+.Ve
+.PP
+.Vb 5
+\& $config\->define(
+\& "file" => {
+\& ALIAS => "filelist|f",
+\& ARGCOUNT => ARGCOUNT_LIST,
+\& });
+.Ve
+.PP
+.Vb 1
+\& $config\->define("user|u=s%");
+.Ve
+.PP
+.Vb 5
+\& $config\->define(
+\& "user" => {
+\& ALIAS => "u",
+\& ARGCOUNT => ARGCOUNT_HASH,
+\& });
+.Ve
+.PP
+Additional configuration options may be specified by hash reference, as per
+normal. The compact definition format will override any configuration
+values provided for \s-1ARGS\s0 and \s-1ARGCOUNT\s0.
+.PP
+.Vb 1
+\& $config\->define("file|filelist|f=s@", { VALIDATE = \e&check_file() } );
+.Ve
+.Sh "\s-1READING\s0 \s-1AND\s0 \s-1MODIFYING\s0 \s-1VARIABLE\s0 \s-1VALUES\s0"
+.IX Subsection "READING AND MODIFYING VARIABLE VALUES"
+AppConfig defines two methods (via AppConfig::State) to manipulate variable
+values
+.PP
+.Vb 2
+\& set($variable, $value);
+\& get($variable);
+.Ve
+.PP
+Once defined, variables may be accessed directly as object methods where
+the method name is the same as the variable name. i.e.
+.PP
+.Vb 1
+\& $config\->set("verbose", 1);
+.Ve
+.PP
+is equivalent to
+.PP
+.Vb 1
+\& $config\->verbose(1);
+.Ve
+.PP
+Note that AppConfig defines the following methods:
+.PP
+.Vb 4
+\& new();
+\& file();
+\& args();
+\& getopt();
+.Ve
+.PP
+And also, through delegation to AppConfig::State:
+.PP
+.Vb 4
+\& define()
+\& get()
+\& set()
+\& varlist()
+.Ve
+.PP
+If you define a variable with one of the above names, you will not be able
+to access it directly as an object method. i.e.
+.PP
+.Vb 1
+\& $config\->file();
+.Ve
+.PP
+This will call the \fIfile()\fR method, instead of returning the value of the
+\&'file' variable. You can work around this by explicitly calling \fIget()\fR and
+\&\fIset()\fR on a variable whose name conflicts:
+.PP
+.Vb 1
+\& $config\->get('file');
+.Ve
+.PP
+or by defining a \*(L"safe\*(R" alias by which the variable can be accessed:
+.PP
+.Vb 3
+\& $config\->define("file", { ALIAS => "fileopt" });
+\&or
+\& $config\->define("file|fileopt");
+.Ve
+.PP
+.Vb 2
+\& ...
+\& $config\->fileopt();
+.Ve
+.PP
+Without parameters, the current value of the variable is returned. If
+a parameter is specified, the variable is set to that value and the
+result of the \fIset()\fR operation is returned.
+.PP
+.Vb 2
+\& $config\->age(29); # sets 'age' to 29, returns 1 (ok)
+\& print $config\->age(); # prints "29"
+.Ve
+.PP
+The \fIvarlist()\fR method can be used to extract a number of variables into
+a hash array. The first parameter should be a regular expression
+used for matching against the variable names.
+.PP
+.Vb 1
+\& my %vars = $config\->varlist("^file"); # all "file*" variables
+.Ve
+.PP
+A second parameter may be specified (any true value) to indicate that
+the part of the variable name matching the regex should be removed
+when copied to the target hash.
+.PP
+.Vb 2
+\& $config\->file_name("/tmp/file");
+\& $config\->file_path("/foo:/bar:/baz");
+.Ve
+.PP
+.Vb 1
+\& my %vars = $config\->varlist("^file_", 1);
+.Ve
+.PP
+.Vb 3
+\& # %vars:
+\& # name => /tmp/file
+\& # path => "/foo:/bar:/baz"
+.Ve
+.Sh "\s-1READING\s0 \s-1CONFIGURATION\s0 \s-1FILES\s0"
+.IX Subsection "READING CONFIGURATION FILES"
+The AppConfig module provides a streamlined interface for reading
+configuration files with the AppConfig::File module. The \fIfile()\fR method
+automatically loads the AppConfig::File module and creates an object
+to process the configuration file or files. Variables stored in the
+internal AppConfig::State are automatically updated with values specified
+in the configuration file.
+.PP
+.Vb 1
+\& $config\->file($filename);
+.Ve
+.PP
+Multiple files may be passed to \fIfile()\fR and should indicate the file name
+or be a reference to an open file handle or glob.
+.PP
+.Vb 1
+\& $config\->file($filename, $filehandle, \e*STDIN, ...);
+.Ve
+.PP
+The file may contain blank lines and comments (prefixed by '#') which
+are ignored. Continutation lines may be marked by ending the line with
+a '\e'.
+.PP
+.Vb 5
+\& # this is a comment
+\& callsign = alpha bravo camel delta echo foxtrot golf hipowls \e
+\& india juliet kilo llama mike november oscar papa \e
+\& quebec romeo sierra tango umbrella victor whiskey \e
+\& x\-ray yankee zebra
+.Ve
+.PP
+Variables that are simple flags and do not expect an argument (\s-1ARGCOUNT\s0 =
+\&\s-1ARGCOUNT_NONE\s0) can be specified without any value. They will be set with
+the value 1, with any value explicitly specified (except \*(L"0\*(R" and \*(L"off\*(R")
+being ignored. The variable may also be specified with a \*(L"no\*(R" prefix to
+implicitly set the variable to 0.
+.PP
+.Vb 7
+\& verbose # on (1)
+\& verbose = 1 # on (1)
+\& verbose = 0 # off (0)
+\& verbose off # off (0)
+\& verbose on # on (1)
+\& verbose mumble # on (1)
+\& noverbose # off (0)
+.Ve
+.PP
+Variables that expect an argument (\s-1ARGCOUNT\s0 = \s-1ARGCOUNT_ONE\s0) will be set to
+whatever follows the variable name, up to the end of the current line
+(including any continuation lines). An optional equals sign may be inserted
+between the variable and value for clarity.
+.PP
+.Vb 2
+\& room = /home/kitchen
+\& room /home/bedroom
+.Ve
+.PP
+Each subsequent re-definition of the variable value overwrites the previous
+value.
+.PP
+.Vb 1
+\& print $config\->room(); # prints "/home/bedroom"
+.Ve
+.PP
+Variables may be defined to accept multiple values (\s-1ARGCOUNT\s0 = \s-1ARGCOUNT_LIST\s0).
+Each subsequent definition of the variable adds the value to the list of
+previously set values for the variable.
+.PP
+.Vb 2
+\& drink = coffee
+\& drink = tea
+.Ve
+.PP
+A reference to a list of values is returned when the variable is requested.
+.PP
+.Vb 2
+\& my $beverages = $config\->drinks();
+\& print join(", ", @$beverages); # prints "coffee, tea"
+.Ve
+.PP
+Variables may also be defined as hash lists (\s-1ARGCOUNT\s0 = \s-1ARGCOUNT_HASH\s0).
+Each subsequent definition creates a new key and value in the hash array.
+.PP
+.Vb 2
+\& alias l="ls \-CF"
+\& alias e="emacs"
+.Ve
+.PP
+A reference to the hash is returned when the variable is requested.
+.PP
+.Vb 4
+\& my $aliases = $config\->alias();
+\& foreach my $k (keys %$aliases) {
+\& print "$k => $aliases\->{ $k }\en";
+\& }
+.Ve
+.PP
+The '\-' prefix can be used to reset a variable to its default value and
+the '+' prefix can be used to set it to 1
+.PP
+.Vb 2
+\& \-verbose
+\& +debug
+.Ve
+.Sh "\s-1VARIABLE\s0 \s-1EXPANSION\s0"
+.IX Subsection "VARIABLE EXPANSION"
+Variable values may contain references to other AppConfig variables,
+environment variables and/or users' home directories. These will be
+expanded depending on the \s-1EXPAND\s0 value for each variable or the \s-1GLOBAL\s0
+\&\s-1EXPAND\s0 value.
+.PP
+Three different expansion types may be applied:
+.PP
+.Vb 2
+\& bin = ~/bin # expand '~' to home dir if EXPAND_UID
+\& tmp = ~abw/tmp # as above, but home dir for user 'abw'
+.Ve
+.PP
+.Vb 2
+\& perl = $bin/perl # expand value of 'bin' variable if EXPAND_VAR
+\& ripl = $(bin)/ripl # as above with explicit parens
+.Ve
+.PP
+.Vb 1
+\& home = ${HOME} # expand HOME environment var if EXPAND_ENV
+.Ve
+.PP
+See AppConfig::State for more information on expanding variable values.
+.PP
+The configuration files may have variables arranged in blocks. A block
+header, consisting of the block name in square brackets, introduces a
+configuration block. The block name and an underscore are then prefixed
+to the names of all variables subsequently referenced in that block. The
+block continues until the next block definition or to the end of the current
+file.
+.PP
+.Vb 2
+\& [block1]
+\& foo = 10 # block1_foo = 10
+.Ve
+.PP
+.Vb 2
+\& [block2]
+\& foo = 20 # block2_foo = 20
+.Ve
+.Sh "\s-1PARSING\s0 \s-1COMMAND\s0 \s-1LINE\s0 \s-1OPTIONS\s0"
+.IX Subsection "PARSING COMMAND LINE OPTIONS"
+There are two methods for processing command line options. The first,
+\&\fIargs()\fR, is a small and efficient implementation which offers basic
+functionality. The second, \fIgetopt()\fR, offers a more powerful and complete
+facility by delegating the task to Johan Vroman's Getopt::Long module.
+The trade-off between \fIargs()\fR and \fIgetopt()\fR is essentially one of speed/size
+against flexibility. Use as appropriate. Both implement on-demand loading
+of modules and incur no overhead until used.
+.PP
+The \fIargs()\fR method is used to parse simple 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.
+.PP
+The method should be passed a reference to a list of arguments to parse.
+The \f(CW@ARGV\fR array is used if \fIargs()\fR is called without parameters.
+.PP
+.Vb 2
+\& $config\->args(\e@myargs);
+\& $config\->args(); # uses @ARGV
+.Ve
+.PP
+Arguments are read and shifted from the array until the first is
+encountered that is not prefixed by '\-' or '\-\-'. At that point, the
+method returns 1 to indicate success, leaving any unprocessed arguments
+remaining in the list.
+.PP
+Each argument should be the name or alias of a variable prefixed by
+\&'\-' or '\-\-'. Arguments that are not prefixed as such (and are not an
+additional parameter to a previous argument) will cause a warning to be
+raised. If the \s-1PEDANTIC\s0 option is set, the method will return 0
+immediately. With \s-1PEDANTIC\s0 unset (default), the method will continue
+to parse the rest of the arguments, returning 0 when done.
+.PP
+If the variable is a simple flag (\s-1ARGCOUNT\s0 = \s-1ARGCOUNT_NONE\s0)
+then it is set to the value 1. The variable may be prefixed by \*(L"no\*(R" to
+set its value to 0.
+.PP
+.Vb 3
+\& myprog \-verbose \-\-debug \-notaste # $config\->verbose(1)
+\& # $config\->debug(1)
+\& # $config\->taste(0)
+.Ve
+.PP
+Variables that expect an additional argument (\s-1ARGCOUNT\s0 != 0) will be set to
+the value of the argument following it.
+.PP
+.Vb 1
+\& myprog \-f /tmp/myfile # $config\->file('/tmp/file');
+.Ve
+.PP
+Variables that expect multiple values (\s-1ARGCOUNT\s0 = \s-1ARGCOUNT_LIST\s0 or
+\&\s-1ARGCOUNT_HASH\s0) will have sucessive values added each time the option
+is encountered.
+.PP
+.Vb 2
+\& myprog \-file /tmp/foo \-file /tmp/bar # $config\->file('/tmp/foo')
+\& # $config\->file('/tmp/bar')
+.Ve
+.PP
+.Vb 1
+\& # file => [ '/tmp/foo', '/tmp/bar' ]
+.Ve
+.PP
+.Vb 3
+\& myprog \-door "jim=Jim Morrison" \-door "ray=Ray Manzarek"
+\& # $config\->door("jim=Jim Morrison");
+\& # $config\->door("ray=Ray Manzarek");
+.Ve
+.PP
+.Vb 1
+\& # door => { 'jim' => 'Jim Morrison', 'ray' => 'Ray Manzarek' }
+.Ve
+.PP
+See AppConfig::Args for further details on parsing command line
+arguments.
+.PP
+The \fIgetopt()\fR method provides a way to use the power and flexibility of
+the Getopt::Long module to parse command line arguments and have the
+internal values of the AppConfig object updates automatically.
+.PP
+The first (non\-list reference) parameters may contain a number of
+configuration string to pass to Getopt::Long::Configure. A reference
+to a list of arguments may additionally be passed or \f(CW@ARGV\fR is used by
+default.
+.PP
+.Vb 4
+\& $config\->getopt(); # uses @ARGV
+\& $config\->getopt(\e@myargs);
+\& $config\->getopt(qw(auto_abbrev debug)); # uses @ARGV
+\& $config\->getopt(qw(debug), \e@myargs);
+.Ve
+.PP
+See Getopt::Long for details of the configuration options available.
+.PP
+The \fIgetopt()\fR method constructs a specification string for each internal
+variable and then initialises Getopt::Long with these values. The
+specification string is constructed from the name, any aliases (delimited
+by a vertical bar '|') and the value of the \s-1ARGS\s0 parameter.
+.PP
+.Vb 4
+\& $config\->define("foo", {
+\& ARGS => "=i",
+\& ALIAS => "bar|baz",
+\& });
+.Ve
+.PP
+.Vb 1
+\& # Getopt::Long specification: "foo|bar|baz=i"
+.Ve
+.PP
+Errors and warning generated by the Getopt::Long module are trapped and
+handled by the AppConfig error handler. This may be a user-defined
+routine installed with the \s-1ERROR\s0 configuration option.
+.PP
+Please note that the AppConfig::Getopt interface is still experimental
+and may not be 100% operational. This is almost undoubtedly due to
+problems in AppConfig::Getopt rather than Getopt::Long.
+.Sh "\s-1PARSING\s0 \s-1CGI\s0 \s-1PARAMETERS\s0"
+.IX Subsection "PARSING CGI PARAMETERS"
+The \fIcgi()\fR method provides an interface to the AppConfig::CGI module
+for updating variable values based on the parameters appended to the
+\&\s-1URL\s0 for a \s-1CGI\s0 script. This is commonly known as the \s-1CGI\s0
+\&\*(L"\s-1GET\s0\*(R" method. The \s-1CGI\s0 \*(L"\s-1POST\s0\*(R" method is currently not supported.
+.PP
+Parameter definitions are separated from the \s-1CGI\s0 script name by a
+question mark and from each other by ampersands. Where variables
+have specific values, these are appended to the variable with an
+equals sign:
+.PP
+.Vb 1
+\& http://www.here.com/cgi\-bin/myscript?foo=bar&baz=qux&verbose
+.Ve
+.PP
+.Vb 3
+\& # $config\->foo('bar');
+\& # $config\->baz('qux');
+\& # $config\->verbose(1);
+.Ve
+.PP
+Certain values specified in a \s-1URL\s0 must be escaped in the appropriate
+manner (see \s-1CGI\s0 specifications at http://www.w3c.org/ for full details).
+The AppConfig::CGI module automatically unescapes the \s-1CGI\s0 query string
+to restore the parameters to their intended values.
+.PP
+.Vb 1
+\& http://where.com/mycgi?title=%22The+Wrong+Trousers%22
+.Ve
+.PP
+.Vb 1
+\& # $config\->title('"The Wrong Trousers"');
+.Ve
+.PP
+Please be considerate of the security implications of providing writeable
+access to script variables via \s-1CGI\s0.
+.PP
+.Vb 2
+\& http://rebel.alliance.com/cgi\-bin/...
+\& .../send_report?file=%2Fetc%2Fpasswd&email=darth%40empire.com
+.Ve
+.PP
+To avoid any accidental or malicious changing of \*(L"private\*(R" variables,
+define only the \*(L"public\*(R" variables before calling the \fIcgi()\fR (or any
+other) method. Further variables can subequently be defined which
+can not be influenced by the \s-1CGI\s0 parameters.
+.PP
+.Vb 2
+\& $config\->define('verbose', 'debug')
+\& $config\->cgi(); # can only set verbose and debug
+.Ve
+.PP
+.Vb 2
+\& $config\->define('email', 'file');
+\& $config\->file($cfgfile); # can set verbose, debug, email + file
+.Ve
+.SH "CONSTANT DEFINITIONS"
+.IX Header "CONSTANT DEFINITIONS"
+A number of constants are defined by the AppConfig module. These may be
+accessed directly (e.g. AppConfig::EXPAND_VARS) or by first importing them
+into the caller's package. Constants are imported by specifying their
+names as arguments to \f(CW\*(C`use AppConfig\*(C'\fR or by importing a set of constants
+identified by its \*(L"tag set\*(R" name.
+.PP
+.Vb 1
+\& use AppConfig qw(ARGCOUNT_NONE ARGCOUNT_ONE);
+.Ve
+.PP
+.Vb 1
+\& use AppConfig qw(:argcount);
+.Ve
+.PP
+The following tag sets are defined:
+.IP ":expand" 4
+.IX Item ":expand"
+The ':expand' tagset defines the following constants:
+.Sp
+.Vb 6
+\& EXPAND_NONE
+\& EXPAND_VAR
+\& EXPAND_UID
+\& EXPAND_ENV
+\& EXPAND_ALL # EXPAND_VAR | EXPAND_UID | EXPAND_ENV
+\& EXPAND_WARN
+.Ve
+.Sp
+See AppConfig::File for full details of the use of these constants.
+.IP ":argcount" 4
+.IX Item ":argcount"
+The ':argcount' tagset defines the following constants:
+.Sp
+.Vb 4
+\& ARGCOUNT_NONE
+\& ARGCOUNT_ONE
+\& ARGCOUNT_LIST
+\& ARGCOUNT_HASH
+.Ve
+.Sp
+See AppConfig::State for full details of the use of these constants.
+.SH "AUTHOR"
+.IX Header "AUTHOR"
+Andy Wardley, <abw@wardley.org>
+.PP
+With contributions from Dave Viner, Ijon Tichy, Axel Gerstmair and
+many others whose names have been lost to the sands of time (reminders
+welcome).
+.SH "COPYRIGHT"
+.IX Header "COPYRIGHT"
+Copyright (C) 1997\-2007 Andy Wardley. All Rights Reserved.
+.PP
+Copyright (C) 1997,1998 Canon Research Centre Europe Ltd.
+.PP
+This module is free software; you can redistribute it and/or modify it
+under the same terms as Perl itself.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+AppConfig::State, AppConfig::File, AppConfig::Args, AppConfig::Getopt,
+AppConfig::CGI, Getopt::Long
projects / catagits/Gitalist.git / blobdiff