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