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

CONSTANT DEFINITIONS

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

AUTHOR

805       Andy Wardley, <abw@wardley.org>
806
807       With contributions from Dave Viner, Ijon Tichy, Axel Gerstmair and many
808       others whose names have been lost to the sands of time (reminders
809       welcome).
810
812       Copyright (C) 1997-2007 Andy Wardley.  All Rights Reserved.
813
814       Copyright (C) 1997,1998 Canon Research Centre Europe Ltd.
815
816       This module is free software; you can redistribute it and/or modify it
817       under the same terms as Perl itself.
818

SEE ALSO

820       AppConfig::State, AppConfig::File, AppConfig::Args, AppConfig::Getopt,
821       AppConfig::CGI, Getopt::Long
822
823
824
825perl v5.16.3                      2007-07-06                      AppConfig(3)
Impressum