1AppConfig(3)          User Contributed Perl Documentation         AppConfig(3)
2
3
4

NAME

6       AppConfig - Perl5 module for reading configuration files and parsing
7       command line arguments.
8

SYNOPSIS

10           use AppConfig;
11
12           # create a new AppConfig object
13           my $config = AppConfig->new( \%cfg );
14
15           # define a new variable
16           $config->define( $varname => \%varopts );
17
18           # create/define combined
19           my $config = AppConfig->new( \%cfg,
20               $varname => \%varopts,
21               $varname => \%varopts,
22               ...
23           );
24
25           # set/get the value
26           $config->set( $varname, $value );
27           $config->get($varname);
28
29           # shortcut form
30           $config->varname($value);
31           $config->varname;
32
33           # read configuration file
34           $config->file($file);
35
36           # parse command line options
37           $config->args(\@args);      # default to \@ARGV
38
39           # advanced command line options with Getopt::Long
40           $config->getopt(\@args);    # default to \@ARGV
41
42           # parse CGI parameters (GET method)
43           $config->cgi($query);       # default to $ENV{ QUERY_STRING }
44

OVERVIEW

46       AppConfig is a Perl5 module for managing application configuration
47       information.  It maintains the state of any number of variables and
48       provides methods for parsing configuration files, command line argu‐
49       ments and CGI script parameters.
50
51       Variables values may be set via configuration files.  Variables may be
52       flags (On/Off), take a single value, or take multiple values stored as
53       a list or hash.  The number of arguments a variable expects is deter‐
54       mined by its configuration when defined.
55
56           # flags
57           verbose
58           nohelp
59           debug = On
60
61           # single value
62           home  = /home/abw/
63
64           # multiple list value
65           file = /tmp/file1
66           file = /tmp/file2
67
68           # multiple hash value
69           book  camel = Programming Perl
70           book  llama = Learning Perl
71
72       The '-' prefix can be used to reset a variable to its default value and
73       the '+' prefix can be used to set it to 1
74
75           -verbose
76           +debug
77
78       Variable, environment variable and tilde (home directory) expansions
79       can be applied (selectively, if necessary) to the values read from con‐
80       figuration files:
81
82           home = ~                    # home directory
83           nntp = ${NNTPSERVER}        # environment variable
84           html = $home/html           # internal variables
85           img  = $html/images
86
87       Configuration files may be arranged in blocks as per the style of Win32
88       "INI" files.
89
90           [file]
91           site = kfs
92           src  = ~/websrc/docs/$site
93           lib  = ~/websrc/lib
94           dest = ~/public_html/$site
95
96           [page]
97           header = $lib/header
98           footer = $lib/footer
99
100       You can also use Perl's "heredoc" syntax to define a large block of
101       text in a configuration file.
102
103           multiline = <<FOOBAR
104           line 1
105           line 2
106           FOOBAR
107
108           paths  exe  = "${PATH}:${HOME}/.bin"
109           paths  link = <<'FOO'
110           ${LD_LIBARRAY_PATH}:${HOME}/lib
111           FOO
112
113       Variables may also be set by parsing command line arguments.
114
115           myapp -verbose -site kfs -file f1 -file f2
116
117       AppConfig provides a simple method (args()) for parsing command line
118       arguments.  A second method (getopt()) allows more complex argument
119       processing by delegation to Johan Vroman's Getopt::Long module.
120
121       AppConfig also allows variables to be set by parameters passed to a CGI
122       script via the URL (GET method).
123
124           http://www.nowhere.com/cgi-bin/myapp?verbose&site=kfs
125

PREREQUISITES

127       AppConfig requires Perl 5.005 or later.
128
129       The Getopt::Long and Test::More modules should be installed.  If you
130       are using a recent version of Perl (e.g. 5.8.0) then these should
131       already be installed.
132

OBTAINING AND INSTALLING THE AppConfig MODULE BUNDLE

