--- 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 <abw@wardley.org></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/</</g;
+ $format =~ s/>/>/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 <abw@wardley.org></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.
![[patchlogo]](http://patch-tracker.debian.org/static/img/swirlpatch.png)