File Coverage

blib/lib/AppConfig.pm
Criterion Covered Total %
statement n/a
branch n/a
condition n/a
subroutine n/a
pod n/a
total n/a


line stmt bran cond sub pod time code
1             package AppConfig;
2              
3             #============================================================================
4             #
5             # AppConfig.pm
6             #
7             # Perl5 module for reading and parsing configuration files and command line
8             # arguments.
9             #
10             # Written by Andy Wardley <abw@wardley.org>
11             #
12             # Copyright (C) 1997-2003 Andy Wardley. All Rights Reserved.
13             # Copyright (C) 1997,1998 Canon Research Centre Europe Ltd.
14             #
15             # $Id: AppConfig.pm,v 1.7 2004/02/04 10:28:28 abw Exp $
16             #
17             #============================================================================
18              
19             use strict;
20              
21             require 5.005;
22              
23             ## This is the main version number for AppConfig
24             ## It is extracted by ExtUtils::MakeMaker and inserted in various places.
25             use vars qw{$VERSION @ISA};
26             BEGIN {
27             require Exporter;
28              
29             $VERSION = '1.64';
30             @ISA     = qw{ Exporter };
31             }
32              
33             # variable expansion constants
34             use constant EXPAND_NONE => 0;
35             use constant EXPAND_VAR => 1;
36             use constant EXPAND_UID => 2;
37             use constant EXPAND_ENV => 4;
38             use constant EXPAND_ALL => EXPAND_VAR | EXPAND_UID | EXPAND_ENV;
39             use constant EXPAND_WARN => 8;
40              
41             # argument count types
42             use constant ARGCOUNT_NONE => 0;
43             use constant ARGCOUNT_ONE => 1;
44             use constant ARGCOUNT_LIST => 2;
45             use constant ARGCOUNT_HASH => 3;
46              
47             # Exporter tagsets
48             my @EXPAND = qw(
49             EXPAND_NONE
50             EXPAND_VAR
51             EXPAND_UID
52             EXPAND_ENV
53             EXPAND_ALL
54             EXPAND_WARN
55             );
56              
57             my @ARGCOUNT = qw(
58             ARGCOUNT_NONE
59             ARGCOUNT_ONE
60             ARGCOUNT_LIST
61             ARGCOUNT_HASH
62             );
63              
64             use vars qw( $AUTOLOAD @EXPORT_OK %EXPORT_TAGS );
65             @EXPORT_OK   = ( @EXPAND, @ARGCOUNT );
66             %EXPORT_TAGS = (
67                 expand => [ @EXPAND ],
68                 argcount => [ @ARGCOUNT ],
69             );
70              
71              
72              
73              
74              
75             #------------------------------------------------------------------------
76             # new(\%config, @vars)
77             #
78             # Module constructor. All parameters passed are forwarded onto the
79             # AppConfig::State constructor. Returns a reference to a newly created
80             # AppConfig object.
81             #------------------------------------------------------------------------
82              
83             sub new {
84             my $class = shift;
85              
86             require AppConfig::State;
87              
88             my $self = {
89             STATE => AppConfig::State->new(@_)
90             };
91              
92             bless $self, $class;
93              
94             return $self;
95             }
96              
97              
98              
99              
100              
101             #------------------------------------------------------------------------
102             # file(@files)
103             #
104             # The file() method is called to parse configuration files. An
105             # AppConfig::File object is instantiated and stored internally for
106             # use in subsequent calls to file().
107             #------------------------------------------------------------------------
108              
109             sub file {
110             my $self = shift;
111             my $state = $self->{ STATE };
112             my $file;
113              
114             require AppConfig::File;
115              
116             # create an AppConfig::File object if one isn't defined
117             $file = $self->{ FILE } ||= AppConfig::File->new($state);
118              
119             # call on the AppConfig::File object to process files.
120             $file->parse(@_);
121             }
122              
123              
124              
125              
126              
127             #------------------------------------------------------------------------
128             # args(\@args)
129             #
130             # The args() method is called to parse command line arguments. An
131             # AppConfig::Args object is instantiated and then stored internally for
132             # use in subsequent calls to args().
133             #------------------------------------------------------------------------
134              
135             sub args {
136             my $self = shift;
137             my $state = $self->{ STATE };
138             my $args;
139              
140             require AppConfig::Args;
141              
142             # create an AppConfig::Args object if one isn't defined
143             $args = $self->{ ARGS } ||= AppConfig::Args->new($state);
144              
145             # call on the AppConfig::Args object to process arguments.
146             $args->parse(shift);
147             }
148              
149              
150              
151              
152              
153             #------------------------------------------------------------------------
154             # getopt(@config, \@args)
155             #
156             # The getopt() method is called to parse command line arguments. The
157             # AppConfig::Getopt module is require()'d and an AppConfig::Getopt object
158             # is created to parse the arguments.
159             #------------------------------------------------------------------------
160              
161             sub getopt {
162             my $self = shift;
163             my $state = $self->{ STATE };
164             my $getopt;
165              
166             require AppConfig::Getopt;
167              
168             # create an AppConfig::Getopt object if one isn't defined
169             $getopt = $self->{ GETOPT } ||= AppConfig::Getopt->new($state);
170              
171             # call on the AppConfig::Getopt object to process arguments.
172             $getopt->parse(@_);
173             }
174              
175              
176              
177              
178              
179             #------------------------------------------------------------------------
180             # cgi($query)
181             #
182             # The cgi() method is called to parse a CGI query string. An
183             # AppConfig::CGI object is instantiated and then stored internally for
184             # use in subsequent calls to args().
185             #------------------------------------------------------------------------
186              
187             sub cgi {
188             my $self = shift;
189             my $state = $self->{ STATE };
190             my $cgi;
191              
192             require AppConfig::CGI;
193              
194             # create an AppConfig::CGI object if one isn't defined
195             $cgi = $self->{ CGI } ||= AppConfig::CGI->new($state);
196              
197             # call on the AppConfig::CGI object to process a query.
198             $cgi->parse(shift);
199             }
200              
201              
202              
203              
204                 
205             #------------------------------------------------------------------------
206             # AUTOLOAD
207             #
208             # Autoload function called whenever an unresolved object method is
209             # called. All methods are delegated to the $self->{ STATE }
210             # AppConfig::State object.
211             #
212             #------------------------------------------------------------------------
213              
214             sub AUTOLOAD {
215             my $self = shift;
216             my $method;
217              
218             # splat the leading package name
219             ($method = $AUTOLOAD) =~ s/.*:://;
220              
221             # ignore destructor
222             $method eq 'DESTROY' && return;
223              
224             # delegate method call to AppConfig::State object in $self->{ STATE }
225             $self->{ STATE }->$method(@_);
226             }
227              
228             1;
229              
230             __END__
231            
232             =head1 NAME
233            
234             AppConfig - Perl5 module for reading configuration files and parsing command line arguments.
235            
236             =head1 SYNOPSIS
237            
238             use AppConfig;
239            
240             # create a new AppConfig object
241             my $config = AppConfig->new( \%cfg );
242            
243             # define a new variable
244             $config->define( $varname => \%varopts );
245            
246             # create/define combined
247             my $config = AppConfig->new( \%cfg,
248             $varname => \%varopts,
249             $varname => \%varopts,
250             ...
251             );
252            
253             # set/get the value
254             $config->set( $varname, $value );
255             $config->get($varname);
256            
257             # shortcut form
258             $config->varname($value);
259             $config->varname;
260            
261             # read configuration file
262             $config->file($file);
263            
264             # parse command line options
265             $config->args(\@args); # default to \@ARGV
266            
267             # advanced command line options with Getopt::Long
268             $config->getopt(\@args); # default to \@ARGV
269            
270             # parse CGI parameters (GET method)
271             $config->cgi($query); # default to $ENV{ QUERY_STRING }
272            
273             =head1 OVERVIEW
274            
275             AppConfig is a Perl5 module for managing application configuration
276             information. It maintains the state of any number of variables and
277             provides methods for parsing configuration files, command line
278             arguments and CGI script parameters.
279            
280             Variables values may be set via configuration files. Variables may be
281             flags (On/Off), take a single value, or take multiple values stored as a
282             list or hash. The number of arguments a variable expects is determined
283             by its configuration when defined.
284            
285             # flags
286             verbose
287             nohelp
288             debug = On
289            
290             # single value
291             home = /home/abw/
292            
293             # multiple list value
294             file = /tmp/file1
295             file = /tmp/file2
296            
297             # multiple hash value
298             book camel = Programming Perl
299             book llama = Learning Perl
300            
301             The '-' prefix can be used to reset a variable to its default value and
302             the '+' prefix can be used to set it to 1
303            
304             -verbose
305             +debug
306            
307             Variable, environment variable and tilde (home directory) expansions
308             can be applied (selectively, if necessary) to the values read from
309             configuration files:
310            
311             home = ~ # home directory
312             nntp = ${NNTPSERVER} # environment variable
313             html = $home/html # internal variables
314             img = $html/images
315            
316             Configuration files may be arranged in blocks as per the style of Win32
317             "INI" files.
318            
319             [file]
320             site = kfs
321             src = ~/websrc/docs/$site
322             lib = ~/websrc/lib
323             dest = ~/public_html/$site
324            
325             [page]
326             header = $lib/header
327             footer = $lib/footer
328            
329             You can also use Perl's "heredoc" syntax to define a large block of
330             text in a configuration file.
331            
332             multiline = <<FOOBAR
333             line 1
334             line 2
335             FOOBAR
336            
337             paths exe = "${PATH}:${HOME}/.bin"
338             paths link = <<'FOO'
339             ${LD_LIBARRAY_PATH}:${HOME}/lib
340             FOO
341            
342             Variables may also be set by parsing command line arguments.
343            
344             myapp -verbose -site kfs -file f1 -file f2
345            
346             AppConfig provides a simple method (args()) for parsing command line
347             arguments. A second method (getopt()) allows more complex argument
348             processing by delegation to Johan Vroman's Getopt::Long module.
349            
350             AppConfig also allows variables to be set by parameters passed to a
351             CGI script via the URL (GET method).
352            
353             http://www.nowhere.com/cgi-bin/myapp?verbose&site=kfs
354            
355             =head1 PREREQUISITES
356            
357             AppConfig requires Perl 5.005 or later.
358            
359             The L<Getopt::Long> and L<Test::More> modules should be installed.
360             If you are using a recent version of Perl (e.g. 5.8.0) then these
361             should already be installed.
362            
363             =head1 OBTAINING AND INSTALLING THE AppConfig MODULE BUNDLE
364            
365             The AppConfig module bundle is available from CPAN. As the 'perlmod'
366             manual page explains:
367            
368             CPAN stands for the Comprehensive Perl Archive Network.
369             This is a globally replicated collection of all known Perl
370             materials, including hundreds of unbundled modules.
371            
372             [...]
373            
374             For an up-to-date listing of CPAN sites, see
375             http://www.perl.com/perl/ or ftp://ftp.perl.com/perl/ .
376            
377             Within the CPAN archive, AppConfig is in the category:
378            
379             12) Option, Argument, Parameter and Configuration File Processing
380            
381             The module is available in the following directories:
382            
383             /modules/by-module/AppConfig/AppConfig-<version>.tar.gz
384             /authors/id/ABW/AppConfig-<version>.tar.gz
385            
386             AppConfig is distributed as a single gzipped tar archive file:
387            
388             AppConfig-<version>.tar.gz
389            
390             Note that "<version>" represents the current AppConfig version
391             number, of the form "n.nn", e.g. "3.14". See the REVISION section
392             below to determine the current version number for AppConfig.
393            
394             Unpack the archive to create a AppConfig installation directory:
395            
396             gunzip AppConfig-<version>.tar.gz
397             tar xvf AppConfig-<version>.tar
398            
399             'cd' into that directory, make, test and install the modules:
400            
401             cd AppConfig-<version>
402             perl Makefile.PL
403             make
404             make test
405             make install
406            
407             The 't' sub-directory contains a number of test scripts that are run when
408             a 'make test' is run.
409            
410             The 'make install' will install the module on your system. You may need
411             administrator privileges to perform this task. If you install the module
412             in a local directory (for example, by executing "perl Makefile.PL
413             LIB=~/lib" in the above - see C<perldoc MakeMaker> for full details), you
414             will need to ensure that the PERL5LIB environment variable is set to
415             include the location, or add a line to your scripts explicitly naming the
416             library location:
417            
418             use lib '/local/path/to/lib';
419            
420             The 'examples' sub-directory contains some simple examples of using the
421             AppConfig modules.
422            
423             =head1 DESCRIPTION
424            
425             =head2 USING THE AppConfig MODULE
426            
427             To import and use the L<AppConfig> module the following line should
428             appear in your Perl script:
429            
430             use AppConfig;
431            
432             To import constants defined by the AppConfig module, specify the name of
433             one or more of the constant or tag sets as parameters to C<use>:
434            
435             use AppConfig qw(:expand :argcount);
436            
437             See L<CONSTANT DEFINITIONS> below for more information on the constant
438             tagsets defined by AppConfig.
439            
440             AppConfig is implemented using object-oriented methods. A
441             new AppConfig object is created and initialised using the
442             new() method. This returns a reference to a new AppConfig
443             object.
444            
445             my $config = AppConfig->new();
446            
447             This will create and return a reference to a new AppConfig object.
448            
449             In doing so, the AppConfig object also creates an internal reference
450             to an AppConfig::State object in which to store variable state. All
451             arguments passed into the AppConfig constructor are passed directly
452             to the AppConfig::State constructor.
453            
454             The first (optional) parameter may be a reference to a hash array
455             containing configuration information.
456            
457             my $config = AppConfig->new( {
458             CASE => 1,
459             ERROR => \&my_error,
460             GLOBAL => {
461             DEFAULT => "<unset>",
462             ARGCOUNT => ARGCOUNT_ONE,
463             },
464             } );
465            
466             See L<AppConfig::State> for full details of the configuration options
467             available. These are, in brief:
468            
469             =over 4
470            
471             =item CASE
472            
473             Used to set case sensitivity for variable names (default: off).
474            
475             =item CREATE
476            
477             Used to indicate that undefined variables should be created automatically
478             (default: off).
479            
480             =item GLOBAL
481            
482             Reference to a hash array of global values used by default when defining
483             variables. Valid global values are DEFAULT, ARGCOUNT, EXPAND, VALIDATE
484             and ACTION.
485            
486             =item PEDANTIC
487            
488             Used to indicate that command line and configuration file parsing routines
489             should return immediately on encountering an error.
490            
491             =item ERROR
492            
493             Used to provide a error handling routine. Arguments as per printf().
494            
495             =back
496            
497             Subsequent parameters may be variable definitions. These are passed
498             to the define() method, described below in L<DEFINING VARIABLES>.
499            
500             my $config = AppConfig->new("foo", "bar", "baz");
501             my $config = AppConfig->new( { CASE => 1 }, qw(foo bar baz) );
502            
503             Note that any unresolved method calls to AppConfig are automatically
504             delegated to the AppConfig::State object. In practice, it means that
505             it is possible to treat the AppConfig object as if it were an
506             AppConfig::State object:
507            
508             # create AppConfig
509             my $config = AppConfig->new('foo', 'bar');
510            
511             # methods get passed through to internal AppConfig::State
512             $config->foo(100);
513             $config->set('bar', 200);
514             $config->define('baz');
515             $config->baz(300);
516            
517             =head2 DEFINING VARIABLES
518            
519             The C<define()> method (delegated to AppConfig::State) is used to
520             pre-declare a variable and specify its configuration.
521            
522             $config->define("foo");
523            
524             Variables may also be defined directly from the AppConfig new()
525             constructor.
526            
527             my $config = AppConfig->new("foo");
528            
529             In both simple examples above, a new variable called "foo" is defined. A
530             reference to a hash array may also be passed to specify configuration
531             information for the variable:
532            
533             $config->define("foo", {
534             DEFAULT => 99,
535             ALIAS => 'metavar1',
536             });
537            
538             Configuration items specified in the GLOBAL option to the module
539             constructor are applied by default when variables are created. e.g.
540            
541             my $config = AppConfig->new( {
542             GLOBAL => {
543             DEFAULT => "<undef>",
544             ARGCOUNT => ARGCOUNT_ONE,
545             }
546             } );
547            
548             $config->define("foo");
549             $config->define("bar", { ARGCOUNT => ARGCOUNT_NONE } );
550            
551             is equivalent to:
552            
553             my $config = AppConfig->new();
554            
555             $config->define( "foo", {
556             DEFAULT => "<undef>",
557             ARGCOUNT => ARGCOUNT_ONE,
558             } );
559            
560             $config->define( "bar",
561             DEFAULT => "<undef>",
562             ARGCOUNT => ARGCOUNT_NONE,
563             } );
564            
565             Multiple variables may be defined in the same call to define().
566             Configuration hashes for variables can be omitted.
567            
568             $config->define("foo", "bar" => { ALIAS = "boozer" }, "baz");
569            
570             See L<AppConfig::State> for full details of the configuration options
571             available when defining variables. These are, in brief:
572            
573             =over
574            
575             =item DEFAULT
576            
577             The default value for the variable (default: undef).
578            
579             =item ALIAS
580            
581             One or more (list reference or "list|like|this") alternative names for the
582             variable.
583            
584             =item ARGCOUNT
585            
586             Specifies the number and type of arguments that the variable expects.
587             Constants in C<:expand> tag set define ARGCOUNT_NONE - simple on/off flag
588             (default), ARGCOUNT_ONE - single value, ARGCOUNT_LIST - multiple values
589             accessed via list reference, ARGCOUNT_HASH - hash table, "key=value",
590             accessed via hash reference.
591            
592             =item ARGS
593            
594             Used to provide an argument specification string to pass to Getopt::Long
595             via AppConfig::Getopt. E.g. "=i", ":s", "=s@". This can also be used to
596             implicitly set the ARGCOUNT value (C</^!/> = ARGCOUNT_NONE, C</@/> =
597             ARGCOUNT_LIST, C</%/> = ARGCOUNT_HASH, C</[=:].*/> = ARGCOUNT_ONE)
598            
599             =item EXPAND
600            
601             Specifies which variable expansion policies should be used when parsing
602             configuration files. Constants in C<:expand> tag set define EXPAND_NONE
603             - no expansion (default), EXPAND_VAR - expand C<$var> or C<$(var)> as
604             other AppConfig variables, EXPAND_UID - expand C<~uid> as user's home
605             directory, EXPAND_ENV - expand C<${var}> as environment variable,
606             EXPAND_ALL - do all expansions. May be logically or'd.
607            
608             =item VALIDATE
609            
610             Regex which the intended variable value should match or code reference
611             which returns 1 to indicate successful validaton (variable may now be set).
612            
613             =item ACTION
614            
615             Code reference to be called whenever variable value changes.
616            
617             =back
618            
619             =head2 COMPACT FORMAT DEFINITION
620            
621             Variables can be specified using a compact format. This is identical to
622             the specification format of Getopt::Long and is of the form:
623            
624             "name|alias|alias<argopts>"
625            
626             The first element indicates the variable name and subsequent ALIAS
627             values may be added, each separated by a vertical bar '|'.
628            
629             The E<lt>argoptsE<gt> element indicates the ARGCOUNT value and may be one of
630             the following;
631            
632             ! ARGCOUNT_NONE
633             =s ARGCOUNT_ONE
634             =s@ ARGCOUNT_LIST
635             =s% ARGCOUNT_HASH
636            
637             Additional constructs supported by Getopt::Long may be specified instead
638             of the "=s" element (e.g. "=f"). The entire E<lt>argoptsE<gt> element
639             is stored in the ARGS parameter for the variable and is passed intact to
640             Getopt::Long when the getopt() method is called.
641            
642             The following examples demonstrate use of the comapct format, with their
643             equivalent full specifications:
644            
645             $config->define("foo|bar|baz!");
646            
647             $config->define(
648             "foo" => {
649             ALIAS => "bar|baz",
650             ARGCOUNT => ARGCOUNT_NONE,
651             });
652            
653             $config->define("name=s");
654            
655             $config->define(
656             "name" => {
657             ARGCOUNT => ARGCOUNT_ONE,
658             });
659            
660             $config->define("file|filelist|f=s@");
661            
662             $config->define(
663             "file" => {
664             ALIAS => "filelist|f",
665             ARGCOUNT => ARGCOUNT_LIST,
666             });
667            
668             $config->define("user|u=s%");
669            
670             $config->define(
671             "user" => {
672             ALIAS => "u",
673             ARGCOUNT => ARGCOUNT_HASH,
674             });
675            
676             Additional configuration options may be specified by hash reference, as per
677             normal. The compact definition format will override any configuration
678             values provided for ARGS and ARGCOUNT.
679            
680             $config->define("file|filelist|f=s@", { VALIDATE = \&check_file() } );
681            
682             =head2 READING AND MODIFYING VARIABLE VALUES
683            
684             AppConfig defines two methods (via AppConfig::State) to manipulate variable
685             values
686            
687             set($variable, $value);
688             get($variable);
689            
690             Once defined, variables may be accessed directly as object methods where
691             the method name is the same as the variable name. i.e.
692            
693             $config->set("verbose", 1);
694            
695             is equivalent to
696            
697             $config->verbose(1);
698            
699             Note that AppConfig defines the following methods:
700            
701             new();
702             file();
703             args();
704             getopt();
705            
706             And also, through delegation to AppConfig::State:
707            
708             define()
709             get()
710             set()
711             varlist()
712            
713             If you define a variable with one of the above names, you will not be able
714             to access it directly as an object method. i.e.
715            
716             $config->file();
717            
718             This will call the file() method, instead of returning the value of the
719             'file' variable. You can work around this by explicitly calling get() and
720             set() on a variable whose name conflicts:
721            
722             $config->get('file');
723            
724             or by defining a "safe" alias by which the variable can be accessed:
725            
726             $config->define("file", { ALIAS => "fileopt" });
727             or
728             $config->define("file|fileopt");
729            
730             ...
731             $config->fileopt();
732            
733             Without parameters, the current value of the variable is returned. If
734             a parameter is specified, the variable is set to that value and the
735             result of the set() operation is returned.
736            
737             $config->age(29); # sets 'age' to 29, returns 1 (ok)
738             print $config->age(); # prints "29"
739            
740             The varlist() method can be used to extract a number of variables into
741             a hash array. The first parameter should be a regular expression
742             used for matching against the variable names.
743            
744             my %vars = $config->varlist("^file"); # all "file*" variables
745            
746             A second parameter may be specified (any true value) to indicate that
747             the part of the variable name matching the regex should be removed
748             when copied to the target hash.
749            
750             $config->file_name("/tmp/file");
751             $config->file_path("/foo:/bar:/baz");
752            
753             my %vars = $config->varlist("^file_", 1);
754            
755             # %vars:
756             # name => /tmp/file
757             # path => "/foo:/bar:/baz"
758            
759            
760             =head2 READING CONFIGURATION FILES
761            
762             The AppConfig module provides a streamlined interface for reading
763             configuration files with the AppConfig::File module. The file() method
764             automatically loads the AppConfig::File module and creates an object
765             to process the configuration file or files. Variables stored in the
766             internal AppConfig::State are automatically updated with values specified
767             in the configuration file.
768            
769             $config->file($filename);
770            
771             Multiple files may be passed to file() and should indicate the file name
772             or be a reference to an open file handle or glob.
773            
774             $config->file($filename, $filehandle, \*STDIN, ...);
775            
776             The file may contain blank lines and comments (prefixed by '#') which
777             are ignored. Continutation lines may be marked by ending the line with
778             a '\'.
779            
780             # this is a comment
781             callsign = alpha bravo camel delta echo foxtrot golf hipowls \
782             india juliet kilo llama mike november oscar papa \
783             quebec romeo sierra tango umbrella victor whiskey \
784             x-ray yankee zebra
785            
786             Variables that are simple flags and do not expect an argument (ARGCOUNT =
787             ARGCOUNT_NONE) can be specified without any value. They will be set with
788             the value 1, with any value explicitly specified (except "0" and "off")
789             being ignored. The variable may also be specified with a "no" prefix to
790             implicitly set the variable to 0.
791            
792             verbose # on (1)
793             verbose = 1 # on (1)
794             verbose = 0 # off (0)
795             verbose off # off (0)
796             verbose on # on (1)
797             verbose mumble # on (1)
798             noverbose # off (0)
799            
800             Variables that expect an argument (ARGCOUNT = ARGCOUNT_ONE) will be set to
801             whatever follows the variable name, up to the end of the current line
802             (including any continuation lines). An optional equals sign may be inserted
803             between the variable and value for clarity.
804            
805             room = /home/kitchen
806             room /home/bedroom
807            
808             Each subsequent re-definition of the variable value overwrites the previous
809             value.
810            
811             print $config->room(); # prints "/home/bedroom"
812            
813             Variables may be defined to accept multiple values (ARGCOUNT = ARGCOUNT_LIST).
814             Each subsequent definition of the variable adds the value to the list of
815             previously set values for the variable.
816            
817             drink = coffee
818             drink = tea
819            
820             A reference to a list of values is returned when the variable is requested.
821            
822             my $beverages = $config->drinks();
823             print join(", ", @$beverages); # prints "coffee, tea"
824            
825             Variables may also be defined as hash lists (ARGCOUNT = ARGCOUNT_HASH).
826             Each subsequent definition creates a new key and value in the hash array.
827            
828             alias l="ls -CF"
829             alias e="emacs"
830            
831             A reference to the hash is returned when the variable is requested.
832            
833             my $aliases = $config->alias();
834             foreach my $k (keys %$aliases) {
835             print "$k => $aliases->{ $k }\n";
836             }
837            
838             The '-' prefix can be used to reset a variable to its default value and
839             the '+' prefix can be used to set it to 1
840            
841             -verbose
842             +debug
843            
844             =head2 VARIABLE EXPANSION
845            
846             Variable values may contain references to other AppConfig variables,
847             environment variables and/or users' home directories. These will be
848             expanded depending on the EXPAND value for each variable or the GLOBAL
849             EXPAND value.
850            
851             Three different expansion types may be applied:
852            
853             bin = ~/bin # expand '~' to home dir if EXPAND_UID
854             tmp = ~abw/tmp # as above, but home dir for user 'abw'
855            
856             perl = $bin/perl # expand value of 'bin' variable if EXPAND_VAR
857             ripl = $(bin)/ripl # as above with explicit parens
858            
859             home = ${HOME} # expand HOME environment var if EXPAND_ENV
860            
861             See L<AppConfig::State> for more information on expanding variable values.
862            
863             The configuration files may have variables arranged in blocks. A block
864             header, consisting of the block name in square brackets, introduces a
865             configuration block. The block name and an underscore are then prefixed
866             to the names of all variables subsequently referenced in that block. The
867             block continues until the next block definition or to the end of the current
868             file.
869            
870             [block1]
871             foo = 10 # block1_foo = 10
872            
873             [block2]
874             foo = 20 # block2_foo = 20
875            
876             =head2 PARSING COMMAND LINE OPTIONS
877            
878             There are two methods for processing command line options. The first,
879             args(), is a small and efficient implementation which offers basic
880             functionality. The second, getopt(), offers a more powerful and complete
881             facility by delegating the task to Johan Vroman's Getopt::Long module.
882             The trade-off between args() and getopt() is essentially one of speed/size
883             against flexibility. Use as appropriate. Both implement on-demand loading
884             of modules and incur no overhead until used.
885            
886             The args() method is used to parse simple command line options. It
887             automatically loads the AppConfig::Args module and creates an object
888             to process the command line arguments. Variables stored in the internal
889             AppConfig::State are automatically updated with values specified in the
890             arguments.
891            
892             The method should be passed a reference to a list of arguments to parse.
893             The @ARGV array is used if args() is called without parameters.
894            
895             $config->args(\@myargs);
896             $config->args(); # uses @ARGV
897            
898             Arguments are read and shifted from the array until the first is
899             encountered that is not prefixed by '-' or '--'. At that point, the
900             method returns 1 to indicate success, leaving any unprocessed arguments
901             remaining in the list.
902            
903             Each argument should be the name or alias of a variable prefixed by
904             '-' or '--'. Arguments that are not prefixed as such (and are not an
905             additional parameter to a previous argument) will cause a warning to be
906             raised. If the PEDANTIC option is set, the method will return 0
907             immediately. With PEDANTIC unset (default), the method will continue
908             to parse the rest of the arguments, returning 0 when done.
909            
910             If the variable is a simple flag (ARGCOUNT = ARGCOUNT_NONE)
911             then it is set to the value 1. The variable may be prefixed by "no" to
912             set its value to 0.
913            
914             myprog -verbose --debug -notaste # $config->verbose(1)
915             # $config->debug(1)
916             # $config->taste(0)
917            
918             Variables that expect an additional argument (ARGCOUNT != 0) will be set to
919             the value of the argument following it.
920            
921             myprog -f /tmp/myfile # $config->file('/tmp/file');
922            
923             Variables that expect multiple values (ARGCOUNT = ARGCOUNT_LIST or
924             ARGCOUNT_HASH) will have sucessive values added each time the option
925             is encountered.
926            
927             myprog -file /tmp/foo -file /tmp/bar # $config->file('/tmp/foo')
928             # $config->file('/tmp/bar')
929            
930             # file => [ '/tmp/foo', '/tmp/bar' ]
931            
932             myprog -door "jim=Jim Morrison" -door "ray=Ray Manzarek"
933             # $config->door("jim=Jim Morrison");
934             # $config->door("ray=Ray Manzarek");
935            
936             # door => { 'jim' => 'Jim Morrison', 'ray' => 'Ray Manzarek' }
937            
938             See L<AppConfig::Args> for further details on parsing command line
939             arguments.
940            
941             The getopt() method provides a way to use the power and flexibility of
942             the Getopt::Long module to parse command line arguments and have the
943             internal values of the AppConfig object updates automatically.
944            
945             The first (non-list reference) parameters may contain a number of
946             configuration string to pass to Getopt::Long::Configure. A reference
947             to a list of arguments may additionally be passed or @ARGV is used by
948             default.
949            
950             $config->getopt(); # uses @ARGV
951             $config->getopt(\@myargs);
952             $config->getopt(qw(auto_abbrev debug)); # uses @ARGV
953             $config->getopt(qw(debug), \@myargs);
954            
955             See Getopt::Long for details of the configuration options available.
956            
957             The getopt() method constructs a specification string for each internal
958             variable and then initialises Getopt::Long with these values. The
959             specification string is constructed from the name, any aliases (delimited
960             by a vertical bar '|') and the value of the ARGS parameter.
961            
962             $config->define("foo", {
963             ARGS => "=i",
964             ALIAS => "bar|baz",
965             });
966            
967             # Getopt::Long specification: "foo|bar|baz=i"
968            
969             Errors and warning generated by the Getopt::Long module are trapped and
970             handled by the AppConfig error handler. This may be a user-defined
971             routine installed with the ERROR configuration option.
972            
973             Please note that the AppConfig::Getopt interface is still experimental
974             and may not be 100% operational. This is almost undoubtedly due to
975             problems in AppConfig::Getopt rather than Getopt::Long.
976            
977             =head2 PARSING CGI PARAMETERS
978            
979             The cgi() method provides an interface to the AppConfig::CGI module
980             for updating variable values based on the parameters appended to the
981             URL for a CGI script. This is commonly known as the CGI
982             "GET" method. The CGI "POST" method is currently not supported.
983            
984             Parameter definitions are separated from the CGI script name by a
985             question mark and from each other by ampersands. Where variables
986             have specific values, these are appended to the variable with an
987             equals sign:
988            
989             http://www.here.com/cgi-bin/myscript?foo=bar&baz=qux&verbose
990            
991             # $config->foo('bar');
992             # $config->baz('qux');
993             # $config->verbose(1);
994            
995             Certain values specified in a URL must be escaped in the appropriate
996             manner (see CGI specifications at http://www.w3c.org/ for full details).
997             The AppConfig::CGI module automatically unescapes the CGI query string
998             to restore the parameters to their intended values.
999            
1000             http://where.com/mycgi?title=%22The+Wrong+Trousers%22
1001            
1002             # $config->title('"The Wrong Trousers"');
1003            
1004             Please be considerate of the security implications of providing writeable
1005             access to script variables via CGI.
1006            
1007             http://rebel.alliance.com/cgi-bin/...
1008             .../send_report?file=%2Fetc%2Fpasswd&email=darth%40empire.com
1009            
1010             To avoid any accidental or malicious changing of "private" variables,
1011             define only the "public" variables before calling the cgi() (or any
1012             other) method. Further variables can subequently be defined which
1013             can not be influenced by the CGI parameters.
1014            
1015             $config->define('verbose', 'debug')
1016             $config->cgi(); # can only set verbose and debug
1017            
1018             $config->define('email', 'file');
1019             $config->file($cfgfile); # can set verbose, debug, email + file
1020            
1021            
1022             =head1 CONSTANT DEFINITIONS
1023            
1024             A number of constants are defined by the AppConfig module. These may be
1025             accessed directly (e.g. AppConfig::EXPAND_VARS) or by first importing them
1026             into the caller's package. Constants are imported by specifying their
1027             names as arguments to C<use AppConfig> or by importing a set of constants
1028             identified by its "tag set" name.
1029            
1030             use AppConfig qw(ARGCOUNT_NONE ARGCOUNT_ONE);
1031            
1032             use AppConfig qw(:argcount);
1033            
1034             The following tag sets are defined:
1035            
1036             =over 4
1037            
1038             =item :expand
1039            
1040             The ':expand' tagset defines the following constants:
1041            
1042             EXPAND_NONE
1043             EXPAND_VAR
1044             EXPAND_UID
1045             EXPAND_ENV
1046             EXPAND_ALL # EXPAND_VAR | EXPAND_UID | EXPAND_ENV
1047             EXPAND_WARN
1048            
1049             See AppConfig::File for full details of the use of these constants.
1050            
1051             =item :argcount
1052            
1053             The ':argcount' tagset defines the following constants:
1054            
1055             ARGCOUNT_NONE
1056             ARGCOUNT_ONE
1057             ARGCOUNT_LIST
1058             ARGCOUNT_HASH
1059            
1060             See AppConfig::State for full details of the use of these constants.
1061            
1062             =back
1063            
1064             =head1 AUTHOR
1065            
1066             Andy Wardley, E<lt>abw@wardley.orgE<gt>
1067            
1068             With contributions from Dave Viner, Ijon Tichy, Axel Gerstmair and
1069             many others whose names have been lost to the sands of time (reminders
1070             welcome).
1071            
1072             =head1 REVISION
1073            
1074             Revision $Revision: 1.7 $ distributed as part of AppConfig 1.56.
1075            
1076             =head1 COPYRIGHT
1077            
1078             Copyright (C) 1997-2004 Andy Wardley. All Rights Reserved.
1079            
1080             Copyright (C) 1997,1998 Canon Research Centre Europe Ltd.
1081            
1082             This module is free software; you can redistribute it and/or modify it
1083             under the same terms as Perl itself.
1084            
1085             =head1 SEE ALSO
1086            
1087             AppConfig::State, AppConfig::File, AppConfig::Args, AppConfig::Getopt,
1088             AppConfig::CGI, Getopt::Long
1089            
1090             =cut
1091