NAME # TODO AppConfig - Perl5 module for managing application configuration information. SYNOPSIS use AppConfig; # create a new AppConfig my $config = AppConfig->new(\%cfg, @vardefs); # define a new variable $config->define($varname, \%varopts); # set/get the value $config->set($varname, $value); $config->get($varname); # shortcut form $config->varname($value); $config->varname(); # read configuration file $config->file($file); # parse command line options $config->args(\@ARGV); OVERVIEW AppConfig is a Perl5 module to handle global configuration variables for perl programs. It maintains the state of any number of variables, handling default values, aliasing, validation, update callbacks and option arguments for use by AppConfig::* modules. The module handles the parsing of configuration files and command line arguments. PREREQUISITES AppConfig requires Perl 5.004 or later. OBTAINING AND INSTALLING THE AppConfig MODULE BUNDLE The AppConfig module bundle is available from CPAN. As the 'perlmod' manual page explains: CPAN stands for the Comprehensive Perl Archive Network. This is a globally replicated collection of all known Perl materials, including hundreds of unbunded modules. [...] For an up-to-date listing of CPAN sites, see http://www.perl.com/perl/ or ftp://ftp.perl.com/perl/ . Within the CPAN archive, AppConfig is in the category: *) TODO: what's the name of this category? The module is available in the following directories: # TODO: check this /modules/by-module/AppConfig-.tar.gz /authors/id/ABW/AppConfig-.tar.gz AppConfig is distributed as a single gzipped tar archive file: AppConfig-.tar.gz Note that "" represents the current AppConfig Revision number, of the form "2.00". See the REVISION manpage below to determine the current version number for AppConfig. Unpack the archive to create a AppConfig installation directory: gunzip AppConfig-.tar.gz tar xvf AppConfig-.tar 'cd' into that directory, make, test and install the modules: cd AppConfig- perl Makefile.PL make make test make install The 't' sub-directory contains a number of small sample files which are processed by the test script (called by 'make test'). See the README file in that directory for more information. The 'make install' will install the module on your system. You may need root access to perform this task. If you install the module in a local directory (for example, by executing "perl Makefile.PL LIB=~/lib" in the above - see perldoc MakeMaker for full details), you will need to ensure that the PERL5LIB environment variable is set to include the location, or add a line to your scripts explicitly naming the library location: use lib '/local/path/to/lib'; The 'examples' sub-directory contains some simple examples of using the AppConfig modules. DESCRIPTION USING THE AppConfig MODULE To import and use the AppConfig module the following line should appear in your Perl script: use AppConfig; AppConfig is implemented using object-oriented methods. A new AppConfig object is created and initialised using the new() method. This returns a reference to a new AppConfig object. my $config = AppConfig->new(); This will create and return a reference to a new AppConfig object. In doing so, the AppConfig object also creates an internal reference to an App::State object in which to store variable state. All arguments passed into the AppConfig constructor are passed directly to the App::State constructor. See the App::State manpage for full details of the configuration options available. Note that any unresolved method calls to AppConfig are automatically delegated to the AppConfig::State object. In practice, it means that it is possible to treat the AppConfig object as if it were an AppConfig::State object: # create AppConfig my $config = AppConfig->new('foo', 'bar'); # methods get passed through to internal AppConfig::State $config->foo(100); $config->set('bar', 200); $config->define('baz'); $config->baz(300); DEFINING VARIABLES The define() function is used to pre-declare a variable and specify its configuration. $config->define("foo"); In the simple example above, a new variable called "foo" is defined. A reference to a hash array may also be passed to specify configuration information for the variable: $config->define("foo", { DEFAULT => 99, ALIAS => 'metavar1', }); See Lset("verbose", 1); is equivalent to $config->verbose(1); Without parameters, the current value of the variable is returned. If a parameter is specified, the variable is set to that value and the original value (before modification) is returned. $config->age(28); $config->age(29); # sets 'age' to 29, returns 28 READING CONFIGURATION FILES The AppConfig module provides a streamlined interface for reading configuration files with the AppConfig::File module. The file() method automatically loads the AppConfig::File module and creates an object to process the configuration file(s). Variables stored in the internal AppConfig::State are automatically updated with values specified in the configuration file. $config->file($file); Multiple files may be passed to file() and should indicate the file name or be a reference to an open file handle or glob. $config->file($file, $filehandle, \*STDIN, ...); The configuration file should contain lines of the form: variable = value The separating '=' is optional. Variables that are simple flags and do not expect an argument (ARGS = 0) can be specified without any value. They will be set with the value 1. Variable values may contain references to other AppConfig variables, environment variables and/or users' home directories. These will be expanded depending on the EXPAND value set in the AppConfig::State. Three different expansion types may be applied: bin = ~/bin # expand '~' to home dir if EXPAND_UID tmp = ~abw/tmp # as above, but home dir for user 'abw' perl = $bin/perl # expand value of 'bin' variable if EXPAND_VAR ripl = $(bin)/ripl # as above with explicit parens home = ${HOME} # expand HOME environment var if EXPAND_ENV See the AppConfig::File manpage for further details on reading configuration files and expanding variable values. PARSING COMMAND LINE OPTIONS The args() method is used to parse command line options. It automatically loads the AppConfig::Args module and creates an object to process the command line arguments. Variables stored in the internal AppConfig::State are automatically updated with values specified in the arguments: $config->args(\@ARGV); Variables should be prefixed by a '-' or '--'. myprog -verbose --debug Variables that expect an additional argument (ARGS != 0) will be set to the value of the argument following it. If the next argument starts with a '-' then a warning will be raised and the value will not be set. myprog --verbose -f /tmp/myfile Variables that do not expect a value (ARGS = 0) will be set to 1. Any arguments remaining at the end of the list that do not start with a '-' will not be processed. These arguments will remain in the list when args() returns. Valid arguments and value will be removed from the list. See the AppConfig::Args manpage for further details on parsing command line arguments. AUTHOR Andy Wardley, Web Technology Group, Canon Research Centre Europe Ltd. REVISION $Revision: 0.1 $ COPYRIGHT Copyright (C) 1998 Canon Research Centre Europe Ltd. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. SEE ALSO AppConfig::State, AppConfig::File, AppConfig::Args