134       The AppConfig module bundle is available from CPAN.  As the 'perlmod'
135       manual page explains:
136
137           CPAN stands for the Comprehensive Perl Archive Network.
138           This is a globally replicated collection of all known Perl
139           materials, including hundreds of unbundled modules.
140
141           [...]
142
143           For an up-to-date listing of CPAN sites, see
144           http://www.perl.com/perl/ or ftp://ftp.perl.com/perl/ .
145
146       Within the CPAN archive, AppConfig is in the category:
147
148           12) Option, Argument, Parameter and Configuration File Processing
149
150       The module is available in the following directories:
151
152           /modules/by-module/AppConfig/AppConfig-<version>.tar.gz
153           /authors/id/ABW/AppConfig-<version>.tar.gz
154
155       AppConfig is distributed as a single gzipped tar archive file:
156
157           AppConfig-<version>.tar.gz
158
159       Note that "<version>" represents the current AppConfig version number,
160       of the form "n.nn", e.g. "3.14".  See the REVISION section below to
161       determine the current version number for AppConfig.
162
163       Unpack the archive to create a AppConfig installation directory:
164
165           gunzip AppConfig-<version>.tar.gz
166           tar xvf AppConfig-<version>.tar
167
168       'cd' into that directory, make, test and install the modules:
169
170           cd AppConfig-<version>
171           perl Makefile.PL
172           make
173           make test
174           make install
175
176       The 't' sub-directory contains a number of test scripts that are run
177       when a 'make test' is run.
178
179       The 'make install' will install the module on your system.  You may
180       need administrator privileges to perform this task.  If you install the
181       module in a local directory (for example, by executing "perl Make‐
182       file.PL LIB=~/lib" in the above - see "perldoc MakeMaker" for full
183       details), you will need to ensure that the PERL5LIB environment vari‐
184       able is set to include the location, or add a line to your scripts
185       explicitly naming the library location:
186
187           use lib '/local/path/to/lib';
188
189       The 'examples' sub-directory contains some simple examples of using the
190       AppConfig modules.
191

DESCRIPTION

