appconfig (1.56-2) direct (non packaging) changes

Summary

 Makefile                        |  761 +++++++++++++++++++++
 Makefile.old                    |  761 +++++++++++++++++++++
 blib/lib/AppConfig.pm           | 1054 +++++++++++++++++++++++++++++
 blib/lib/AppConfig/Args.pm      |  249 +++++++
 blib/lib/AppConfig/CGI.pm       |  244 ++++++
 blib/lib/AppConfig/File.pm      |  730 ++++++++++++++++++++
 blib/lib/AppConfig/Getopt.pm    |  281 +++++++
 blib/lib/AppConfig/State.pm     | 1413 ++++++++++++++++++++++++++++++++++++++++
 blib/lib/AppConfig/Sys.pm       |  304 ++++++++
 blib/man3/AppConfig.3pm         | 1158 ++++++++++++++++++++++++++++++++
 blib/man3/AppConfig::Args.3pm   |  237 ++++++
 blib/man3/AppConfig::CGI.3pm    |  209 +++++
 blib/man3/AppConfig::File.3pm   |  396 +++++++++++
 blib/man3/AppConfig::Getopt.3pm |  230 ++++++
 blib/man3/AppConfig::State.3pm  |  716 ++++++++++++++++++++
 blib/man3/AppConfig::Sys.3pm    |  214 ++++++
 lib/AppConfig.pm                |    2 
 17 files changed, 8958 insertions(+), 1 deletion(-)

    
download this patch

Patch contents

--- appconfig-1.56.orig/lib/AppConfig.pm
+++ appconfig-1.56/lib/AppConfig.pm
@@ -547,7 +547,7 @@
 =item ARGCOUNT
 
 Specifies the number and type of arguments that the variable expects.
-Constants in C<:expand> tag set define ARGCOUNT_NONE - simple on/off flag
+Constants in C<:argcount> tag set define ARGCOUNT_NONE - simple on/off flag
 (default), ARGCOUNT_ONE - single value, ARGCOUNT_LIST - multiple values
 accessed via list reference, ARGCOUNT_HASH - hash table, "key=value",
 accessed via hash reference.