193       USING THE AppConfig MODULE
194
195       To import and use the AppConfig module the following line should appear
196       in your Perl script:
197
198            use AppConfig;
199
200       To import constants defined by the AppConfig module, specify the name
201       of one or more of the constant or tag sets as parameters to "use":
202
203           use AppConfig qw(:expand :argcount);
204
205       See "CONSTANT DEFINITIONS" below for more information on the constant
206       tagsets defined by AppConfig.
207
208       AppConfig is implemented using object-oriented methods.  A new AppCon‐
209       fig object is created and initialised using the new() method.  This
210       returns a reference to a new AppConfig object.
211
212           my $config = AppConfig->new();
213
214       This will create and return a reference to a new AppConfig object.
215
216       In doing so, the AppConfig object also creates an internal reference to
217       an AppConfig::State object in which to store variable state.  All argu‐
218       ments passed into the AppConfig constructor are passed directly to the
219       AppConfig::State constructor.
220
221       The first (optional) parameter may be a reference to a hash array con‐
222       taining configuration information.
223
224           my $config = AppConfig->new( {
225                   CASE   => 1,
226                   ERROR  => \&my_error,
227                   GLOBAL => {
228                           DEFAULT  => "<unset>",
229                           ARGCOUNT => ARGCOUNT_ONE,
230                       },
231               } );
232
233       See AppConfig::State for full details of the configuration options
234       available.  These are, in brief:
235
236       CASE
237           Used to set case sensitivity for variable names (default: off).
238
239       CREATE
240           Used to indicate that undefined variables should be created auto‐
241           matically (default: off).
242
243       GLOBAL
244           Reference to a hash array of global values used by default when
245           defining variables.  Valid global values are DEFAULT, ARGCOUNT,
246           EXPAND, VALIDATE and ACTION.
247
248       PEDANTIC
249           Used to indicate that command line and configuration file parsing
250           routines should return immediately on encountering an error.
251
252       ERROR
253           Used to provide a error handling routine.  Arguments as per
254           printf().
255
256       Subsequent parameters may be variable definitions.  These are passed to
257       the define() method, described below in "DEFINING VARIABLES".
258
259           my $config = AppConfig->new("foo", "bar", "baz");
260           my $config = AppConfig->new( { CASE => 1 }, qw(foo bar baz) );
261
262       Note that any unresolved method calls to AppConfig are automatically
263       delegated to the AppConfig::State object.  In practice, it means that
264       it is possible to treat the AppConfig object as if it were an AppCon‐
265       fig::State object:
266
267           # create AppConfig
268           my $config = AppConfig->new('foo', 'bar');
269
270           # methods get passed through to internal AppConfig::State
271           $config->foo(100);
272           $config->set('bar', 200);
273           $config->define('baz');
274           $config->baz(300);
275
276       DEFINING VARIABLES
277
278       The "define()" method (delegated to AppConfig::State) is used to pre-
279       declare a variable and specify its configuration.
280
281           $config->define("foo");
282
283       Variables may also be defined directly from the AppConfig new() con‐
284       structor.
285
286           my $config = AppConfig->new("foo");
287
288       In both simple examples above, a new variable called "foo" is defined.
289       A reference to a hash array may also be passed to specify configuration
290       information for the variable:
291
292           $config->define("foo", {
293                   DEFAULT   => 99,
294                   ALIAS     => 'metavar1',
295               });
296
297       Configuration items specified in the GLOBAL option to the module con‐
298       structor are applied by default when variables are created.  e.g.
299
300           my $config = AppConfig->new( {
301               GLOBAL => {
302                   DEFAULT  => "<undef>",
303                   ARGCOUNT => ARGCOUNT_ONE,
304               }
305           } );
306
307           $config->define("foo");
308           $config->define("bar", { ARGCOUNT => ARGCOUNT_NONE } );
309
310       is equivalent to:
311
312           my $config = AppConfig->new();
313
314           $config->define( "foo", {
315               DEFAULT  => "<undef>",
316               ARGCOUNT => ARGCOUNT_ONE,
317           } );
318
319           $config->define( "bar",
320               DEFAULT  => "<undef>",
321               ARGCOUNT => ARGCOUNT_NONE,
322           } );
323
324       Multiple variables may be defined in the same call to define().  Con‐
325       figuration hashes for variables can be omitted.
326
327           $config->define("foo", "bar" => { ALIAS = "boozer" }, "baz");
328
329       See AppConfig::State for full details of the configuration options
330       available when defining variables.  These are, in brief:
331
332       DEFAULT
333           The default value for the variable (default: undef).
334
335       ALIAS
336           One or more (list reference or "list⎪like⎪this") alternative names
337           for the variable.
338
339       ARGCOUNT
340           Specifies the number and type of arguments that the variable
341           expects.  Constants in ":expand" tag set define ARGCOUNT_NONE -
342           simple on/off flag (default), ARGCOUNT_ONE - single value,
343           ARGCOUNT_LIST - multiple values accessed via list reference,
344           ARGCOUNT_HASH - hash table, "key=value", accessed via hash refer‐
345           ence.
346
347       ARGS
348           Used to provide an argument specification string to pass to
349           Getopt::Long via AppConfig::Getopt.  E.g. "=i", ":s", "=s@".  This
350           can also be used to implicitly set the ARGCOUNT value ("/^!/" =
351           ARGCOUNT_NONE, "/@/" = ARGCOUNT_LIST, "/%/" = ARGCOUNT_HASH,
352           "/[=:].*/" = ARGCOUNT_ONE)
353
354       EXPAND
355           Specifies which variable expansion policies should be used when
356           parsing configuration files.  Constants in ":expand" tag set define
357           EXPAND_NONE - no expansion (default), EXPAND_VAR - expand $var or
358           "$(var)" as other AppConfig variables, EXPAND_UID - expand "~uid"
359           as user's home directory, EXPAND_ENV - expand "${var}" as environ‐
360           ment variable, EXPAND_ALL - do all expansions.  May be logically
361           or'd.
362
363       VALIDATE
364           Regex which the intended variable value should match or code refer‐
365           ence which returns 1 to indicate successful validaton (variable may
366           now be set).
367
368       ACTION
369           Code reference to be called whenever variable value changes.
370
371       COMPACT FORMAT DEFINITION
372
373       Variables can be specified using a compact format.  This is identical
374       to the specification format of Getopt::Long and is of the form:
375
376           "name⎪alias⎪alias<argopts>"
377
378       The first element indicates the variable name and subsequent ALIAS val‐
379       ues may be added, each separated by a vertical bar '⎪'.
380
381       The <argopts> element indicates the ARGCOUNT value and may be one of
382       the following;
383
384           !                  ARGCOUNT_NONE
385           =s                 ARGCOUNT_ONE
386           =s@                ARGCOUNT_LIST
387           =s%                ARGCOUNT_HASH
388
389       Additional constructs supported by Getopt::Long may be specified
390       instead of the "=s" element (e.g. "=f").  The entire <argopts> element
391       is stored in the ARGS parameter for the variable and is passed intact
392       to Getopt::Long when the getopt() method is called.
393
394       The following examples demonstrate use of the comapct format, with
395       their equivalent full specifications:
396
397           $config->define("foo⎪bar⎪baz!");
398
399           $config->define(
400                   "foo" => {
401                       ALIAS    => "bar⎪baz",
402                       ARGCOUNT => ARGCOUNT_NONE,
403                   });
404
405           $config->define("name=s");
406
407           $config->define(
408                   "name" => {
409                       ARGCOUNT => ARGCOUNT_ONE,
410                   });
411
412           $config->define("file⎪filelist⎪f=s@");
413
414           $config->define(
415                   "file" => {
416                       ALIAS    => "filelist⎪f",
417                       ARGCOUNT => ARGCOUNT_LIST,
418                   });
419
420           $config->define("user⎪u=s%");
421
422           $config->define(
423                   "user" => {
424                       ALIAS    => "u",
425                       ARGCOUNT => ARGCOUNT_HASH,
426                   });
427
428       Additional configuration options may be specified by hash reference, as
429       per normal.  The compact definition format will override any configura‐
430       tion values provided for ARGS and ARGCOUNT.
431
432           $config->define("file⎪filelist⎪f=s@", { VALIDATE = \&check_file() } );
433
434       READING AND MODIFYING VARIABLE VALUES
435
436       AppConfig defines two methods (via AppConfig::State) to manipulate
437       variable values
438
439           set($variable, $value);
440           get($variable);
441
442       Once defined, variables may be accessed directly as object methods
443       where the method name is the same as the variable name.  i.e.
444
445           $config->set("verbose", 1);
446
447       is equivalent to
448
449           $config->verbose(1);
450
451       Note that AppConfig defines the following methods:
452
453           new();
454           file();
455           args();
456           getopt();
457
458       And also, through delegation to AppConfig::State:
459
460           define()
461           get()
462           set()
463           varlist()
464
465       If you define a variable with one of the above names, you will not be
466       able to access it directly as an object method.  i.e.
467
468           $config->file();
469
470       This will call the file() method, instead of returning the value of the
471       'file' variable.  You can work around this by explicitly calling get()
472       and set() on a variable whose name conflicts:
473
474           $config->get('file');
475
476       or by defining a "safe" alias by which the variable can be accessed:
477
478           $config->define("file", { ALIAS => "fileopt" });
479       or
480           $config->define("file⎪fileopt");
481
482           ...
483           $config->fileopt();
484
485       Without parameters, the current value of the variable is returned.  If
486       a parameter is specified, the variable is set to that value and the
487       result of the set() operation is returned.
488
489           $config->age(29);        # sets 'age' to 29, returns 1 (ok)
490           print $config->age();    # prints "29"
491
492       The varlist() method can be used to extract a number of variables into
493       a hash array.  The first parameter should be a regular expression used
494       for matching against the variable names.
495
496           my %vars = $config->varlist("^file");   # all "file*" variables
497
498       A second parameter may be specified (any true value) to indicate that
499       the part of the variable name matching the regex should be removed when
500       copied to the target hash.
501
502           $config->file_name("/tmp/file");
503           $config->file_path("/foo:/bar:/baz");
504
505           my %vars = $config->varlist("^file_", 1);
506
507           # %vars:
508           #    name => /tmp/file
509           #    path => "/foo:/bar:/baz"
510
511       READING CONFIGURATION FILES
512
513       The AppConfig module provides a streamlined interface for reading con‐
514       figuration files with the AppConfig::File module.  The file() method
515       automatically loads the AppConfig::File module and creates an object to
516       process the configuration file or files.  Variables stored in the
517       internal AppConfig::State are automatically updated with values speci‐
518       fied in the configuration file.
519
520           $config->file($filename);
521
522       Multiple files may be passed to file() and should indicate the file
523       name or be a reference to an open file handle or glob.
524
525           $config->file($filename, $filehandle, \*STDIN, ...);
526
527       The file may contain blank lines and comments (prefixed by '#') which
528       are ignored.  Continutation lines may be marked by ending the line with
529       a '\'.
530
531           # this is a comment
532           callsign = alpha bravo camel delta echo foxtrot golf hipowls \
533                      india juliet kilo llama mike november oscar papa  \
534                      quebec romeo sierra tango umbrella victor whiskey \
535                      x-ray yankee zebra
536
537       Variables that are simple flags and do not expect an argument (ARGCOUNT
538       = ARGCOUNT_NONE) can be specified without any value.  They will be set
539       with the value 1, with any value explicitly specified (except "0" and
540       "off") being ignored.  The variable may also be specified with a "no"
541       prefix to implicitly set the variable to 0.
542
543           verbose                              # on  (1)
544           verbose = 1                          # on  (1)
545           verbose = 0                          # off (0)
546           verbose off                          # off (0)
547           verbose on                           # on  (1)
548           verbose mumble                       # on  (1)
549           noverbose                            # off (0)
550
551       Variables that expect an argument (ARGCOUNT = ARGCOUNT_ONE) will be set
552       to whatever follows the variable name, up to the end of the current
553       line (including any continuation lines).  An optional equals sign may
554       be inserted between the variable and value for clarity.
555
556           room = /home/kitchen
557           room   /home/bedroom
558
559       Each subsequent re-definition of the variable value overwrites the pre‐
560       vious value.
561
562           print $config->room();               # prints "/home/bedroom"
563
564       Variables may be defined to accept multiple values (ARGCOUNT =
565       ARGCOUNT_LIST).  Each subsequent definition of the variable adds the
566       value to the list of previously set values for the variable.
567
568           drink = coffee
569           drink = tea
570
571       A reference to a list of values is returned when the variable is
572       requested.
573
574           my $beverages = $config->drinks();
575           print join(", ", @$beverages);      # prints "coffee, tea"
576
577       Variables may also be defined as hash lists (ARGCOUNT = ARGCOUNT_HASH).
578       Each subsequent definition creates a new key and value in the hash
579       array.
580
581           alias l="ls -CF"
582           alias e="emacs"
583
584       A reference to the hash is returned when the variable is requested.
585
586           my $aliases = $config->alias();
587           foreach my $k (keys %$aliases) {
588               print "$k => $aliases->{ $k }\n";
589           }
590
591       The '-' prefix can be used to reset a variable to its default value and
592       the '+' prefix can be used to set it to 1
593
594           -verbose
595           +debug
596
597       VARIABLE EXPANSION
598
599       Variable values may contain references to other AppConfig variables,
600       environment variables and/or users' home directories.  These will be
601       expanded depending on the EXPAND value for each variable or the GLOBAL
602       EXPAND value.
603
604       Three different expansion types may be applied:
605
606           bin = ~/bin          # expand '~' to home dir if EXPAND_UID
607           tmp = ~abw/tmp       # as above, but home dir for user 'abw'
608
609           perl = $bin/perl     # expand value of 'bin' variable if EXPAND_VAR
610           ripl = $(bin)/ripl   # as above with explicit parens
611
612           home = ${HOME}       # expand HOME environment var if EXPAND_ENV
613
614       See AppConfig::State for more information on expanding variable values.
615
616       The configuration files may have variables arranged in blocks.  A block
617       header, consisting of the block name in square brackets, introduces a
618       configuration block.  The block name and an underscore are then pre‐
619       fixed to the names of all variables subsequently referenced in that
620       block.  The block continues until the next block definition or to the
621       end of the current file.
622
623           [block1]
624           foo = 10             # block1_foo = 10
625
626           [block2]
627           foo = 20             # block2_foo = 20
628
629       PARSING COMMAND LINE OPTIONS
630
631       There are two methods for processing command line options.  The first,
632       args(), is a small and efficient implementation which offers basic
633       functionality.  The second, getopt(), offers a more powerful and com‐
634       plete facility by delegating the task to Johan Vroman's Getopt::Long
635       module.  The trade-off between args() and getopt() is essentially one
636       of speed/size against flexibility.  Use as appropriate.  Both implement
637       on-demand loading of modules and incur no overhead until used.
638
639       The args() method is used to parse simple command line options.  It
640       automatically loads the AppConfig::Args module and creates an object to
641       process the command line arguments.  Variables stored in the internal
642       AppConfig::State are automatically updated with values specified in the
643       arguments.
644
645       The method should be passed a reference to a list of arguments to
646       parse.  The @ARGV array is used if args() is called without parameters.
647
648           $config->args(\@myargs);
649           $config->args();               # uses @ARGV
650
651       Arguments are read and shifted from the array until the first is
652       encountered that is not prefixed by '-' or '--'.  At that point, the
653       method returns 1 to indicate success, leaving any unprocessed arguments
654       remaining in the list.
655
656       Each argument should be the name or alias of a variable prefixed by '-'
657       or '--'.  Arguments that are not prefixed as such (and are not an addi‐
658       tional parameter to a previous argument) will cause a warning to be
659       raised.  If the PEDANTIC option is set, the method will return 0 imme‐
660       diately.  With PEDANTIC unset (default), the method will continue to
661       parse the rest of the arguments, returning 0 when done.
662
663       If the variable is a simple flag (ARGCOUNT = ARGCOUNT_NONE) then it is
664       set to the value 1.  The variable may be prefixed by "no" to set its
665       value to 0.
666
667           myprog -verbose --debug -notaste     # $config->verbose(1)
668                                                # $config->debug(1)
669                                                # $config->taste(0)
670
671       Variables that expect an additional argument (ARGCOUNT != 0) will be
672       set to the value of the argument following it.
673
674           myprog -f /tmp/myfile                # $config->file('/tmp/file');
675
676       Variables that expect multiple values (ARGCOUNT = ARGCOUNT_LIST or
677       ARGCOUNT_HASH) will have sucessive values added each time the option is
678       encountered.
679
680           myprog -file /tmp/foo -file /tmp/bar # $config->file('/tmp/foo')
681                                                # $config->file('/tmp/bar')
682
683           # file => [ '/tmp/foo', '/tmp/bar' ]
684
685           myprog -door "jim=Jim Morrison" -door "ray=Ray Manzarek"
686                                           # $config->door("jim=Jim Morrison");
687                                           # $config->door("ray=Ray Manzarek");
688
689           # door => { 'jim' => 'Jim Morrison', 'ray' => 'Ray Manzarek' }
690
691       See AppConfig::Args for further details on parsing command line argu‐
692       ments.
693
694       The getopt() method provides a way to use the power and flexibility of
695       the Getopt::Long module to parse command line arguments and have the
696       internal values of the AppConfig object updates automatically.
697
698       The first (non-list reference) parameters may contain a number of con‐
699       figuration string to pass to Getopt::Long::Configure.  A reference to a
700       list of arguments may additionally be passed or @ARGV is used by
701       default.
702
703           $config->getopt();                       # uses @ARGV
704           $config->getopt(\@myargs);
705           $config->getopt(qw(auto_abbrev debug));  # uses @ARGV
706           $config->getopt(qw(debug), \@myargs);
707
708       See Getopt::Long for details of the configuration options available.
709
710       The getopt() method constructs a specification string for each internal
711       variable and then initialises Getopt::Long with these values.  The
712       specification string is constructed from the name, any aliases (delim‐
713       ited by a vertical bar '⎪') and the value of the ARGS parameter.
714
715           $config->define("foo", {
716               ARGS  => "=i",
717               ALIAS => "bar⎪baz",
718           });
719
720           # Getopt::Long specification: "foo⎪bar⎪baz=i"
721
722       Errors and warning generated by the Getopt::Long module are trapped and
723       handled by the AppConfig error handler.  This may be a user-defined
724       routine installed with the ERROR configuration option.
725
726       Please note that the AppConfig::Getopt interface is still experimental
727       and may not be 100% operational.  This is almost undoubtedly due to
728       problems in AppConfig::Getopt rather than Getopt::Long.
729
730       PARSING CGI PARAMETERS
731
732       The cgi() method provides an interface to the AppConfig::CGI module for
733       updating variable values based on the parameters appended to the URL
734       for a CGI script.  This is commonly known as the CGI "GET" method.  The
735       CGI "POST" method is currently not supported.
736
737       Parameter definitions are separated from the CGI script name by a ques‐
738       tion mark and from each other by ampersands.  Where variables have spe‐
739       cific values, these are appended to the variable with an equals sign:
740
741           http://www.here.com/cgi-bin/myscript?foo=bar&baz=qux&verbose
742
743               # $config->foo('bar');
744               # $config->baz('qux');
745               # $config->verbose(1);
746
747       Certain values specified in a URL must be escaped in the appropriate
748       manner (see CGI specifications at http://www.w3c.org/ for full
749       details).  The AppConfig::CGI module automatically unescapes the CGI
750       query string to restore the parameters to their intended values.
751
752           http://where.com/mycgi?title=%22The+Wrong+Trousers%22
753
754           # $config->title('"The Wrong Trousers"');
755
756       Please be considerate of the security implications of providing write‐
757       able access to script variables via CGI.
758
759           http://rebel.alliance.com/cgi-bin/...
760               .../send_report?file=%2Fetc%2Fpasswd&email=darth%40empire.com
761
762       To avoid any accidental or malicious changing of "private" variables,
763       define only the "public" variables before calling the cgi() (or any
764       other) method.  Further variables can subequently be defined which can
765       not be influenced by the CGI parameters.
766
767           $config->define('verbose', 'debug')
768           $config->cgi();             # can only set verbose and debug
769
770           $config->define('email', 'file');
771           $config->file($cfgfile);    # can set verbose, debug, email + file
772