--- appconfig-1.56.orig/Makefile.old
+++ appconfig-1.56/Makefile.old
@@ -0,0 +1,761 @@
+# This Makefile is for the AppConfig extension to perl.
+#
+# It was generated automatically by MakeMaker version
+# 6.17 (Revision: 1.133) from the contents of
+# Makefile.PL. Don't edit this file, edit Makefile.PL instead.
+#
+#       ANY CHANGES MADE HERE WILL BE LOST!
+#
+#   MakeMaker ARGV: (q[INSTALLDIRS=vendor])
+#
+#   MakeMaker Parameters:
+
+#     ABSTRACT => q[AppConfig is a bundle of Perl5 modules for reading configuration files and parsing command line arguments.]
+#     AUTHOR => q[Andy Wardley <abw@wardley.org>]
+#     MAN3PODS => { lib/AppConfig/Args.pm=>q[$(INST_MAN3DIR)/AppConfig::Args.$(MAN3EXT)], lib/AppConfig/CGI.pm=>q[$(INST_MAN3DIR)/AppConfig::CGI.$(MAN3EXT)], lib/AppConfig/File.pm=>q[$(INST_MAN3DIR)/AppConfig::File.$(MAN3EXT)], lib/AppConfig/State.pm=>q[$(INST_MAN3DIR)/AppConfig::State.$(MAN3EXT)], lib/AppConfig/Getopt.pm=>q[$(INST_MAN3DIR)/AppConfig::Getopt.$(MAN3EXT)], lib/AppConfig.pm=>q[$(INST_MAN3DIR)/AppConfig.$(MAN3EXT)], lib/AppConfig/Sys.pm=>q[$(INST_MAN3DIR)/AppConfig::Sys.$(MAN3EXT)] }
+#     NAME => q[AppConfig]
+#     PMLIBDIRS => [q[lib]]
+#     PREREQ_PM => { Test::More=>q[0] }
+#     VERSION_FROM => q[lib/AppConfig.pm]
+#     dist => { COMPRESS=>q[gzip], PREOP=>q[cp docs/header README; \                        pod2text lib/AppConfig.pm >> README], SUFFIX=>q[gz] }
+
+# --- MakeMaker post_initialize section:
+
+
+# --- MakeMaker const_config section:
+
+# These definitions are from config.sh (via /usr/lib/perl/5.8/Config.pm)
+
+# They may have been overridden via Makefile.PL or on the command line
+AR = ar
+CC = cc
+CCCDLFLAGS = -fPIC
+CCDLFLAGS = -Wl,-E
+DLEXT = so
+DLSRC = dl_dlopen.xs
+LD = cc
+LDDLFLAGS = -shared -L/usr/local/lib
+LDFLAGS =  -L/usr/local/lib
+LIBC = /lib/libc-2.3.2.so
+LIB_EXT = .a
+OBJ_EXT = .o
+OSNAME = linux
+OSVERS = 2.4.26-ti1211
+RANLIB = :
+SITELIBEXP = /usr/local/share/perl/5.8.4
+SITEARCHEXP = /usr/local/lib/perl/5.8.4
+SO = so
+EXE_EXT = 
+FULL_AR = /usr/bin/ar
+VENDORARCHEXP = /usr/lib/perl5
+VENDORLIBEXP = /usr/share/perl5
+
+
+# --- MakeMaker constants section:
+AR_STATIC_ARGS = cr
+DIRFILESEP = /
+NAME = AppConfig
+NAME_SYM = AppConfig
+VERSION = 1.56
+VERSION_MACRO = VERSION
+VERSION_SYM = 1_56
+DEFINE_VERSION = -D$(VERSION_MACRO)=\"$(VERSION)\"
+XS_VERSION = 1.56
+XS_VERSION_MACRO = XS_VERSION
+XS_DEFINE_VERSION = -D$(XS_VERSION_MACRO)=\"$(XS_VERSION)\"
+INST_ARCHLIB = blib/arch
+INST_SCRIPT = blib/script
+INST_BIN = blib/bin
+INST_LIB = blib/lib
+INST_MAN1DIR = blib/man1
+INST_MAN3DIR = blib/man3
+MAN1EXT = 1p
+MAN3EXT = 3pm
+INSTALLDIRS = vendor
+DESTDIR = 
+PREFIX = /usr
+PERLPREFIX = $(PREFIX)
+SITEPREFIX = $(PREFIX)/local
+VENDORPREFIX = $(PREFIX)
+INSTALLPRIVLIB = $(PERLPREFIX)/share/perl/5.8
+DESTINSTALLPRIVLIB = $(DESTDIR)$(INSTALLPRIVLIB)
+INSTALLSITELIB = $(SITEPREFIX)/share/perl/5.8.4
+DESTINSTALLSITELIB = $(DESTDIR)$(INSTALLSITELIB)
+INSTALLVENDORLIB = $(VENDORPREFIX)/share/perl5
+DESTINSTALLVENDORLIB = $(DESTDIR)$(INSTALLVENDORLIB)
+INSTALLARCHLIB = $(PERLPREFIX)/lib/perl/5.8
+DESTINSTALLARCHLIB = $(DESTDIR)$(INSTALLARCHLIB)
+INSTALLSITEARCH = $(SITEPREFIX)/lib/perl/5.8.4
+DESTINSTALLSITEARCH = $(DESTDIR)$(INSTALLSITEARCH)
+INSTALLVENDORARCH = $(VENDORPREFIX)/lib/perl5
+DESTINSTALLVENDORARCH = $(DESTDIR)$(INSTALLVENDORARCH)
+INSTALLBIN = $(PERLPREFIX)/bin
+DESTINSTALLBIN = $(DESTDIR)$(INSTALLBIN)
+INSTALLSITEBIN = $(SITEPREFIX)/bin
+DESTINSTALLSITEBIN = $(DESTDIR)$(INSTALLSITEBIN)
+INSTALLVENDORBIN = $(VENDORPREFIX)/bin
+DESTINSTALLVENDORBIN = $(DESTDIR)$(INSTALLVENDORBIN)
+INSTALLSCRIPT = $(PERLPREFIX)/bin
+DESTINSTALLSCRIPT = $(DESTDIR)$(INSTALLSCRIPT)
+INSTALLMAN1DIR = $(PERLPREFIX)/share/man/man1
+DESTINSTALLMAN1DIR = $(DESTDIR)$(INSTALLMAN1DIR)
+INSTALLSITEMAN1DIR = $(SITEPREFIX)/man/man1
+DESTINSTALLSITEMAN1DIR = $(DESTDIR)$(INSTALLSITEMAN1DIR)
+INSTALLVENDORMAN1DIR = $(VENDORPREFIX)/share/man/man1
+DESTINSTALLVENDORMAN1DIR = $(DESTDIR)$(INSTALLVENDORMAN1DIR)
+INSTALLMAN3DIR = $(PERLPREFIX)/share/man/man3
+DESTINSTALLMAN3DIR = $(DESTDIR)$(INSTALLMAN3DIR)
+INSTALLSITEMAN3DIR = $(SITEPREFIX)/man/man3
+DESTINSTALLSITEMAN3DIR = $(DESTDIR)$(INSTALLSITEMAN3DIR)
+INSTALLVENDORMAN3DIR = $(VENDORPREFIX)/share/man/man3
+DESTINSTALLVENDORMAN3DIR = $(DESTDIR)$(INSTALLVENDORMAN3DIR)
+PERL_LIB = /usr/share/perl/5.8
+PERL_ARCHLIB = /usr/lib/perl/5.8
+LIBPERL_A = libperl.a
+FIRST_MAKEFILE = Makefile
+MAKEFILE_OLD = $(FIRST_MAKEFILE).old
+MAKE_APERL_FILE = $(FIRST_MAKEFILE).aperl
+PERLMAINCC = $(CC)
+PERL_INC = /usr/lib/perl/5.8/CORE
+PERL = /usr/bin/perl
+FULLPERL = /usr/bin/perl
+ABSPERL = $(PERL)
+PERLRUN = $(PERL)
+FULLPERLRUN = $(FULLPERL)
+ABSPERLRUN = $(ABSPERL)
+PERLRUNINST = $(PERLRUN) "-I$(INST_ARCHLIB)" "-I$(INST_LIB)"
+FULLPERLRUNINST = $(FULLPERLRUN) "-I$(INST_ARCHLIB)" "-I$(INST_LIB)"
+ABSPERLRUNINST = $(ABSPERLRUN) "-I$(INST_ARCHLIB)" "-I$(INST_LIB)"
+PERL_CORE = 0
+PERM_RW = 644
+PERM_RWX = 755
+
+MAKEMAKER   = /usr/share/perl/5.8/ExtUtils/MakeMaker.pm
+MM_VERSION  = 6.17
+MM_REVISION = 1.133
+
+# FULLEXT = Pathname for extension directory (eg Foo/Bar/Oracle).
+# BASEEXT = Basename part of FULLEXT. May be just equal FULLEXT. (eg Oracle)
+# PARENT_NAME = NAME without BASEEXT and no trailing :: (eg Foo::Bar)
+# DLBASE  = Basename part of dynamic library. May be just equal BASEEXT.
+FULLEXT = AppConfig
+BASEEXT = AppConfig
+PARENT_NAME = 
+DLBASE = $(BASEEXT)
+VERSION_FROM = lib/AppConfig.pm
+OBJECT = 
+LDFROM = $(OBJECT)
+LINKTYPE = dynamic
+
+# Handy lists of source code files:
+XS_FILES = 
+C_FILES  = 
+O_FILES  = 
+H_FILES  = 
+MAN1PODS = 
+MAN3PODS = lib/AppConfig.pm \
+	lib/AppConfig/Args.pm \
+	lib/AppConfig/CGI.pm \
+	lib/AppConfig/File.pm \
+	lib/AppConfig/Getopt.pm \
+	lib/AppConfig/State.pm \
+	lib/AppConfig/Sys.pm
+
+# Where is the Config information that we are using/depend on
+CONFIGDEP = $(PERL_ARCHLIB)$(DIRFILESEP)Config.pm $(PERL_INC)$(DIRFILESEP)config.h
+
+# Where to build things
+INST_LIBDIR      = $(INST_LIB)
+INST_ARCHLIBDIR  = $(INST_ARCHLIB)
+
+INST_AUTODIR     = $(INST_LIB)/auto/$(FULLEXT)
+INST_ARCHAUTODIR = $(INST_ARCHLIB)/auto/$(FULLEXT)
+
+INST_STATIC      = 
+INST_DYNAMIC     = 
+INST_BOOT        = 
+
+# Extra linker info
+EXPORT_LIST        = 
+PERL_ARCHIVE       = 
+PERL_ARCHIVE_AFTER = 
+
+
+TO_INST_PM = lib/AppConfig.pm \
+	lib/AppConfig/Args.pm \
+	lib/AppConfig/CGI.pm \
+	lib/AppConfig/File.pm \
+	lib/AppConfig/Getopt.pm \
+	lib/AppConfig/State.pm \
+	lib/AppConfig/Sys.pm
+
+PM_TO_BLIB = lib/AppConfig/Args.pm \
+	blib/lib/AppConfig/Args.pm \
+	lib/AppConfig/CGI.pm \
+	blib/lib/AppConfig/CGI.pm \
+	lib/AppConfig/File.pm \
+	blib/lib/AppConfig/File.pm \
+	lib/AppConfig/State.pm \
+	blib/lib/AppConfig/State.pm \
+	lib/AppConfig/Getopt.pm \
+	blib/lib/AppConfig/Getopt.pm \
+	lib/AppConfig.pm \
+	blib/lib/AppConfig.pm \
+	lib/AppConfig/Sys.pm \
+	blib/lib/AppConfig/Sys.pm
+
+
+# --- MakeMaker platform_constants section:
+MM_Unix_VERSION = 1.42
+PERL_MALLOC_DEF = -DPERL_EXTMALLOC_DEF -Dmalloc=Perl_malloc -Dfree=Perl_mfree -Drealloc=Perl_realloc -Dcalloc=Perl_calloc
+
+
+# --- MakeMaker tool_autosplit section:
+# Usage: $(AUTOSPLITFILE) FileToSplit AutoDirToSplitInto
+AUTOSPLITFILE = $(PERLRUN)  -e 'use AutoSplit;  autosplit($$ARGV[0], $$ARGV[1], 0, 1, 1)'
+
+
+
+# --- MakeMaker tool_xsubpp section:
+
+
+# --- MakeMaker tools_other section:
+SHELL = /bin/sh
+CHMOD = chmod
+CP = cp
+MV = mv
+NOOP = $(SHELL) -c true
+NOECHO = @
+RM_F = rm -f
+RM_RF = rm -rf
+TEST_F = test -f
+TOUCH = touch
+UMASK_NULL = umask 0
+DEV_NULL = > /dev/null 2>&1
+MKPATH = $(PERLRUN) "-MExtUtils::Command" -e mkpath
+EQUALIZE_TIMESTAMP = $(PERLRUN) "-MExtUtils::Command" -e eqtime
+ECHO = echo
+ECHO_N = echo -n
+UNINST = 0
+VERBINST = 0
+MOD_INSTALL = $(PERLRUN) -MExtUtils::Install -e 'install({@ARGV}, '\''$(VERBINST)'\'', 0, '\''$(UNINST)'\'');'
+DOC_INSTALL = $(PERLRUN) "-MExtUtils::Command::MM" -e perllocal_install
+UNINSTALL = $(PERLRUN) "-MExtUtils::Command::MM" -e uninstall
+WARN_IF_OLD_PACKLIST = $(PERLRUN) "-MExtUtils::Command::MM" -e warn_if_old_packlist
+
+
+# --- MakeMaker makemakerdflt section:
+makemakerdflt: all
+	$(NOECHO) $(NOOP)
+
+
+# --- MakeMaker dist section:
+TAR = tar
+TARFLAGS = cvf
+ZIP = zip
+ZIPFLAGS = -r
+COMPRESS = gzip
+SUFFIX = gz
+SHAR = shar
+PREOP = cp docs/header README; \
+                       pod2text lib/AppConfig.pm >> README
+POSTOP = $(NOECHO) $(NOOP)
+TO_UNIX = $(NOECHO) $(NOOP)
+CI = ci -u
+RCS_LABEL = rcs -Nv$(VERSION_SYM): -q
+DIST_CP = best
+DIST_DEFAULT = tardist
+DISTNAME = AppConfig
+DISTVNAME = AppConfig-1.56
+
+
+# --- MakeMaker macro section:
+
+
+# --- MakeMaker depend section:
+
+
+# --- MakeMaker cflags section:
+
+
+# --- MakeMaker const_loadlibs section:
+
+
+# --- MakeMaker const_cccmd section:
+
+
+# --- MakeMaker post_constants section:
+
+
+# --- MakeMaker pasthru section:
+
+PASTHRU = LIB="$(LIB)"\
+	LIBPERL_A="$(LIBPERL_A)"\
+	LINKTYPE="$(LINKTYPE)"\
+	PREFIX="$(PREFIX)"\
+	OPTIMIZE="$(OPTIMIZE)"\
+	PASTHRU_DEFINE="$(PASTHRU_DEFINE)"\
+	PASTHRU_INC="$(PASTHRU_INC)"
+
+
+# --- MakeMaker special_targets section:
+.SUFFIXES: .xs .c .C .cpp .i .s .cxx .cc $(OBJ_EXT)
+
+.PHONY: all config static dynamic test linkext manifest
+
+
+
+# --- MakeMaker c_o section:
+
+
+# --- MakeMaker xs_c section:
+
+
+# --- MakeMaker xs_o section:
+
+
+# --- MakeMaker top_targets section:
+all :: pure_all manifypods
+	$(NOECHO) $(NOOP)
+
+
+pure_all :: config pm_to_blib subdirs linkext
+	$(NOECHO) $(NOOP)
+
+subdirs :: $(MYEXTLIB)
+	$(NOECHO) $(NOOP)
+
+config :: $(FIRST_MAKEFILE) $(INST_LIBDIR)$(DIRFILESEP).exists
+	$(NOECHO) $(NOOP)
+
+config :: $(INST_ARCHAUTODIR)$(DIRFILESEP).exists
+	$(NOECHO) $(NOOP)
+
+config :: $(INST_AUTODIR)$(DIRFILESEP).exists
+	$(NOECHO) $(NOOP)
+
+$(INST_AUTODIR)/.exists :: /usr/lib/perl/5.8/CORE/perl.h
+	$(NOECHO) $(MKPATH) $(INST_AUTODIR)
+	$(NOECHO) $(EQUALIZE_TIMESTAMP) /usr/lib/perl/5.8/CORE/perl.h $(INST_AUTODIR)/.exists
+
+	-$(NOECHO) $(CHMOD) $(PERM_RWX) $(INST_AUTODIR)
+
+$(INST_LIBDIR)/.exists :: /usr/lib/perl/5.8/CORE/perl.h
+	$(NOECHO) $(MKPATH) $(INST_LIBDIR)
+	$(NOECHO) $(EQUALIZE_TIMESTAMP) /usr/lib/perl/5.8/CORE/perl.h $(INST_LIBDIR)/.exists
+
+	-$(NOECHO) $(CHMOD) $(PERM_RWX) $(INST_LIBDIR)
+
+$(INST_ARCHAUTODIR)/.exists :: /usr/lib/perl/5.8/CORE/perl.h
+	$(NOECHO) $(MKPATH) $(INST_ARCHAUTODIR)
+	$(NOECHO) $(EQUALIZE_TIMESTAMP) /usr/lib/perl/5.8/CORE/perl.h $(INST_ARCHAUTODIR)/.exists
+
+	-$(NOECHO) $(CHMOD) $(PERM_RWX) $(INST_ARCHAUTODIR)
+
+config :: $(INST_MAN3DIR)$(DIRFILESEP).exists
+	$(NOECHO) $(NOOP)
+
+
+$(INST_MAN3DIR)/.exists :: /usr/lib/perl/5.8/CORE/perl.h
+	$(NOECHO) $(MKPATH) $(INST_MAN3DIR)
+	$(NOECHO) $(EQUALIZE_TIMESTAMP) /usr/lib/perl/5.8/CORE/perl.h $(INST_MAN3DIR)/.exists
+
+	-$(NOECHO) $(CHMOD) $(PERM_RWX) $(INST_MAN3DIR)
+
+help:
+	perldoc ExtUtils::MakeMaker
+
+
+# --- MakeMaker linkext section:
+
+linkext :: $(LINKTYPE)
+	$(NOECHO) $(NOOP)
+
+
+# --- MakeMaker dlsyms section:
+
+
+# --- MakeMaker dynamic section:
+
+dynamic :: $(FIRST_MAKEFILE) $(INST_DYNAMIC) $(INST_BOOT)
+	$(NOECHO) $(NOOP)
+
+
+# --- MakeMaker dynamic_bs section:
+
+BOOTSTRAP =
+
+
+# --- MakeMaker dynamic_lib section:
+
+
+# --- MakeMaker static section:
+
+## $(INST_PM) has been moved to the all: target.
+## It remains here for awhile to allow for old usage: "make static"
+static :: $(FIRST_MAKEFILE) $(INST_STATIC)
+	$(NOECHO) $(NOOP)
+
+
+# --- MakeMaker static_lib section:
+
+
+# --- MakeMaker manifypods section:
+
+POD2MAN_EXE = $(PERLRUN) "-MExtUtils::Command::MM" -e pod2man "--"
+POD2MAN = $(POD2MAN_EXE)
+
+
+manifypods : pure_all  \
+	lib/AppConfig/Args.pm \
+	lib/AppConfig/CGI.pm \
+	lib/AppConfig/File.pm \
+	lib/AppConfig/State.pm \
+	lib/AppConfig/Getopt.pm \
+	lib/AppConfig.pm \
+	lib/AppConfig/Sys.pm \
+	lib/AppConfig/Args.pm \
+	lib/AppConfig/CGI.pm \
+	lib/AppConfig/File.pm \
+	lib/AppConfig/State.pm \
+	lib/AppConfig/Getopt.pm \
+	lib/AppConfig.pm \
+	lib/AppConfig/Sys.pm
+	$(NOECHO) $(POD2MAN) --section=3pm --perm_rw=$(PERM_RW)\
+	  lib/AppConfig/Args.pm $(INST_MAN3DIR)/AppConfig::Args.$(MAN3EXT) \
+	  lib/AppConfig/CGI.pm $(INST_MAN3DIR)/AppConfig::CGI.$(MAN3EXT) \
+	  lib/AppConfig/File.pm $(INST_MAN3DIR)/AppConfig::File.$(MAN3EXT) \
+	  lib/AppConfig/State.pm $(INST_MAN3DIR)/AppConfig::State.$(MAN3EXT) \
+	  lib/AppConfig/Getopt.pm $(INST_MAN3DIR)/AppConfig::Getopt.$(MAN3EXT) \
+	  lib/AppConfig.pm $(INST_MAN3DIR)/AppConfig.$(MAN3EXT) \
+	  lib/AppConfig/Sys.pm $(INST_MAN3DIR)/AppConfig::Sys.$(MAN3EXT) 
+
+
+
+
+# --- MakeMaker processPL section:
+
+
+# --- MakeMaker installbin section:
+
+
+# --- MakeMaker subdirs section:
+
+# none
+
+# --- MakeMaker clean_subdirs section:
+clean_subdirs :
+	$(NOECHO) $(NOOP)
+
+
+# --- MakeMaker clean section:
+
+# Delete temporary files but do not touch installed files. We don't delete
+# the Makefile here so a later make realclean still has a makefile to use.
+
+clean :: clean_subdirs
+	-$(RM_RF) ./blib $(MAKE_APERL_FILE) $(INST_ARCHAUTODIR)/extralibs.all $(INST_ARCHAUTODIR)/extralibs.ld perlmain.c tmon.out mon.out so_locations pm_to_blib *$(OBJ_EXT) *$(LIB_EXT) perl.exe perl perl$(EXE_EXT) $(BOOTSTRAP) $(BASEEXT).bso $(BASEEXT).def lib$(BASEEXT).def $(BASEEXT).exp $(BASEEXT).x core core.*perl.*.? *perl.core core.[0-9] core.[0-9][0-9] core.[0-9][0-9][0-9] core.[0-9][0-9][0-9][0-9] core.[0-9][0-9][0-9][0-9][0-9]
+	-$(MV) $(FIRST_MAKEFILE) $(MAKEFILE_OLD) $(DEV_NULL)
+
+
+# --- MakeMaker realclean_subdirs section:
+realclean_subdirs :
+	$(NOECHO) $(NOOP)
+
+
+# --- MakeMaker realclean section:
+
+# Delete temporary files (via clean) and also delete installed files
+realclean purge ::  clean realclean_subdirs
+	$(RM_RF) $(INST_AUTODIR) $(INST_ARCHAUTODIR)
+	$(RM_RF) $(DISTVNAME)
+	$(RM_F)  blib/lib/AppConfig/Sys.pm blib/lib/AppConfig/Getopt.pm blib/lib/AppConfig.pm blib/lib/AppConfig/Args.pm $(MAKEFILE_OLD) blib/lib/AppConfig/State.pm blib/lib/AppConfig/CGI.pm blib/lib/AppConfig/File.pm
+	$(RM_F) $(FIRST_MAKEFILE)
+
+
+# --- MakeMaker metafile section:
+metafile :
+	$(NOECHO) $(ECHO) '# http://module-build.sourceforge.net/META-spec.html' > META.yml
+	$(NOECHO) $(ECHO) '#XXXXXXX This is a prototype!!!  It will change in the future!!! XXXXX#' >> META.yml
+	$(NOECHO) $(ECHO) 'name:         AppConfig' >> META.yml
+	$(NOECHO) $(ECHO) 'version:      1.56' >> META.yml
+	$(NOECHO) $(ECHO) 'version_from: lib/AppConfig.pm' >> META.yml
+	$(NOECHO) $(ECHO) 'installdirs:  vendor' >> META.yml
+	$(NOECHO) $(ECHO) 'requires:' >> META.yml
+	$(NOECHO) $(ECHO) '    Test::More:                    0' >> META.yml
+	$(NOECHO) $(ECHO) '' >> META.yml
+	$(NOECHO) $(ECHO) 'distribution_type: module' >> META.yml
+	$(NOECHO) $(ECHO) 'generated_by: ExtUtils::MakeMaker version 6.17' >> META.yml
+
+
+# --- MakeMaker metafile_addtomanifest section:
+metafile_addtomanifest:
+	$(NOECHO) $(PERLRUN) -MExtUtils::Manifest=maniadd -e 'eval { maniadd({q{META.yml} => q{Module meta-data (added by MakeMaker)}}) } ' \
+	-e '    or print "Could not add META.yml to MANIFEST: $${'\''@'\''}\n"'
+
+
+# --- MakeMaker dist_basics section:
+distclean :: realclean distcheck
+	$(NOECHO) $(NOOP)
+
+distcheck :
+	$(PERLRUN) "-MExtUtils::Manifest=fullcheck" -e fullcheck
+
+skipcheck :
+	$(PERLRUN) "-MExtUtils::Manifest=skipcheck" -e skipcheck
+
+manifest :
+	$(PERLRUN) "-MExtUtils::Manifest=mkmanifest" -e mkmanifest
+
+veryclean : realclean
+	$(RM_F) *~ *.orig */*~ */*.orig
+
+
+
+# --- MakeMaker dist_core section:
+
+dist : $(DIST_DEFAULT) $(FIRST_MAKEFILE)
+	$(NOECHO) $(PERLRUN) -l -e 'print '\''Warning: Makefile possibly out of date with $(VERSION_FROM)'\''' \
+	-e '    if -e '\''$(VERSION_FROM)'\'' and -M '\''$(VERSION_FROM)'\'' < -M '\''$(FIRST_MAKEFILE)'\'';'
+
+tardist : $(DISTVNAME).tar$(SUFFIX)
+	$(NOECHO) $(NOOP)
+
+uutardist : $(DISTVNAME).tar$(SUFFIX)
+	uuencode $(DISTVNAME).tar$(SUFFIX) $(DISTVNAME).tar$(SUFFIX) > $(DISTVNAME).tar$(SUFFIX)_uu
+
+$(DISTVNAME).tar$(SUFFIX) : distdir
+	$(PREOP)
+	$(TO_UNIX)
+	$(TAR) $(TARFLAGS) $(DISTVNAME).tar $(DISTVNAME)
+	$(RM_RF) $(DISTVNAME)
+	$(COMPRESS) $(DISTVNAME).tar
+	$(POSTOP)
+
+zipdist : $(DISTVNAME).zip
+	$(NOECHO) $(NOOP)
+
+$(DISTVNAME).zip : distdir
+	$(PREOP)
+	$(ZIP) $(ZIPFLAGS) $(DISTVNAME).zip $(DISTVNAME)
+	$(RM_RF) $(DISTVNAME)
+	$(POSTOP)
+
+shdist : distdir
+	$(PREOP)
+	$(SHAR) $(DISTVNAME) > $(DISTVNAME).shar
+	$(RM_RF) $(DISTVNAME)
+	$(POSTOP)
+
+
+# --- MakeMaker distdir section:
+distdir : metafile metafile_addtomanifest
+	$(RM_RF) $(DISTVNAME)
+	$(PERLRUN) "-MExtUtils::Manifest=manicopy,maniread" \
+		-e "manicopy(maniread(),'$(DISTVNAME)', '$(DIST_CP)');"
+
+
+
+# --- MakeMaker dist_test section:
+
+disttest : distdir
+	cd $(DISTVNAME) && $(ABSPERLRUN) Makefile.PL
+	cd $(DISTVNAME) && $(MAKE) $(PASTHRU)
+	cd $(DISTVNAME) && $(MAKE) test $(PASTHRU)
+
+
+# --- MakeMaker dist_ci section:
+
+ci :
+	$(PERLRUN) "-MExtUtils::Manifest=maniread" \
+	  -e "@all = keys %{ maniread() };" \
+	  -e "print(qq{Executing $(CI) @all\n}); system(qq{$(CI) @all});" \
+	  -e "print(qq{Executing $(RCS_LABEL) ...\n}); system(qq{$(RCS_LABEL) @all});"
+
+
+# --- MakeMaker install section:
+
+install :: all pure_install doc_install
+
+install_perl :: all pure_perl_install doc_perl_install
+
+install_site :: all pure_site_install doc_site_install
+
+install_vendor :: all pure_vendor_install doc_vendor_install
+
+pure_install :: pure_$(INSTALLDIRS)_install
+
+doc_install :: doc_$(INSTALLDIRS)_install
+
+pure__install : pure_site_install
+	$(NOECHO) $(ECHO) INSTALLDIRS not defined, defaulting to INSTALLDIRS=site
+
+doc__install : doc_site_install
+	$(NOECHO) $(ECHO) INSTALLDIRS not defined, defaulting to INSTALLDIRS=site
+
+pure_perl_install ::
+	$(NOECHO) umask 022; $(MOD_INSTALL) \
+		$(INST_LIB) $(DESTINSTALLPRIVLIB) \
+		$(INST_ARCHLIB) $(DESTINSTALLARCHLIB) \
+		$(INST_BIN) $(DESTINSTALLBIN) \
+		$(INST_SCRIPT) $(DESTINSTALLSCRIPT) \
+		$(INST_MAN1DIR) $(DESTINSTALLMAN1DIR) \
+		$(INST_MAN3DIR) $(DESTINSTALLMAN3DIR)
+	$(NOECHO) $(WARN_IF_OLD_PACKLIST) \
+		$(SITEARCHEXP)/auto/$(FULLEXT)
+
+
+pure_site_install ::
+	$(NOECHO) umask 02; $(MOD_INSTALL) \
+		read $(SITEARCHEXP)/auto/$(FULLEXT)/.packlist \
+		write $(DESTINSTALLSITEARCH)/auto/$(FULLEXT)/.packlist \
+		$(INST_LIB) $(DESTINSTALLSITELIB) \
+		$(INST_ARCHLIB) $(DESTINSTALLSITEARCH) \
+		$(INST_BIN) $(DESTINSTALLSITEBIN) \
+		$(INST_SCRIPT) $(DESTINSTALLSCRIPT) \
+		$(INST_MAN1DIR) $(DESTINSTALLSITEMAN1DIR) \
+		$(INST_MAN3DIR) $(DESTINSTALLSITEMAN3DIR)
+	$(NOECHO) $(WARN_IF_OLD_PACKLIST) \
+		$(PERL_ARCHLIB)/auto/$(FULLEXT)
+
+pure_vendor_install ::
+	$(NOECHO) umask 022; $(MOD_INSTALL) \
+		$(INST_LIB) $(DESTINSTALLVENDORLIB) \
+		$(INST_ARCHLIB) $(DESTINSTALLVENDORARCH) \
+		$(INST_BIN) $(DESTINSTALLVENDORBIN) \
+		$(INST_SCRIPT) $(DESTINSTALLSCRIPT) \
+		$(INST_MAN1DIR) $(DESTINSTALLVENDORMAN1DIR) \
+		$(INST_MAN3DIR) $(DESTINSTALLVENDORMAN3DIR)
+
+doc_perl_install ::
+
+doc_site_install ::
+	$(NOECHO) $(ECHO) Appending installation info to $(DESTINSTALLSITEARCH)/perllocal.pod
+	-$(NOECHO) umask 02; $(MKPATH) $(DESTINSTALLSITEARCH)
+	-$(NOECHO) umask 02; $(DOC_INSTALL) \
+		"Module" "$(NAME)" \
+		"installed into" "$(INSTALLSITELIB)" \
+		LINKTYPE "$(LINKTYPE)" \
+		VERSION "$(VERSION)" \
+		EXE_FILES "$(EXE_FILES)" \
+		>> $(DESTINSTALLSITEARCH)/perllocal.pod
+
+doc_vendor_install ::
+
+
+uninstall :: uninstall_from_$(INSTALLDIRS)dirs
+
+uninstall_from_perldirs ::
+	$(NOECHO) $(UNINSTALL) $(PERL_ARCHLIB)/auto/$(FULLEXT)/.packlist
+
+uninstall_from_sitedirs ::
+	$(NOECHO) $(UNINSTALL) $(SITEARCHEXP)/auto/$(FULLEXT)/.packlist
+
+uninstall_from_vendordirs ::
+	$(NOECHO) $(UNINSTALL) $(VENDORARCHEXP)/auto/$(FULLEXT)/.packlist
+
+
+# --- MakeMaker force section:
+# Phony target to force checking subdirectories.
+FORCE:
+	$(NOECHO) $(NOOP)
+
+
+# --- MakeMaker perldepend section:
+
+
+# --- MakeMaker makefile section:
+
+# We take a very conservative approach here, but it's worth it.
+# We move Makefile to Makefile.old here to avoid gnu make looping.
+$(FIRST_MAKEFILE) : Makefile.PL $(CONFIGDEP)
+	$(NOECHO) $(ECHO) "Makefile out-of-date with respect to $?"
+	$(NOECHO) $(ECHO) "Cleaning current config before rebuilding Makefile..."
+	$(NOECHO) $(RM_F) $(MAKEFILE_OLD)
+	$(NOECHO) $(MV)   $(FIRST_MAKEFILE) $(MAKEFILE_OLD)
+	-$(MAKE) -f $(MAKEFILE_OLD) clean $(DEV_NULL) || $(NOOP)
+	$(PERLRUN) Makefile.PL "INSTALLDIRS=vendor"
+	$(NOECHO) $(ECHO) "==> Your Makefile has been rebuilt. <=="
+	$(NOECHO) $(ECHO) "==> Please rerun the make command.  <=="
+	false
+
+
+
+# --- MakeMaker staticmake section:
+
+# --- MakeMaker makeaperl section ---
+MAP_TARGET    = perl
+FULLPERL      = /usr/bin/perl
+
+$(MAP_TARGET) :: static $(MAKE_APERL_FILE)
+	$(MAKE) -f $(MAKE_APERL_FILE) $@
+
+$(MAKE_APERL_FILE) : $(FIRST_MAKEFILE)
+	$(NOECHO) $(ECHO) Writing \"$(MAKE_APERL_FILE)\" for this $(MAP_TARGET)
+	$(NOECHO) $(PERLRUNINST) \
+		Makefile.PL DIR= \
+		MAKEFILE=$(MAKE_APERL_FILE) LINKTYPE=static \
+		MAKEAPERL=1 NORECURS=1 CCCDLFLAGS= \
+		INSTALLDIRS=vendor
+
+
+# --- MakeMaker test section:
+
+TEST_VERBOSE=0
+TEST_TYPE=test_$(LINKTYPE)
+TEST_FILE = test.pl
+TEST_FILES = t/*.t
+TESTDB_SW = -d
+
+testdb :: testdb_$(LINKTYPE)
+
+test :: $(TEST_TYPE)
+
+test_dynamic :: pure_all
+	PERL_DL_NONLAZY=1 $(FULLPERLRUN) "-MExtUtils::Command::MM" "-e" "test_harness($(TEST_VERBOSE), '$(INST_LIB)', '$(INST_ARCHLIB)')" $(TEST_FILES)
+
+testdb_dynamic :: pure_all
+	PERL_DL_NONLAZY=1 $(FULLPERLRUN) $(TESTDB_SW) "-I$(INST_LIB)" "-I$(INST_ARCHLIB)" $(TEST_FILE)
+
+test_ : test_dynamic
+
+test_static :: test_dynamic
+testdb_static :: testdb_dynamic
+
+
+# --- MakeMaker ppd section:
+# Creates a PPD (Perl Package Description) for a binary distribution.
+ppd:
+	$(NOECHO) $(ECHO) '<SOFTPKG NAME="$(DISTNAME)" VERSION="1,56,0,0">' > $(DISTNAME).ppd
+	$(NOECHO) $(ECHO) '    <TITLE>$(DISTNAME)</TITLE>' >> $(DISTNAME).ppd
+	$(NOECHO) $(ECHO) '    <ABSTRACT>AppConfig is a bundle of Perl5 modules for reading configuration files and parsing command line arguments.</ABSTRACT>' >> $(DISTNAME).ppd
+	$(NOECHO) $(ECHO) '    <AUTHOR>Andy Wardley &lt;abw@wardley.org&gt;</AUTHOR>' >> $(DISTNAME).ppd
+	$(NOECHO) $(ECHO) '    <IMPLEMENTATION>' >> $(DISTNAME).ppd
+	$(NOECHO) $(ECHO) '        <DEPENDENCY NAME="Test-More" VERSION="0,0,0,0" />' >> $(DISTNAME).ppd
+	$(NOECHO) $(ECHO) '        <OS NAME="$(OSNAME)" />' >> $(DISTNAME).ppd
+	$(NOECHO) $(ECHO) '        <ARCHITECTURE NAME="i386-linux-thread-multi" />' >> $(DISTNAME).ppd
+	$(NOECHO) $(ECHO) '        <CODEBASE HREF="" />' >> $(DISTNAME).ppd
+	$(NOECHO) $(ECHO) '    </IMPLEMENTATION>' >> $(DISTNAME).ppd
+	$(NOECHO) $(ECHO) '</SOFTPKG>' >> $(DISTNAME).ppd
+
+
+# --- MakeMaker pm_to_blib section:
+
+pm_to_blib: $(TO_INST_PM)
+	$(NOECHO) $(PERLRUN) -MExtUtils::Install -e 'pm_to_blib({@ARGV}, '\''$(INST_LIB)/auto'\'', '\''$(PM_FILTER)'\'')'\
+	  lib/AppConfig/Args.pm blib/lib/AppConfig/Args.pm \
+	  lib/AppConfig/CGI.pm blib/lib/AppConfig/CGI.pm \
+	  lib/AppConfig/File.pm blib/lib/AppConfig/File.pm \
+	  lib/AppConfig/State.pm blib/lib/AppConfig/State.pm \
+	  lib/AppConfig/Getopt.pm blib/lib/AppConfig/Getopt.pm \
+	  lib/AppConfig.pm blib/lib/AppConfig.pm \
+	  lib/AppConfig/Sys.pm blib/lib/AppConfig/Sys.pm 
+	$(NOECHO) $(TOUCH) $@
+
+# --- MakeMaker selfdocument section:
+
+
+# --- MakeMaker postamble section:
+
+
+# End.
--- appconfig-1.56.orig/blib/lib/AppConfig/Args.pm
+++ appconfig-1.56/blib/lib/AppConfig/Args.pm
@@ -0,0 +1,249 @@
+#============================================================================
+#
+# AppConfig::Args.pm
+#
+# Perl5 module to read command line argument and update the variable 
+# values in an AppConfig::State object accordingly.
+#
+# Written by Andy Wardley <abw@wardley.org>
+#
+# Copyright (C) 1997-2003 Andy Wardley.  All Rights Reserved.
+# Copyright (C) 1997,1998 Canon Research Centre Europe Ltd.
+#
+# $Id: Args.pm,v 1.60 2003/04/29 10:42:39 abw Exp $
+#
+#============================================================================
+
+package AppConfig::Args;
+
+require 5.004;
+use AppConfig::State;
+use strict;
+use vars qw( $VERSION );
+
+$VERSION = sprintf("%d.%02d", q$Revision: 1.60 $ =~ /(\d+)\.(\d+)/);
+
+
+#------------------------------------------------------------------------
+# new($state, \@args)
+#
+# Module constructor.  The first, mandatory parameter should be a 
+# reference to an AppConfig::State object to which all actions should 
+# be applied.  The second parameter may be a reference to a list of 
+# command line arguments.  This list reference is passed to args() for
+# processing.
+#
+# Returns a reference to a newly created AppConfig::Args object.
+#------------------------------------------------------------------------
+
+sub new {
+    my $class = shift;
+    my $state = shift;
+    
+
+    my $self = {
+        STATE    => $state,                # AppConfig::State ref
+	DEBUG    => $state->_debug(),      # store local copy of debug
+	PEDANTIC => $state->_pedantic,     # and pedantic flags
+    };
+
+    bless $self, $class;
+	
+    # call parse() to parse any arg list passed 
+    $self->parse(shift)
+	if @_;
+
+    return $self;
+}
+
+
+#------------------------------------------------------------------------
+# parse(\@args)
+#
+# Examines the argument list and updates the contents of the 
+# AppConfig::State referenced by $self->{ STATE } accordingly.  If 
+# no argument list is provided then the method defaults to examining 
+# @ARGV.  The method reports any warning conditions (such as undefined
+# variables) by calling $self->{ STATE }->_error() and then continues to
+# examine the rest of the list.  If the PEDANTIC option is set in the
+# AppConfig::State object, this behaviour is overridden and the method
+# returns 0 immediately on any parsing error.
+#
+# Returns 1 on success or 0 if one or more warnings were raised.
+#------------------------------------------------------------------------
+
+sub parse {
+    my $self = shift;
+    my $argv = shift || \@ARGV;
+    my $warnings = 0;
+    my ($arg, $nargs, $variable, $value);
+
+
+    # take a local copy of the state to avoid much hash dereferencing
+    my ($state, $debug, $pedantic) = @$self{ qw( STATE DEBUG PEDANTIC ) };
+
+
+
+    # loop around arguments
+    ARG: while (@$argv && $argv->[0] =~ /^-/) {
+	$arg = shift(@$argv);
+
+	# '--' indicates the end of the options
+	last if $arg eq '--';
+
+	# strip leading '-';
+	($variable = $arg) =~ s/^-(-)?//;
+
+	# test for '--' prefix and push back any '=value' item
+	if (defined $1) {
+	    ($variable, $value) = split(/=/, $variable);
+	    unshift(@$argv, $value) if defined $value;
+	}
+
+	# check the variable exists
+	if ($state->_exists($variable)) {
+
+	    # see if it expects any mandatory arguments
+	    $nargs = $state->_argcount($variable);
+	    if ($nargs) {
+		# check there's another arg and it's not another '-opt'
+		if(defined($argv->[0])) {
+		    $value = shift(@$argv);
+		}
+		else {
+		    $state->_error("$arg expects an argument");
+		    $warnings++;
+		    last ARG if $pedantic;
+		    next;
+		}
+	    }
+	    else {
+		# set a value of 1 if option doesn't expect an argument
+		$value = 1;
+	    }
+
+	    # set the variable with the new value
+	    $state->set($variable, $value);
+	}
+	else {
+	    $state->_error("$arg: invalid option");
+	    $warnings++;
+	    last ARG if $pedantic;
+	}
+    }
+
+    # return status
+    return $warnings ? 0 : 1;
+}
+
+
+
+1;
+
+__END__
+
+=head1 NAME
+
+AppConfig::Args - Perl5 module for reading command line arguments.
+
+=head1 SYNOPSIS
+
+    use AppConfig::Args;
+
+    my $state   = AppConfig::State->new(\%cfg);
+    my $cfgargs = AppConfig::Args->new($state);
+
+    $cfgargs->parse(\@args);            # read args
+
+=head1 OVERVIEW
+
+AppConfig::Args is a Perl5 module which reads command line arguments and 
+uses the options therein to update variable values in an AppConfig::State 
+object.
+
+AppConfig::File is distributed as part of the AppConfig bundle.
+
+=head1 DESCRIPTION
+
+=head2 USING THE AppConfig::Args MODULE
+
+To import and use the AppConfig::Args module the following line should appear
+in your Perl script:
+
+    use AppConfig::Args;
+
+AppConfig::Args is used automatically if you use the AppConfig module 
+and create an AppConfig::Args object through the parse() method.
+      
+AppConfig::File is implemented using object-oriented methods.  A new 
+AppConfig::Args object is created and initialised using the new() method.
+This returns a reference to a new AppConfig::File object.  A reference to
+an AppConfig::State object should be passed in as the first parameter:
+       
+    my $state   = AppConfig::State->new();
+    my $cfgargs = AppConfig::Args->new($state);
+
+This will create and return a reference to a new AppConfig::Args object. 
+
+=head2 PARSING COMMAND LINE ARGUMENTS
+
+The C<parse()> method is used to read a list of command line arguments and 
+update the STATE accordingly.  A reference to the list of arguments should
+be passed in.
+
+    $cfgargs->parse(\@ARGV);
+
+If the method is called without a reference to an argument list then it
+will examine and manipulate @ARGV.
+
+If the PEDANTIC option is turned off in the AppConfig::State object, any 
+parsing errors (invalid variables, unvalidated values, etc) will generate
+warnings, but not cause the method to return.  Having processed all
+arguments, the method will return 1 if processed without warning or 0 if
+one or more warnings were raised.  When the PEDANTIC option is turned on,
+the method generates a warning and immediately returns a value of 0 as soon
+as it encounters any parsing error.
+
+The method continues parsing arguments until it detects the first one that
+does not start with a leading dash, '-'.  Arguments that constitute values
+for other options are not examined in this way.
+
+=head1 FUTURE DEVELOPMENT
+
+This module was developed to provide backwards compatibility (to some 
+degree) with the preceeding App::Config module.  The argument parsing 
+it provides is basic but offers a quick and efficient solution for those
+times when simple option handling is all that is required.
+
+If you require more flexibility in parsing command line arguments, then 
+you should consider using the AppConfig::Getopt module.  This is loaded 
+and used automatically by calling the AppConfig getopt() method.
+
+The AppConfig::Getopt module provides considerably extended functionality 
+over the AppConfig::Args module by delegating out the task of argument 
+parsing to Johan Vromans' Getopt::Long module.  For advanced command-line 
+parsing, this module (either Getopt::Long by itself, or in conjunction with 
+AppConfig::Getopt) is highly recommended.
+
+=head1 AUTHOR
+
+Andy Wardley, E<lt>abw@wardley.orgE<gt>
+
+=head1 REVISION
+
+$Revision: 1.60 $
+
+=head1 COPYRIGHT
+
+Copyright (C) 1997-2003 Andy Wardley.  All Rights Reserved.
+
+Copyright (C) 1997,1998 Canon Research Centre Europe Ltd.
+
+This module is free software; you can redistribute it and/or modify it 
+under the same terms as Perl itself.
+
+=head1 SEE ALSO
+
+AppConfig, AppConfig::State, AppConfig::Getopt, Getopt::Long
+
+=cut
--- appconfig-1.56.orig/blib/lib/AppConfig/CGI.pm
+++ appconfig-1.56/blib/lib/AppConfig/CGI.pm
@@ -0,0 +1,244 @@
+#============================================================================
+#
+# AppConfig::CGI.pm
+#
+# Perl5 module to provide a CGI interface to AppConfig.  Internal variables
+# may be set through the CGI "arguments" appended to a URL.
+# 
+# Written by Andy Wardley <abw@wardley.org>
+#
+# Copyright (C) 1997-2003 Andy Wardley.  All Rights Reserved.
+# Copyright (C) 1997,1998 Canon Research Centre Europe Ltd.
+#
+# $Id: CGI.pm,v 1.60 2003/04/29 10:43:50 abw Exp $
+#
+#============================================================================
+
+package AppConfig::CGI;
+
+require 5.004;
+use AppConfig::State;
+use strict;
+use vars qw( $VERSION );
+
+$VERSION = sprintf("%d.%02d", q$Revision: 1.60 $ =~ /(\d+)\.(\d+)/);
+
+
+#------------------------------------------------------------------------
+# new($state, $query)
+#
+# Module constructor.  The first, mandatory parameter should be a 
+# reference to an AppConfig::State object to which all actions should 
+# be applied.  The second parameter may be a string containing a CGI
+# QUERY_STRING which is then passed to parse() to process.  If no second
+# parameter is specifiied then the parse() process is skipped.
+#
+# Returns a reference to a newly created AppConfig::CGI object.
+#------------------------------------------------------------------------
+
+sub new {
+    my $class = shift;
+    my $state = shift;
+
+    
+    my $self = {
+        STATE    => $state,                # AppConfig::State ref
+	DEBUG    => $state->_debug(),      # store local copy of debug
+	PEDANTIC => $state->_pedantic,     # and pedantic flags
+   };
+
+    bless $self, $class;
+	
+    # call parse(@_) to parse any arg list passed 
+    $self->parse(@_)
+	if @_;
+
+    return $self;
+}
+
+
+#------------------------------------------------------------------------
+# parse($query)
+#
+# Method used to parse a CGI QUERY_STRING and set internal variable 
+# values accordingly.  If a query is not passed as the first parameter,
+# then _get_cgi_query() is called to try to determine the query by 
+# examing the environment as per CGI protocol.
+#
+# Returns 0 if one or more errors or warnings were raised or 1 if the
+# string parsed successfully.
+#------------------------------------------------------------------------
+
+sub parse {
+    my $self     = shift;
+    my $query    = shift;
+    my $warnings = 0;
+    my ($variable, $value, $nargs);
+    
+
+    # take a local copy of the state to avoid much hash dereferencing
+    my ($state, $debug, $pedantic) = @$self{ qw( STATE DEBUG PEDANTIC ) };
+
+    # get the cgi query if not defined
+    $query = $ENV{ QUERY_STRING }
+	unless defined $query;
+
+    # no query to process
+    return 1 unless defined $query;
+
+    # we want to install a custom error handler into the AppConfig::State 
+    # which appends filename and line info to error messages and then 
+    # calls the previous handler;  we start by taking a copy of the 
+    # current handler..
+    my $errhandler = $state->_ehandler();
+
+    # install a closure as a new error handler
+    $state->_ehandler(
+	sub {
+	    # modify the error message 
+	    my $format  = shift;
+	    $format =~ s/</&lt;/g;
+	    $format =~ s/>/&gt;/g;
+	    $format  = "<p>\n<b>[ AppConfig::CGI error: </b>$format<b> ] </b>\n<p>\n";
+	    # send error to stdout for delivery to web client
+	    printf($format, @_);
+	}
+    );
+
+
+    PARAM: foreach (split('&', $query)) {
+
+	# extract parameter and value from query token
+	($variable, $value) = map { _unescape($_) } split('=');
+
+	# check an argument was provided if one was expected
+	if ($nargs = $state->_argcount($variable)) {
+	    unless (defined $value) {
+		$state->_error("$variable expects an argument");
+		$warnings++;
+		last PARAM if $pedantic;
+		next;
+	    }
+	}
+	# default an undefined value to 1 if ARGCOUNT_NONE
+	else {
+	    $value = 1 unless defined $value;
+	}
+
+	# set the variable, noting any error
+	unless ($state->set($variable, $value)) {
+	    $warnings++;
+	    last PARAM if $pedantic;
+	}
+    }
+
+    # restore original error handler
+    $state->_ehandler($errhandler);
+
+    # return $warnings => 0, $success => 1
+    return $warnings ? 0 : 1;
+}
+
+
+
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+# The following sub-routine was lifted from Lincoln Stein's CGI.pm
+# module, version 2.36.  Name has been prefixed by a '_'.
+
+# unescape URL-encoded data
+sub _unescape {
+    my($todecode) = @_;
+    $todecode =~ tr/+/ /;       # pluses become spaces
+    $todecode =~ s/%([0-9a-fA-F]{2})/pack("c",hex($1))/ge;
+    return $todecode;
+}
+
+#
+# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+
+
+
+
+1;
+
+__END__
+
+=head1 NAME
+
+AppConfig::CGI - Perl5 module for processing CGI script parameters.
+
+=head1 SYNOPSIS
+
+    use AppConfig::CGI;
+
+    my $state = AppConfig::State->new(\%cfg);
+    my $cgi   = AppConfig::CGI->new($state);
+
+    $cgi->parse($cgi_query);
+    $cgi->parse();               # looks for CGI query in environment
+
+=head1 OVERVIEW
+
+AppConfig::CGI is a Perl5 module which implements a CGI interface to 
+AppConfig.  It examines the QUERY_STRING environment variable, or a string
+passed explicitly by parameter, which represents the additional parameters
+passed to a CGI query.  This is then used to update variable values in an
+AppConfig::State object accordingly.
+
+AppConfig::CGI is distributed as part of the AppConfig bundle.
+
+=head1 DESCRIPTION
+
+=head2 USING THE AppConfig::CGI MODULE
+
+To import and use the AppConfig::CGI module the following line should appear
+in your Perl script:
+
+    use AppConfig::CGI;
+
+AppConfig::CGI is used automatically if you use the AppConfig module
+and create an AppConfig::CGI object through the cgi() method.
+AppConfig::CGI is implemented using object-oriented methods.  A new
+AppConfig::CGI object is created and initialised using the new()
+method.  This returns a reference to a new AppConfig::CGI object.  A
+reference to an AppConfig::State object should be passed in as the
+first parameter: 
+
+    my $state = AppConfig::State->new(); 
+    my $cgi   = AppConfig::CGI->new($state);
+
+This will create and return a reference to a new AppConfig::CGI object. 
+
+=head2 PARSING CGI QUERIES
+
+The C<parse()> method is used to parse a CGI query which can be specified 
+explicitly, or is automatically extracted from the "QUERY_STRING" CGI 
+environment variable.  This currently limits the module to only supporting 
+the GET method.
+
+See AppConfig for information about using the AppConfig::CGI
+module via the cgi() method.
+
+=head1 AUTHOR
+
+Andy Wardley, C<E<lt>abw@wardley.org<gt>>
+
+=head1 REVISION
+
+$Revision: 1.60 $
+
+=head1 COPYRIGHT
+
+Copyright (C) 1997-2003 Andy Wardley.  All Rights Reserved.
+
+Copyright (C) 1997,1998 Canon Research Centre Europe Ltd.
+
+This module is free software; you can redistribute it and/or modify it 
+under the same terms as Perl itself.
+
+=head1 SEE ALSO
+
+AppConfig, AppConfig::State
+
+=cut
+
--- appconfig-1.56.orig/blib/lib/AppConfig/File.pm
+++ appconfig-1.56/blib/lib/AppConfig/File.pm
@@ -0,0 +1,730 @@
+#============================================================================
+#
+# AppConfig::File.pm
+#
+# Perl5 module to read configuration files and use the contents therein 
+# to update variable values in an AppConfig::State object.
+#
+# Written by Andy Wardley <abw@wardley.org>
+#
+# Copyright (C) 1997-2003 Andy Wardley.  All Rights Reserved.
+# Copyright (C) 1997,1998 Canon Research Centre Europe Ltd.
+#
+# $Id: File.pm,v 1.62 2004/02/04 10:28:28 abw Exp $
+#
+#============================================================================
+
+package AppConfig::File;
+
+require 5.005;
+use AppConfig;
+use AppConfig::State;
+use strict;
+use vars qw( $VERSION );
+
+$VERSION = sprintf("%d.%02d", q$Revision: 1.62 $ =~ /(\d+)\.(\d+)/);
+
+
+#------------------------------------------------------------------------
+# new($state, $file, [$file, ...])
+#
+# Module constructor.  The first, mandatory parameter should be a 
+# reference to an AppConfig::State object to which all actions should 
+# be applied.  The remaining parameters are assumed to be file names or
+# file handles for reading and are passed to parse().
+#
+# Returns a reference to a newly created AppConfig::File object.
+#------------------------------------------------------------------------
+
+sub new {
+    my $class = shift;
+    my $state = shift;
+    
+    my $self = {
+        STATE    => $state,                # AppConfig::State ref
+        DEBUG    => $state->_debug(),      # store local copy of debug 
+        PEDANTIC => $state->_pedantic,     # and pedantic flags
+    };
+
+    bless $self, $class;
+
+    # call parse(@_) to parse any files specified as further params
+    $self->parse(@_)
+	if @_;
+
+    return $self;
+}
+
+
+#------------------------------------------------------------------------
+# parse($file, [file, ...])
+#
+# Reads and parses a config file, updating the contents of the 
+# AppConfig::State referenced by $self->{ STATE } according to the 
+# contents of the file.  Multiple files may be specified and are 
+# examined in turn.  The method reports any error condition via 
+# $self->{ STATE }->_error() and immediately returns undef if it 
+# encounters a system error (i.e. cannot open one of the files.  
+# Parsing errors such as unknown variables or unvalidated values will 
+# also cause warnings to be raised vi the same _error(), but parsing
+# continues to the end of the current file and through any subsequent
+# files.  If the PEDANTIC option is set in the $self->{ STATE } object, 
+# the behaviour is overridden and the method returns 0 immediately on 
+# any system or parsing error.
+#
+# The EXPAND option for each variable determines how the variable
+# value should be expanded.
+#
+# Returns undef on system error, 0 if all files were parsed but generated
+# one or more warnings, 1 if all files parsed without warnings.
+#------------------------------------------------------------------------
+
+sub parse {
+    my $self     = shift;
+    my $warnings = 0;
+    my $prefix;           # [block] defines $prefix
+    my $file;
+    my $flag;
+
+    # take a local copy of the state to avoid much hash dereferencing
+    my ($state, $debug, $pedantic) = @$self{ qw( STATE DEBUG PEDANTIC ) };
+
+    # we want to install a custom error handler into the AppConfig::State 
+    # which appends filename and line info to error messages and then 
+    # calls the previous handler;  we start by taking a copy of the 
+    # current handler..
+    my $errhandler = $state->_ehandler();
+
+    # ...and if it doesn't exist, we craft a default handler
+    $errhandler = sub { warn(sprintf(shift, @_), "\n") }
+	unless defined $errhandler;
+
+    # install a closure as a new error handler
+    $state->_ehandler(
+	sub {
+	    # modify the error message 
+	    my $format  = shift;
+	       $format .= ref $file 
+	                  ? " at line $."
+	                  : " at $file line $.";
+
+	    # chain call to prevous handler
+	    &$errhandler($format, @_);
+	}
+    );
+
+    # trawl through all files passed as params
+    FILE: while ($file = shift) {
+
+	# local/lexical vars ensure opened files get closed
+	my $handle;
+	local *FH;
+
+	# if the file is a reference, we assume it's a file handle, if
+	# not, we assume it's a filename and attempt to open it
+	$handle = $file;
+	if (ref($file)) {
+	    $handle = $file;
+
+	    # DEBUG
+	    print STDERR "reading from file handle: $file\n" if $debug;
+	}
+	else {
+	    # open and read config file
+	    open(FH, $file) or do {
+		# restore original error handler and report error
+	    	$state->_ehandler($errhandler);
+		$state->_error("$file: $!");
+
+		return undef;
+	    };
+	    $handle = \*FH;
+
+	    # DEBUG
+	    print STDERR "reading file: $file\n" if $debug;
+	}
+
+	# initialise $prefix to nothing (no [block])
+	$prefix = '';
+
+	while (<$handle>) {
+	    chomp;
+
+            # Throw away everything from an unescaped # to EOL
+            s/(^|\s+)#.*/$1/;
+
+	    # add next line if there is one and this is a continuation
+	    if (s/\\$// && !eof($handle)) {
+		$_ .= <$handle>;
+		redo;
+	    }
+
+            # Convert \# -> #
+            s/\\#/#/g;
+
+            # ignore blank lines
+            next if /^\s*$/;
+
+	    # strip leading and trailing whitespace
+	    s/^\s+//;
+	    s/\s+$//;
+
+	    # look for a [block] to set $prefix
+	    if (/^\[([^\]]+)\]$/) {
+		$prefix = $1;
+		print STDERR "Entering [$prefix] block\n" if $debug;
+		next;
+	    }
+
+	    # split line up by whitespace (\s+) or "equals" (\s*=\s*)
+	    if (/^([^\s=]+)(?:(?:(?:\s*=\s*)|\s+)(.*))?/) {
+		my ($variable, $value) = ($1, $2);
+
+		if (defined $value) {
+		    # here document
+		    if ($value =~ /^([^\s=]+\s*=)?\s*<<(['"]?)(\S+)\2$/) { # '<<XX' or 'hashkey =<<XX'
+			my $boundary = "$3\n";
+			$value = defined($1) ? $1 : '';
+			while (<$handle>) {
+			    last if $_ eq $boundary;
+			    $value .= $_;
+			};
+			$value =~ s/[\r\n]$//;
+		    } else {
+			# strip any quoting from the variable value
+			$value =~ s/^(['"])(.*)\1$/$2/;
+		    };
+		};
+
+		# strip any leading '+/-' from the variable
+		$variable =~ s/^([\-+]?)//;
+		$flag = $1;
+
+		# $variable gets any $prefix 
+		$variable = $prefix . '_' . $variable
+		    if length $prefix;
+
+		# if the variable doesn't exist, we call set() to give 
+		# AppConfig::State a chance to auto-create it
+		unless ($state->_exists($variable) 
+			    || $state->set($variable, 1)) {
+		    $warnings++;
+		    last FILE if $pedantic;
+		    next;
+		}	
+
+		my $nargs = $state->_argcount($variable);
+
+		# variables prefixed '-' are reset to their default values
+		if ($flag eq '-') {
+		    $state->_default($variable);
+		    next;
+		}
+		# those prefixed '+' get set to 1
+		elsif ($flag eq '+') {
+		    $value = 1 unless defined $value;
+		}
+
+		# determine if any extra arguments were expected
+		if ($nargs) {
+		    if (defined $value && length $value) {
+			# expand any embedded variables, ~uids or
+			# environment variables, testing the return value
+			# for errors;  we pass in any variable-specific
+			# EXPAND value 
+			unless ($self->_expand(\$value, 
+				$state->_expand($variable), $prefix)) {
+			    print STDERR "expansion of [$value] failed\n" 
+				if $debug;
+			    $warnings++;
+			    last FILE if $pedantic;
+			}
+		    }
+		    else {
+			$state->_error("$variable expects an argument");
+			$warnings++;
+			last FILE if $pedantic;
+			next;
+		    }
+		}
+		# $nargs = 0
+		else {
+		    # default value to 1 unless it is explicitly defined
+		    # as '0' or "off"
+		    if (defined $value) {
+			# "off" => 0
+    			$value = 0 if $value =~ /off/i;
+			# any value => 1
+			$value = 1 if $value;
+		    }
+		    else {
+			# assume 1 unless explicitly defined off/0
+    			$value = 1;
+		    }
+		    print STDERR "$variable => $value (no expansion)\n"
+			if $debug;
+		}
+	   
+		# set the variable, noting any failure from set()
+		unless ($state->set($variable, $value)) {
+		    $warnings++;
+		    last FILE if $pedantic;
+		}
+	    }
+	    else {
+		$state->_error("parse error");
+		$warnings++;
+	    }
+	}
+    }
+
+    # restore original error handler
+    $state->_ehandler($errhandler);
+    
+    # return $warnings => 0, $success => 1
+    return $warnings ? 0 : 1;
+}
+
+
+
+#========================================================================
+#                      -----  PRIVATE METHODS -----
+#========================================================================
+
+#------------------------------------------------------------------------
+# _expand(\$value, $expand, $prefix)
+#
+# The variable value string, referenced by $value, is examined and any 
+# embedded variables, environment variables or tilde globs (home 
+# directories) are replaced with their respective values, depending on 
+# the value of the second parameter, $expand.  The third paramter may
+# specify the name of the current [block] in which the parser is 
+# parsing.  This prefix is prepended to any embedded variable name that
+# can't otherwise be resolved.  This allows the following to work:
+#
+#   [define]
+#   home = /home/abw
+#   html = $define_home/public_html
+#   html = $home/public_html     # same as above, 'define' is prefix
+#
+# Modifications are made directly into the variable referenced by $value.
+# The method returns 1 on success or 0 if any warnings (undefined 
+# variables) were encountered.
+#------------------------------------------------------------------------
+
+sub _expand {
+    my ($self, $value, $expand, $prefix) = @_;
+    my $warnings = 0;
+    my ($sys, $var, $val);
+
+
+    # ensure prefix contains something (nothing!) valid for length()
+    $prefix = "" unless defined $prefix;
+
+    # take a local copy of the state to avoid much hash dereferencing
+    my ($state, $debug, $pedantic) = @$self{ qw( STATE DEBUG PEDANTIC ) };
+
+    # bail out if there's nothing to do
+    return 1 unless $expand && defined($$value);
+
+    # create an AppConfig::Sys instance, or re-use a previous one, 
+    # to handle platform dependant functions: getpwnam(), getpwuid()
+    unless ($sys = $self->{ SYS }) {
+	require AppConfig::Sys;
+	$sys = $self->{ SYS } = AppConfig::Sys->new();
+    }
+
+    print STDERR "Expansion of [$$value] " if $debug;
+
+    EXPAND: {
+
+        # 
+	# EXPAND_VAR
+	# expand $(var) and $var as AppConfig::State variables
+	#
+	if ($expand & AppConfig::EXPAND_VAR) {
+
+	    $$value =~ s{
+                (?<!\\)\$ (?: \((\w+)\) | (\w+) ) # $2 => $(var) | $3 => $var
+
+	    } {
+		# embedded variable name will be one of $2 or $3
+		$var = defined $1 ? $1 : $2;
+
+		# expand the variable if defined
+		if ($state->_exists($var)) {
+		    $val = $state->get($var);
+		}
+		elsif (length $prefix 
+			&& $state->_exists($prefix . '_' . $var)) {
+		    print STDERR "(\$$var => \$${prefix}_$var) "
+			if $debug;
+		    $var = $prefix . '_' . $var;
+		    $val = $state->get($var);
+		}
+		else {
+		    # raise a warning if EXPAND_WARN set
+		    if ($expand & AppConfig::EXPAND_WARN) {
+			$state->_error("$var: no such variable");
+			$warnings++;
+		    }
+
+		    # replace variable with nothing
+		    $val = '';
+		}
+
+		# $val gets substituted back into the $value string
+		$val;
+	    }gex;
+
+            $$value =~ s/\\\$/\$/g;
+
+	    # bail out now if we need to
+	    last EXPAND if $warnings && $pedantic;
+	}
+
+
+	#
+	# EXPAND_UID
+	# expand ~uid as home directory (for $< if uid not specified)
+	#
+	if ($expand & AppConfig::EXPAND_UID) {
+
+	    $$value =~ s{
+		~(\w+)?                    # $1 => username (optional)
+	    } {
+		$val = undef;
+
+		# embedded user name may be in $1
+		if (defined ($var = $1)) {
+		    # try and get user's home directory
+		    if ($sys->can_getpwnam()) {
+			$val = ($sys->getpwnam($var))[7];
+		    }
+		}
+		else {
+		    # determine home directory 
+		    unless (defined($val = $self->{ HOME })) {
+			if (exists $ENV{ HOME }) {
+			    $val = $ENV{ HOME };
+			}
+			elsif ($sys->can_getpwuid()) {
+			    $val = ($sys->getpwuid($<))[7];
+			}
+
+			# cache value for next time
+			$self->{ HOME } = $val;
+		    }
+		}
+
+		# catch-all for undefined $dir
+		unless (defined $val) {
+		    # raise a warning if EXPAND_WARN set
+		    if ($expand & AppConfig::EXPAND_WARN) {
+			$state->_error("cannot determine home directory%s",
+			    defined $var ? " for $var" : "");
+			$warnings++;
+		    }
+
+		    # replace variable with nothing
+		    $val = '';
+		}
+
+		# $val gets substituted back into the $value string
+		$val;
+	    }gex;
+
+	    # bail out now if we need to
+	    last EXPAND if $warnings && $pedantic;
+	}
+
+
+	#
+	# EXPAND_ENV
+	# expand ${VAR} as environment variables
+	#
+	if ($expand & AppConfig::EXPAND_ENV) {
+
+	    $$value =~ s{ 
+		( \$ \{ (\w+) \} )
+	    } {
+		$var = $2;
+
+		# expand the variable if defined
+		if (exists $ENV{ $var }) {
+		    $val = $ENV{ $var };
+		}
+		else {
+		    # raise a warning if EXPAND_WARN set
+		    if ($expand & AppConfig::EXPAND_WARN) {
+			$state->_error("$var: no such environment variable");
+			$warnings++;
+		    }
+
+		    # replace variable with nothing
+		    $val = '';
+		}
+		# $val gets substituted back into the $value string
+		$val;
+	    }gex;
+
+	    # bail out now if we need to
+	    last EXPAND if $warnings && $pedantic;
+	}
+    }
+
+    print STDERR "=> [$$value] (EXPAND = $expand)\n" if $debug;
+
+    # return status 
+    return $warnings ? 0 : 1;
+}
+
+
+
+#------------------------------------------------------------------------
+# _dump()
+#
+# Dumps the contents of the Config object.
+#------------------------------------------------------------------------
+
+sub _dump {
+    my $self = shift;
+
+    foreach my $key (keys %$self) {
+	printf("%-10s => %s\n", $key, 
+		defined($self->{ $key }) ? $self->{ $key } : "<undef>");
+    }	    
+} 
+
+
+
+1;
+
+__END__
+
+=head1 NAME
+
+AppConfig::File - Perl5 module for reading configuration files.
+
+=head1 SYNOPSIS
+
+    use AppConfig::File;
+
+    my $state   = AppConfig::State->new(\%cfg1);
+    my $cfgfile = AppConfig::File->new($state, $file);
+
+    $cfgfile->parse($file);            # read config file
+
+=head1 OVERVIEW
+
+AppConfig::File is a Perl5 module which reads configuration files and use 
+the contents therein to update variable values in an AppConfig::State 
+object.
+
+AppConfig::File is distributed as part of the AppConfig bundle.
+
+=head1 DESCRIPTION
+
+=head2 USING THE AppConfig::File MODULE
+
+To import and use the AppConfig::File module the following line should appear
+in your Perl script:
+
+    use AppConfig::File;
+
+AppConfig::File is used automatically if you use the AppConfig module 
+and create an AppConfig::File object through the file() method.
+
+AppConfig::File is implemented using object-oriented methods.  A new 
+AppConfig::File object is created and initialised using the 
+AppConfig::File->new() method.  This returns a reference to a new 
+AppConfig::File object.  A reference to an AppConfig::State object 
+should be passed in as the first parameter:
+       
+    my $state   = AppConfig::State->new();
+    my $cfgfile = AppConfig::File->new($state);
+
+This will create and return a reference to a new AppConfig::File object.
+
+=head2 READING CONFIGURATION FILES 
+
+The C<parse()> method is used to read a configuration file and have the 
+contents update the STATE accordingly.
+
+    $cfgfile->parse($file);
+
+Multiple files maye be specified and will be read in turn.
+
+    $cfgfile->parse($file1, $file2, $file3);
+
+The method will return an undef value if it encounters any errors opening
+the files.  It will return immediately without processing any further files.
+By default, the PEDANTIC option in the AppConfig::State object, 
+$self->{ STATE }, is turned off and any parsing errors (invalid variables,
+unvalidated values, etc) will generated warnings, but not cause the method
+to return.  Having processed all files, the method will return 1 if all
+files were processed without warning or 0 if one or more warnings were
+raised.  When the PEDANTIC option is turned on, the method generates a
+warning and immediately returns a value of 0 as soon as it encounters any
+parsing error.
+
+Variables values in the configuration files may be expanded depending on 
+the value of their EXPAND option, as determined from the App::State object.
+See L<AppConfig::State> for more information on variable expansion.
+
+=head2 CONFIGURATION FILE FORMAT
+
+A configuration file may contain blank lines and comments which are
+ignored.  Comments begin with a '#' as the first character on a line
+or following one or more whitespace tokens, and continue to the end of
+the line.
+
+    # this is a comment
+    foo = bar               # so is this
+    url = index.html#hello  # this too, but not the '#welcome'
+
+Notice how the '#welcome' part of the URL is not treated as a comment
+because a whitespace character doesn't precede it.  
+
+Long lines can be continued onto the next line by ending the first 
+line with a '\'.
+
+    callsign = alpha bravo camel delta echo foxtrot golf hipowls \
+               india juliet kilo llama mike november oscar papa  \
+	       quebec romeo sierra tango umbrella victor whiskey \
+	       x-ray yankee zebra
+
+Variables that are simple flags and do not expect an argument (ARGCOUNT = 
+ARGCOUNT_NONE) can be specified without any value.  They will be set with 
+the value 1, with any value explicitly specified (except "0" and "off")
+being ignored.  The variable may also be specified with a "no" prefix to 
+implicitly set the variable to 0.
+
+    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)
+
+Variables that expect an argument (ARGCOUNT = ARGCOUNT_ONE) will be set to 
+whatever follows the variable name, up to the end of the current line.  An
+equals sign may be inserted between the variable and value for clarity.
+
+    room = /home/kitchen     
+    room   /home/bedroom
+
+Each subsequent re-definition of the variable value overwrites the previous
+value.
+
+    print $config->room();               # prints "/home/bedroom"
+
+Variables may be defined to accept multiple values (ARGCOUNT = ARGCOUNT_LIST).
+Each subsequent definition of the variable adds the value to the list of
+previously set values for the variable.  
+
+    drink = coffee
+    drink = tea
+
+A reference to a list of values is returned when the variable is requested.
+
+    my $beverages = $config->drinks();
+    print join(", ", @$beverages);      # prints "coffee, tea"
+
+Variables may also be defined as hash lists (ARGCOUNT = ARGCOUNT_HASH).
+Each subsequent definition creates a new key and value in the hash array.
+
+    alias l="ls -CF"
+    alias h="history"
+
+A reference to the hash is returned when the variable is requested.
+
+    my $aliases = $config->alias();
+    foreach my $k (keys %$aliases) {
+	print "$k => $aliases->{ $k }\n";
+    }
+
+A large chunk of text can be defined using Perl's "heredoc" quoting
+style.
+
+   scalar = <<BOUNDARY_STRING
+   line 1
+   line 2: Space/linebreaks within a HERE document are kept.
+   line 3: The last linebreak (\n) is stripped.
+   BOUNDARY_STRING
+
+   hash   key1 = <<'FOO'
+     * Quotes (['"]) around the boundary string are simply ignored.
+     * Whether the variables in HERE document are expanded depends on
+       the EXPAND option of the variable or global setting.
+   FOO
+
+   hash = key2 = <<"_bar_"
+   Text within HERE document are kept as is.
+   # comments are treated as a normal text.
+   The same applies to line continuation. \
+   _bar_
+   
+Note that you cannot use HERE document as a key in a hash or a name 
+of a variable.
+
+The '-' prefix can be used to reset a variable to its default value and
+the '+' prefix can be used to set it to 1
+
+    -verbose
+    +debug
+
+Variable, environment variable and tilde (home directory) expansions
+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 for each variable or the GLOBAL
+EXPAND value.
+
+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 L<AppConfig::State> for more information on expanding variable values.
+
+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.
+
+    [block1]
+    foo = 10             # block1_foo = 10
+
+    [block2]
+    foo = 20             # block2_foo = 20
+
+=head1 AUTHOR
+
+Andy Wardley, E<lt>abw@wardley.orgE<gt>
+
+=head1 REVISION
+
+$Revision: 1.62 $
+
+=head1 COPYRIGHT
+
+Copyright (C) 1997-2003 Andy Wardley.  All Rights Reserved.
+
+Copyright (C) 1997,1998 Canon Research Centre Europe Ltd.
+
+This module is free software; you can redistribute it and/or modify it 
+under the same terms as Perl itself.
+
+=head1 SEE ALSO
+
+AppConfig, AppConfig::State
+
+=cut
--- appconfig-1.56.orig/blib/lib/AppConfig/Getopt.pm
+++ appconfig-1.56/blib/lib/AppConfig/Getopt.pm
@@ -0,0 +1,281 @@
+#============================================================================
+#
+# AppConfig::Getopt.pm
+#
+# Perl5 module to interface AppConfig::* to Johan Vromans' Getopt::Long
+# module.  Getopt::Long implements the POSIX standard for command line
+# options, with GNU extensions, and also traditional one-letter options.
+# AppConfig::Getopt constructs the necessary Getopt:::Long configuration
+# from the internal AppConfig::State and delegates the parsing of command
+# line arguments to it.  Internal variable values are updated by callback
+# from GetOptions().
+# 
+# Written by Andy Wardley <abw@wardley.org>
+#
+# Copyright (C) 1997-2003 Andy Wardley.  All Rights Reserved.
+# Copyright (C) 1997,1998 Canon Research Centre Europe Ltd.
+#
+# $Id: Getopt.pm,v 1.60 2003/04/29 10:43:21 abw Exp $
+#
+#============================================================================
+
+package AppConfig::Getopt;
+
+require 5.005;
+use AppConfig::State;
+use Getopt::Long 2.17;
+use strict;
+use vars qw( $VERSION );
+
+$VERSION = sprintf("%d.%02d", q$Revision: 1.60 $ =~ /(\d+)\.(\d+)/);
+
+
+#------------------------------------------------------------------------
+# new($state, \@args)
+#
+# Module constructor.  The first, mandatory parameter should be a 
+# reference to an AppConfig::State object to which all actions should 
+# be applied.  The second parameter may be a reference to a list of 
+# command line arguments.  This list reference is passed to parse() for
+# processing.
+#
+# Returns a reference to a newly created AppConfig::Getopt object.
+#------------------------------------------------------------------------
+
+sub new {
+    my $class = shift;
+    my $state = shift;
+
+    
+    my $self = {
+        STATE => $state,
+   };
+
+    bless $self, $class;
+	
+    # call parse() to parse any arg list passed 
+    $self->parse(@_)
+	if @_;
+
+    return $self;
+}
+
+
+#------------------------------------------------------------------------
+# parse(@$config, \@args)
+#
+# Constructs the appropriate configuration information and then delegates
+# the task of processing command line options to Getopt::Long.
+#
+# Returns 1 on success or 0 if one or more warnings were raised.
+#------------------------------------------------------------------------
+
+sub parse {
+    my $self  = shift;
+    my $state = $self->{ STATE };
+    my (@config, $args, $getopt);
+    
+    local $" = ', ';
+
+    # we trap $SIG{__WARN__} errors and patch them into AppConfig::State
+    local $SIG{__WARN__} = sub {
+	my $msg = shift;
+
+	# AppConfig::State doesn't expect CR terminated error messages
+	# and it uses printf, so we protect any embedded '%' chars 
+	chomp($msg);
+	$state->_error("%s", $msg);
+    };
+    
+    # slurp all config items into @config
+    push(@config, shift) while defined $_[0] && ! ref($_[0]);   
+
+    # add debug status if appropriate (hmm...can't decide about this)
+#    push(@config, 'debug') if $state->_debug();
+
+    # next parameter may be a reference to a list of args
+    $args = shift;
+
+    # copy any args explicitly specified into @ARGV
+    @ARGV = @$args if defined $args;
+
+    # we enclose in an eval block because constructor may die()
+    eval {
+	# configure Getopt::Long
+	Getopt::Long::Configure(@config);
+
+	# construct options list from AppConfig::State variables
+	my @opts = $self->{ STATE   }->_getopt_state();
+
+	# DEBUG
+	if ($state->_debug()) {
+	    print STDERR "Calling GetOptions(@opts)\n";
+	    print STDERR "\@ARGV = (@ARGV)\n";
+	};
+
+	# call GetOptions() with specifications constructed from the state
+	$getopt = GetOptions(@opts);
+    };
+    if ($@) {
+	chomp($@);
+	$state->_error("%s", $@);
+	return 0;
+    }
+
+    # udpdate any args reference passed to include only that which is left 
+    # in @ARGV
+    @$args = @ARGV if defined $args;
+
+    return $getopt;
+}
+
+
+#========================================================================
+# AppConfig::State
+#========================================================================
+
+package AppConfig::State;
+
+#------------------------------------------------------------------------
+# _getopt_state()
+#
+# Constructs option specs in the Getopt::Long format for each variable 
+# definition.
+#
+# Returns a list of specification strings.
+#------------------------------------------------------------------------
+
+sub _getopt_state {
+    my $self = shift;
+    my ($var, $spec, $args, $argcount, @specs);
+
+    my $linkage = sub { $self->set(@_) };
+
+    foreach $var (keys %{ $self->{ VARIABLE } }) {
+	$spec  = join('|', $var, @{ $self->{ ALIASES }->{ $var } || [ ] });
+
+	# an ARGS value is used, if specified
+	unless (defined ($args = $self->{ ARGS }->{ $var })) {
+	    # otherwise, construct a basic one from ARGCOUNT
+	    ARGCOUNT: {
+		last ARGCOUNT unless 
+		    defined ($argcount = $self->{ ARGCOUNT }->{ $var });
+
+		$args = "=s",  last ARGCOUNT if $argcount eq ARGCOUNT_ONE;
+		$args = "=s@", last ARGCOUNT if $argcount eq ARGCOUNT_LIST;
+		$args = "=s%", last ARGCOUNT if $argcount eq ARGCOUNT_HASH;
+		$args = "!";
+	    }
+	}
+	$spec .= $args if defined $args;
+
+	push(@specs, $spec, $linkage);
+    }
+
+    return @specs;
+}
+
+
+
+1;
+
+__END__
+
+=head1 NAME
+
+AppConfig::Getopt - Perl5 module for processing command line arguments via delegation to Getopt::Long.
+
+=head1 SYNOPSIS
+
+    use AppConfig::Getopt;
+
+    my $state  = AppConfig::State->new(\%cfg);
+    my $getopt = AppConfig::Getopt->new($state);
+
+    $getopt->parse(\@args);            # read args
+
+=head1 OVERVIEW
+
+AppConfig::Getopt is a Perl5 module which delegates to Johan Vroman's
+Getopt::Long module to parse command line arguments and update values 
+in an AppConfig::State object accordingly.
+
+AppConfig::Getopt is distributed as part of the AppConfig bundle.
+
+=head1 DESCRIPTION
+
+=head2 USING THE AppConfig::Getopt MODULE
+
+To import and use the AppConfig::Getopt module the following line should appear
+in your Perl script:
+
+    use AppConfig::Getopt;
+
+AppConfig::Getopt is used automatically if you use the AppConfig module 
+and create an AppConfig::Getopt object through the getopt() method.
+      
+AppConfig::Getopt is implemented using object-oriented methods.  A new 
+AppConfig::Getopt object is created and initialised using the new() method.
+This returns a reference to a new AppConfig::Getopt object.  A reference to
+an AppConfig::State object should be passed in as the first parameter:
+       
+    my $state  = AppConfig::State->new();
+    my $getopt = AppConfig::Getopt->new($state);
+
+This will create and return a reference to a new AppConfig::Getopt object. 
+
+=head2 PARSING COMMAND LINE ARGUMENTS
+
+The C<parse()> method is used to read a list of command line arguments and 
+update the state accordingly.  
+
+The first (non-list reference) parameters may contain a number of 
+configuration strings to pass to Getopt::Long::Configure.  A reference 
+to a list of arguments may additionally be passed or @ARGV is used by 
+default.
+
+    $getopt->parse();                       # uses @ARGV
+    $getopt->parse(\@myargs);
+    $getopt->parse(qw(auto_abbrev debug));  # uses @ARGV
+    $getopt->parse(qw(debug), \@myargs);
+
+See Getopt::Long for details of the configuartion options available.
+
+A Getopt::Long specification string is constructed for each variable 
+defined in the AppConfig::State.  This consists of the name, any aliases
+and the ARGS value for the variable.
+
+These specification string are then passed to Getopt::Long, the arguments
+are parsed and the values in the AppConfig::State updated.
+
+See AppConfig for information about using the AppConfig::Getopt
+module via the getopt() method.
+
+=head1 AUTHOR
+
+Andy Wardley, E<lt>abw@wardley.orgE<gt>
+
+=head1 REVISION
+
+$Revision: 1.60 $
+
+=head1 COPYRIGHT
+
+Copyright (C) 1997-2003 Andy Wardley.  All Rights Reserved.
+
+Copyright (C) 1997,1998 Canon Research Centre Europe Ltd.
+
+This module is free software; you can redistribute it and/or modify it 
+under the same terms as Perl itself.
+
+=head1 ACKNOWLEDGMENTS
+
+Many thanks are due to Johan Vromans for the Getopt::Long module.  He was 
+kind enough to offer assistance and access to early releases of his code to 
+enable this module to be written.
+
+=head1 SEE ALSO
+
+AppConfig, AppConfig::State, AppConfig::Args, Getopt::Long
+
+=cut
--- appconfig-1.56.orig/blib/lib/AppConfig/State.pm
+++ appconfig-1.56/blib/lib/AppConfig/State.pm
@@ -0,0 +1,1413 @@
+#============================================================================
+#
+# AppConfig::State.pm
+#
+# Perl5 module in which configuration information for an application can
+# be stored and manipulated.  AppConfig::State objects maintain knowledge 
+# about variables; their identities, options, aliases, targets, callbacks 
+# and so on.  This module is used by a number of other AppConfig::* modules.
+#
+# Written by Andy Wardley <abw@wardley.org>
+#
+# Copyright (C) 1997-2003 Andy Wardley.  All Rights Reserved.
+# Copyright (C) 1997,1998 Canon Research Centre Europe Ltd.
+#
+# $Id: State.pm,v 1.61 2004/02/04 10:11:23 abw Exp $
+#
+#----------------------------------------------------------------------------
+#
+# TODO
+#
+# * Change varlist() to varhash() and provide another varlist() method
+#   which returns a list.  Multiple parameters passed implies a hash 
+#   slice/list grep, a single parameter should indicate a regex.
+#
+# * Perhaps allow a callback to be installed which is called *instead* of 
+#   the get() and set() methods (or rather, is called by them).
+#
+# * Maybe CMDARG should be in there to specify extra command-line only 
+#   options that get added to the AppConfig::GetOpt alias construction, 
+#   but not applied in config files, general usage, etc.  The GLOBAL 
+#   CMDARG might be specified as a format, e.g. "-%c" where %s = name, 
+#   %c = first character, %u - first unique sequence(?).  Will 
+#   GetOpt::Long handle --long to -l application automagically?
+#
+# * ..and an added thought is that CASE sensitivity may be required for the
+#   command line (-v vs -V, -r vs -R, for example), but not for parsing 
+#   config files where you may wish to treat "Name", "NAME" and "name" alike.
+#
+#============================================================================
+
+package AppConfig::State;
+
+require 5.004;
+
+use strict;
+use vars qw( $VERSION $AUTOLOAD $DEBUG );
+
+# need access to AppConfig::ARGCOUNT_*
+use AppConfig qw(:argcount);
+
+$VERSION = sprintf("%d.%02d", q$Revision: 1.61 $ =~ /(\d+)\.(\d+)/);
+$DEBUG   = 0;
+
+# internal per-variable hashes that AUTOLOAD should provide access to
+my %METHVARS;
+   @METHVARS{ qw( EXPAND ARGS ARGCOUNT ) } = ();
+
+# internal values that AUTOLOAD should provide access to
+my %METHFLAGS;
+   @METHFLAGS{ qw( PEDANTIC ) } = ();
+
+# variable attributes that may be specified in GLOBAL;
+my @GLOBAL_OK = qw( DEFAULT EXPAND VALIDATE ACTION ARGS ARGCOUNT );
+
+
+#------------------------------------------------------------------------
+# new(\%config, @vars)
+#
+# Module constructor.  A reference to a hash array containing 
+# configuration options may be passed as the first parameter.  This is 
+# passed off to _configure() for processing.  See _configure() for 
+# information about configurarion options.  The remaining parameters
+# may be variable definitions and are passed en masse to define() for
+# processing.
+#
+# Returns a reference to a newly created AppConfig::State object.
+#------------------------------------------------------------------------
+
+sub new {
+    my $class = shift;
+    
+    my $self = {
+        # internal hash arrays to store variable specification information
+        VARIABLE   => { },     # variable values
+        DEFAULT    => { },     # default values
+        ALIAS      => { },     # known aliases  ALIAS => VARIABLE
+        ALIASES    => { },     # reverse alias lookup VARIABLE => ALIASES
+        ARGCOUNT   => { },     # arguments expected
+        ARGS       => { },     # specific argument pattern (AppConfig::Getopt)
+        EXPAND     => { },     # variable expansion (AppConfig::File)
+        VALIDATE   => { },     # validation regexen or functions
+        ACTION     => { },     # callback functions for when variable is set
+        GLOBAL     => { },     # default global settings for new variables
+        
+        # other internal data
+        CREATE     => 0,       # auto-create variables when set
+        CASE       => 0,       # case sensitivity flag (1 = sensitive)
+        PEDANTIC   => 0,       # return immediately on parse warnings
+        EHANDLER   => undef,   # error handler (let's hope we don't need it!)
+        ERROR      => '',      # error message
+    };
+
+    bless $self, $class;
+	
+    # configure if first param is a config hash ref
+    $self->_configure(shift)
+        if ref($_[0]) eq 'HASH';
+
+    # call define(@_) to handle any variables definitions
+    $self->define(@_)
+        if @_;
+
+    return $self;
+}
+
+
+#------------------------------------------------------------------------
+# define($variable, \%cfg, [$variable, \%cfg, ...])
+#
+# Defines one or more variables.  The first parameter specifies the 
+# variable name.  The following parameter may reference a hash of 
+# configuration options for the variable.  Further variables and 
+# configuration hashes may follow and are processed in turn.  If the 
+# parameter immediately following a variable name isn't a hash reference 
+# then it is ignored and the variable is defined without a specific 
+# configuration, although any default parameters as specified in the 
+# GLOBAL option will apply.
+#
+# The $variable value may contain an alias/args definition in compact
+# format, such as "Foo|Bar=1".  
+#
+# A warning is issued (via _error()) if an invalid option is specified.
+#------------------------------------------------------------------------
+
+sub define {
+    my $self = shift;
+    my ($var, $args, $count, $opt, $val, $cfg, @names);
+
+    while (@_) {
+        $var = shift;
+        $cfg = ref($_[0]) eq 'HASH' ? shift : { };
+
+        # variable may be specified in compact format, 'foo|bar=i@'
+        if ($var =~ s/(.+?)([!+=:].*)/$1/) {
+
+            # anything coming after the name|alias list is the ARGS
+            $cfg->{ ARGS } = $2
+                if length $2;
+        }
+
+        # examine any ARGS option
+        if (defined ($args = $cfg->{ ARGS })) {
+          ARGGCOUNT: {
+              $count = ARGCOUNT_NONE, last if $args =~ /^!/;
+              $count = ARGCOUNT_LIST, last if $args =~ /@/;
+              $count = ARGCOUNT_HASH, last if $args =~ /%/;
+              $count = ARGCOUNT_ONE;
+          }
+            $cfg->{ ARGCOUNT } = $count;
+        }
+
+        # split aliases out
+        @names = split(/\|/, $var);
+        $var = shift @names;
+        $cfg->{ ALIAS } = [ @names ] if @names;
+
+        # variable name gets folded to lower unless CASE sensitive
+        $var = lc $var unless $self->{ CASE };
+
+        # activate $variable (so it does 'exist()') 
+        $self->{ VARIABLE }->{ $var } = undef;
+
+        # merge GLOBAL and variable-specific configurations
+        $cfg = { %{ $self->{ GLOBAL } }, %$cfg };
+
+        # examine each variable configuration parameter
+        while (($opt, $val) = each %$cfg) {
+            $opt = uc $opt;
+            
+            # DEFAULT, VALIDATE, EXPAND, ARGS and ARGCOUNT are stored as 
+            # they are;
+            $opt =~ /^DEFAULT|VALIDATE|EXPAND|ARGS|ARGCOUNT$/ && do {
+                $self->{ $opt }->{ $var } = $val;
+                next;
+            };
+            
+            # CMDARG has been deprecated
+            $opt eq 'CMDARG' && do {
+                $self->_error("CMDARG has been deprecated.  "
+                              . "Please use an ALIAS if required.");
+                next;
+            };
+            
+            # ACTION should be a code ref
+            $opt eq 'ACTION' && do {
+                unless (ref($val) eq 'CODE') {
+                    $self->_error("'$opt' value is not a code reference");
+                    next;
+                };
+                
+                # store code ref, forcing keyword to upper case
+                $self->{ ACTION }->{ $var } = $val;
+                
+                next;
+            };
+            
+            # ALIAS creates alias links to the variable name
+            $opt eq 'ALIAS' && do {
+                
+                # coerce $val to an array if not already so
+                $val = [ split(/\|/, $val) ]
+                    unless ref($val) eq 'ARRAY';
+                
+                # fold to lower case unless CASE sensitivity set
+                unless ($self->{ CASE }) {
+                    @$val = map { lc } @$val;
+                }
+                
+                # store list of aliases...
+                $self->{ ALIASES }->{ $var } = $val;
+                
+                # ...and create ALIAS => VARIABLE lookup hash entries
+                foreach my $a (@$val) {
+                    $self->{ ALIAS }->{ $a } = $var;
+                }
+                
+                next;
+            };
+            
+            # default 
+            $self->_error("$opt is not a valid configuration item");
+        }
+        
+    	# set variable to default value
+        $self->_default($var);
+        
+        # DEBUG: dump new variable definition
+        if ($DEBUG) {
+            print STDERR "Variable defined:\n";
+    	    $self->_dump_var($var);
+        }
+    }
+}
+
+
+#------------------------------------------------------------------------
+# get($variable)
+#
+# Returns the value of the variable specified, $variable.  Returns undef
+# if the variable does not exists or is undefined and send a warning
+# message to the _error() function.
+#------------------------------------------------------------------------
+
+sub get {
+    my $self     = shift;
+    my $variable = shift;
+    my $negate   = 0;
+    my $value;
+
+    # _varname returns variable name after aliasing and case conversion
+    # $negate indicates if the name got converted from "no<var>" to "<var>"
+    $variable = $self->_varname($variable, \$negate);
+
+    # check the variable has been defined
+    unless (exists($self->{ VARIABLE }->{ $variable })) {
+        $self->_error("$variable: no such variable");
+        return undef;
+    }
+
+    # DEBUG
+    print STDERR "$self->get($variable) => ", 
+	   defined $self->{ VARIABLE }->{ $variable }
+		  ? $self->{ VARIABLE }->{ $variable }
+		  : "<undef>",
+	  "\n"
+          if $DEBUG;
+
+    # return variable value, possibly negated if the name was "no<var>"
+    $value = $self->{ VARIABLE }->{ $variable };
+
+    return $negate ? !$value : $value;
+}
+
+
+#------------------------------------------------------------------------
+# set($variable, $value)
+#
+# Assigns the value, $value, to the variable specified.
+#
+# Returns 1 if the variable is successfully updated or 0 if the variable 
+# does not exist.  If an ACTION sub-routine exists for the variable, it 
+# will be executed and its return value passed back.
+#------------------------------------------------------------------------
+
+sub set {
+    my $self     = shift;
+    my $variable = shift;
+    my $value    = shift;
+    my $negate   = 0;
+    my $create;
+
+    # _varname returns variable name after aliasing and case conversion
+    # $negate indicates if the name got converted from "no<var>" to "<var>"
+    $variable = $self->_varname($variable, \$negate);
+
+    # check the variable exists
+    if (exists($self->{ VARIABLE }->{ $variable })) {
+        # variable found, so apply any value negation
+        $value = $value ? 0 : 1 if $negate;
+    }
+    else {
+        # auto-create variable if CREATE is 1 or a pattern matching 
+        # the variable name (real name, not an alias)
+        $create = $self->{ CREATE };
+        if (defined $create
+            && ($create eq '1' || $variable =~ /$create/)) {
+            $self->define($variable);
+            
+            print STDERR "Auto-created $variable\n" if $DEBUG;
+        }
+        else {
+            $self->_error("$variable: no such variable");
+            return 0;
+        }
+    }
+    
+    # call the validate($variable, $value) method to perform any validation
+    unless ($self->_validate($variable, $value)) {
+        $self->_error("$variable: invalid value: $value");
+        return 0;
+    }
+    
+    # DEBUG
+    print STDERR "$self->set($variable, ", 
+    defined $value
+        ? $value
+        : "<undef>",
+        ")\n"
+        if $DEBUG;
+    
+
+    # set the variable value depending on its ARGCOUNT
+    my $argcount = $self->{ ARGCOUNT }->{ $variable };
+    $argcount = AppConfig::ARGCOUNT_ONE unless defined $argcount;
+
+    if ($argcount eq AppConfig::ARGCOUNT_LIST) {
+        # push value onto the end of the list
+        push(@{ $self->{ VARIABLE }->{ $variable } }, $value);
+    }
+    elsif ($argcount eq AppConfig::ARGCOUNT_HASH) {
+        # insert "<key>=<value>" data into hash 
+        my ($k, $v) = split(/\s*=\s*/, $value, 2);
+        # strip quoting
+        $v =~ s/^(['"])(.*)\1$/$2/ if defined $v;
+        $self->{ VARIABLE }->{ $variable }->{ $k } = $v;
+    }
+    else {
+        # set simple variable
+        $self->{ VARIABLE }->{ $variable } = $value;
+    }
+
+
+    # call any ACTION function bound to this variable
+    return &{ $self->{ ACTION }->{ $variable } }($self, $variable, $value)
+    	if (exists($self->{ ACTION }->{ $variable }));
+
+    # ...or just return 1 (ok)
+    return 1;
+}
+
+
+#------------------------------------------------------------------------
+# varlist($criteria, $filter)
+#
+# Returns a hash array of all variables and values whose real names 
+# match the $criteria regex pattern passed as the first parameter.
+# If $filter is set to any true value, the keys of the hash array 
+# (variable names) will have the $criteria part removed.  This allows 
+# the caller to specify the variables from one particular [block] and
+# have the "block_" prefix removed, for example.  
+#
+# TODO: This should be changed to varhash().  varlist() should return a 
+# list.  Also need to consider specification by list rather than regex.
+#
+#------------------------------------------------------------------------
+
+sub varlist {
+    my $self     = shift;
+    my $criteria = shift;
+    my $strip    = shift;
+
+    $criteria = "" unless defined $criteria;
+
+    # extract relevant keys and slice out corresponding values
+    my @keys = grep(/$criteria/, keys %{ $self->{ VARIABLE } });
+    my @vals = @{ $self->{ VARIABLE } }{ @keys };
+    my %set;
+
+    # clean off the $criteria part if $strip is set
+    @keys = map { s/$criteria//; $_ } @keys if $strip;
+
+    # slice values into the target hash 
+    @set{ @keys } = @vals;
+    return %set;
+}
+
+    
+#------------------------------------------------------------------------
+# AUTOLOAD
+#
+# Autoload function called whenever an unresolved object method is 
+# called.  If the method name relates to a defined VARIABLE, we patch
+# in $self->get() and $self->set() to magically update the varaiable
+# (if a parameter is supplied) and return the previous value.
+#
+# Thus the function can be used in the folowing ways:
+#    $state->variable(123);     # set a new value
+#    $foo = $state->variable(); # get the current value
+#
+# Returns the current value of the variable, taken before any new value
+# is set.  Prints a warning if the variable isn't defined (i.e. doesn't
+# exist rather than exists with an undef value) and returns undef.
+#------------------------------------------------------------------------
+
+sub AUTOLOAD {
+    my $self = shift;
+    my ($variable, $attrib);
+
+
+    # splat the leading package name
+    ($variable = $AUTOLOAD) =~ s/.*:://;
+
+    # ignore destructor
+    $variable eq 'DESTROY' && return;
+
+
+    # per-variable attributes and internal flags listed as keys in 
+    # %METHFLAGS and %METHVARS respectively can be accessed by a 
+    # method matching the attribute or flag name in lower case with 
+    # a leading underscore_
+    if (($attrib = $variable) =~ s/_//g) {
+        $attrib = uc $attrib;
+	
+        if (exists $METHFLAGS{ $attrib }) {
+            return $self->{ $attrib };
+        }
+
+        if (exists $METHVARS{ $attrib }) {
+            # next parameter should be variable name
+            $variable = shift;
+            $variable = $self->_varname($variable);
+            
+            # check we've got a valid variable
+#	    $self->_error("$variable: no such variable or method"), 
+#		    return undef
+#		unless exists($self->{ VARIABLE }->{ $variable });
+            
+            # return attribute
+            return $self->{ $attrib }->{ $variable };
+        }
+    }
+    
+    # set a new value if a parameter was supplied or return the old one
+    return defined($_[0])
+           ? $self->set($variable, shift)
+           : $self->get($variable);
+}
+
+
+
+#========================================================================
+#                      -----  PRIVATE METHODS -----
+#========================================================================
+
+#------------------------------------------------------------------------
+# _configure(\%cfg)
+#
+# Sets the various configuration options using the values passed in the
+# hash array referenced by $cfg.
+#------------------------------------------------------------------------
+
+sub _configure {
+    my $self = shift;
+    my $cfg  = shift || return;
+
+    # construct a regex to match values which are ok to be found in GLOBAL
+    my $global_ok = join('|', @GLOBAL_OK);
+
+    foreach my $opt (keys %$cfg) {
+
+        # GLOBAL must be a hash ref
+        $opt =~ /^GLOBALS?$/i && do {
+            unless (ref($cfg->{ $opt }) eq 'HASH') {
+                $self->_error("\U$opt\E parameter is not a hash ref");
+                next;
+            }
+
+            # we check each option is ok to be in GLOBAL, but we don't do 
+            # any error checking on the values they contain (but should?).
+            foreach my $global ( keys %{ $cfg->{ $opt } } )  {
+
+                # continue if the attribute is ok to be GLOBAL 
+                next if ($global =~ /(^$global_ok$)/io);
+                         
+                $self->_error( "\U$global\E parameter cannot be GLOBAL");
+            }
+            $self->{ GLOBAL } = $cfg->{ $opt };
+            next;
+        };
+            
+	
+        # CASE, CREATE and PEDANTIC are stored as they are
+        $opt =~ /^CASE|CREATE|PEDANTIC$/i && do {
+            $self->{ uc $opt } = $cfg->{ $opt };
+            next;
+        };
+
+        # ERROR triggers $self->_ehandler()
+        $opt =~ /^ERROR$/i && do {
+            $self->_ehandler($cfg->{ $opt });
+            next;
+        };
+
+        # DEBUG triggers $self->_debug()
+        $opt =~ /^DEBUG$/i && do {
+            $self->_debug($cfg->{ $opt });
+            next;
+        };
+            
+        # warn about invalid options
+        $self->_error("\U$opt\E is not a valid configuration option");
+    }
+}
+
+
+#------------------------------------------------------------------------
+# _varname($variable, \$negated)
+#
+# Variable names are treated case-sensitively or insensitively, depending 
+# on the value of $self->{ CASE }.  When case-insensitive ($self->{ CASE } 
+# != 0), all variable names are converted to lower case.  Variable values 
+# are not converted.  This function simply converts the parameter 
+# (variable) to lower case if $self->{ CASE } isn't set.  _varname() also 
+# expands a variable alias to the name of the target variable.  
+#
+# Variables with an ARGCOUNT of ARGCOUNT_ZERO may be specified as 
+# "no<var>" in which case, the intended value should be negated.  The 
+# leading "no" part is stripped from the variable name.  A reference to 
+# a scalar value can be passed as the second parameter and if the 
+# _varname() method identified such a variable, it will negate the value.  
+# This allows the intended value or a simple negate flag to be passed by
+# reference and be updated to indicate any negation activity taking place.
+#
+# The (possibly modified) variable name is returned.
+#------------------------------------------------------------------------
+
+sub _varname {
+    my $self     = shift;
+    my $variable = shift;
+    my $negated  = shift;
+
+    # convert to lower case if case insensitive
+    $variable = $self->{ CASE } ? $variable : lc $variable;
+
+    # get the actual name if this is an alias
+    $variable = $self->{ ALIAS }->{ $variable }
+	if (exists($self->{ ALIAS }->{ $variable }));
+
+    # if the variable doesn't exist, we can try to chop off a leading 
+    # "no" and see if the remainder matches an ARGCOUNT_ZERO variable
+    unless (exists($self->{ VARIABLE }->{ $variable })) {
+        # see if the variable is specified as "no<var>"
+        if ($variable =~ /^no(.*)/) {
+            # see if the real variable (minus "no") exists and it
+            # has an ARGOUNT of ARGCOUNT_NONE (or no ARGCOUNT at all)
+            my $novar = $self->_varname($1);
+            if (exists($self->{ VARIABLE }->{ $novar })
+                && ! $self->{ ARGCOUNT }->{ $novar }) {
+                # set variable name and negate value 
+                $variable = $novar;
+                $$negated = ! $$negated if defined $negated;
+            }
+        }
+    }
+    
+    # return the variable name
+    $variable;
+}
+
+
+#------------------------------------------------------------------------
+# _default($variable)
+#
+# Sets the variable specified to the default value or undef if it doesn't
+# have a default.  The default value is returned.
+#------------------------------------------------------------------------
+
+sub _default {
+    my $self     = shift;
+    my $variable = shift;
+
+    # _varname returns variable name after aliasing and case conversion
+    $variable = $self->_varname($variable);
+
+    # check the variable exists
+    if (exists($self->{ VARIABLE }->{ $variable })) {
+        # set variable value to the default scalar, an empty list or empty
+        # hash array, depending on its ARGCOUNT value
+        my $argcount = $self->{ ARGCOUNT }->{ $variable };
+        $argcount = AppConfig::ARGCOUNT_ONE unless defined $argcount;
+        
+        if ($argcount == AppConfig::ARGCOUNT_NONE) {
+            return $self->{ VARIABLE }->{ $variable } 
+		    = $self->{ DEFAULT }->{ $variable } || 0;
+        }
+        elsif ($argcount == AppConfig::ARGCOUNT_LIST) {
+            my $deflist = $self->{ DEFAULT }->{ $variable };
+            return $self->{ VARIABLE }->{ $variable } = 
+                [ ref $deflist eq 'ARRAY' ? @$deflist : ( ) ];
+            
+        }
+        elsif ($argcount == AppConfig::ARGCOUNT_HASH) {
+            my $defhash = $self->{ DEFAULT }->{ $variable };
+            return $self->{ VARIABLE }->{ $variable } = 
+            { ref $defhash eq 'HASH' ? %$defhash : () };
+        }
+        else {
+            return $self->{ VARIABLE }->{ $variable } 
+		    = $self->{ DEFAULT }->{ $variable };
+        }
+    }
+    else {
+        $self->_error("$variable: no such variable");
+        return 0;
+    }
+}
+
+
+#------------------------------------------------------------------------
+# _exists($variable)
+#
+# Returns 1 if the variable specified exists or 0 if not.
+#------------------------------------------------------------------------
+
+sub _exists {
+    my $self     = shift;
+    my $variable = shift;
+
+
+    # _varname returns variable name after aliasing and case conversion
+    $variable = $self->_varname($variable);
+
+    # check the variable has been defined
+    return exists($self->{ VARIABLE }->{ $variable });
+}
+
+
+#------------------------------------------------------------------------
+# _validate($variable, $value)
+#
+# Uses any validation rules or code defined for the variable to test if
+# the specified value is acceptable.
+#
+# Returns 1 if the value passed validation checks, 0 if not.
+#------------------------------------------------------------------------
+
+sub _validate {
+    my $self     = shift;
+    my $variable = shift;
+    my $value    = shift;
+    my $validator;
+
+
+    # _varname returns variable name after aliasing and case conversion
+    $variable = $self->_varname($variable);
+
+    # return OK unless there is a validation function
+    return 1 unless defined($validator = $self->{ VALIDATE }->{ $variable });
+
+    #
+    # the validation performed is based on the validator type;
+    #
+    #   CODE ref: code executed, returning 1 (ok) or 0 (failed)
+    #   SCALAR  : a regex which should match the value
+    #
+
+    # CODE ref
+    ref($validator) eq 'CODE' && do {
+    	# run the validation function and return the result
+       	return &$validator($variable, $value);
+    };
+
+    # non-ref (i.e. scalar)
+    ref($validator) || do {
+        # not a ref - assume it's a regex
+        return $value =~ /$validator/;
+    };
+    
+    # validation failed
+    return 0;
+}
+
+
+#------------------------------------------------------------------------
+# _error($format, @params)
+#
+# Checks for the existence of a user defined error handling routine and
+# if defined, passes all variable straight through to that.  The routine
+# is expected to handle a string format and optional parameters as per
+# printf(3C).  If no error handler is defined, the message is formatted
+# and passed to warn() which prints it to STDERR.
+#------------------------------------------------------------------------
+
+sub _error {
+    my $self   = shift;
+    my $format = shift;
+
+    # user defined error handler?
+    if (ref($self->{ EHANDLER }) eq 'CODE') {
+        &{ $self->{ EHANDLER } }($format, @_);
+    }
+    else {
+        warn(sprintf("$format\n", @_));
+    }
+}
+
+
+#------------------------------------------------------------------------
+# _ehandler($handler)
+#
+# Allows a new error handler to be installed.  The current value of 
+# the error handler is returned.
+#
+# This is something of a kludge to allow other AppConfig::* modules to 
+# install their own error handlers to format error messages appropriately.
+# For example, AppConfig::File appends a message of the form 
+# "at $file line $line" to each error message generated while parsing 
+# configuration files.  The previous handler is returned (and presumably
+# stored by the caller) to allow new error handlers to chain control back
+# to any user-defined handler, and also restore the original handler when 
+# done.
+#------------------------------------------------------------------------
+
+sub _ehandler {
+    my $self    = shift;
+    my $handler = shift;
+
+    # save previous value
+    my $previous = $self->{ EHANDLER };
+
+    # update internal reference if a new handler vas provide
+    if (defined $handler) {
+        # check this is a code reference
+        if (ref($handler) eq 'CODE') {
+            $self->{ EHANDLER } = $handler;
+            
+            # DEBUG
+            print STDERR "installed new ERROR handler: $handler\n" if $DEBUG;
+        }
+        else {
+            $self->_error("ERROR handler parameter is not a code ref");
+        }
+    }
+   
+    return $previous;
+}
+
+
+#------------------------------------------------------------------------
+# _debug($debug)
+#
+# Sets the package debugging variable, $AppConfig::State::DEBUG depending 
+# on the value of the $debug parameter.  1 turns debugging on, 0 turns 
+# debugging off.
+#
+# May be called as an object method, $state->_debug(1), or as a package
+# function, AppConfig::State::_debug(1).  Returns the previous value of 
+# $DEBUG, before any new value was applied.
+#------------------------------------------------------------------------
+
+sub _debug {
+    # object reference may not be present if called as a package function
+    my $self   = shift if ref($_[0]);
+    my $newval = shift;
+
+    # save previous value
+    my $oldval = $DEBUG;
+
+    # update $DEBUG if a new value was provided
+    $DEBUG = $newval if defined $newval;
+
+    # return previous value
+    $oldval;
+}
+
+
+#------------------------------------------------------------------------
+# _dump_var($var)
+#
+# Displays the content of the specified variable, $var.
+#------------------------------------------------------------------------
+
+sub _dump_var {
+    my $self   = shift;
+    my $var    = shift;
+
+    return unless defined $var;
+
+    # $var may be an alias, so we resolve the real variable name
+    my $real = $self->_varname($var);
+    if ($var eq $real) {
+    	print STDERR "$var\n";
+    }
+    else {
+    	print STDERR "$real  ('$var' is an alias)\n";
+        $var = $real;
+    }
+
+    # for some bizarre reason, the variable VALUE is stored in VARIABLE
+    # (it made sense at some point in time)
+    printf STDERR "    VALUE        => %s\n", 
+		defined($self->{ VARIABLE }->{ $var }) 
+		    ? $self->{ VARIABLE }->{ $var } 
+		    : "<undef>";
+
+    # the rest of the values can be read straight out of their hashes
+    foreach my $param (qw( DEFAULT ARGCOUNT VALIDATE ACTION EXPAND )) {
+	printf STDERR "    %-12s => %s\n", $param, 
+		defined($self->{ $param }->{ $var }) 
+		    ? $self->{ $param }->{ $var } 
+		    : "<undef>";
+    }
+
+    # summarise all known aliases for this variable
+    print STDERR "    ALIASES      => ", 
+	    join(", ", @{ $self->{ ALIASES }->{ $var } }), "\n"
+            if defined $self->{ ALIASES }->{ $var };
+} 
+
+
+#------------------------------------------------------------------------
+# _dump()
+#
+# Dumps the contents of the Config object and all stored variables.  
+#------------------------------------------------------------------------
+
+sub _dump {
+    my $self = shift;
+    my $var;
+
+    print STDERR "=" x 71, "\n";
+    print STDERR 
+	"Status of AppConfig::State (version $VERSION) object:\n\t$self\n";
+
+    
+    print STDERR "- " x 36, "\nINTERNAL STATE:\n";
+    foreach (qw( CREATE CASE PEDANTIC EHANDLER ERROR )) {
+        printf STDERR "    %-12s => %s\n", $_, 
+		defined($self->{ $_ }) ? $self->{ $_ } : "<undef>";
+    }	    
+
+    print STDERR "- " x 36, "\nVARIABLES:\n";
+    foreach $var (keys %{ $self->{ VARIABLE } }) {
+        $self->_dump_var($var);
+    }
+
+    print STDERR "- " x 36, "\n", "ALIASES:\n";
+    foreach $var (keys %{ $self->{ ALIAS } }) {
+        printf("    %-12s => %s\n", $var, $self->{ ALIAS }->{ $var });
+    }
+    print STDERR "=" x 72, "\n";
+} 
+
+
+
+1;
+
+__END__
+
+=head1 NAME
+
+AppConfig::State - application configuration state
+
+=head1 SYNOPSIS
+
+    use AppConfig::State;
+
+    my $state = AppConfig::State->new(\%cfg);
+
+    $state->define("foo");            # very simple variable definition
+    $state->define("bar", \%varcfg);  # variable specific configuration
+    $state->define("foo|bar=i@");     # compact format
+
+    $state->set("foo", 123);          # trivial set/get examples
+    $state->get("foo");      
+    
+    $state->foo();                    # shortcut variable access 
+    $state->foo(456);                 # shortcut variable update 
+
+=head1 OVERVIEW
+
+AppConfig::State 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 other AppConfig::* modules.  
+
+AppConfig::State is distributed as part of the AppConfig bundle.
+
+=head1 DESCRIPTION
+
+=head2 USING THE AppConfig::State MODULE
+
+To import and use the AppConfig::State module the following line should 
+appear in your Perl script:
+
+     use AppConfig::State;
+
+The AppConfig::State module is loaded automatically by the new()
+constructor of the AppConfig module.
+      
+AppConfig::State is implemented using object-oriented methods.  A 
+new AppConfig::State object is created and initialised using the 
+new() method.  This returns a reference to a new AppConfig::State 
+object.
+       
+    my $state = AppConfig::State->new();
+
+This will create a reference to a new AppConfig::State with all 
+configuration options set to their default values.  You can initialise 
+the object by passing a reference to a hash array containing 
+configuration options:
+
+    $state = AppConfig::State->new( {
+	CASE      => 1,
+	ERROR     => \&my_error,
+    } );
+
+The new() constructor of the AppConfig module automatically passes all 
+parameters to the AppConfig::State new() constructor.  Thus, any global 
+configuration values and variable definitions for AppConfig::State are 
+also applicable to AppConfig.
+
+The following configuration options may be specified.  
+
+=over 4
+
+=item 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".
+
+=item CREATE
+
+By default, CREATE is turned off meaning that all variables accessed via
+set() (which includes access via shortcut such as 
+C<$state-E<gt>variable($value)> which delegates to set()) must previously 
+have been defined via define().  When CREATE is set to 1, calling 
+set($variable, $value) on a variable that doesn't exist will cause it 
+to be created automatically.
+
+When CREATE is set to any other non-zero value, it is assumed to be a
+regular expression pattern.  If the variable name matches the regex, the
+variable is created.  This can be used to specify configuration file 
+blocks in which variables should be created, for example:
+
+    $state = AppConfig::State->new( {
+	CREATE => '^define_',
+    } );
+
+In a config file:
+
+    [define]
+    name = fred           # define_name gets created automatically
+
+    [other]
+    name = john           # other_name doesn't - warning raised
+
+Note that a regex pattern specified in CREATE is applied to the real 
+variable name rather than any alias by which the variables may be 
+accessed.  
+
+=item PEDANTIC
+
+The PEDANTIC option determines what action the configuration file 
+(AppConfig::File) or argument parser (AppConfig::Args) should take 
+on encountering a warning condition (typically caused when trying to set an
+undeclared variable).  If PEDANTIC is set to any true value, the parsing
+methods will immediately return a value of 0 on encountering such a
+condition.  If PEDANTIC is not set, the method will continue to parse the
+remainder of the current file(s) or arguments, returning 0 when complete.
+
+If no warnings or errors are encountered, the method returns 1.
+
+In the case of a system error (e.g. unable to open a file), the method
+returns undef immediately, regardless of the PEDANTIC option.
+
+=item ERROR
+
+Specifies a user-defined error handling routine.  When the handler is 
+called, a format string is passed as the first parameter, followed by 
+any additional values, as per printf(3C).
+
+=item DEBUG
+
+Turns debugging on or off when set to 1 or 0 accordingly.  Debugging may 
+also be activated by calling _debug() as an object method 
+(C<$state-E<gt>_debug(1)>) or as a package function 
+(C<AppConfig::State::_debug(1)>), passing in a true/false value to 
+set the debugging state accordingly.  The package variable 
+$AppConfig::State::DEBUG can also be set directly.  
+
+The _debug() method returns the current debug value.  If a new value 
+is passed in, the internal value is updated, but the previous value is 
+returned.
+
+Note that any AppConfig::File or App::Config::Args objects that are 
+instantiated with a reference to an App::State will inherit the 
+DEBUG (and also PEDANTIC) values of the state at that time.  Subsequent
+changes to the AppConfig::State debug value will not affect them.
+
+=item GLOBAL 
+
+The GLOBAL option allows default values to be set for the DEFAULT, ARGCOUNT, 
+EXPAND, VALIDATE and ACTION options for any subsequently defined variables.
+
+    $state = AppConfig::State->new({
+	GLOBAL => {
+	    DEFAULT  => '<undef>',     # default value for new vars
+	    ARGCOUNT => 1,             # vars expect an argument
+	    ACTION   => \&my_set_var,  # callback when vars get set
+	}
+    });
+
+Any attributes specified explicitly when a variable is defined will
+override any GLOBAL values.
+
+See L<DEFINING VARIABLES> below which describes these options in detail.
+
+=back
+
+=head2 DEFINING VARIABLES
+
+The C<define()> function is used to pre-declare a variable and specify 
+its configuration.
+
+    $state->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:
+
+    $state->define("foo", {
+	    DEFAULT   => 99,
+	    ALIAS     => 'metavar1',
+	});
+
+Any variable-wide GLOBAL values passed to the new() constructor in the 
+configuration hash will also be applied.  Values explicitly specified 
+in a variable's define() configuration will override the respective GLOBAL 
+values.
+
+The following configuration options may be specified
+
+=over 4
+
+=item DEFAULT
+
+The DEFAULT value is used to initialise the variable.  
+
+    $state->define("drink", {
+	    DEFAULT => 'coffee',
+	});
+
+    print $state->drink();        # prints "coffee"
+
+=item 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 can be specified as a reference to an array of alternatives or as 
+a string of names separated by vertical bars, '|'.  e.g.:
+
+    $state->define("name", {
+	    ALIAS  => 'person',
+	});
+or
+    $state->define("name", {
+	    ALIAS => [ 'person', 'user', 'uid' ],
+	});
+or
+    $state->define("name", {
+	    ALIAS => 'person|user|uid',
+	});
+
+    $state->user('abw');     # equivalent to $state->name('abw');
+
+=item ARGCOUNT
+
+The ARGCOUNT option specifies the number of arguments that should be 
+supplied for this variable.  By default, no additional arguments are 
+expected for variables (ARGCOUNT_NONE).
+
+The ARGCOUNT_* constants can be imported from the AppConfig module:
+
+    use AppConfig ':argcount';
+
+    $state->define('foo', { ARGCOUNT => ARGCOUNT_ONE });
+
+or can be accessed directly from the AppConfig package:
+
+    use AppConfig;
+
+    $state->define('foo', { ARGCOUNT => AppConfig::ARGCOUNT_ONE });
+
+The following values for ARGCOUNT may be specified.  
+
+=over 4
+
+=item ARGCOUNT_NONE (0)
+
+Indicates that no additional arguments are expected.  If the variable is
+identified in a confirguration file or in the command line arguments, it
+is set to a value of 1 regardless of whatever arguments follow it.
+
+=item ARGCOUNT_ONE (1)
+
+Indicates that the variable expects a single argument to be provided.
+The variable value will be overwritten with a new value each time it 
+is encountered.
+
+=item ARGCOUNT_LIST (2)
+
+Indicates that the variable expects multiple arguments.  The variable 
+value will be appended to the list of previous values each time it is
+encountered.  
+
+=item ARGCOUNT_HASH (3)
+
+Indicates that the variable expects multiple arguments and that each
+argument is of the form "key=value".  The argument will be split into 
+a key/value pair and inserted into the hash of values each time it 
+is encountered.
+
+=back
+
+=item ARGS
+
+The ARGS option can also be used to specify advanced command line options 
+for use with AppConfig::Getopt, which itself delegates to Getopt::Long.  
+See those two modules for more information on the format and meaning of
+these options.
+
+    $state->define("name", {
+	    ARGS => "=i@",
+	});
+
+=item EXPAND 
+
+The EXPAND option specifies how the AppConfig::File processor should 
+expand embedded variables in the configuration file values it reads.
+By default, EXPAND is turned off (EXPAND_NONE) and no expansion is made.  
+
+The EXPAND_* constants can be imported from the AppConfig module:
+
+    use AppConfig ':expand';
+
+    $state->define('foo', { EXPAND => EXPAND_VAR });
+
+or can be accessed directly from the AppConfig package:
+
+    use AppConfig;
+
+    $state->define('foo', { EXPAND => AppConfig::EXPAND_VAR });
+
+The following values for EXPAND may be specified.  Multiple values should
+be combined with vertical bars , '|', e.g. C<EXPAND_UID | EXPAND_VAR>).
+
+=over 4
+
+=item EXPAND_NONE
+
+Indicates that no variable expansion should be attempted.
+
+=item EXPAND_VAR
+
+Indicates that variables embedded as $var or $(var) should be expanded
+to the values of the relevant AppConfig::State variables.
+
+=item EXPAND_UID 
+
+Indicates that '~' or '~uid' patterns in the string should be 
+expanded to the current users ($<), or specified user's home directory.
+
+=item EXPAND_ENV
+
+Inidicates that variables embedded as ${var} should be expanded to the 
+value of the relevant environment variable.
+
+=item EXPAND_ALL
+
+Equivalent to C<EXPAND_VARS | EXPAND_UIDS | EXPAND_ENVS>).
+
+=item EXPAND_WARN
+
+Indicates that embedded variables that are not defined should raise a
+warning.  If PEDANTIC is set, this will cause the read() method to return 0
+immediately.
+
+=back
+
+=item VALIDATE
+
+Each variable may have a sub-routine or regular expression defined which 
+is used to validate the intended value for a variable before it is set.
+
+If VALIDATE is defined as a regular expression, it is applied to the
+value and deemed valid if the pattern matches.  In this case, the
+variable is then set to the new value.  A warning message is generated
+if the pattern match fails.
+
+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 (see GLOBAL in L<DESCRIPTION> 
+above) then this value will be used as the default VALIDATE for each 
+variable unless otherwise specified.
+
+    $state->define("age", {
+    	    VALIDATE => '\d+',
+	});
+
+    $state->define("pin", {
+	    VALIDATE => \&check_pin,
+	});
+
+=item ACTION
+
+The ACTION option allows a sub-routine to be bound to a variable as a
+callback that is executed whenever the variable is set.  The ACTION is
+passed a reference to the AppConfig::State 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:
+
+    $state->define("foo", { ACTION => \&my_notify });
+
+    sub my_notify {
+	my $state = shift;
+	my $var   = shift;
+	my $val   = shift;
+
+	print "$variable set to $value";
+    }
+
+    $state->foo(42);        # prints "foo set to 42"
+
+Be aware that calling C<$state-E<gt>set()> to update the same variable
+from within the ACTION function will cause a recursive loop as the
+ACTION function is repeatedly called.  
+
+=item 
+
+=back
+
+=head2 DEFINING VARIABLES USING THE COMPACT FORMAT
+
+Variables may be defined in a compact format which allows any ALIAS and
+ARGS values to be specified as part of the variable name.  This is designed
+to mimic the behaviour of Johan Vromans' Getopt::Long module.
+
+Aliases for a variable should be specified after the variable name, 
+separated by vertical bars, '|'.  Any ARGS parameter should be appended 
+after the variable name(s) and/or aliases.
+
+The following examples are equivalent:
+
+    $state->define("foo", { 
+	    ALIAS => [ 'bar', 'baz' ],
+	    ARGS  => '=i',
+	});
+
+    $state->define("foo|bar|baz=i");
+
+=head2 READING AND MODIFYING VARIABLE VALUES
+
+AppConfig::State defines two methods to manipulate variable values: 
+
+    set($variable, $value);
+    get($variable);
+
+Both functions take the variable name as the first parameter and
+C<set()> takes an additional parameter which is the new value for the
+variable.  C<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 C<set()>.  The C<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.
+
+    $state->set("verbose", 1);
+
+is equivalent to 
+
+    $state->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 
+result of the set() operation is returned.
+
+    $state->age(29);        # sets 'age' to 29, returns 1 (ok)
+
+=head2 INTERNAL METHODS
+
+The interal (private) methods of the AppConfig::State class are listed 
+below.
+
+They aren't intended for regular use and potential users should consider
+the fact that nothing about the internal implementation is guaranteed to
+remain the same.  Having said that, the AppConfig::State class is
+intended to co-exist and work with a number of other modules and these
+are considered "friend" classes.  These methods are provided, in part,
+as services to them.  With this acknowledged co-operation in mind, it is
+safe to assume some stability in this core interface.
+
+The _varname() method can be used to determine the real name of a variable 
+from an alias:
+
+    $varname->_varname($alias);
+
+Note that all methods that take a variable name, including those listed
+below, can accept an alias and automatically resolve it to the correct 
+variable name.  There is no need to call _varname() explicitly to do 
+alias expansion.  The _varname() method will fold all variables names
+to lower case unless CASE sensititvity is set.
+
+The _exists() method can be used to check if a variable has been
+defined:
+
+    $state->_exists($varname);
+
+The _default() method can be used to reset a variable to its default value:
+
+    $state->_default($varname);
+
+The _expand() method can be used to determine the EXPAND value for a 
+variable:
+
+    print "$varname EXPAND: ", $state->_expand($varname), "\n";
+
+The _argcount() method returns the value of the ARGCOUNT attribute for a 
+variable:
+
+    print "$varname ARGCOUNT: ", $state->_argcount($varname), "\n";
+
+The _validate() method can be used to determine if a new value for a variable
+meets any validation criteria specified for it.  The variable name and 
+intended value should be passed in.  The methods returns a true/false value
+depending on whether or not the validation succeeded:
+
+    print "OK\n" if $state->_validate($varname, $value);
+
+The _pedantic() method can be called to determine the current value of the
+PEDANTIC option.
+
+    print "pedantic mode is ", $state->_pedantic() ? "on" ; "off", "\n";
+
+The _debug() method can be used to turn debugging on or off (pass 1 or 0
+as a parameter).  It can also be used to check the debug state,
+returning the current internal value of $AppConfig::State::DEBUG.  If a
+new debug value is provided, the debug state is updated and the previous
+state is returned.
+
+    $state->_debug(1);               # debug on, returns previous value
+
+The _dump_var($varname) and _dump() methods may also be called for
+debugging purposes.  
+
+    $state->_dump_var($varname);    # show variable state
+    $state->_dump();                # show internal state and all vars
+
+=head1 AUTHOR
+
+Andy Wardley, E<lt>abw@wardley.orgE<gt>
+
+=head1 REVISION
+
+$Revision: 1.61 $
+
+=head1 COPYRIGHT
+
+Copyright (C) 1997-2003 Andy Wardley.  All Rights Reserved.
+
+Copyright (C) 1997,1998 Canon Research Centre Europe Ltd.
+
+This module is free software; you can redistribute it and/or modify it 
+under the same terms as Perl itself.
+
+=head1 SEE ALSO
+
+AppConfig, AppConfig::File, AppConfig::Args, AppConfig::Getopt
+
+=cut
--- appconfig-1.56.orig/blib/lib/AppConfig/Sys.pm
+++ appconfig-1.56/blib/lib/AppConfig/Sys.pm
@@ -0,0 +1,304 @@
+#============================================================================
+#
+# AppConfig::Sys.pm
+#
+# Perl5 module providing platform-specific information and operations as 
+# required by other AppConfig::* modules.
+#
+# Written by Andy Wardley <abw@wardley.org>
+#
+# Copyright (C) 1997-2003 Andy Wardley.  All Rights Reserved.
+# Copyright (C) 1997,1998 Canon Research Centre Europe Ltd.
+#
+# $Id: Sys.pm,v 1.61 2004/02/04 10:11:23 abw Exp $
+#
+#============================================================================
+
+package AppConfig::Sys;
+
+require 5.004;
+use strict;
+use vars qw( $VERSION $AUTOLOAD $OS %CAN %METHOD);
+use POSIX qw( getpwnam getpwuid );
+
+$VERSION = sprintf("%d.%02d", q$Revision: 1.61 $ =~ /(\d+)\.(\d+)/);
+
+BEGIN {
+    # define the methods that may be available
+    if($^O =~ m/win32/i) {
+        $METHOD{ getpwuid } = sub { 
+            return wantarray() 
+                ? ( (undef) x 7, getlogin() )
+                : getlogin(); 
+        };
+        $METHOD{ getpwnam } = sub { 
+            die("Can't getpwnam on win32"); 
+        };
+    }
+    else
+    {
+        $METHOD{ getpwuid } = sub { 
+            getpwuid( defined $_[0] ? shift : $< ); 
+        };
+        $METHOD{ getpwnam } = sub { 
+            getpwnam( defined $_[0] ? shift : '' );
+        };
+    }
+    
+    # try out each METHOD to see if it's supported on this platform;
+    # it's important we do this before defining AUTOLOAD which would
+    # otherwise catch the unresolved call
+    foreach my $method  (keys %METHOD) {
+        eval { &{ $METHOD{ $method } }() };
+    	$CAN{ $method } = ! $@;
+    }
+}
+
+
+
+#------------------------------------------------------------------------
+# new($os)
+#
+# Module constructor.  An optional operating system string may be passed
+# to explicitly define the platform type.
+#
+# Returns a reference to a newly created AppConfig::Sys object.
+#------------------------------------------------------------------------
+
+sub new {
+    my $class = shift;
+    
+    my $self = {
+        METHOD => \%METHOD,
+        CAN    => \%CAN,
+    };
+
+    bless $self, $class;
+
+    $self->_configure(@_);
+	
+    return $self;
+}
+
+
+#------------------------------------------------------------------------
+# AUTOLOAD
+#
+# Autoload function called whenever an unresolved object method is 
+# called.  If the method name relates to a METHODS entry, then it is 
+# called iff the corresponding CAN_$method is set true.  If the 
+# method name relates to a CAN_$method value then that is returned.
+#------------------------------------------------------------------------
+
+sub AUTOLOAD {
+    my $self = shift;
+    my $method;
+
+
+    # splat the leading package name
+    ($method = $AUTOLOAD) =~ s/.*:://;
+
+    # ignore destructor
+    $method eq 'DESTROY' && return;
+
+    # can_method()
+    if ($method =~ s/^can_//i && exists $self->{ CAN }->{ $method }) {
+        return $self->{ CAN }->{ $method };
+    }
+    # method() 
+    elsif (exists $self->{ METHOD }->{ $method }) {
+        if ($self->{ CAN }->{ $method }) {
+            return &{ $self->{ METHOD }->{ $method } }(@_);
+        }
+        else {
+            return undef;
+        }
+    } 
+    # variable
+    elsif (exists $self->{ uc $method }) {
+        return $self->{ uc $method };
+    }
+    else {
+        warn("AppConfig::Sys->", $method, "(): no such method or variable\n");
+    }
+
+    return undef;
+}
+
+
+#------------------------------------------------------------------------
+# _configure($os)
+#
+# Uses the first parameter, $os, the package variable $AppConfig::Sys::OS,
+# the value of $^O, or as a last resort, the value of
+# $Config::Config('osname') to determine the current operating
+# system/platform.  Sets internal variables accordingly.
+#------------------------------------------------------------------------
+
+sub _configure {
+    my $self = shift;
+
+    # operating system may be defined as a parameter or in $OS
+    my $os = shift || $OS;
+
+
+    # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 
+    # The following was lifted (and adapated slightly) from Lincoln Stein's 
+    # CGI.pm module, version 2.36...
+    #
+    # FIGURE OUT THE OS WE'RE RUNNING UNDER
+    # Some systems support the $^O variable.  If not
+    # available then require() the Config library
+    unless ($os) {
+	unless ($os = $^O) {
+	    require Config;
+	    $os = $Config::Config{'osname'};
+	}
+    }
+    if ($os =~ /win32/i) {
+        $os = 'WINDOWS';
+    } elsif ($os =~ /vms/i) {
+        $os = 'VMS';
+    } elsif ($os =~ /mac/i) {
+        $os = 'MACINTOSH';
+    } elsif ($os =~ /os2/i) {
+        $os = 'OS2';
+    } else {
+        $os = 'UNIX';
+    }
+
+
+    # The path separator is a slash, backslash or semicolon, depending
+    # on the platform.
+    my $ps = {
+        UNIX      => '/',
+        OS2       => '\\',
+        WINDOWS   => '\\',
+        MACINTOSH => ':',
+        VMS       => '\\'
+    }->{ $os };
+    #
+    # Thanks Lincoln!
+    # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 
+
+
+    $self->{ OS      } = $os;
+    $self->{ PATHSEP } = $ps;
+}
+
+
+#------------------------------------------------------------------------
+# _dump()
+#
+# Dump internals for debugging.
+#------------------------------------------------------------------------
+
+sub _dump {
+    my $self = shift;
+
+    print "=" x 71, "\n";
+    print "Status of AppConfig::Sys (Version $VERSION) object: $self\n";
+    print "    Operating System : ", $self->{ OS      }, "\n";
+    print "      Path Separator : ", $self->{ PATHSEP }, "\n";
+    print "   Available methods :\n";
+    foreach my $can (keys %{ $self->{ CAN } }) {
+        printf "%20s : ", $can;
+        print  $self->{ CAN }->{ $can } ? "yes" : "no", "\n";
+    }
+    print "=" x 71, "\n";
+}
+
+
+
+1;
+
+__END__
+
+=head1 NAME
+
+AppConfig::Sys - Perl5 module defining platform-specific information and methods for other AppConfig::* modules.
+
+=head1 SYNOPSIS
+
+    use AppConfig::Sys;
+    my $sys = AppConfig::Sys->new();
+
+    @fields = $sys->getpwuid($userid);
+    @fields = $sys->getpwnam($username);
+
+=head1 OVERVIEW
+
+AppConfig::Sys is a Perl5 module provides platform-specific information and
+operations as required by other AppConfig::* modules.
+
+AppConfig::Sys is distributed as part of the AppConfig bundle.
+
+=head1 DESCRIPTION
+
+=head2 USING THE AppConfig::Sys MODULE
+
+To import and use the AppConfig::Sys module the following line should
+appear in your Perl script:
+
+     use AppConfig::Sys;
+
+AppConfig::Sys is implemented using object-oriented methods.  A new
+AppConfig::Sys object is created and initialised using the
+AppConfig::Sys->new() method.  This returns a reference to a new
+AppConfig::Sys object.  
+
+    my $sys = AppConfig::Sys->new();
+
+This will attempt to detect your operating system and create a reference to
+a new AppConfig::Sys object that is applicable to your platform.  You may 
+explicitly specify an operating system name to override this automatic 
+detection:
+
+    $unix_sys = AppConfig::Sys->new("Unix");
+
+Alternatively, the package variable $AppConfig::Sys::OS can be set to an
+operating system name.  The valid operating system names are: Win32, VMS,
+Mac, OS2 and Unix.  They are not case-specific.
+
+=head2 AppConfig::Sys METHODS
+
+AppConfig::Sys defines the following methods:
+
+=over 4
+
+=item getpwnam()
+
+Calls the system function getpwnam() if available and returns the result.
+Returns undef if not available.  The can_getpwnam() method can be called to
+determine if this function is available.
+
+=item getpwuid()
+
+Calls the system function getpwuid() if available and returns the result.
+Returns undef if not available.  The can_getpwuid() method can be called to
+determine if this function is available.
+
+=item 
+
+=head1 AUTHOR
+
+Andy Wardley, E<lt>abw@wardley.orgE<gt>
+
+=head1 REVISION
+
+$Revision: 1.61 $
+
+=head1 COPYRIGHT
+
+Copyright (C) 1997-2004 Andy Wardley.  All Rights Reserved.
+
+Copyright (C) 1997,1998 Canon Research Centre Europe Ltd.
+
+This module is free software; you can redistribute it and/or modify it under 
+the term of the Perl Artistic License.
+
+=head1 SEE ALSO
+
+AppConfig, AppConfig::File
+
+=cut
--- appconfig-1.56.orig/blib/lib/AppConfig.pm
+++ appconfig-1.56/blib/lib/AppConfig.pm
@@ -0,0 +1,1054 @@
+#============================================================================
+#
+# AppConfig.pm
+#
+# Perl5 module for reading and parsing configuration files and command line 
+# arguments.
+#
+# Written by Andy Wardley <abw@wardley.org>
+#
+# Copyright (C) 1997-2003 Andy Wardley.  All Rights Reserved.
+# Copyright (C) 1997,1998 Canon Research Centre Europe Ltd.
+#
+# $Id: AppConfig.pm,v 1.7 2004/02/04 10:28:28 abw Exp $
+#
+#============================================================================
+
+package AppConfig;
+
+require 5.005;
+
+use strict;
+use Exporter;
+use vars qw( $VERSION $AUTOLOAD @EXPORT_OK %EXPORT_TAGS );
+use base qw( Exporter );
+
+## This is the main version number for AppConfig
+## It is extracted by ExtUtils::MakeMaker and inserted in various places.
+$VERSION = '1.56';
+
+# variable expansion constants
+use constant EXPAND_NONE    => 0;
+use constant EXPAND_VAR     => 1;
+use constant EXPAND_UID     => 2;
+use constant EXPAND_ENV     => 4;
+use constant EXPAND_ALL     => EXPAND_VAR | EXPAND_UID | EXPAND_ENV;
+use constant EXPAND_WARN    => 8;
+
+# argument count types
+use constant ARGCOUNT_NONE  => 0;
+use constant ARGCOUNT_ONE   => 1;
+use constant ARGCOUNT_LIST  => 2;
+use constant ARGCOUNT_HASH  => 3;
+
+# Exporter tagsets
+my @EXPAND   = qw(EXPAND_NONE EXPAND_VAR EXPAND_UID EXPAND_ENV 
+                  EXPAND_ALL EXPAND_WARN);
+my @ARGCOUNT = qw(ARGCOUNT_NONE ARGCOUNT_ONE ARGCOUNT_LIST ARGCOUNT_HASH);
+
+@EXPORT_OK   = (@EXPAND, @ARGCOUNT);
+%EXPORT_TAGS = (
+    expand   => [ @EXPAND   ],
+    argcount => [ @ARGCOUNT ],
+);
+
+
+#------------------------------------------------------------------------
+# new(\%config, @vars)
+#
+# Module constructor.  All parameters passed are forwarded onto the 
+# AppConfig::State constructor.  Returns a reference to a newly created 
+# AppConfig object.
+#------------------------------------------------------------------------
+
+sub new {
+    my $class = shift;
+
+    require AppConfig::State;
+
+    my $self = {
+        STATE => AppConfig::State->new(@_)
+    };
+
+    bless $self, $class;
+	
+    return $self;
+}
+
+
+#------------------------------------------------------------------------
+# file(@files)
+#
+# The file() method is called to parse configuration files.  An 
+# AppConfig::File object is instantiated and stored internally for
+# use in subsequent calls to file().
+#------------------------------------------------------------------------
+
+sub file {
+    my $self  = shift;
+    my $state = $self->{ STATE };
+    my $file;
+
+    require AppConfig::File;
+
+    # create an AppConfig::File object if one isn't defined 
+    $file = $self->{ FILE } ||= AppConfig::File->new($state);
+
+    # call on the AppConfig::File object to process files.
+    $file->parse(@_);
+}
+
+
+#------------------------------------------------------------------------
+# args(\@args)
+#
+# The args() method is called to parse command line arguments.  An 
+# AppConfig::Args object is instantiated and then stored internally for
+# use in subsequent calls to args().
+#------------------------------------------------------------------------
+
+sub args {
+    my $self  = shift;
+    my $state = $self->{ STATE };
+    my $args;
+
+    require AppConfig::Args;
+
+    # create an AppConfig::Args object if one isn't defined
+    $args = $self->{ ARGS } ||= AppConfig::Args->new($state);
+
+    # call on the AppConfig::Args object to process arguments.
+    $args->parse(shift);
+}
+
+
+#------------------------------------------------------------------------
+# getopt(@config, \@args)
+#
+# The getopt() method is called to parse command line arguments.  The
+# AppConfig::Getopt module is require()'d and an AppConfig::Getopt object
+# is created to parse the arguments.
+#------------------------------------------------------------------------
+
+sub getopt {
+    my $self  = shift;
+    my $state = $self->{ STATE };
+    my $getopt;
+
+    require AppConfig::Getopt;
+
+    # create an AppConfig::Getopt object if one isn't defined
+    $getopt = $self->{ GETOPT } ||= AppConfig::Getopt->new($state);
+
+    # call on the AppConfig::Getopt object to process arguments.
+    $getopt->parse(@_);
+}
+
+
+#------------------------------------------------------------------------
+# cgi($query)
+#
+# The cgi() method is called to parse a CGI query string.  An 
+# AppConfig::CGI object is instantiated and then stored internally for
+# use in subsequent calls to args().
+#------------------------------------------------------------------------
+
+sub cgi {
+    my $self  = shift;
+    my $state = $self->{ STATE };
+    my $cgi;
+
+    require AppConfig::CGI;
+
+    # create an AppConfig::CGI object if one isn't defined
+    $cgi = $self->{ CGI } ||= AppConfig::CGI->new($state);
+
+    # call on the AppConfig::CGI object to process a query.
+    $cgi->parse(shift);
+}
+
+    
+#------------------------------------------------------------------------
+# AUTOLOAD
+#
+# Autoload function called whenever an unresolved object method is 
+# called.  All methods are delegated to the $self->{ STATE } 
+# AppConfig::State object.
+#
+#------------------------------------------------------------------------
+sub AUTOLOAD {
+    my $self = shift;
+    my $method;
+
+    # splat the leading package name
+    ($method = $AUTOLOAD) =~ s/.*:://;
+
+    # ignore destructor
+    $method eq 'DESTROY' && return;
+
+    # delegate method call to AppConfig::State object in $self->{ STATE } 
+    $self->{ STATE }->$method(@_);
+}
+
+
+1;
+
+__END__
+
+=head1 NAME
+
+AppConfig - Perl5 module for reading configuration files and parsing command line arguments.
+
+=head1 SYNOPSIS
+
+    use AppConfig;
+
+    # create a new AppConfig object
+    my $config = AppConfig->new(\%cfg);
+
+    # define a new variable
+    $config->define($varname => \%varopts);
+
+    # create/define combined
+    my $config = AppConfig->new(\%cfg, 
+    $varname => \%varopts, $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(\@args);	# default to \@ARGV
+
+    # advanced command line options with Getopt::Long
+    $config->getopt(\@args);	# default to \@ARGV
+
+    # parse CGI parameters (GET method)
+    $config->cgi($query);	# default to $ENV{ QUERY_STRING }
+
+=head1 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 CGI script parameters.
+
+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.
+
+    # flags
+    verbose 
+    nohelp
+    debug = On
+
+    # single value
+    home  = /home/abw/
+
+    # multiple list value
+    file = /tmp/file1
+    file = /tmp/file2
+
+    # multiple hash value
+    book  camel = Programming Perl
+    book  llama = Learning Perl
+
+The '-' prefix can be used to reset a variable to its default value and
+the '+' prefix can be used to set it to 1
+
+    -verbose
+    +debug
+
+Variable, environment variable and tilde (home directory) expansions
+can be applied (selectively, if necessary) to the values read from 
+configuration files:
+
+    home = ~                    # home directory
+    nntp = ${NNTPSERVER}        # environment variable
+    html = $home/html           # internal variables
+    img  = $html/images
+
+Configuration files may be arranged in blocks as per the style of Win32 
+"INI" files.
+
+    [file]
+    site = kfs
+    src  = ~/websrc/docs/$site
+    lib  = ~/websrc/lib
+    dest = ~/public_html/$site
+
+    [page]
+    header = $lib/header
+    footer = $lib/footer
+
+You can also use Perl's "heredoc" syntax to define a large block of
+text in a configuration file.
+
+    multiline = <<FOOBAR
+    line 1
+    line 2
+    FOOBAR
+
+    paths  exe  = "${PATH}:${HOME}/.bin"
+    paths  link = <<'FOO'
+    ${LD_LIBARRAY_PATH}:${HOME}/lib
+    FOO
+
+Variables may also be set by parsing command line arguments.
+
+    myapp -verbose -site kfs -file f1 -file f2
+
+AppConfig provides a simple method (args()) for parsing command line 
+arguments.  A second method (getopt()) allows more complex argument 
+processing by delegation to Johan Vroman's Getopt::Long module.
+
+AppConfig also allows variables to be set by parameters passed to a 
+CGI script via the URL (GET method).
+
+    http://www.nowhere.com/cgi-bin/myapp?verbose&site=kfs
+
+=head1 PREREQUISITES
+
+AppConfig requires Perl 5.005 or later.  
+
+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.
+
+=head1 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 unbundled 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:
+
+    12) Option, Argument, Parameter and Configuration File Processing
+
+The module is available in the following directories:
+
+    /modules/by-module/AppConfig/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 version
+number, of the form "n.nn", e.g. "3.14".  See the REVISION section
+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 test scripts that are run when 
+a 'make test' is run.
+
+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 "perl Makefile.PL
+LIB=~/lib" in the above - see C<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.
+
+=head1 DESCRIPTION
+
+=head2 USING THE AppConfig MODULE
+
+To import and use the AppConfig module the following line should 
+appear in your Perl script:
+
+     use AppConfig;
+
+To import constants defined by the AppConfig module, specify the name of
+one or more of the constant or tag sets as parameters to C<use>:
+
+    use AppConfig qw(:expand :argcount);
+
+See L<CONSTANT DEFINITIONS> below for more information on the constant
+tagsets defined by 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 AppConfig::State object in which to store variable state.  All 
+arguments passed into the AppConfig constructor are passed directly
+to the AppConfig::State constructor.  
+
+The first (optional) parameter may be a reference to a hash array
+containing configuration information.  
+
+    my $config = AppConfig->new({
+	    CASE   => 1,
+	    ERROR  => \&my_error,
+	    GLOBAL => { 
+		    DEFAULT  => "<unset>", 
+		    ARGCOUNT => ARGCOUNT_ONE,
+		},
+	});
+
+See L<AppConfig::State> for full details of the configuration options
+available.  These are, in brief:
+
+=over 4
+
+=item CASE
+
+Used to set case sensitivity for variable names (default: off).
+
+=item CREATE
+
+Used to indicate that undefined variables should be created automatically
+(default: off).
+
+=item GLOBAL 
+
+Reference to a hash array of global values used by default when defining 
+variables.  Valid global values are DEFAULT, ARGCOUNT, EXPAND, VALIDATE
+and ACTION.
+
+=item PEDANTIC
+
+Used to indicate that command line and configuration file parsing routines
+should return immediately on encountering an error.
+
+=item ERROR
+
+Used to provide a error handling routine.  Arguments as per printf().
+
+=back
+
+Subsequent parameters may be variable definitions.  These are passed 
+to the define() method, described below in L<DEFINING VARIABLES>.
+
+    my $config = AppConfig->new("foo", "bar", "baz");
+    my $config = AppConfig->new({ CASE => 1 }, qw(foo bar baz));
+
+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);
+
+=head2 DEFINING VARIABLES
+
+The C<define()> method (delegated to AppConfig::State) is used to 
+pre-declare a variable and specify its configuration.
+
+    $config->define("foo");
+
+Variables may also be defined directly from the AppConfig new()
+constructor.
+
+    my $config = AppConfig->new("foo");
+
+In both simple examples 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',
+	});
+
+Configuration items specified in the GLOBAL option to the module 
+constructor are applied by default when variables are created.  e.g.
+
+    my $config = AppConfig->new({ 
+	    GLOBAL => {
+		    DEFAULT  => "<undef>",
+		    ARGCOUNT => ARGCOUNT_ONE,
+		}
+	});
+    
+    $config->define("foo");
+    $config->define("bar", { ARGCOUNT => ARGCOUNT_NONE } );
+
+is equivalent to:
+
+    my $config = AppConfig->new();
+
+    $config->define("foo", {
+		DEFAULT  => "<undef>",
+		ARGCOUNT => ARGCOUNT_ONE,
+	    });
+
+    $config->define("bar", 
+		DEFAULT  => "<undef>",
+		ARGCOUNT => ARGCOUNT_NONE,
+	    });
+
+Multiple variables may be defined in the same call to define().
+Configuration hashes for variables can be omitted.
+
+    $config->define("foo", "bar" => { ALIAS = "boozer" }, "baz");
+
+See L<AppConfig::State> for full details of the configuration options
+available when defining variables.  These are, in brief:
+
+=over 
+
+=item DEFAULT
+
+The default value for the variable (default: undef).
+
+=item ALIAS
+
+One or more (list reference or "list|like|this") alternative names for the
+variable.
+
+=item ARGCOUNT
+
+Specifies the number and type of arguments that the variable expects.
+Constants in C<:argcount> tag set define ARGCOUNT_NONE - simple on/off flag
+(default), ARGCOUNT_ONE - single value, ARGCOUNT_LIST - multiple values
+accessed via list reference, ARGCOUNT_HASH - hash table, "key=value",
+accessed via hash reference.
+
+=item ARGS 
+
+Used to provide an argument specification string to pass to Getopt::Long 
+via AppConfig::Getopt.  E.g. "=i", ":s", "=s@".  This can also be used to 
+implicitly set the ARGCOUNT value (C</^!/> = ARGCOUNT_NONE, C</@/> = 
+ARGCOUNT_LIST, C</%/> = ARGCOUNT_HASH, C</[=:].*/> = ARGCOUNT_ONE)
+
+=item EXPAND
+
+Specifies which variable expansion policies should be used when parsing 
+configuration files.  Constants in C<:expand> tag set define EXPAND_NONE
+- no expansion (default), EXPAND_VAR - expand C<$var> or C<$(var)> as 
+other AppConfig variables, EXPAND_UID - expand C<~uid> as user's home 
+directory, EXPAND_ENV - expand C<${var}> as environment variable,
+EXPAND_ALL - do all expansions.  May be logically or'd.
+
+=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).
+
+=item ACTION
+
+Code reference to be called whenever variable value changes.
+
+=back
+
+=head2 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:
+
+    "name|alias|alias<argopts>"
+
+The first element indicates the variable name and subsequent ALIAS 
+values may be added, each separated by a vertical bar '|'.
+
+The E<lt>argoptsE<gt> element indicates the ARGCOUNT value and may be one of 
+the following;
+
+    !                  ARGCOUNT_NONE
+    =s                 ARGCOUNT_ONE
+    =s@                ARGCOUNT_LIST
+    =s%                ARGCOUNT_HASH
+
+Additional constructs supported by Getopt::Long may be specified instead
+of the "=s" element (e.g. "=f").  The entire E<lt>argoptsE<gt> element 
+is stored in the ARGS parameter for the variable and is passed intact to 
+Getopt::Long when the getopt() method is called.  
+
+The following examples demonstrate use of the comapct format, with their
+equivalent full specifications:
+
+    $config->define("foo|bar|baz!");
+
+    $config->define(
+	    "foo" => { 
+		ALIAS    => "bar|baz", 
+		ARGCOUNT => ARGCOUNT_NONE,
+	    });
+
+    $config->define("name=s");
+
+    $config->define(
+	    "name" => { 
+		ARGCOUNT => ARGCOUNT_ONE,
+	    });
+
+    $config->define("file|filelist|f=s@");
+
+    $config->define(
+	    "file" => { 
+		ALIAS    => "filelist|f", 
+		ARGCOUNT => ARGCOUNT_LIST,
+	    });
+
+
+    $config->define("user|u=s%");
+
+    $config->define(
+	    "user" => { 
+		ALIAS    => "u", 
+		ARGCOUNT => ARGCOUNT_HASH,
+	    });
+
+Additional configuration options may be specified by hash reference, as per 
+normal.  The compact definition format will override any configuration 
+values provided for ARGS and ARGCOUNT.
+
+    $config->define("file|filelist|f=s@", { VALIDATE = \&check_file() } );
+
+=head2 READING AND MODIFYING VARIABLE VALUES
+
+AppConfig defines two methods (via AppConfig::State) 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); 
+
+Note that AppConfig defines the following methods:
+
+    new();
+    file();
+    args();
+    getopt();
+
+And also, through delegation to AppConfig::State:
+
+    define()
+    get()
+    set()
+    varlist()
+
+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.
+
+    $config->file();
+
+This will call the file() method, instead of returning the value of the 
+'file' variable.  You can work around this by explicitly calling get() and 
+set() on a variable whose name conflicts:
+
+    $config->get('file');
+
+or by defining a "safe" alias by which the variable can be accessed:
+
+    $config->define("file", { ALIAS => "fileopt" });
+or
+    $config->define("file|fileopt");
+
+    ...
+    $config->fileopt();
+
+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 set() operation is returned.
+
+    $config->age(29);        # sets 'age' to 29, returns 1 (ok)
+    print $config->age();    # prints "29"
+
+The varlist() 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. 
+
+    my %vars = $config->varlist("^file");   # all "file*" variables
+
+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.
+
+    $config->file_name("/tmp/file");
+    $config->file_path("/foo:/bar:/baz");
+
+    my %vars = $config->varlist("^file_", 1);
+
+    # %vars:
+    #    name => /tmp/file
+    #    path => "/foo:/bar:/baz"
+
+
+=head2 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 or files.  Variables stored in the 
+internal AppConfig::State are automatically updated with values specified 
+in the configuration file.  
+
+    $config->file($filename);
+
+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($filename, $filehandle, \*STDIN, ...);
+
+The file may contain blank lines and comments (prefixed by '#') which 
+are ignored.  Continutation lines may be marked by ending the line with 
+a '\'.
+
+    # this is a comment
+    callsign = alpha bravo camel delta echo foxtrot golf hipowls \
+               india juliet kilo llama mike november oscar papa  \
+	       quebec romeo sierra tango umbrella victor whiskey \
+	       x-ray yankee zebra
+
+Variables that are simple flags and do not expect an argument (ARGCOUNT = 
+ARGCOUNT_NONE) can be specified without any value.  They will be set with 
+the value 1, with any value explicitly specified (except "0" and "off")
+being ignored.  The variable may also be specified with a "no" prefix to 
+implicitly set the variable to 0.
+
+    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)
+
+Variables that expect an argument (ARGCOUNT = ARGCOUNT_ONE) 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.
+
+    room = /home/kitchen     
+    room   /home/bedroom
+
+Each subsequent re-definition of the variable value overwrites the previous
+value.
+
+    print $config->room();               # prints "/home/bedroom"
+
+Variables may be defined to accept multiple values (ARGCOUNT = ARGCOUNT_LIST).
+Each subsequent definition of the variable adds the value to the list of
+previously set values for the variable.  
+
+    drink = coffee
+    drink = tea
+
+A reference to a list of values is returned when the variable is requested.
+
+    my $beverages = $config->drinks();
+    print join(", ", @$beverages);      # prints "coffee, tea"
+
+Variables may also be defined as hash lists (ARGCOUNT = ARGCOUNT_HASH).
+Each subsequent definition creates a new key and value in the hash array.
+
+    alias l="ls -CF"
+    alias e="emacs"
+
+A reference to the hash is returned when the variable is requested.
+
+    my $aliases = $config->alias();
+    foreach my $k (keys %$aliases) {
+	print "$k => $aliases->{ $k }\n";
+    }
+
+The '-' prefix can be used to reset a variable to its default value and
+the '+' prefix can be used to set it to 1
+
+    -verbose
+    +debug
+
+=head2 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 EXPAND value for each variable or the GLOBAL
+EXPAND value.
+
+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 L<AppConfig::State> for more information on expanding variable values.
+
+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.
+
+    [block1]
+    foo = 10             # block1_foo = 10
+
+    [block2]
+    foo = 20             # block2_foo = 20
+
+=head2 PARSING COMMAND LINE OPTIONS
+
+There are two methods for processing command line options.  The first, 
+args(), is a small and efficient implementation which offers basic 
+functionality.  The second, getopt(), offers a more powerful and complete
+facility by delegating the task to Johan Vroman's Getopt::Long module.  
+The trade-off between args() and getopt() is essentially one of speed/size
+against flexibility.  Use as appropriate.  Both implement on-demand loading 
+of modules and incur no overhead until used.  
+
+The args() 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.  
+
+The method should be passed a reference to a list of arguments to parse.
+The @ARGV array is used if args() is called without parameters.
+
+    $config->args(\@myargs);
+    $config->args();               # uses @ARGV
+
+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.
+
+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 PEDANTIC option is set, the method will return 0 
+immediately.  With PEDANTIC unset (default), the method will continue
+to parse the rest of the arguments, returning 0 when done.
+
+If the variable is a simple flag (ARGCOUNT = ARGCOUNT_NONE)
+then it is set to the value 1.  The variable may be prefixed by "no" to
+set its value to 0.
+
+    myprog -verbose --debug -notaste     # $config->verbose(1)
+                                         # $config->debug(1)
+                                         # $config->taste(0)
+
+Variables that expect an additional argument (ARGCOUNT != 0) will be set to 
+the value of the argument following it.  
+
+    myprog -f /tmp/myfile                # $config->file('/tmp/file');
+
+Variables that expect multiple values (ARGCOUNT = ARGCOUNT_LIST or
+ARGCOUNT_HASH) will have sucessive values added each time the option
+is encountered.
+
+    myprog -file /tmp/foo -file /tmp/bar # $config->file('/tmp/foo')
+                                         # $config->file('/tmp/bar')
+
+    # file => [ '/tmp/foo', '/tmp/bar' ]
+    
+    myprog -door "jim=Jim Morrison" -door "ray=Ray Manzarek"
+                                    # $config->door("jim=Jim Morrison");
+                                    # $config->door("ray=Ray Manzarek");
+
+    # door => { 'jim' => 'Jim Morrison', 'ray' => 'Ray Manzarek' }
+
+See L<AppConfig::Args> for further details on parsing command line
+arguments.
+
+The getopt() 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.
+
+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 @ARGV is used by 
+default.
+
+    $config->getopt();                       # uses @ARGV
+    $config->getopt(\@myargs);
+    $config->getopt(qw(auto_abbrev debug));  # uses @ARGV
+    $config->getopt(qw(debug), \@myargs);
+
+See Getopt::Long for details of the configuration options available.
+
+The getopt() 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 ARGS parameter.
+
+    $config->define("foo", {
+	ARGS  => "=i",
+	ALIAS => "bar|baz",
+    });
+
+    # Getopt::Long specification: "foo|bar|baz=i"
+
+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 ERROR configuration option.
+
+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.
+
+=head2 PARSING CGI PARAMETERS
+
+The cgi() method provides an interface to the AppConfig::CGI module
+for updating variable values based on the parameters appended to the
+URL for a CGI script.  This is commonly known as the CGI 
+"GET" method.  The CGI "POST" method is currently not supported.
+
+Parameter definitions are separated from the CGI 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:
+
+    http://www.here.com/cgi-bin/myscript?foo=bar&baz=qux&verbose
+
+	# $config->foo('bar');
+	# $config->baz('qux');
+	# $config->verbose(1);
+
+Certain values specified in a URL must be escaped in the appropriate 
+manner (see CGI specifications at http://www.w3c.org/ for full details).  
+The AppConfig::CGI module automatically unescapes the CGI query string
+to restore the parameters to their intended values.
+
+    http://where.com/mycgi?title=%22The+Wrong+Trousers%22
+
+	# $config->title('"The Wrong Trousers"');
+
+Please be considerate of the security implications of providing writeable
+access to script variables via CGI.
+
+    http://rebel.alliance.com/cgi-bin/...
+	.../send_report?file=%2Fetc%2Fpasswd&email=darth%40empire.com
+
+To avoid any accidental or malicious changing of "private" variables, 
+define only the "public" variables before calling the cgi() (or any 
+other) method.  Further variables can subequently be defined which 
+can not be influenced by the CGI parameters.
+
+    $config->define('verbose', 'debug')
+    $config->cgi();		# can only set verbose and debug
+
+    $config->define('email', 'file');
+    $config->file($cfgfile);	# can set verbose, debug, email + file
+
+
+=head1 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 C<use AppConfig> or by importing a set of constants
+identified by its "tag set" name.
+
+    use AppConfig qw(ARGCOUNT_NONE ARGCOUNT_ONE);
+
+    use AppConfig qw(:argcount);
+
+The following tag sets are defined:
+
+=over 4
+
+=item :expand
+
+The ':expand' tagset defines the following constants:
+
+    EXPAND_NONE
+    EXPAND_VAR
+    EXPAND_UID 
+    EXPAND_ENV
+    EXPAND_ALL       # EXPAND_VAR | EXPAND_UID | EXPAND_ENV
+    EXPAND_WARN
+
+See AppConfig::File for full details of the use of these constants.
+
+=item :argcount
+
+The ':argcount' tagset defines the following constants:
+
+    ARGCOUNT_NONE
+    ARGCOUNT_ONE
+    ARGCOUNT_LIST 
+    ARGCOUNT_HASH
+
+See AppConfig::State for full details of the use of these constants.
+
+=back
+
+=head1 AUTHOR
+
+Andy Wardley, E<lt>abw@wardley.orgE<gt>
+
+With contributions from Dave Viner, Ijon Tichy, Axel Gerstmair and
+many others whose names have been lost to the sands of time (reminders
+welcome).
+
+=head1 REVISION
+
+Revision $Revision: 1.7 $ distributed as part of AppConfig 1.56.
+
+=head1 COPYRIGHT
+
+Copyright (C) 1997-2004 Andy Wardley.  All Rights Reserved.
+
+Copyright (C) 1997,1998 Canon Research Centre Europe Ltd.
+
+This module is free software; you can redistribute it and/or modify it 
+under the same terms as Perl itself.
+
+=head1 SEE ALSO
+
+AppConfig::State, AppConfig::File, AppConfig::Args, AppConfig::Getopt,
+AppConfig::CGI, Getopt::Long
+
+=cut
--- appconfig-1.56.orig/blib/man3/AppConfig::Args.3pm
+++ appconfig-1.56/blib/man3/AppConfig::Args.3pm
@@ -0,0 +1,237 @@
+.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
+.\"
+.\" 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::Args 3pm"
+.TH AppConfig::Args 3pm "2003-04-29" "perl v5.8.4" "User Contributed Perl Documentation"
+.SH "NAME"
+AppConfig::Args \- Perl5 module for reading command line arguments.
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+.Vb 1
+\&    use AppConfig::Args;
+.Ve
+.PP
+.Vb 2
+\&    my $state   = AppConfig::State->new(\e%cfg);
+\&    my $cfgargs = AppConfig::Args->new($state);
+.Ve
+.PP
+.Vb 1
+\&    $cfgargs->parse(\e@args);            # read args
+.Ve
+.SH "OVERVIEW"
+.IX Header "OVERVIEW"
+AppConfig::Args is a Perl5 module which reads command line arguments and 
+uses the options therein to update variable values in an AppConfig::State 
+object.
+.PP
+AppConfig::File is distributed as part of the AppConfig bundle.
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+.Sh "\s-1USING\s0 \s-1THE\s0 AppConfig::Args \s-1MODULE\s0"
+.IX Subsection "USING THE AppConfig::Args MODULE"
+To import and use the AppConfig::Args module the following line should appear
+in your Perl script:
+.PP
+.Vb 1
+\&    use AppConfig::Args;
+.Ve
+.PP
+AppConfig::Args is used automatically if you use the AppConfig module 
+and create an AppConfig::Args object through the \fIparse()\fR method.
+.PP
+AppConfig::File is implemented using object-oriented methods.  A new 
+AppConfig::Args object is created and initialised using the \fInew()\fR method.
+This returns a reference to a new AppConfig::File object.  A reference to
+an AppConfig::State object should be passed in as the first parameter:
+.PP
+.Vb 2
+\&    my $state   = AppConfig::State->new();
+\&    my $cfgargs = AppConfig::Args->new($state);
+.Ve
+.PP
+This will create and return a reference to a new AppConfig::Args object. 
+.Sh "\s-1PARSING\s0 \s-1COMMAND\s0 \s-1LINE\s0 \s-1ARGUMENTS\s0"
+.IX Subsection "PARSING COMMAND LINE ARGUMENTS"
+The \f(CW\*(C`parse()\*(C'\fR method is used to read a list of command line arguments and 
+update the \s-1STATE\s0 accordingly.  A reference to the list of arguments should
+be passed in.
+.PP
+.Vb 1
+\&    $cfgargs->parse(\e@ARGV);
+.Ve
+.PP
+If the method is called without a reference to an argument list then it
+will examine and manipulate \f(CW@ARGV\fR.
+.PP
+If the \s-1PEDANTIC\s0 option is turned off in the AppConfig::State object, any 
+parsing errors (invalid variables, unvalidated values, etc) will generate
+warnings, but not cause the method to return.  Having processed all
+arguments, the method will return 1 if processed without warning or 0 if
+one or more warnings were raised.  When the \s-1PEDANTIC\s0 option is turned on,
+the method generates a warning and immediately returns a value of 0 as soon
+as it encounters any parsing error.
+.PP
+The method continues parsing arguments until it detects the first one that
+does not start with a leading dash, '\-'.  Arguments that constitute values
+for other options are not examined in this way.
+.SH "FUTURE DEVELOPMENT"
+.IX Header "FUTURE DEVELOPMENT"
+This module was developed to provide backwards compatibility (to some 
+degree) with the preceeding App::Config module.  The argument parsing 
+it provides is basic but offers a quick and efficient solution for those
+times when simple option handling is all that is required.
+.PP
+If you require more flexibility in parsing command line arguments, then 
+you should consider using the AppConfig::Getopt module.  This is loaded 
+and used automatically by calling the AppConfig \fIgetopt()\fR method.
+.PP
+The AppConfig::Getopt module provides considerably extended functionality 
+over the AppConfig::Args module by delegating out the task of argument 
+parsing to Johan Vromans' Getopt::Long module.  For advanced command-line 
+parsing, this module (either Getopt::Long by itself, or in conjunction with 
+AppConfig::Getopt) is highly recommended.
+.SH "AUTHOR"
+.IX Header "AUTHOR"
+Andy Wardley, <abw@wardley.org>
+.SH "REVISION"
+.IX Header "REVISION"
+$Revision: 1.60 $
+.SH "COPYRIGHT"
+.IX Header "COPYRIGHT"
+Copyright (C) 1997\-2003 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, AppConfig::State, AppConfig::Getopt, Getopt::Long
--- appconfig-1.56.orig/blib/man3/AppConfig::CGI.3pm
+++ appconfig-1.56/blib/man3/AppConfig::CGI.3pm
@@ -0,0 +1,209 @@
+.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
+.\"
+.\" 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::CGI 3pm"
+.TH AppConfig::CGI 3pm "2003-04-29" "perl v5.8.4" "User Contributed Perl Documentation"
+.SH "NAME"
+AppConfig::CGI \- Perl5 module for processing CGI script parameters.
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+.Vb 1
+\&    use AppConfig::CGI;
+.Ve
+.PP
+.Vb 2
+\&    my $state = AppConfig::State->new(\e%cfg);
+\&    my $cgi   = AppConfig::CGI->new($state);
+.Ve
+.PP
+.Vb 2
+\&    $cgi->parse($cgi_query);
+\&    $cgi->parse();               # looks for CGI query in environment
+.Ve
+.SH "OVERVIEW"
+.IX Header "OVERVIEW"
+AppConfig::CGI is a Perl5 module which implements a \s-1CGI\s0 interface to 
+AppConfig.  It examines the \s-1QUERY_STRING\s0 environment variable, or a string
+passed explicitly by parameter, which represents the additional parameters
+passed to a \s-1CGI\s0 query.  This is then used to update variable values in an
+AppConfig::State object accordingly.
+.PP
+AppConfig::CGI is distributed as part of the AppConfig bundle.
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+.Sh "\s-1USING\s0 \s-1THE\s0 AppConfig::CGI \s-1MODULE\s0"
+.IX Subsection "USING THE AppConfig::CGI MODULE"
+To import and use the AppConfig::CGI module the following line should appear
+in your Perl script:
+.PP
+.Vb 1
+\&    use AppConfig::CGI;
+.Ve
+.PP
+AppConfig::CGI is used automatically if you use the AppConfig module
+and create an AppConfig::CGI object through the \fIcgi()\fR method.
+AppConfig::CGI is implemented using object-oriented methods.  A new
+AppConfig::CGI object is created and initialised using the \fInew()\fR
+method.  This returns a reference to a new AppConfig::CGI object.  A
+reference to an AppConfig::State object should be passed in as the
+first parameter: 
+.PP
+.Vb 2
+\&    my $state = AppConfig::State->new(); 
+\&    my $cgi   = AppConfig::CGI->new($state);
+.Ve
+.PP
+This will create and return a reference to a new AppConfig::CGI object. 
+.Sh "\s-1PARSING\s0 \s-1CGI\s0 \s-1QUERIES\s0"
+.IX Subsection "PARSING CGI QUERIES"
+The \f(CW\*(C`parse()\*(C'\fR method is used to parse a \s-1CGI\s0 query which can be specified 
+explicitly, or is automatically extracted from the \*(L"\s-1QUERY_STRING\s0\*(R" \s-1CGI\s0 
+environment variable.  This currently limits the module to only supporting 
+the \s-1GET\s0 method.
+.PP
+See AppConfig for information about using the AppConfig::CGI
+module via the \fIcgi()\fR method.
+.SH "AUTHOR"
+.IX Header "AUTHOR"
+Andy Wardley, \f(CW\*(C`<abw@wardley.org<gt\*(C'\fR>
+.SH "REVISION"
+.IX Header "REVISION"
+$Revision: 1.60 $
+.SH "COPYRIGHT"
+.IX Header "COPYRIGHT"
+Copyright (C) 1997\-2003 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, AppConfig::State
--- appconfig-1.56.orig/blib/man3/AppConfig::File.3pm
+++ appconfig-1.56/blib/man3/AppConfig::File.3pm
@@ -0,0 +1,396 @@
+.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
+.\"
+.\" 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::File 3pm"
+.TH AppConfig::File 3pm "2003-04-29" "perl v5.8.4" "User Contributed Perl Documentation"
+.SH "NAME"
+AppConfig::File \- Perl5 module for reading configuration files.
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+.Vb 1
+\&    use AppConfig::File;
+.Ve
+.PP
+.Vb 2
+\&    my $state   = AppConfig::State->new(\e%cfg1);
+\&    my $cfgfile = AppConfig::File->new($state, $file);
+.Ve
+.PP
+.Vb 1
+\&    $cfgfile->parse($file);            # read config file
+.Ve
+.SH "OVERVIEW"
+.IX Header "OVERVIEW"
+AppConfig::File is a Perl5 module which reads configuration files and use 
+the contents therein to update variable values in an AppConfig::State 
+object.
+.PP
+AppConfig::File is distributed as part of the AppConfig bundle.
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+.Sh "\s-1USING\s0 \s-1THE\s0 AppConfig::File \s-1MODULE\s0"
+.IX Subsection "USING THE AppConfig::File MODULE"
+To import and use the AppConfig::File module the following line should appear
+in your Perl script:
+.PP
+.Vb 1
+\&    use AppConfig::File;
+.Ve
+.PP
+AppConfig::File is used automatically if you use the AppConfig module 
+and create an AppConfig::File object through the \fIfile()\fR method.
+.PP
+AppConfig::File is implemented using object-oriented methods.  A new 
+AppConfig::File object is created and initialised using the 
+AppConfig::File\->\fInew()\fR method.  This returns a reference to a new 
+AppConfig::File object.  A reference to an AppConfig::State object 
+should be passed in as the first parameter:
+.PP
+.Vb 2
+\&    my $state   = AppConfig::State->new();
+\&    my $cfgfile = AppConfig::File->new($state);
+.Ve
+.PP
+This will create and return a reference to a new AppConfig::File object.
+.Sh "\s-1READING\s0 \s-1CONFIGURATION\s0 \s-1FILES\s0"
+.IX Subsection "READING CONFIGURATION FILES"
+The \f(CW\*(C`parse()\*(C'\fR method is used to read a configuration file and have the 
+contents update the \s-1STATE\s0 accordingly.
+.PP
+.Vb 1
+\&    $cfgfile->parse($file);
+.Ve
+.PP
+Multiple files maye be specified and will be read in turn.
+.PP
+.Vb 1
+\&    $cfgfile->parse($file1, $file2, $file3);
+.Ve
+.PP
+The method will return an undef value if it encounters any errors opening
+the files.  It will return immediately without processing any further files.
+By default, the \s-1PEDANTIC\s0 option in the AppConfig::State object, 
+\&\f(CW$self\fR\->{ \s-1STATE\s0 }, is turned off and any parsing errors (invalid variables,
+unvalidated values, etc) will generated warnings, but not cause the method
+to return.  Having processed all files, the method will return 1 if all
+files were processed without warning or 0 if one or more warnings were
+raised.  When the \s-1PEDANTIC\s0 option is turned on, the method generates a
+warning and immediately returns a value of 0 as soon as it encounters any
+parsing error.
+.PP
+Variables values in the configuration files may be expanded depending on 
+the value of their \s-1EXPAND\s0 option, as determined from the App::State object.
+See AppConfig::State for more information on variable expansion.
+.Sh "\s-1CONFIGURATION\s0 \s-1FILE\s0 \s-1FORMAT\s0"
+.IX Subsection "CONFIGURATION FILE FORMAT"
+A configuration file may contain blank lines and comments which are
+ignored.  Comments begin with a '#' as the first character on a line
+or following one or more whitespace tokens, and continue to the end of
+the line.
+.PP
+.Vb 3
+\&    # this is a comment
+\&    foo = bar               # so is this
+\&    url = index.html#hello  # this too, but not the '#welcome'
+.Ve
+.PP
+Notice how the '#welcome' part of the \s-1URL\s0 is not treated as a comment
+because a whitespace character doesn't precede it.  
+.PP
+Long lines can be continued onto the next line by ending the first 
+line with a '\e'.
+.PP
+.Vb 4
+\&    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.  An
+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 h="history"
+.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
+A large chunk of text can be defined using Perl's \*(L"heredoc\*(R" quoting
+style.
+.PP
+.Vb 5
+\&   scalar = <<BOUNDARY_STRING
+\&   line 1
+\&   line 2: Space/linebreaks within a HERE document are kept.
+\&   line 3: The last linebreak (\en) is stripped.
+\&   BOUNDARY_STRING
+.Ve
+.PP
+.Vb 5
+\&   hash   key1 = <<'FOO'
+\&     * Quotes (['"]) around the boundary string are simply ignored.
+\&     * Whether the variables in HERE document are expanded depends on
+\&       the EXPAND option of the variable or global setting.
+\&   FOO
+.Ve
+.PP
+.Vb 5
+\&   hash = key2 = <<"_bar_"
+\&   Text within HERE document are kept as is.
+\&   # comments are treated as a normal text.
+\&   The same applies to line continuation. \e
+\&   _bar_
+.Ve
+.PP
+Note that you cannot use \s-1HERE\s0 document as a key in a hash or a name 
+of a variable.
+.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
+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 "AUTHOR"
+.IX Header "AUTHOR"
+Andy Wardley, <abw@wardley.org>
+.SH "REVISION"
+.IX Header "REVISION"
+$Revision: 1.62 $
+.SH "COPYRIGHT"
+.IX Header "COPYRIGHT"
+Copyright (C) 1997\-2003 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, AppConfig::State
--- appconfig-1.56.orig/blib/man3/AppConfig::State.3pm
+++ appconfig-1.56/blib/man3/AppConfig::State.3pm
@@ -0,0 +1,716 @@
+.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
+.\"
+.\" 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::State 3pm"
+.TH AppConfig::State 3pm "2003-04-29" "perl v5.8.4" "User Contributed Perl Documentation"
+.SH "NAME"
+AppConfig::State \- application configuration state
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+.Vb 1
+\&    use AppConfig::State;
+.Ve
+.PP
+.Vb 1
+\&    my $state = AppConfig::State->new(\e%cfg);
+.Ve
+.PP
+.Vb 3
+\&    $state->define("foo");            # very simple variable definition
+\&    $state->define("bar", \e%varcfg);  # variable specific configuration
+\&    $state->define("foo|bar=i@");     # compact format
+.Ve
+.PP
+.Vb 2
+\&    $state->set("foo", 123);          # trivial set/get examples
+\&    $state->get("foo");
+.Ve
+.PP
+.Vb 2
+\&    $state->foo();                    # shortcut variable access 
+\&    $state->foo(456);                 # shortcut variable update
+.Ve
+.SH "OVERVIEW"
+.IX Header "OVERVIEW"
+AppConfig::State 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 other AppConfig::* modules.  
+.PP
+AppConfig::State is distributed as part of the AppConfig bundle.
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+.Sh "\s-1USING\s0 \s-1THE\s0 AppConfig::State \s-1MODULE\s0"
+.IX Subsection "USING THE AppConfig::State MODULE"
+To import and use the AppConfig::State module the following line should 
+appear in your Perl script:
+.PP
+.Vb 1
+\&     use AppConfig::State;
+.Ve
+.PP
+The AppConfig::State module is loaded automatically by the \fInew()\fR
+constructor of the AppConfig module.
+.PP
+AppConfig::State is implemented using object-oriented methods.  A 
+new AppConfig::State object is created and initialised using the 
+\&\fInew()\fR method.  This returns a reference to a new AppConfig::State 
+object.
+.PP
+.Vb 1
+\&    my $state = AppConfig::State->new();
+.Ve
+.PP
+This will create a reference to a new AppConfig::State with all 
+configuration options set to their default values.  You can initialise 
+the object by passing a reference to a hash array containing 
+configuration options:
+.PP
+.Vb 4
+\&    $state = AppConfig::State->new( {
+\&        CASE      => 1,
+\&        ERROR     => \e&my_error,
+\&    } );
+.Ve
+.PP
+The \fInew()\fR constructor of the AppConfig module automatically passes all 
+parameters to the AppConfig::State \fInew()\fR constructor.  Thus, any global 
+configuration values and variable definitions for AppConfig::State are 
+also applicable to AppConfig.
+.PP
+The following configuration options may be specified.  
+.IP "\s-1CASE\s0" 4
+.IX Item "CASE"
+Determines if the variable names are treated case sensitively.  Any non-zero
+value makes case significant when naming variables.  By default, \s-1CASE\s0 is set
+to 0 and thus \*(L"Variable\*(R", \*(L"\s-1VARIABLE\s0\*(R" and \*(L"VaRiAbLe\*(R" are all treated as 
+\&\*(L"variable\*(R".
+.IP "\s-1CREATE\s0" 4
+.IX Item "CREATE"
+By default, \s-1CREATE\s0 is turned off meaning that all variables accessed via
+\&\fIset()\fR (which includes access via shortcut such as 
+\&\f(CW\*(C`$state\->variable($value)\*(C'\fR which delegates to \fIset()\fR) must previously 
+have been defined via \fIdefine()\fR.  When \s-1CREATE\s0 is set to 1, calling 
+set($variable, \f(CW$value\fR) on a variable that doesn't exist will cause it 
+to be created automatically.
+.Sp
+When \s-1CREATE\s0 is set to any other non-zero value, it is assumed to be a
+regular expression pattern.  If the variable name matches the regex, the
+variable is created.  This can be used to specify configuration file 
+blocks in which variables should be created, for example:
+.Sp
+.Vb 3
+\&    $state = AppConfig::State->new( {
+\&        CREATE => '^define_',
+\&    } );
+.Ve
+.Sp
+In a config file:
+.Sp
+.Vb 2
+\&    [define]
+\&    name = fred           # define_name gets created automatically
+.Ve
+.Sp
+.Vb 2
+\&    [other]
+\&    name = john           # other_name doesn't - warning raised
+.Ve
+.Sp
+Note that a regex pattern specified in \s-1CREATE\s0 is applied to the real 
+variable name rather than any alias by which the variables may be 
+accessed.  
+.IP "\s-1PEDANTIC\s0" 4
+.IX Item "PEDANTIC"
+The \s-1PEDANTIC\s0 option determines what action the configuration file 
+(AppConfig::File) or argument parser (AppConfig::Args) should take 
+on encountering a warning condition (typically caused when trying to set an
+undeclared variable).  If \s-1PEDANTIC\s0 is set to any true value, the parsing
+methods will immediately return a value of 0 on encountering such a
+condition.  If \s-1PEDANTIC\s0 is not set, the method will continue to parse the
+remainder of the current file(s) or arguments, returning 0 when complete.
+.Sp
+If no warnings or errors are encountered, the method returns 1.
+.Sp
+In the case of a system error (e.g. unable to open a file), the method
+returns undef immediately, regardless of the \s-1PEDANTIC\s0 option.
+.IP "\s-1ERROR\s0" 4
+.IX Item "ERROR"
+Specifies a user-defined error handling routine.  When the handler is 
+called, a format string is passed as the first parameter, followed by 
+any additional values, as per printf(3C).
+.IP "\s-1DEBUG\s0" 4
+.IX Item "DEBUG"
+Turns debugging on or off when set to 1 or 0 accordingly.  Debugging may 
+also be activated by calling \fI_debug()\fR as an object method 
+(\f(CW\*(C`$state\->_debug(1)\*(C'\fR) or as a package function 
+(\f(CWAppConfig::State::_debug(1)\fR), passing in a true/false value to 
+set the debugging state accordingly.  The package variable 
+\&\f(CW$AppConfig::State::DEBUG\fR can also be set directly.  
+.Sp
+The \fI_debug()\fR method returns the current debug value.  If a new value 
+is passed in, the internal value is updated, but the previous value is 
+returned.
+.Sp
+Note that any AppConfig::File or App::Config::Args objects that are 
+instantiated with a reference to an App::State will inherit the 
+\&\s-1DEBUG\s0 (and also \s-1PEDANTIC\s0) values of the state at that time.  Subsequent
+changes to the AppConfig::State debug value will not affect them.
+.IP "\s-1GLOBAL\s0" 4
+.IX Item "GLOBAL"
+The \s-1GLOBAL\s0 option allows default values to be set for the \s-1DEFAULT\s0, \s-1ARGCOUNT\s0, 
+\&\s-1EXPAND\s0, \s-1VALIDATE\s0 and \s-1ACTION\s0 options for any subsequently defined variables.
+.Sp
+.Vb 7
+\&    $state = AppConfig::State->new({
+\&        GLOBAL => {
+\&            DEFAULT  => '<undef>',     # default value for new vars
+\&            ARGCOUNT => 1,             # vars expect an argument
+\&            ACTION   => \e&my_set_var,  # callback when vars get set
+\&        }
+\&    });
+.Ve
+.Sp
+Any attributes specified explicitly when a variable is defined will
+override any \s-1GLOBAL\s0 values.
+.Sp
+See \*(L"\s-1DEFINING\s0 \s-1VARIABLES\s0\*(R" below which describes these options in detail.
+.Sh "\s-1DEFINING\s0 \s-1VARIABLES\s0"
+.IX Subsection "DEFINING VARIABLES"
+The \f(CW\*(C`define()\*(C'\fR function is used to pre-declare a variable and specify 
+its configuration.
+.PP
+.Vb 1
+\&    $state->define("foo");
+.Ve
+.PP
+In the simple example 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
+\&    $state->define("foo", {
+\&            DEFAULT   => 99,
+\&            ALIAS     => 'metavar1',
+\&        });
+.Ve
+.PP
+Any variable-wide \s-1GLOBAL\s0 values passed to the \fInew()\fR constructor in the 
+configuration hash will also be applied.  Values explicitly specified 
+in a variable's \fIdefine()\fR configuration will override the respective \s-1GLOBAL\s0 
+values.
+.PP
+The following configuration options may be specified
+.IP "\s-1DEFAULT\s0" 4
+.IX Item "DEFAULT"
+The \s-1DEFAULT\s0 value is used to initialise the variable.  
+.Sp
+.Vb 3
+\&    $state->define("drink", {
+\&            DEFAULT => 'coffee',
+\&        });
+.Ve
+.Sp
+.Vb 1
+\&    print $state->drink();        # prints "coffee"
+.Ve
+.IP "\s-1ALIAS\s0" 4
+.IX Item "ALIAS"
+The \s-1ALIAS\s0 option allows a number of alternative names to be specified for 
+this variable.  A single alias should be specified as a string.  Multiple 
+aliases can be specified as a reference to an array of alternatives or as 
+a string of names separated by vertical bars, '|'.  e.g.:
+.Sp
+.Vb 11
+\&    $state->define("name", {
+\&            ALIAS  => 'person',
+\&        });
+\&or
+\&    $state->define("name", {
+\&            ALIAS => [ 'person', 'user', 'uid' ],
+\&        });
+\&or
+\&    $state->define("name", {
+\&            ALIAS => 'person|user|uid',
+\&        });
+.Ve
+.Sp
+.Vb 1
+\&    $state->user('abw');     # equivalent to $state->name('abw');
+.Ve
+.IP "\s-1ARGCOUNT\s0" 4
+.IX Item "ARGCOUNT"
+The \s-1ARGCOUNT\s0 option specifies the number of arguments that should be 
+supplied for this variable.  By default, no additional arguments are 
+expected for variables (\s-1ARGCOUNT_NONE\s0).
+.Sp
+The ARGCOUNT_* constants can be imported from the AppConfig module:
+.Sp
+.Vb 1
+\&    use AppConfig ':argcount';
+.Ve
+.Sp
+.Vb 1
+\&    $state->define('foo', { ARGCOUNT => ARGCOUNT_ONE });
+.Ve
+.Sp
+or can be accessed directly from the AppConfig package:
+.Sp
+.Vb 1
+\&    use AppConfig;
+.Ve
+.Sp
+.Vb 1
+\&    $state->define('foo', { ARGCOUNT => AppConfig::ARGCOUNT_ONE });
+.Ve
+.Sp
+The following values for \s-1ARGCOUNT\s0 may be specified.  
+.RS 4
+.IP "\s-1ARGCOUNT_NONE\s0 (0)" 4
+.IX Item "ARGCOUNT_NONE (0)"
+Indicates that no additional arguments are expected.  If the variable is
+identified in a confirguration file or in the command line arguments, it
+is set to a value of 1 regardless of whatever arguments follow it.
+.IP "\s-1ARGCOUNT_ONE\s0 (1)" 4
+.IX Item "ARGCOUNT_ONE (1)"
+Indicates that the variable expects a single argument to be provided.
+The variable value will be overwritten with a new value each time it 
+is encountered.
+.IP "\s-1ARGCOUNT_LIST\s0 (2)" 4
+.IX Item "ARGCOUNT_LIST (2)"
+Indicates that the variable expects multiple arguments.  The variable 
+value will be appended to the list of previous values each time it is
+encountered.  
+.IP "\s-1ARGCOUNT_HASH\s0 (3)" 4
+.IX Item "ARGCOUNT_HASH (3)"
+Indicates that the variable expects multiple arguments and that each
+argument is of the form \*(L"key=value\*(R".  The argument will be split into 
+a key/value pair and inserted into the hash of values each time it 
+is encountered.
+.RE
+.RS 4
+.RE
+.IP "\s-1ARGS\s0" 4
+.IX Item "ARGS"
+The \s-1ARGS\s0 option can also be used to specify advanced command line options 
+for use with AppConfig::Getopt, which itself delegates to Getopt::Long.  
+See those two modules for more information on the format and meaning of
+these options.
+.Sp
+.Vb 3
+\&    $state->define("name", {
+\&            ARGS => "=i@",
+\&        });
+.Ve
+.IP "\s-1EXPAND\s0" 4
+.IX Item "EXPAND"
+The \s-1EXPAND\s0 option specifies how the AppConfig::File processor should 
+expand embedded variables in the configuration file values it reads.
+By default, \s-1EXPAND\s0 is turned off (\s-1EXPAND_NONE\s0) and no expansion is made.  
+.Sp
+The EXPAND_* constants can be imported from the AppConfig module:
+.Sp
+.Vb 1
+\&    use AppConfig ':expand';
+.Ve
+.Sp
+.Vb 1
+\&    $state->define('foo', { EXPAND => EXPAND_VAR });
+.Ve
+.Sp
+or can be accessed directly from the AppConfig package:
+.Sp
+.Vb 1
+\&    use AppConfig;
+.Ve
+.Sp
+.Vb 1
+\&    $state->define('foo', { EXPAND => AppConfig::EXPAND_VAR });
+.Ve
+.Sp
+The following values for \s-1EXPAND\s0 may be specified.  Multiple values should
+be combined with vertical bars , '|', e.g. \f(CW\*(C`EXPAND_UID | EXPAND_VAR\*(C'\fR).
+.RS 4
+.IP "\s-1EXPAND_NONE\s0" 4
+.IX Item "EXPAND_NONE"
+Indicates that no variable expansion should be attempted.
+.IP "\s-1EXPAND_VAR\s0" 4
+.IX Item "EXPAND_VAR"
+Indicates that variables embedded as \f(CW$var\fR or $(var) should be expanded
+to the values of the relevant AppConfig::State variables.
+.IP "\s-1EXPAND_UID\s0" 4
+.IX Item "EXPAND_UID"
+Indicates that '~' or '~uid' patterns in the string should be 
+expanded to the current users ($<), or specified user's home directory.
+.IP "\s-1EXPAND_ENV\s0" 4
+.IX Item "EXPAND_ENV"
+Inidicates that variables embedded as ${var} should be expanded to the 
+value of the relevant environment variable.
+.IP "\s-1EXPAND_ALL\s0" 4
+.IX Item "EXPAND_ALL"
+Equivalent to \f(CW\*(C`EXPAND_VARS | EXPAND_UIDS | EXPAND_ENVS\*(C'\fR).
+.IP "\s-1EXPAND_WARN\s0" 4
+.IX Item "EXPAND_WARN"
+Indicates that embedded variables that are not defined should raise a
+warning.  If \s-1PEDANTIC\s0 is set, this will cause the \fIread()\fR method to return 0
+immediately.
+.RE
+.RS 4
+.RE
+.IP "\s-1VALIDATE\s0" 4
+.IX Item "VALIDATE"
+Each variable may have a sub-routine or regular expression defined which 
+is used to validate the intended value for a variable before it is set.
+.Sp
+If \s-1VALIDATE\s0 is defined as a regular expression, it is applied to the
+value and deemed valid if the pattern matches.  In this case, the
+variable is then set to the new value.  A warning message is generated
+if the pattern match fails.
+.Sp
+\&\s-1VALIDATE\s0 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.
+.Sp
+If the \s-1GLOBAL\s0 \s-1VALIDATE\s0 variable is set (see \s-1GLOBAL\s0 in \s-1DESCRIPTION\s0 
+above) then this value will be used as the default \s-1VALIDATE\s0 for each 
+variable unless otherwise specified.
+.Sp
+.Vb 3
+\&    $state->define("age", {
+\&            VALIDATE => '\ed+',
+\&        });
+.Ve
+.Sp
+.Vb 3
+\&    $state->define("pin", {
+\&            VALIDATE => \e&check_pin,
+\&        });
+.Ve
+.IP "\s-1ACTION\s0" 4
+.IX Item "ACTION"
+The \s-1ACTION\s0 option allows a sub-routine to be bound to a variable as a
+callback that is executed whenever the variable is set.  The \s-1ACTION\s0 is
+passed a reference to the AppConfig::State object, the name of the
+variable and the value of the variable.
+.Sp
+The \s-1ACTION\s0 routine may be used, for example, to post-process variable
+data, update the value of some other dependant variable, generate a
+warning message, etc.
+.Sp
+Example:
+.Sp
+.Vb 1
+\&    $state->define("foo", { ACTION => \e&my_notify });
+.Ve
+.Sp
+.Vb 4
+\&    sub my_notify {
+\&        my $state = shift;
+\&        my $var   = shift;
+\&        my $val   = shift;
+.Ve
+.Sp
+.Vb 2
+\&        print "$variable set to $value";
+\&    }
+.Ve
+.Sp
+.Vb 1
+\&    $state->foo(42);        # prints "foo set to 42"
+.Ve
+.Sp
+Be aware that calling \f(CW\*(C`$state\->set()\*(C'\fR to update the same variable
+from within the \s-1ACTION\s0 function will cause a recursive loop as the
+\&\s-1ACTION\s0 function is repeatedly called.  
+.IP "*" 4
+.Sh "\s-1DEFINING\s0 \s-1VARIABLES\s0 \s-1USING\s0 \s-1THE\s0 \s-1COMPACT\s0 \s-1FORMAT\s0"
+.IX Subsection "DEFINING VARIABLES USING THE COMPACT FORMAT"
+Variables may be defined in a compact format which allows any \s-1ALIAS\s0 and
+\&\s-1ARGS\s0 values to be specified as part of the variable name.  This is designed
+to mimic the behaviour of Johan Vromans' Getopt::Long module.
+.PP
+Aliases for a variable should be specified after the variable name, 
+separated by vertical bars, '|'.  Any \s-1ARGS\s0 parameter should be appended 
+after the variable name(s) and/or aliases.
+.PP
+The following examples are equivalent:
+.PP
+.Vb 4
+\&    $state->define("foo", { 
+\&            ALIAS => [ 'bar', 'baz' ],
+\&            ARGS  => '=i',
+\&        });
+.Ve
+.PP
+.Vb 1
+\&    $state->define("foo|bar|baz=i");
+.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::State defines two methods to manipulate variable values: 
+.PP
+.Vb 2
+\&    set($variable, $value);
+\&    get($variable);
+.Ve
+.PP
+Both functions take the variable name as the first parameter and
+\&\f(CW\*(C`set()\*(C'\fR takes an additional parameter which is the new value for the
+variable.  \f(CW\*(C`set()\*(C'\fR returns 1 or 0 to indicate successful or
+unsuccessful update of the variable value.  If there is an \s-1ACTION\s0
+routine associated with the named variable, the value returned will be
+passed back from \f(CW\*(C`set()\*(C'\fR.  The \f(CW\*(C`get()\*(C'\fR function returns the current
+value of the variable.
+.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
+\&    $state->set("verbose", 1);
+.Ve
+.PP
+is equivalent to 
+.PP
+.Vb 1
+\&    $state->verbose(1);
+.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 1
+\&    $state->age(29);        # sets 'age' to 29, returns 1 (ok)
+.Ve
+.Sh "\s-1INTERNAL\s0 \s-1METHODS\s0"
+.IX Subsection "INTERNAL METHODS"
+The interal (private) methods of the AppConfig::State class are listed 
+below.
+.PP
+They aren't intended for regular use and potential users should consider
+the fact that nothing about the internal implementation is guaranteed to
+remain the same.  Having said that, the AppConfig::State class is
+intended to co-exist and work with a number of other modules and these
+are considered \*(L"friend\*(R" classes.  These methods are provided, in part,
+as services to them.  With this acknowledged co-operation in mind, it is
+safe to assume some stability in this core interface.
+.PP
+The \fI_varname()\fR method can be used to determine the real name of a variable 
+from an alias:
+.PP
+.Vb 1
+\&    $varname->_varname($alias);
+.Ve
+.PP
+Note that all methods that take a variable name, including those listed
+below, can accept an alias and automatically resolve it to the correct 
+variable name.  There is no need to call \fI_varname()\fR explicitly to do 
+alias expansion.  The \fI_varname()\fR method will fold all variables names
+to lower case unless \s-1CASE\s0 sensititvity is set.
+.PP
+The \fI_exists()\fR method can be used to check if a variable has been
+defined:
+.PP
+.Vb 1
+\&    $state->_exists($varname);
+.Ve
+.PP
+The \fI_default()\fR method can be used to reset a variable to its default value:
+.PP
+.Vb 1
+\&    $state->_default($varname);
+.Ve
+.PP
+The \fI_expand()\fR method can be used to determine the \s-1EXPAND\s0 value for a 
+variable:
+.PP
+.Vb 1
+\&    print "$varname EXPAND: ", $state->_expand($varname), "\en";
+.Ve
+.PP
+The \fI_argcount()\fR method returns the value of the \s-1ARGCOUNT\s0 attribute for a 
+variable:
+.PP
+.Vb 1
+\&    print "$varname ARGCOUNT: ", $state->_argcount($varname), "\en";
+.Ve
+.PP
+The \fI_validate()\fR method can be used to determine if a new value for a variable
+meets any validation criteria specified for it.  The variable name and 
+intended value should be passed in.  The methods returns a true/false value
+depending on whether or not the validation succeeded:
+.PP
+.Vb 1
+\&    print "OK\en" if $state->_validate($varname, $value);
+.Ve
+.PP
+The \fI_pedantic()\fR method can be called to determine the current value of the
+\&\s-1PEDANTIC\s0 option.
+.PP
+.Vb 1
+\&    print "pedantic mode is ", $state->_pedantic() ? "on" ; "off", "\en";
+.Ve
+.PP
+The \fI_debug()\fR method can be used to turn debugging on or off (pass 1 or 0
+as a parameter).  It can also be used to check the debug state,
+returning the current internal value of \f(CW$AppConfig::State::DEBUG\fR.  If a
+new debug value is provided, the debug state is updated and the previous
+state is returned.
+.PP
+.Vb 1
+\&    $state->_debug(1);               # debug on, returns previous value
+.Ve
+.PP
+The _dump_var($varname) and \fI_dump()\fR methods may also be called for
+debugging purposes.  
+.PP
+.Vb 2
+\&    $state->_dump_var($varname);    # show variable state
+\&    $state->_dump();                # show internal state and all vars
+.Ve
+.SH "AUTHOR"
+.IX Header "AUTHOR"
+Andy Wardley, <abw@wardley.org>
+.SH "REVISION"
+.IX Header "REVISION"
+$Revision: 1.61 $
+.SH "COPYRIGHT"
+.IX Header "COPYRIGHT"
+Copyright (C) 1997\-2003 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, AppConfig::File, AppConfig::Args, AppConfig::Getopt
--- appconfig-1.56.orig/blib/man3/AppConfig::Getopt.3pm
+++ appconfig-1.56/blib/man3/AppConfig::Getopt.3pm
@@ -0,0 +1,230 @@
+.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
+.\"
+.\" 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::Getopt 3pm"
+.TH AppConfig::Getopt 3pm "2003-04-29" "perl v5.8.4" "User Contributed Perl Documentation"
+.SH "NAME"
+AppConfig::Getopt \- Perl5 module for processing command line arguments via delegation to Getopt::Long.
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+.Vb 1
+\&    use AppConfig::Getopt;
+.Ve
+.PP
+.Vb 2
+\&    my $state  = AppConfig::State->new(\e%cfg);
+\&    my $getopt = AppConfig::Getopt->new($state);
+.Ve
+.PP
+.Vb 1
+\&    $getopt->parse(\e@args);            # read args
+.Ve
+.SH "OVERVIEW"
+.IX Header "OVERVIEW"
+AppConfig::Getopt is a Perl5 module which delegates to Johan Vroman's
+Getopt::Long module to parse command line arguments and update values 
+in an AppConfig::State object accordingly.
+.PP
+AppConfig::Getopt is distributed as part of the AppConfig bundle.
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+.Sh "\s-1USING\s0 \s-1THE\s0 AppConfig::Getopt \s-1MODULE\s0"
+.IX Subsection "USING THE AppConfig::Getopt MODULE"
+To import and use the AppConfig::Getopt module the following line should appear
+in your Perl script:
+.PP
+.Vb 1
+\&    use AppConfig::Getopt;
+.Ve
+.PP
+AppConfig::Getopt is used automatically if you use the AppConfig module 
+and create an AppConfig::Getopt object through the \fIgetopt()\fR method.
+.PP
+AppConfig::Getopt is implemented using object-oriented methods.  A new 
+AppConfig::Getopt object is created and initialised using the \fInew()\fR method.
+This returns a reference to a new AppConfig::Getopt object.  A reference to
+an AppConfig::State object should be passed in as the first parameter:
+.PP
+.Vb 2
+\&    my $state  = AppConfig::State->new();
+\&    my $getopt = AppConfig::Getopt->new($state);
+.Ve
+.PP
+This will create and return a reference to a new AppConfig::Getopt object. 
+.Sh "\s-1PARSING\s0 \s-1COMMAND\s0 \s-1LINE\s0 \s-1ARGUMENTS\s0"
+.IX Subsection "PARSING COMMAND LINE ARGUMENTS"
+The \f(CW\*(C`parse()\*(C'\fR method is used to read a list of command line arguments and 
+update the state accordingly.  
+.PP
+The first (non\-list reference) parameters may contain a number of 
+configuration strings 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
+\&    $getopt->parse();                       # uses @ARGV
+\&    $getopt->parse(\e@myargs);
+\&    $getopt->parse(qw(auto_abbrev debug));  # uses @ARGV
+\&    $getopt->parse(qw(debug), \e@myargs);
+.Ve
+.PP
+See Getopt::Long for details of the configuartion options available.
+.PP
+A Getopt::Long specification string is constructed for each variable 
+defined in the AppConfig::State.  This consists of the name, any aliases
+and the \s-1ARGS\s0 value for the variable.
+.PP
+These specification string are then passed to Getopt::Long, the arguments
+are parsed and the values in the AppConfig::State updated.
+.PP
+See AppConfig for information about using the AppConfig::Getopt
+module via the \fIgetopt()\fR method.
+.SH "AUTHOR"
+.IX Header "AUTHOR"
+Andy Wardley, <abw@wardley.org>
+.SH "REVISION"
+.IX Header "REVISION"
+$Revision: 1.60 $
+.SH "COPYRIGHT"
+.IX Header "COPYRIGHT"
+Copyright (C) 1997\-2003 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 "ACKNOWLEDGMENTS"
+.IX Header "ACKNOWLEDGMENTS"
+Many thanks are due to Johan Vromans for the Getopt::Long module.  He was 
+kind enough to offer assistance and access to early releases of his code to 
+enable this module to be written.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+AppConfig, AppConfig::State, AppConfig::Args, Getopt::Long
--- appconfig-1.56.orig/blib/man3/AppConfig.3pm
+++ appconfig-1.56/blib/man3/AppConfig.3pm
@@ -0,0 +1,1158 @@
+.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
+.\"
+.\" 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 3pm"
+.TH AppConfig 3pm "2003-04-29" "perl v5.8.4" "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 3
+\&    # 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`:argcount\*(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 \s-1EXPAND_NONE\s0
+\&\- no expansion (default), \s-1EXPAND_VAR\s0 \- expand \f(CW$var\fR or \f(CW\*(C`$(var)\*(C'\fR as 
+other AppConfig variables, \s-1EXPAND_UID\s0 \- expand \f(CW\*(C`~uid\*(C'\fR as user's home 
+directory, \s-1EXPAND_ENV\s0 \- expand \f(CW\*(C`${var}\*(C'\fR as environment variable,
+\&\s-1EXPAND_ALL\s0 \- do all expansions.  May be logically or'd.
+.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 "REVISION"
+.IX Header "REVISION"
+Revision \f(CW$Revision:\fR 1.7 $ distributed as part of AppConfig 1.56.
+.SH "COPYRIGHT"
+.IX Header "COPYRIGHT"
+Copyright (C) 1997\-2004 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
--- appconfig-1.56.orig/blib/man3/AppConfig::Sys.3pm
+++ appconfig-1.56/blib/man3/AppConfig::Sys.3pm
@@ -0,0 +1,214 @@
+.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
+.\"
+.\" 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::Sys 3pm"
+.TH AppConfig::Sys 3pm "2003-04-29" "perl v5.8.4" "User Contributed Perl Documentation"
+.SH "NAME"
+AppConfig::Sys \- Perl5 module defining platform\-specific information and methods for other AppConfig::* modules.
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+.Vb 2
+\&    use AppConfig::Sys;
+\&    my $sys = AppConfig::Sys->new();
+.Ve
+.PP
+.Vb 2
+\&    @fields = $sys->getpwuid($userid);
+\&    @fields = $sys->getpwnam($username);
+.Ve
+.SH "OVERVIEW"
+.IX Header "OVERVIEW"
+AppConfig::Sys is a Perl5 module provides platform-specific information and
+operations as required by other AppConfig::* modules.
+.PP
+AppConfig::Sys is distributed as part of the AppConfig bundle.
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+.Sh "\s-1USING\s0 \s-1THE\s0 AppConfig::Sys \s-1MODULE\s0"
+.IX Subsection "USING THE AppConfig::Sys MODULE"
+To import and use the AppConfig::Sys module the following line should
+appear in your Perl script:
+.PP
+.Vb 1
+\&     use AppConfig::Sys;
+.Ve
+.PP
+AppConfig::Sys is implemented using object-oriented methods.  A new
+AppConfig::Sys object is created and initialised using the
+AppConfig::Sys\->\fInew()\fR method.  This returns a reference to a new
+AppConfig::Sys object.  
+.PP
+.Vb 1
+\&    my $sys = AppConfig::Sys->new();
+.Ve
+.PP
+This will attempt to detect your operating system and create a reference to
+a new AppConfig::Sys object that is applicable to your platform.  You may 
+explicitly specify an operating system name to override this automatic 
+detection:
+.PP
+.Vb 1
+\&    $unix_sys = AppConfig::Sys->new("Unix");
+.Ve
+.PP
+Alternatively, the package variable \f(CW$AppConfig::Sys::OS\fR can be set to an
+operating system name.  The valid operating system names are: Win32, \s-1VMS\s0,
+Mac, \s-1OS2\s0 and Unix.  They are not case\-specific.
+.Sh "AppConfig::Sys \s-1METHODS\s0"
+.IX Subsection "AppConfig::Sys METHODS"
+AppConfig::Sys defines the following methods:
+.IP "\fIgetpwnam()\fR" 4
+.IX Item "getpwnam()"
+Calls the system function \fIgetpwnam()\fR if available and returns the result.
+Returns undef if not available.  The \fIcan_getpwnam()\fR method can be called to
+determine if this function is available.
+.IP "\fIgetpwuid()\fR" 4
+.IX Item "getpwuid()"
+Calls the system function \fIgetpwuid()\fR if available and returns the result.
+Returns undef if not available.  The \fIcan_getpwuid()\fR method can be called to
+determine if this function is available.
+.IP "*" 4
+.SH "AUTHOR"
+.IX Header "AUTHOR"
+Andy Wardley, <abw@wardley.org>
+.SH "REVISION"
+.IX Header "REVISION"
+$Revision: 1.61 $
+.SH "COPYRIGHT"
+.IX Header "COPYRIGHT"
+Copyright (C) 1997\-2004 Andy Wardley.  All Rights Reserved.
+.Sp
+Copyright (C) 1997,1998 Canon Research Centre Europe Ltd.
+.Sp
+This module is free software; you can redistribute it and/or modify it under 
+the term of the Perl Artistic License.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+AppConfig, AppConfig::File
--- appconfig-1.56.orig/Makefile
+++ appconfig-1.56/Makefile
@@ -0,0 +1,761 @@
+# This Makefile is for the AppConfig extension to perl.
+#
+# It was generated automatically by MakeMaker version
+# 6.17 (Revision: 1.133) from the contents of
+# Makefile.PL. Don't edit this file, edit Makefile.PL instead.
+#
+#       ANY CHANGES MADE HERE WILL BE LOST!
+#
+#   MakeMaker ARGV: (q[INSTALLDIRS=vendor])
+#
+#   MakeMaker Parameters:
+
+#     ABSTRACT => q[AppConfig is a bundle of Perl5 modules for reading configuration files and parsing command line arguments.]
+#     AUTHOR => q[Andy Wardley <abw@wardley.org>]
+#     MAN3PODS => { lib/AppConfig/Args.pm=>q[$(INST_MAN3DIR)/AppConfig::Args.$(MAN3EXT)], lib/AppConfig/CGI.pm=>q[$(INST_MAN3DIR)/AppConfig::CGI.$(MAN3EXT)], lib/AppConfig/File.pm=>q[$(INST_MAN3DIR)/AppConfig::File.$(MAN3EXT)], lib/AppConfig/State.pm=>q[$(INST_MAN3DIR)/AppConfig::State.$(MAN3EXT)], lib/AppConfig/Getopt.pm=>q[$(INST_MAN3DIR)/AppConfig::Getopt.$(MAN3EXT)], lib/AppConfig.pm=>q[$(INST_MAN3DIR)/AppConfig.$(MAN3EXT)], lib/AppConfig/Sys.pm=>q[$(INST_MAN3DIR)/AppConfig::Sys.$(MAN3EXT)] }
+#     NAME => q[AppConfig]
+#     PMLIBDIRS => [q[lib]]
+#     PREREQ_PM => { Test::More=>q[0] }
+#     VERSION_FROM => q[lib/AppConfig.pm]
+#     dist => { COMPRESS=>q[gzip], PREOP=>q[cp docs/header README; \                        pod2text lib/AppConfig.pm >> README], SUFFIX=>q[gz] }
+
+# --- MakeMaker post_initialize section:
+
+
+# --- MakeMaker const_config section:
+
+# These definitions are from config.sh (via /usr/lib/perl/5.8/Config.pm)
+
+# They may have been overridden via Makefile.PL or on the command line
+AR = ar
+CC = cc
+CCCDLFLAGS = -fPIC
+CCDLFLAGS = -Wl,-E
+DLEXT = so
+DLSRC = dl_dlopen.xs
+LD = cc
+LDDLFLAGS = -shared -L/usr/local/lib
+LDFLAGS =  -L/usr/local/lib
+LIBC = /lib/libc-2.3.2.so
+LIB_EXT = .a
+OBJ_EXT = .o
+OSNAME = linux
+OSVERS = 2.6.7.fb
+RANLIB = :
+SITELIBEXP = /usr/local/share/perl/5.8.4
+SITEARCHEXP = /usr/local/lib/perl/5.8.4
+SO = so
+EXE_EXT = 
+FULL_AR = /usr/bin/ar
+VENDORARCHEXP = /usr/lib/perl5
+VENDORLIBEXP = /usr/share/perl5
+
+
+# --- MakeMaker constants section:
+AR_STATIC_ARGS = cr
+DIRFILESEP = /
+NAME = AppConfig
+NAME_SYM = AppConfig
+VERSION = 1.56
+VERSION_MACRO = VERSION
+VERSION_SYM = 1_56
+DEFINE_VERSION = -D$(VERSION_MACRO)=\"$(VERSION)\"
+XS_VERSION = 1.56
+XS_VERSION_MACRO = XS_VERSION
+XS_DEFINE_VERSION = -D$(XS_VERSION_MACRO)=\"$(XS_VERSION)\"
+INST_ARCHLIB = blib/arch
+INST_SCRIPT = blib/script
+INST_BIN = blib/bin
+INST_LIB = blib/lib
+INST_MAN1DIR = blib/man1
+INST_MAN3DIR = blib/man3
+MAN1EXT = 1p
+MAN3EXT = 3pm
+INSTALLDIRS = vendor
+DESTDIR = 
+PREFIX = /usr
+PERLPREFIX = $(PREFIX)
+SITEPREFIX = $(PREFIX)/local
+VENDORPREFIX = $(PREFIX)
+INSTALLPRIVLIB = $(PERLPREFIX)/share/perl/5.8
+DESTINSTALLPRIVLIB = $(DESTDIR)$(INSTALLPRIVLIB)
+INSTALLSITELIB = $(SITEPREFIX)/share/perl/5.8.4
+DESTINSTALLSITELIB = $(DESTDIR)$(INSTALLSITELIB)
+INSTALLVENDORLIB = $(VENDORPREFIX)/share/perl5
+DESTINSTALLVENDORLIB = $(DESTDIR)$(INSTALLVENDORLIB)
+INSTALLARCHLIB = $(PERLPREFIX)/lib/perl/5.8
+DESTINSTALLARCHLIB = $(DESTDIR)$(INSTALLARCHLIB)
+INSTALLSITEARCH = $(SITEPREFIX)/lib/perl/5.8.4
+DESTINSTALLSITEARCH = $(DESTDIR)$(INSTALLSITEARCH)
+INSTALLVENDORARCH = $(VENDORPREFIX)/lib/perl5
+DESTINSTALLVENDORARCH = $(DESTDIR)$(INSTALLVENDORARCH)
+INSTALLBIN = $(PERLPREFIX)/bin
+DESTINSTALLBIN = $(DESTDIR)$(INSTALLBIN)
+INSTALLSITEBIN = $(SITEPREFIX)/bin
+DESTINSTALLSITEBIN = $(DESTDIR)$(INSTALLSITEBIN)
+INSTALLVENDORBIN = $(VENDORPREFIX)/bin
+DESTINSTALLVENDORBIN = $(DESTDIR)$(INSTALLVENDORBIN)
+INSTALLSCRIPT = $(PERLPREFIX)/bin
+DESTINSTALLSCRIPT = $(DESTDIR)$(INSTALLSCRIPT)
+INSTALLMAN1DIR = $(PERLPREFIX)/share/man/man1
+DESTINSTALLMAN1DIR = $(DESTDIR)$(INSTALLMAN1DIR)
+INSTALLSITEMAN1DIR = $(SITEPREFIX)/man/man1
+DESTINSTALLSITEMAN1DIR = $(DESTDIR)$(INSTALLSITEMAN1DIR)
+INSTALLVENDORMAN1DIR = $(VENDORPREFIX)/share/man/man1
+DESTINSTALLVENDORMAN1DIR = $(DESTDIR)$(INSTALLVENDORMAN1DIR)
+INSTALLMAN3DIR = $(PERLPREFIX)/share/man/man3
+DESTINSTALLMAN3DIR = $(DESTDIR)$(INSTALLMAN3DIR)
+INSTALLSITEMAN3DIR = $(SITEPREFIX)/man/man3
+DESTINSTALLSITEMAN3DIR = $(DESTDIR)$(INSTALLSITEMAN3DIR)
+INSTALLVENDORMAN3DIR = $(VENDORPREFIX)/share/man/man3
+DESTINSTALLVENDORMAN3DIR = $(DESTDIR)$(INSTALLVENDORMAN3DIR)
+PERL_LIB = /usr/share/perl/5.8
+PERL_ARCHLIB = /usr/lib/perl/5.8
+LIBPERL_A = libperl.a
+FIRST_MAKEFILE = Makefile
+MAKEFILE_OLD = $(FIRST_MAKEFILE).old
+MAKE_APERL_FILE = $(FIRST_MAKEFILE).aperl
+PERLMAINCC = $(CC)
+PERL_INC = /usr/lib/perl/5.8/CORE
+PERL = /usr/bin/perl
+FULLPERL = /usr/bin/perl
+ABSPERL = $(PERL)
+PERLRUN = $(PERL)
+FULLPERLRUN = $(FULLPERL)
+ABSPERLRUN = $(ABSPERL)
+PERLRUNINST = $(PERLRUN) "-I$(INST_ARCHLIB)" "-I$(INST_LIB)"
+FULLPERLRUNINST = $(FULLPERLRUN) "-I$(INST_ARCHLIB)" "-I$(INST_LIB)"
+ABSPERLRUNINST = $(ABSPERLRUN) "-I$(INST_ARCHLIB)" "-I$(INST_LIB)"
+PERL_CORE = 0
+PERM_RW = 644
+PERM_RWX = 755
+
+MAKEMAKER   = /usr/share/perl/5.8/ExtUtils/MakeMaker.pm
+MM_VERSION  = 6.17
+MM_REVISION = 1.133
+
+# FULLEXT = Pathname for extension directory (eg Foo/Bar/Oracle).
+# BASEEXT = Basename part of FULLEXT. May be just equal FULLEXT. (eg Oracle)
+# PARENT_NAME = NAME without BASEEXT and no trailing :: (eg Foo::Bar)
+# DLBASE  = Basename part of dynamic library. May be just equal BASEEXT.
+FULLEXT = AppConfig
+BASEEXT = AppConfig
+PARENT_NAME = 
+DLBASE = $(BASEEXT)
+VERSION_FROM = lib/AppConfig.pm
+OBJECT = 
+LDFROM = $(OBJECT)
+LINKTYPE = dynamic
+
+# Handy lists of source code files:
+XS_FILES = 
+C_FILES  = 
+O_FILES  = 
+H_FILES  = 
+MAN1PODS = 
+MAN3PODS = lib/AppConfig.pm \
+	lib/AppConfig/Args.pm \
+	lib/AppConfig/CGI.pm \
+	lib/AppConfig/File.pm \
+	lib/AppConfig/Getopt.pm \
+	lib/AppConfig/State.pm \
+	lib/AppConfig/Sys.pm
+
+# Where is the Config information that we are using/depend on
+CONFIGDEP = $(PERL_ARCHLIB)$(DIRFILESEP)Config.pm $(PERL_INC)$(DIRFILESEP)config.h
+
+# Where to build things
+INST_LIBDIR      = $(INST_LIB)
+INST_ARCHLIBDIR  = $(INST_ARCHLIB)
+
+INST_AUTODIR     = $(INST_LIB)/auto/$(FULLEXT)
+INST_ARCHAUTODIR = $(INST_ARCHLIB)/auto/$(FULLEXT)
+
+INST_STATIC      = 
+INST_DYNAMIC     = 
+INST_BOOT        = 
+
+# Extra linker info
+EXPORT_LIST        = 
+PERL_ARCHIVE       = 
+PERL_ARCHIVE_AFTER = 
+
+
+TO_INST_PM = lib/AppConfig.pm \
+	lib/AppConfig/Args.pm \
+	lib/AppConfig/CGI.pm \
+	lib/AppConfig/File.pm \
+	lib/AppConfig/Getopt.pm \
+	lib/AppConfig/State.pm \
+	lib/AppConfig/Sys.pm
+
+PM_TO_BLIB = lib/AppConfig/Args.pm \
+	blib/lib/AppConfig/Args.pm \
+	lib/AppConfig/CGI.pm \
+	blib/lib/AppConfig/CGI.pm \
+	lib/AppConfig/File.pm \
+	blib/lib/AppConfig/File.pm \
+	lib/AppConfig/State.pm \
+	blib/lib/AppConfig/State.pm \
+	lib/AppConfig/Getopt.pm \
+	blib/lib/AppConfig/Getopt.pm \
+	lib/AppConfig.pm \
+	blib/lib/AppConfig.pm \
+	lib/AppConfig/Sys.pm \
+	blib/lib/AppConfig/Sys.pm
+
+
+# --- MakeMaker platform_constants section:
+MM_Unix_VERSION = 1.42
+PERL_MALLOC_DEF = -DPERL_EXTMALLOC_DEF -Dmalloc=Perl_malloc -Dfree=Perl_mfree -Drealloc=Perl_realloc -Dcalloc=Perl_calloc
+
+
+# --- MakeMaker tool_autosplit section:
+# Usage: $(AUTOSPLITFILE) FileToSplit AutoDirToSplitInto
+AUTOSPLITFILE = $(PERLRUN)  -e 'use AutoSplit;  autosplit($$ARGV[0], $$ARGV[1], 0, 1, 1)'
+
+
+
+# --- MakeMaker tool_xsubpp section:
+
+
+# --- MakeMaker tools_other section:
+SHELL = /bin/sh
+CHMOD = chmod
+CP = cp
+MV = mv
+NOOP = $(SHELL) -c true
+NOECHO = @
+RM_F = rm -f
+RM_RF = rm -rf
+TEST_F = test -f
+TOUCH = touch
+UMASK_NULL = umask 0
+DEV_NULL = > /dev/null 2>&1
+MKPATH = $(PERLRUN) "-MExtUtils::Command" -e mkpath
+EQUALIZE_TIMESTAMP = $(PERLRUN) "-MExtUtils::Command" -e eqtime
+ECHO = echo
+ECHO_N = echo -n
+UNINST = 0
+VERBINST = 0
+MOD_INSTALL = $(PERLRUN) -MExtUtils::Install -e 'install({@ARGV}, '\''$(VERBINST)'\'', 0, '\''$(UNINST)'\'');'
+DOC_INSTALL = $(PERLRUN) "-MExtUtils::Command::MM" -e perllocal_install
+UNINSTALL = $(PERLRUN) "-MExtUtils::Command::MM" -e uninstall
+WARN_IF_OLD_PACKLIST = $(PERLRUN) "-MExtUtils::Command::MM" -e warn_if_old_packlist
+
+
+# --- MakeMaker makemakerdflt section:
+makemakerdflt: all
+	$(NOECHO) $(NOOP)
+
+
+# --- MakeMaker dist section:
+TAR = tar
+TARFLAGS = cvf
+ZIP = zip
+ZIPFLAGS = -r
+COMPRESS = gzip
+SUFFIX = gz
+SHAR = shar
+PREOP = cp docs/header README; \
+                       pod2text lib/AppConfig.pm >> README
+POSTOP = $(NOECHO) $(NOOP)
+TO_UNIX = $(NOECHO) $(NOOP)
+CI = ci -u
+RCS_LABEL = rcs -Nv$(VERSION_SYM): -q
+DIST_CP = best
+DIST_DEFAULT = tardist
+DISTNAME = AppConfig
+DISTVNAME = AppConfig-1.56
+
+
+# --- MakeMaker macro section:
+
+
+# --- MakeMaker depend section:
+
+
+# --- MakeMaker cflags section:
+
+
+# --- MakeMaker const_loadlibs section:
+
+
+# --- MakeMaker const_cccmd section:
+
+
+# --- MakeMaker post_constants section:
+
+
+# --- MakeMaker pasthru section:
+
+PASTHRU = LIB="$(LIB)"\
+	LIBPERL_A="$(LIBPERL_A)"\
+	LINKTYPE="$(LINKTYPE)"\
+	PREFIX="$(PREFIX)"\
+	OPTIMIZE="$(OPTIMIZE)"\
+	PASTHRU_DEFINE="$(PASTHRU_DEFINE)"\
+	PASTHRU_INC="$(PASTHRU_INC)"
+
+
+# --- MakeMaker special_targets section:
+.SUFFIXES: .xs .c .C .cpp .i .s .cxx .cc $(OBJ_EXT)
+
+.PHONY: all config static dynamic test linkext manifest
+
+
+
+# --- MakeMaker c_o section:
+
+
+# --- MakeMaker xs_c section:
+
+
+# --- MakeMaker xs_o section:
+
+
+# --- MakeMaker top_targets section:
+all :: pure_all manifypods
+	$(NOECHO) $(NOOP)
+
+
+pure_all :: config pm_to_blib subdirs linkext
+	$(NOECHO) $(NOOP)
+
+subdirs :: $(MYEXTLIB)
+	$(NOECHO) $(NOOP)
+
+config :: $(FIRST_MAKEFILE) $(INST_LIBDIR)$(DIRFILESEP).exists
+	$(NOECHO) $(NOOP)
+
+config :: $(INST_ARCHAUTODIR)$(DIRFILESEP).exists
+	$(NOECHO) $(NOOP)
+
+config :: $(INST_AUTODIR)$(DIRFILESEP).exists
+	$(NOECHO) $(NOOP)
+
+$(INST_AUTODIR)/.exists :: /usr/lib/perl/5.8/CORE/perl.h
+	$(NOECHO) $(MKPATH) $(INST_AUTODIR)
+	$(NOECHO) $(EQUALIZE_TIMESTAMP) /usr/lib/perl/5.8/CORE/perl.h $(INST_AUTODIR)/.exists
+
+	-$(NOECHO) $(CHMOD) $(PERM_RWX) $(INST_AUTODIR)
+
+$(INST_LIBDIR)/.exists :: /usr/lib/perl/5.8/CORE/perl.h
+	$(NOECHO) $(MKPATH) $(INST_LIBDIR)
+	$(NOECHO) $(EQUALIZE_TIMESTAMP) /usr/lib/perl/5.8/CORE/perl.h $(INST_LIBDIR)/.exists
+
+	-$(NOECHO) $(CHMOD) $(PERM_RWX) $(INST_LIBDIR)
+
+$(INST_ARCHAUTODIR)/.exists :: /usr/lib/perl/5.8/CORE/perl.h
+	$(NOECHO) $(MKPATH) $(INST_ARCHAUTODIR)
+	$(NOECHO) $(EQUALIZE_TIMESTAMP) /usr/lib/perl/5.8/CORE/perl.h $(INST_ARCHAUTODIR)/.exists
+
+	-$(NOECHO) $(CHMOD) $(PERM_RWX) $(INST_ARCHAUTODIR)
+
+config :: $(INST_MAN3DIR)$(DIRFILESEP).exists
+	$(NOECHO) $(NOOP)
+
+
+$(INST_MAN3DIR)/.exists :: /usr/lib/perl/5.8/CORE/perl.h
+	$(NOECHO) $(MKPATH) $(INST_MAN3DIR)
+	$(NOECHO) $(EQUALIZE_TIMESTAMP) /usr/lib/perl/5.8/CORE/perl.h $(INST_MAN3DIR)/.exists
+
+	-$(NOECHO) $(CHMOD) $(PERM_RWX) $(INST_MAN3DIR)
+
+help:
+	perldoc ExtUtils::MakeMaker
+
+
+# --- MakeMaker linkext section:
+
+linkext :: $(LINKTYPE)
+	$(NOECHO) $(NOOP)
+
+
+# --- MakeMaker dlsyms section:
+
+
+# --- MakeMaker dynamic section:
+
+dynamic :: $(FIRST_MAKEFILE) $(INST_DYNAMIC) $(INST_BOOT)
+	$(NOECHO) $(NOOP)
+
+
+# --- MakeMaker dynamic_bs section:
+
+BOOTSTRAP =
+
+
+# --- MakeMaker dynamic_lib section:
+
+
+# --- MakeMaker static section:
+
+## $(INST_PM) has been moved to the all: target.
+## It remains here for awhile to allow for old usage: "make static"
+static :: $(FIRST_MAKEFILE) $(INST_STATIC)
+	$(NOECHO) $(NOOP)
+
+
+# --- MakeMaker static_lib section:
+
+
+# --- MakeMaker manifypods section:
+
+POD2MAN_EXE = $(PERLRUN) "-MExtUtils::Command::MM" -e pod2man "--"
+POD2MAN = $(POD2MAN_EXE)
+
+
+manifypods : pure_all  \
+	lib/AppConfig/Args.pm \
+	lib/AppConfig/CGI.pm \
+	lib/AppConfig/File.pm \
+	lib/AppConfig/State.pm \
+	lib/AppConfig/Getopt.pm \
+	lib/AppConfig.pm \
+	lib/AppConfig/Sys.pm \
+	lib/AppConfig/Args.pm \
+	lib/AppConfig/CGI.pm \
+	lib/AppConfig/File.pm \
+	lib/AppConfig/State.pm \
+	lib/AppConfig/Getopt.pm \
+	lib/AppConfig.pm \
+	lib/AppConfig/Sys.pm
+	$(NOECHO) $(POD2MAN) --section=3pm --perm_rw=$(PERM_RW)\
+	  lib/AppConfig/Args.pm $(INST_MAN3DIR)/AppConfig::Args.$(MAN3EXT) \
+	  lib/AppConfig/CGI.pm $(INST_MAN3DIR)/AppConfig::CGI.$(MAN3EXT) \
+	  lib/AppConfig/File.pm $(INST_MAN3DIR)/AppConfig::File.$(MAN3EXT) \
+	  lib/AppConfig/State.pm $(INST_MAN3DIR)/AppConfig::State.$(MAN3EXT) \
+	  lib/AppConfig/Getopt.pm $(INST_MAN3DIR)/AppConfig::Getopt.$(MAN3EXT) \
+	  lib/AppConfig.pm $(INST_MAN3DIR)/AppConfig.$(MAN3EXT) \
+	  lib/AppConfig/Sys.pm $(INST_MAN3DIR)/AppConfig::Sys.$(MAN3EXT) 
+
+
+
+
+# --- MakeMaker processPL section:
+
+
+# --- MakeMaker installbin section:
+
+
+# --- MakeMaker subdirs section:
+
+# none
+
+# --- MakeMaker clean_subdirs section:
+clean_subdirs :
+	$(NOECHO) $(NOOP)
+
+
+# --- MakeMaker clean section:
+
+# Delete temporary files but do not touch installed files. We don't delete
+# the Makefile here so a later make realclean still has a makefile to use.
+
+clean :: clean_subdirs
+	-$(RM_RF) ./blib $(MAKE_APERL_FILE) $(INST_ARCHAUTODIR)/extralibs.all $(INST_ARCHAUTODIR)/extralibs.ld perlmain.c tmon.out mon.out so_locations pm_to_blib *$(OBJ_EXT) *$(LIB_EXT) perl.exe perl perl$(EXE_EXT) $(BOOTSTRAP) $(BASEEXT).bso $(BASEEXT).def lib$(BASEEXT).def $(BASEEXT).exp $(BASEEXT).x core core.*perl.*.? *perl.core core.[0-9] core.[0-9][0-9] core.[0-9][0-9][0-9] core.[0-9][0-9][0-9][0-9] core.[0-9][0-9][0-9][0-9][0-9]
+	-$(MV) $(FIRST_MAKEFILE) $(MAKEFILE_OLD) $(DEV_NULL)
+
+
+# --- MakeMaker realclean_subdirs section:
+realclean_subdirs :
+	$(NOECHO) $(NOOP)
+
+
+# --- MakeMaker realclean section:
+
+# Delete temporary files (via clean) and also delete installed files
+realclean purge ::  clean realclean_subdirs
+	$(RM_RF) $(INST_AUTODIR) $(INST_ARCHAUTODIR)
+	$(RM_RF) $(DISTVNAME)
+	$(RM_F)  blib/lib/AppConfig/Sys.pm blib/lib/AppConfig/Getopt.pm blib/lib/AppConfig.pm blib/lib/AppConfig/Args.pm $(MAKEFILE_OLD) blib/lib/AppConfig/State.pm blib/lib/AppConfig/CGI.pm blib/lib/AppConfig/File.pm
+	$(RM_F) $(FIRST_MAKEFILE)
+
+
+# --- MakeMaker metafile section:
+metafile :
+	$(NOECHO) $(ECHO) '# http://module-build.sourceforge.net/META-spec.html' > META.yml
+	$(NOECHO) $(ECHO) '#XXXXXXX This is a prototype!!!  It will change in the future!!! XXXXX#' >> META.yml
+	$(NOECHO) $(ECHO) 'name:         AppConfig' >> META.yml
+	$(NOECHO) $(ECHO) 'version:      1.56' >> META.yml
+	$(NOECHO) $(ECHO) 'version_from: lib/AppConfig.pm' >> META.yml
+	$(NOECHO) $(ECHO) 'installdirs:  vendor' >> META.yml
+	$(NOECHO) $(ECHO) 'requires:' >> META.yml
+	$(NOECHO) $(ECHO) '    Test::More:                    0' >> META.yml
+	$(NOECHO) $(ECHO) '' >> META.yml
+	$(NOECHO) $(ECHO) 'distribution_type: module' >> META.yml
+	$(NOECHO) $(ECHO) 'generated_by: ExtUtils::MakeMaker version 6.17' >> META.yml
+
+
+# --- MakeMaker metafile_addtomanifest section:
+metafile_addtomanifest:
+	$(NOECHO) $(PERLRUN) -MExtUtils::Manifest=maniadd -e 'eval { maniadd({q{META.yml} => q{Module meta-data (added by MakeMaker)}}) } ' \
+	-e '    or print "Could not add META.yml to MANIFEST: $${'\''@'\''}\n"'
+
+
+# --- MakeMaker dist_basics section:
+distclean :: realclean distcheck
+	$(NOECHO) $(NOOP)
+
+distcheck :
+	$(PERLRUN) "-MExtUtils::Manifest=fullcheck" -e fullcheck
+
+skipcheck :
+	$(PERLRUN) "-MExtUtils::Manifest=skipcheck" -e skipcheck
+
+manifest :
+	$(PERLRUN) "-MExtUtils::Manifest=mkmanifest" -e mkmanifest
+
+veryclean : realclean
+	$(RM_F) *~ *.orig */*~ */*.orig
+
+
+
+# --- MakeMaker dist_core section:
+
+dist : $(DIST_DEFAULT) $(FIRST_MAKEFILE)
+	$(NOECHO) $(PERLRUN) -l -e 'print '\''Warning: Makefile possibly out of date with $(VERSION_FROM)'\''' \
+	-e '    if -e '\''$(VERSION_FROM)'\'' and -M '\''$(VERSION_FROM)'\'' < -M '\''$(FIRST_MAKEFILE)'\'';'
+
+tardist : $(DISTVNAME).tar$(SUFFIX)
+	$(NOECHO) $(NOOP)
+
+uutardist : $(DISTVNAME).tar$(SUFFIX)
+	uuencode $(DISTVNAME).tar$(SUFFIX) $(DISTVNAME).tar$(SUFFIX) > $(DISTVNAME).tar$(SUFFIX)_uu
+
+$(DISTVNAME).tar$(SUFFIX) : distdir
+	$(PREOP)
+	$(TO_UNIX)
+	$(TAR) $(TARFLAGS) $(DISTVNAME).tar $(DISTVNAME)
+	$(RM_RF) $(DISTVNAME)
+	$(COMPRESS) $(DISTVNAME).tar
+	$(POSTOP)
+
+zipdist : $(DISTVNAME).zip
+	$(NOECHO) $(NOOP)
+
+$(DISTVNAME).zip : distdir
+	$(PREOP)
+	$(ZIP) $(ZIPFLAGS) $(DISTVNAME).zip $(DISTVNAME)
+	$(RM_RF) $(DISTVNAME)
+	$(POSTOP)
+
+shdist : distdir
+	$(PREOP)
+	$(SHAR) $(DISTVNAME) > $(DISTVNAME).shar
+	$(RM_RF) $(DISTVNAME)
+	$(POSTOP)
+
+
+# --- MakeMaker distdir section:
+distdir : metafile metafile_addtomanifest
+	$(RM_RF) $(DISTVNAME)
+	$(PERLRUN) "-MExtUtils::Manifest=manicopy,maniread" \
+		-e "manicopy(maniread(),'$(DISTVNAME)', '$(DIST_CP)');"
+
+
+
+# --- MakeMaker dist_test section:
+
+disttest : distdir
+	cd $(DISTVNAME) && $(ABSPERLRUN) Makefile.PL
+	cd $(DISTVNAME) && $(MAKE) $(PASTHRU)
+	cd $(DISTVNAME) && $(MAKE) test $(PASTHRU)
+
+
+# --- MakeMaker dist_ci section:
+
+ci :
+	$(PERLRUN) "-MExtUtils::Manifest=maniread" \
+	  -e "@all = keys %{ maniread() };" \
+	  -e "print(qq{Executing $(CI) @all\n}); system(qq{$(CI) @all});" \
+	  -e "print(qq{Executing $(RCS_LABEL) ...\n}); system(qq{$(RCS_LABEL) @all});"
+
+
+# --- MakeMaker install section:
+
+install :: all pure_install doc_install
+
+install_perl :: all pure_perl_install doc_perl_install
+
+install_site :: all pure_site_install doc_site_install
+
+install_vendor :: all pure_vendor_install doc_vendor_install
+
+pure_install :: pure_$(INSTALLDIRS)_install
+
+doc_install :: doc_$(INSTALLDIRS)_install
+
+pure__install : pure_site_install
+	$(NOECHO) $(ECHO) INSTALLDIRS not defined, defaulting to INSTALLDIRS=site
+
+doc__install : doc_site_install
+	$(NOECHO) $(ECHO) INSTALLDIRS not defined, defaulting to INSTALLDIRS=site
+
+pure_perl_install ::
+	$(NOECHO) umask 022; $(MOD_INSTALL) \
+		$(INST_LIB) $(DESTINSTALLPRIVLIB) \
+		$(INST_ARCHLIB) $(DESTINSTALLARCHLIB) \
+		$(INST_BIN) $(DESTINSTALLBIN) \
+		$(INST_SCRIPT) $(DESTINSTALLSCRIPT) \
+		$(INST_MAN1DIR) $(DESTINSTALLMAN1DIR) \
+		$(INST_MAN3DIR) $(DESTINSTALLMAN3DIR)
+	$(NOECHO) $(WARN_IF_OLD_PACKLIST) \
+		$(SITEARCHEXP)/auto/$(FULLEXT)
+
+
+pure_site_install ::
+	$(NOECHO) umask 02; $(MOD_INSTALL) \
+		read $(SITEARCHEXP)/auto/$(FULLEXT)/.packlist \
+		write $(DESTINSTALLSITEARCH)/auto/$(FULLEXT)/.packlist \
+		$(INST_LIB) $(DESTINSTALLSITELIB) \
+		$(INST_ARCHLIB) $(DESTINSTALLSITEARCH) \
+		$(INST_BIN) $(DESTINSTALLSITEBIN) \
+		$(INST_SCRIPT) $(DESTINSTALLSCRIPT) \
+		$(INST_MAN1DIR) $(DESTINSTALLSITEMAN1DIR) \
+		$(INST_MAN3DIR) $(DESTINSTALLSITEMAN3DIR)
+	$(NOECHO) $(WARN_IF_OLD_PACKLIST) \
+		$(PERL_ARCHLIB)/auto/$(FULLEXT)
+
+pure_vendor_install ::
+	$(NOECHO) umask 022; $(MOD_INSTALL) \
+		$(INST_LIB) $(DESTINSTALLVENDORLIB) \
+		$(INST_ARCHLIB) $(DESTINSTALLVENDORARCH) \
+		$(INST_BIN) $(DESTINSTALLVENDORBIN) \
+		$(INST_SCRIPT) $(DESTINSTALLSCRIPT) \
+		$(INST_MAN1DIR) $(DESTINSTALLVENDORMAN1DIR) \
+		$(INST_MAN3DIR) $(DESTINSTALLVENDORMAN3DIR)
+
+doc_perl_install ::
+
+doc_site_install ::
+	$(NOECHO) $(ECHO) Appending installation info to $(DESTINSTALLSITEARCH)/perllocal.pod
+	-$(NOECHO) umask 02; $(MKPATH) $(DESTINSTALLSITEARCH)
+	-$(NOECHO) umask 02; $(DOC_INSTALL) \
+		"Module" "$(NAME)" \
+		"installed into" "$(INSTALLSITELIB)" \
+		LINKTYPE "$(LINKTYPE)" \
+		VERSION "$(VERSION)" \
+		EXE_FILES "$(EXE_FILES)" \
+		>> $(DESTINSTALLSITEARCH)/perllocal.pod
+
+doc_vendor_install ::
+
+
+uninstall :: uninstall_from_$(INSTALLDIRS)dirs
+
+uninstall_from_perldirs ::
+	$(NOECHO) $(UNINSTALL) $(PERL_ARCHLIB)/auto/$(FULLEXT)/.packlist
+
+uninstall_from_sitedirs ::
+	$(NOECHO) $(UNINSTALL) $(SITEARCHEXP)/auto/$(FULLEXT)/.packlist
+
+uninstall_from_vendordirs ::
+	$(NOECHO) $(UNINSTALL) $(VENDORARCHEXP)/auto/$(FULLEXT)/.packlist
+
+
+# --- MakeMaker force section:
+# Phony target to force checking subdirectories.
+FORCE:
+	$(NOECHO) $(NOOP)
+
+
+# --- MakeMaker perldepend section:
+
+
+# --- MakeMaker makefile section:
+
+# We take a very conservative approach here, but it's worth it.
+# We move Makefile to Makefile.old here to avoid gnu make looping.
+$(FIRST_MAKEFILE) : Makefile.PL $(CONFIGDEP)
+	$(NOECHO) $(ECHO) "Makefile out-of-date with respect to $?"
+	$(NOECHO) $(ECHO) "Cleaning current config before rebuilding Makefile..."
+	$(NOECHO) $(RM_F) $(MAKEFILE_OLD)
+	$(NOECHO) $(MV)   $(FIRST_MAKEFILE) $(MAKEFILE_OLD)
+	-$(MAKE) -f $(MAKEFILE_OLD) clean $(DEV_NULL) || $(NOOP)
+	$(PERLRUN) Makefile.PL "INSTALLDIRS=vendor"
+	$(NOECHO) $(ECHO) "==> Your Makefile has been rebuilt. <=="
+	$(NOECHO) $(ECHO) "==> Please rerun the make command.  <=="
+	false
+
+
+
+# --- MakeMaker staticmake section:
+
+# --- MakeMaker makeaperl section ---
+MAP_TARGET    = perl
+FULLPERL      = /usr/bin/perl
+
+$(MAP_TARGET) :: static $(MAKE_APERL_FILE)
+	$(MAKE) -f $(MAKE_APERL_FILE) $@
+
+$(MAKE_APERL_FILE) : $(FIRST_MAKEFILE)
+	$(NOECHO) $(ECHO) Writing \"$(MAKE_APERL_FILE)\" for this $(MAP_TARGET)
+	$(NOECHO) $(PERLRUNINST) \
+		Makefile.PL DIR= \
+		MAKEFILE=$(MAKE_APERL_FILE) LINKTYPE=static \
+		MAKEAPERL=1 NORECURS=1 CCCDLFLAGS= \
+		INSTALLDIRS=vendor
+
+
+# --- MakeMaker test section:
+
+TEST_VERBOSE=0
+TEST_TYPE=test_$(LINKTYPE)
+TEST_FILE = test.pl
+TEST_FILES = t/*.t
+TESTDB_SW = -d
+
+testdb :: testdb_$(LINKTYPE)
+
+test :: $(TEST_TYPE)
+
+test_dynamic :: pure_all
+	PERL_DL_NONLAZY=1 $(FULLPERLRUN) "-MExtUtils::Command::MM" "-e" "test_harness($(TEST_VERBOSE), '$(INST_LIB)', '$(INST_ARCHLIB)')" $(TEST_FILES)
+
+testdb_dynamic :: pure_all
+	PERL_DL_NONLAZY=1 $(FULLPERLRUN) $(TESTDB_SW) "-I$(INST_LIB)" "-I$(INST_ARCHLIB)" $(TEST_FILE)
+
+test_ : test_dynamic
+
+test_static :: test_dynamic
+testdb_static :: testdb_dynamic
+
+
+# --- MakeMaker ppd section:
+# Creates a PPD (Perl Package Description) for a binary distribution.
+ppd:
+	$(NOECHO) $(ECHO) '<SOFTPKG NAME="$(DISTNAME)" VERSION="1,56,0,0">' > $(DISTNAME).ppd
+	$(NOECHO) $(ECHO) '    <TITLE>$(DISTNAME)</TITLE>' >> $(DISTNAME).ppd
+	$(NOECHO) $(ECHO) '    <ABSTRACT>AppConfig is a bundle of Perl5 modules for reading configuration files and parsing command line arguments.</ABSTRACT>' >> $(DISTNAME).ppd
+	$(NOECHO) $(ECHO) '    <AUTHOR>Andy Wardley &lt;abw@wardley.org&gt;</AUTHOR>' >> $(DISTNAME).ppd
+	$(NOECHO) $(ECHO) '    <IMPLEMENTATION>' >> $(DISTNAME).ppd
+	$(NOECHO) $(ECHO) '        <DEPENDENCY NAME="Test-More" VERSION="0,0,0,0" />' >> $(DISTNAME).ppd
+	$(NOECHO) $(ECHO) '        <OS NAME="$(OSNAME)" />' >> $(DISTNAME).ppd
+	$(NOECHO) $(ECHO) '        <ARCHITECTURE NAME="i386-linux-thread-multi" />' >> $(DISTNAME).ppd
+	$(NOECHO) $(ECHO) '        <CODEBASE HREF="" />' >> $(DISTNAME).ppd
+	$(NOECHO) $(ECHO) '    </IMPLEMENTATION>' >> $(DISTNAME).ppd
+	$(NOECHO) $(ECHO) '</SOFTPKG>' >> $(DISTNAME).ppd
+
+
+# --- MakeMaker pm_to_blib section:
+
+pm_to_blib: $(TO_INST_PM)
+	$(NOECHO) $(PERLRUN) -MExtUtils::Install -e 'pm_to_blib({@ARGV}, '\''$(INST_LIB)/auto'\'', '\''$(PM_FILTER)'\'')'\
+	  lib/AppConfig/Args.pm blib/lib/AppConfig/Args.pm \
+	  lib/AppConfig/CGI.pm blib/lib/AppConfig/CGI.pm \
+	  lib/AppConfig/File.pm blib/lib/AppConfig/File.pm \
+	  lib/AppConfig/State.pm blib/lib/AppConfig/State.pm \
+	  lib/AppConfig/Getopt.pm blib/lib/AppConfig/Getopt.pm \
+	  lib/AppConfig.pm blib/lib/AppConfig.pm \
+	  lib/AppConfig/Sys.pm blib/lib/AppConfig/Sys.pm 
+	$(NOECHO) $(TOUCH) $@
+
+# --- MakeMaker selfdocument section:
+
+
+# --- MakeMaker postamble section:
+
+
+# End.