CONSTANT DEFINITIONS

774       A number of constants are defined by the AppConfig module.  These may
775       be accessed directly (e.g. AppConfig::EXPAND_VARS) or by first import‐
776       ing them into the caller's package.  Constants are imported by specify‐
777       ing their names as arguments to "use AppConfig" or by importing a set
778       of constants identified by its "tag set" name.
779
780           use AppConfig qw(ARGCOUNT_NONE ARGCOUNT_ONE);
781
782           use AppConfig qw(:argcount);
783
784       The following tag sets are defined:
785
786       :expand
787           The ':expand' tagset defines the following constants:
788
789               EXPAND_NONE
790               EXPAND_VAR
791               EXPAND_UID
792               EXPAND_ENV
793               EXPAND_ALL       # EXPAND_VAR ⎪ EXPAND_UID ⎪ EXPAND_ENV
794               EXPAND_WARN
795
796           See AppConfig::File for full details of the use of these constants.
797
798       :argcount
799           The ':argcount' tagset defines the following constants:
800
801               ARGCOUNT_NONE
802               ARGCOUNT_ONE
803               ARGCOUNT_LIST
804               ARGCOUNT_HASH
805
806           See AppConfig::State for full details of the use of these con‐
807           stants.
808

AUTHOR

810       Andy Wardley, <abw@wardley.org>
811
812       With contributions from Dave Viner, Ijon Tichy, Axel Gerstmair and many
813       others whose names have been lost to the sands of time (reminders wel‐
814       come).
815

REVISION

817       Revision $Revision: 1.7 $ distributed as part of AppConfig 1.56.
818
820       Copyright (C) 1997-2004 Andy Wardley.  All Rights Reserved.
821
822       Copyright (C) 1997,1998 Canon Research Centre Europe Ltd.
823
824       This module is free software; you can redistribute it and/or modify it
825       under the same terms as Perl itself.
826

SEE ALSO

828       AppConfig::State, AppConfig::File, AppConfig::Args, AppConfig::Getopt,
829       AppConfig::CGI, Getopt::Long
830
831
832
833perl v5.8.8                       2007-01-02                      AppConfig(3)
Impressum