This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: Apache/iNcom/Request, Next: Apache/iNcom/Session, Prev: Apache/iNcom/OrderManager, Up: Module List Manages the Apache::iNcom request's informations. ************************************************* NAME ==== Apache::iNcom::Request - Manages the Apache::iNcom request's informations. SYNOPSIS ======== my $user = $Request->user etc. DESCRIPTION =========== This module is responsible for managing the environment in which the Apache::iNcom page will execute. It setups all the objects that will be accessible to the pages through globals and also provides the page with a bunch of utility functions. It also provides a bunch of methods for managing the information associated with the request. INITIALIZATION ============== An object is automatically initialized on each request by the Apache::iNcom framework. It is accessible through the $Request global variable in Apache::iNcom pages. logged_in --------- Returns true if the request is associated with a UserDB's user. user ---- Returns the UserDB's user associated with the current request. current ------- Returns the name of the current page relative to INCOM_PREFIX. previous -------- Returns the name of the previous page fetched by the user. browser ------- Returns the user agent string sent by the user's browser. remote_host ----------- Returns the hostname of the user. This can be an IP address is hostname resolution is turn off. remote_ip --------- Returns the ip address of the user. login ( $username, $password ) ------------------------------ Invokes the login methods of the UserDB and if the login succeeded, the user will be associated with the current Session, and its informations will be available on each subsequent requests until the user logout. logout ------ Removes the association between the user and the request. APACHE::INCOM PAGE GLOBALS ========================== Here is a list of the global variables that are defined in the page when it is executing. $Request An Apache::iNcom::Request object which can used to query information about the current request. $DB A DBIx::SearchProfiles object initialized with as requested by the Apache::iNcom configuration. $Cart An Apache::iNcom::CartManager object initialized with the configured pricing profile. $Order An Apache::iNcom::OrderManager object initialized with the configured order profiles. %Session A hash which associated with the current client. Values in that hash will persist across request until the user close its browser or INCOM_SESSION_EXPIRES time has elapsed. %UserSession A hash which associated with the user currently logged. Values in that hash will persist across request as long as the client is logged in and will be cleared once the user logs out. $UserDB A DBIx::UserDB object which should be used for user management. $Validator An HTML::Validator object initialized with the configured input profiles. $Localizer An Apache::iNcom::Localizer object initialized with the user requested language. $Locale A Locale::Maketext object initialized with the proper locale. The Locale::Maketext subclass used is specified in the INCOM_LOCALE configuration directives. APACHE::INCOM PAGE FUNCTIONS ============================ Here is list of the helper functions that are defined in the context of the executing page and that can be used. Localize ( ... ) ---------------- This acts as a wrapper around $Locale->maketext. It should be used to format messages in a localized format for the user. Currency ( ... ) ---------------- This acts as a wrapper around $Locale->currency. It should be used to format amount of money for display. Include ( $file_or_param_ref ) ------------------------------ This is a function which is like HTML::Embperl::Execute in that it includes another page in the current one. The difference is that this included page will be executed in the name space of the current so that all global variables remains accessible. Also, this functions checks for the presence of a localized version of the file and checks in the INCOM_TEMPLATE_PATH if the path is not absolute. TextInclude ( file ) -------------------- This is a function is like `Include' except that it is not interpreted for embedded perl. QueryArgs ( [ $fdat ], [ $odat ], [ $idat ] ) --------------------------------------------- This function is similar to the [$ hidden $] directive in HTML::Embperl but instead of generating hidden input fields, it returns the form data as a query string. $fdat The form data to output. Defaults to the %fdat hash. $odat Override data. Fields present in that hash will override the one in %fdat. $idat Ignored data. Fields present in that hash will be ignored and not output in the resulting query string. Usage example : Next AUTHOR ====== Copyright (c) 1999 Francis J. Lacoste and iNsu Innovations Inc. All rights reserved. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. SEE ALSO ======== Apache::iNcom(3) Apache::iNcom::OrderManager(3) Apache::iNcom::CartManager(3) DBIx::SearchProfiles(3) DBIx::UserDB(3) Locale::Maketext(3) HTML::Embperl  File: pm.info, Node: Apache/iNcom/Session, Next: Apache/iNcom/SessionLocker, Prev: Apache/iNcom/Request, Up: Module List Apache::Session implementation for Apache::iNcom ************************************************ NAME ==== Apache::iNcom::Session - Apache::Session implementation for Apache::iNcom SYNOPSIS ======== use Apache::iNcom::Session; DESCRIPTION =========== This is a subclass of Apache::Session used by the iNcom framework. This Apache::Session implementation used the DBIBase64Store and NullLocker for handling session persistence. The other special thing about this implementation is that session IDs are 128bits long and generated using the /dev/urandom device if available. This is a security feature to make session id very hard to guess. AUTHOR ====== Copyright (c) 1999 Francis J. Lacoste and iNsu Innovations Inc. All rights reserved. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. SEE ALSO ======== Apache::iNcom(3) Apache::Session(3) Apache::Session::DBIBase64Store(3) Apache::Session::NullLocker(3)  File: pm.info, Node: Apache/iNcom/SessionLocker, Next: Apache/iNcom/UserDBAuthen, Prev: Apache/iNcom/Session, Up: Module List Manage locks for iNcom's sessions. ********************************** NAME ==== Apache::iNcom::SessionLocker - Manage locks for iNcom's sessions. SYNOPSIS ======== package MySession; sub get_lock_manager { my $self = shift; return new Apache::iNcom::SessionLocker; } DESCRIPTION =========== Apache::iNcom::SessionLocker will serialize access to the sessions if the configuration directive INCOM_SESSION_SERIALIZE_ACCESS is set. A maximum of 5 seconds is waited for lock. SCHEMA ====== This modules expect a table created with the following schema : CREATE TABLE sessions ( id CHAR(32) PRIMARY KEY, length INT, a_session TEXT, created TIMESTAMP DEFAULT 'now()', last_update TIMESTAMP DEFAULT 'now()', locked_by INT ); The previous SQL statement is valid for PostgreSQL. Adapt for your specific DBMS. AUTHOR ====== Copyright (c) 1999 Francis J. Lacoste and iNsu Innovations Inc. All rights reserved. This program is free software; you can redistribute it and/or modify it under the terms as perl itself. SEE ALSO ======== Apache::Session(3) Apache::Session::DBIStore(3) DBI(3)  File: pm.info, Node: Apache/iNcom/UserDBAuthen, Next: Apache/iNcom/UserDBAuthz, Prev: Apache/iNcom/SessionLocker, Up: Module List mod_perl authentication handler that use the UserDB. **************************************************** NAME ==== Apache::iNcom::UserDBAuthen - mod_perl authentication handler that use the UserDB. SYNOPSIS ======== PerlRequire Apache::iNcom:UserDBAuthen AuthType Basic AuthName "iNcom Users" PerlAuthenHandler Apache::iNcom::UserDBAuthen require valid-user DESCRIPTION =========== This module integrates the DBIx::UserDB modules used by the Apache::iNcom with the apache authentication phase. This module can either try to authenticate the user by trying to login() on the standard DBIx::UserDB object. Or it can set the username associated with the connection based on the login status set in the Apache::iNcom session. CONFIGURATION ============= This module takes on configuration directive `INCOM_AUTH_SESSION'. Set it to true to sync the Apache authentication status with the one in the Apache::iNcom session. If this directive is set to false or left undefined. The module will authenticate the user against the default Apache::iNcom DBIx::UserDB object. The DBIx::UserDB used in the process is configured via the normal Apache::iNcom directives. AUTHOR ====== Copyright (c) 1999 Francis J. Lacoste and iNsu Innovations Inc. All rights reserved. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. SEE ALSO ======== Apache::iNcom(3) DBIx::UserDB(3) Apache::iNcom::UserDBAuthz(3)  File: pm.info, Node: Apache/iNcom/UserDBAuthz, Next: Apache/libapreq, Prev: Apache/iNcom/UserDBAuthen, Up: Module List mod_perl authorization handler that use the UserDB. *************************************************** NAME ==== Apache::iNcom::UserDBAuthz - mod_perl authorization handler that use the UserDB. SYNOPSIS ======== PerlRequire Apache::iNcom:UserDBAuthz AuthType Basic AuthName "iNcom Users" PerlAuthenHandler Apache::iNcom::UserDBAuthen PerlAuthzHandler Apache::iNcom::UserDBAuthz require valid-user require user foo require group bar require user foo and write require group baz; exec on test require valid-user, admin code DESCRIPTION =========== This module integrates the DBIx::UserDB module used by the Apache::iNcom framework with the apache authorization phase. This module will set the authorization on the authenticated user by checking the DBIx::UserDB ACL. CONFIGURATION ============= The DBIx::UserDB used is configured via the normal Apache::iNcom directives. REQUIREMENTS DIRECTIVES ======================= This module will let the user if ANY require directives match. This means that different require ar ORed together. In a require directive, different clause can be ANDed together by separating them by and, comma (,) or semi-colon (;). Here are the different expression that are understood by the module. valid-user This requirements will pass everytime the user was authenticated successfully. user This requirement will succeed if the user's username is identical. group This requirement will suceed if the user is a member of that group. This requirement will succeed if the user has the specified privilege on the current URL. The INCOM_URL_PREFIX is stripped from the URL. The privilege is checked by using the allowed method of the UserDB. [on] This requirement will succeed if the user has the specified privilege on the specified target. The privilege is checked by using the allowed method of the UserDB. AUTHOR ====== Copyright (c) 1999 Francis J. Lacoste and iNsu Innovations Inc. All rights reserved. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. SEE ALSO ======== Apache::iNcom(3) DBIx::UserDB(3) Apache::iNcom::UserDBAuthen(3)  File: pm.info, Node: Apache/libapreq, Next: Apache/src, Prev: Apache/iNcom/UserDBAuthz, Up: Module List Generate compiler and linker flags for libapreq *********************************************** NAME ==== Apache::libapreq - Generate compiler and linker flags for libapreq SYNOPSIS ======== #Makefile CCOPTS = `perl -MApache::libapreq -e ccopts` LDOPTS = `perl -MApache::libapreq -e ldopts` DESCRIPTION =========== The *libapreq* package installs libraries and include files into Perl architecture dependent locations. FUNCTIONS ========= ccopts Simply invokes: print "-I$Config{installsitearch}/auto/libapreq/include" ldopts Simply invokes: print "-L$Config{installsitearch}/auto/libapreq -lapreq" AUTHOR ====== Doug MacEachern  File: pm.info, Node: Apache/src, Next: Apache/test, Prev: Apache/libapreq, Up: Module List my $src = Apache::src->new; for my $path ($src->find) { my $mmn = $src->module_magic_number($path); my $v = $src->httpd_version($path); next unless $v; print "path = $path ($mmn,$v)\n"; my $dir = $src->prompt("Configure with $path?"); } Methods for locating and parsing bits of Apache source code *********************************************************** NAME ==== Apache::src - Methods for locating and parsing bits of Apache source code SYNOPSIS ======== use Apache::src (); my $src = Apache::src->new; DESCRIPTION =========== This module provides methods for locating and parsing bits of Apache source code. METHODS ======= new Create an object blessed into the *Apache::src* class. my $src = Apache::src->new; dir Top level directory where source files are located. my $dir = $src->dir; -d $dir or die "can't stat $dir $!\n"; main Apache's source tree was reorganized during development of version 1.3. So, common header files such as `httpd.h' are in different directories between versions less than 1.3 and those equal to or greater. This method will return the right directory. Example: -e join "/", $src->main, "httpd.h" or die "can't stat httpd.h\n"; find Searches for apache source directories, return a list of those found. Example: for my $dir ($src->find) { my $yn = prompt "Configure with $dir ?", "y"; ... } inc Print include paths for MakeMaker's INC argument to `WriteMakefile'. Example: use ExtUtils::MakeMaker; use Apache::src (); WriteMakefile( 'NAME' => 'Apache::Module', 'VERSION' => '0.01', 'INC' => Apache::src->new->inc, ); module_magic_number Return the *MODULE_MAGIC_NUMBER* defined in the apache source. Example: my $mmn = $src->module_magic_number; httpd_version Return the server version. Example: my $v = $src->httpd_version; otherldflags Return other ld flags for MakeMaker's dynamic_lib argument to `WriteMakefile'. This might be needed on systems like AIX that need special flags to the linker to be able to reference mod_perl or httpd symbols. Example: use ExtUtils::MakeMaker; use Apache::src (); WriteMakefile( 'NAME' => 'Apache::Module', 'VERSION' => '0.01', 'INC' => Apache::src->new->inc, 'dynamic_lib' => { 'OTHERLDFLAGS' => Apache::src->new->otherldflags, }, ); AUTHOR ====== Doug MacEachern  File: pm.info, Node: Apache/test, Next: App/Config, Prev: Apache/src, Up: Module List Facilitates testing of Apache::* modules **************************************** NAME ==== Apache::Test - Facilitates testing of Apache::* modules SYNOPSIS ======== # In Makefile.PL use Apache::test; my %params = Apache::test->get_test_params(); Apache::test->write_httpd_conf(%params, include => $more_directives); *MY::test = sub { Apache::test->MM_test(%params) }; # In t/*.t script (or test.pl) use Apache::test qw(skip_test have_httpd); skip_test unless have_httpd; (Some more methods of Doug's that I haven't reviewed or documented yet) DESCRIPTION =========== This module helps authors of Apache::* modules write test suites that can query an actual running Apache server with mod_perl and their modules loaded into it. Its functionality is generally separated into methods that go in a Makefile.PL to configure, start, and stop the server, and methods that go in one of the test scripts to make HTTP queries and manage the results. METHODS ======= get_test_params() ----------------- This will ask the user a few questions about where the httpd binary is, and what user/group/port should be used when running the server. It will return a hash of the information it discovers. This hash is suitable for passing to the `write_httpd_conf()' method. write_httpd_conf(%params) ------------------------- This will write a basic httpd.conf file suitable for starting a HTTP server during the 'make test' stage. A hash of key/value pairs that affect the written file can be passed as arguments. The following keys are recognized: * conf_file The path to the file that will be created. Default is 't/httpd.conf'. * port The port that the Apache server will listen on. * user The user that the Apache server will run as. * group The group that the Apache server will run as. * include Any additional text you want added at the end of the config file. Typically you'll have some `PerlModule' and `Perl*Handler' directives to pass control to the module you're testing. The `blib/' directories will be added to the `@INC' path when searching for modules, so that's nice. MM_test(%params) ---------------- This method helps write a Makefile that supports running a web server during the 'make test' stage. When you execute 'make test', 'make' will run 'make start_httpd', 'make run_tests', and 'make kill_httpd' in sequence. You can also run these commands independently if you want. Pass the hash of parameters returned by get_test_params() as an argument to `MM_test()'. To patch into the ExtUtils::MakeMaker wizardry (voodoo?), typically you'll do the following in your Makefile.PL: *MY::test = sub { Apache::test->MM_test(%params) }; fetch ----- Apache::test->fetch($request); Apache::test->fetch($user_agent, $request); Call this method in a test script in order to fetch a page from the running web server. If you pass two arguments, the first should be an LWP::UserAgent object, and the second should specify the request to make of the server. If you only pass one argument, it specifies the request to make. The request can be specified either by a simple string indicating the URI to fetch, or by a hash reference, which gives you more control over the request. The following keys are recognized in the hash: * uri The URI to fetch from the server. If the URI does not begin with "http", we prepend "http://localhost:$PORT" so that we make requests of the test server. * method The request method to use. Default is 'GET'. * content The request content body. Typically used to simulate HTML fill-out form submission for POST requests. Default is null. * headers A hash of headers you want sent with the request. You might use this to send cookies or provide some application-specific header. If you don't provide a 'headers' parameter and you set the 'method' to 'POST', then we assume that you're trying to simulate HTML form submission and we add a 'Content_Type' header with a value of 'application/x-www-form-urlencoded'. In a scalar context, fetch() returns the content of the web server's response. In a list context, fetch() returns the content and the HTTP::Response object itself. This can be handy if you need to check the response headers, or the HTTP return code, or whatever. static_modules -------------- Example: $mods = Apache::test->static_modules('/path/to/httpd'); This method returns a hashref whose keys are all the modules statically compiled into the given httpd binary. The corresponding values are all 1. EXAMPLES ======== No good examples yet. Example submissions are welcome. In the meantime, see `http:' in this node , which I'm retrofitting to use Apache::test. TO DO ===== The MM_test method doesn't try to be very smart, it just writes the text that seems to work in my configuration. I am morally against using the 'make' command for installing Perl modules (though of course I do it anyway), so I haven't looked into this very much. Send bug reports or better (patches). I've got lots of code in my Apache::AuthCookie module (etc.) that assists in actually making the queries of the running server. I plan to add that to this module, but first I need to compare what's already here that does the same stuff. KUDOS ===== To Doug MacEachern for writing the first version of this module. To caelum@debian.org (Rafael Kitover) for contributing the code to parse existing httpd.conf files for -enable-shared=max and DSOs. CAVEATS ======= Except for making sure that the mod_perl distribution itself can run 'make test' okay, I haven't tried very hard to keep compatibility with older versions of this module. In particular MM_test() has changed and probably isn't usable in the old ways, since some of its assumptions are gone. But none of this was ever documented, and MM_test() doesn't seem to actually be used anywhere in the mod_perl disribution, so I don't feel so bad about it. AUTHOR ====== Doug MacEachern (original version) Ken Williams (latest changes and this documentation)  File: pm.info, Node: App/Config, Next: App/Manager, Prev: Apache/test, Up: Module List Perl5 extension for managing global application configuration information. ************************************************************************** NAME ==== App::Config - Perl5 extension for managing global application configuration information. SYNOPSIS ======== use App::Config; my $cfg = App::Config->new(); $cfg->define("foo"); # very simple variable definition $cfg->set("foo", 123); # trivial set/get examples $fval = $cfg->get("foo"); $cfg->foo(456); # direct variable access $cfg->cfg_file(".myconfigrc"); # read config file $cfg->cmd_line(\@ARGV); # process command line OVERVIEW ======== App::Config is a Perl5 module to handle global configuration variables for perl programs. The advantages of using such a module over the standard "global variables" approach include: * Reduction of clutter in the main namespace. * Default values can be specified. * Multiple names (aliases) can refer to the same variable. * Configuration values can be set directly from config files and/or command line arguments. * Data values can be automatically validated by pattern matching (e.g. "\d+" to accept digits only) or through user-supplied routines. * User-defined routines can be called automatically when configuration values are changed. PREREQUISITES ============= App::Config requires Perl version 5.004 or later. If you have an older version of Perl, please upgrade to latest version. Perl 5.004 is known to be stable and includes new features and bug fixes over previous versions. Perl itself is available from your nearest CPAN site (see http://www.perl.com/CPAN). INSTALLATION ============ To install this module type the following: perl Makefile.PL make make install 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'; DESCRIPTION =========== USING THE App::Config MODULE ---------------------------- To import and use the App::Config module the following line should appear in your Perl script: use App::Config; App::Config is implemented using object-oriented methods. A new App::Config object is created and initialised using the App::Config->new() method. This returns a reference to a new App::Config object. my $cfg = App::Config->new(); This will create a reference to a new App::Config with all configuration options set to their default values. You can initialise the object by passing a hash array reference containing configuration options: $cfg = App::Config->new( { CASE => 1, FILEPARSE => \&my_parser, ERROR => \&my_error, } ); The following configuration options may be specified. Some of these use default values as may be specified in the GLOBAL configuration option. CASE Determines if the variable names are treated case sensitively. Any non-zero value makes case significant when naming variables. By default, CASE is set to 0 and thus "Variable", "VARIABLE" and "VaRiAbLe" are all treated as "variable". ERROR Specifies a user-defined error handling routine. A format string is passed as the first parameter, followed by any additional values, as per printf(3C). FILEPARSE Specifies a user-defined routine for parsing a configuration file. The function is called by `cfg_file()' and is passed a reference to the App::Config object and the name of the file to parse. The routine should update any variable values directly. The return value is expected to be 1 to indicate success or 0 to indicate failure. This value is returned directly from `cfg_file()'; Pseudo-Code Example: $cfg = App::Config->new( { FILEPARSE => \&my_parser } ); sub my_parser { my $cfg = shift; my $file = shift; # open file, read lines, etc. # ... $cfg->set($variable, $value); # set variable value # close file, etc. return 1; } LINEPARSE Instead of providing a routine to parse the entire config file, LINEPARSE can be used to define a function to handle each line of the config file. The `cfg_file()' routine reads the file and passes each line to the LINEPARSE function, where defined. Four parameters are passed to the LINEPARSE function: * a reference to the App::Config object * the config filename The function should return 1 to indicate that the line has been successfully parsed, or 0 to indicate that no action was taken and the default line parser should now be used for this line. * the current line number within the file, and * the line of text itself (the filename and line number are useful for reporting errors). Note that `cfg_file()' does some elementary pre-processing before calling the LINEPARSE function. See `READING A CONFIGURATION FILE' in this node for more details. CMDPARSE Specifies a user-defined routine for parsing the command line. The function is called by cmd_line() and is passed a reference to the App::Config object and a reference to a list of command line arguments (usually @ARGV). The function is required to set variable values directly and return 1 or 0 to indicate success or failure, as is described in the FILEPARSE section above. ARGPARSE Just as a LINEPARSE routine can be defined to parse each line of a config file, an ARGPARSE routine can also be specified to parse each command line argument. The function is called from cmd_line() and is passed a reference to the App::Config object through which variable values can be manipulated. Other parameters passed are the command line argument in question (e.g. `"-v"'), the name of the variable to which it corresponds (e.g. `"verbose"') and a reference to the remaining argument list. The function is expected to modify the argument list if necessary, shifting off additional parameters where required. A pseudo-code example is shown: my $cfg = App::Config->new( { ARGPARSE => \&my_arg_parse, } ); sub my_arg_parse { my $cfg = shift; my $arg = shift; my $var = shift; my $argvref = shift; VAR: { $var eq 'verbose' && do { $cfg->set($var, 1); last VAR; }; # this time, look at $arg instead of $var $arg eq '-f' && do { $cfg->set($var, shift(@$argvref)); # should error check last VAR; }; # not interested in anything else # (let default parser have a go) return 0; } # we processed it so return 1 return 1; } CMDENV The CMDENV option is used to specify the name of an environment variable which may contain default command line options. If defined, the variable is examined by the cmd_line() routine where it is split into whitespace separated tokens and parsed along with the rest of the command line options. Environment variable options are processed before any real command line options. Note that the variable is split on whitespace and does not take into account quoted whitespace. Thus 'foo "bar baz" qux' will be split into the tokens 'foo', '"bar', 'baz"' and 'qux'. This will be fixed in a future release. From the Unix shell: $ SPLATOPTS="-z -f foobar" Perl App::Config usage: my $cfg = App::Config->new( { CMDENV => "SPLATOPTS" } ); $cfg->cmd_line(\@ARGV); # parses ("-z", "-f", "foobar", @ARGV) ENDOFARGS The ENDOFARGS option can be used to specify the marker that signifies the end of the command line argument list. Typically, and by default, this is '-'. Any arguments appearing in the command line after this token will be ignored. my $cfg = App::Config->new( { ENDOFARGS => "STOP" } ); @args = qw(-f -g -h STOP -i -am -ignored); $cfg->cmd_line(\@args); # @args now contains qw(-i -am -ignored) GLOBAL The GLOBAL option allows default values to be set for the ARGCOUNT, EXPAND, CMDARG and VALIDATE options for all variables. `DEFINING VARIABLES' in this node below describes these options in detail. The CMDARG global option, when set to any true value, specifies that the command line option for any variable should be of the form "-variable". Any aliases specified for a variable can also be used in this way. e.g. my $cfg = App::Config->new({ GLOBAL => { ARGCOUNT => 1, CMDARG => 1 } }); $cfg->define("foo", { ALIAS => 'bar' }); The GLOBAL ARGCOUNT parameter specifies that the foo variable expects an argument. An ARGCOUNT option specified in the define() method call would override this default. The GLOBAL CMDARG option specifies that the 'foo' variable should be specified on the command line as '-foo'. The ALIAS name for foo can also be specified as such: '-bar'. DEFINING VARIABLES ------------------ The define() function is used to pre-declare a variable and specify its configuration. $cfg->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: $cfg->define("foo", { DEFAULT => 99, ALIAS => 'metavar1', }); The following configuration options may be specified DEFAULT The DEFAULT value is used to initialise the variable. The variable remains set to this value unless otherwise changed via set(), `cfg_file()' or `cmd_line()'. ALIAS The ALIAS option allows a number of alternative names to be specified for this variable. A single alias should be specified as a string, multiple aliases as a reference to an array. e.g.: $cfg->define("foo", { ALIAS => 'metavar1', }); or $cfg->define("bar", { ALIAS => [ 'metavar2', 'metalrod', 'boozer' ], }); In the first example, `$cfg->set("metavar1")' (or any other variable-related function) is equivalent to `$cfg->set("foo")'. Likewise for the second example, with all 3 aliases defined. CMDARG When processing a list of command line arguments, flags may be used to refer to certain variable values. For example, -v is a common flag indicating verbose mode. The 'verbose' variable might be defined as such: $cfg->define("verbose", { CMDARG => '-v', }); If the `cmd_line()' function detects -v in the command line arguments, it will update the 'verbose' value. See also the ARGCOUNT option below which influences the variable values that are set by the command line processing function. A variable may have more than one related command line argument. These can be specified by passing a reference to an array of arguments: $cfg->define("verbose", { CMDARG => [ '-v', '-V' ], }); If the GLOBAL CMDARG variable is set (see GLOBAL in `DESCRIPTION' in this node above) then the default CMDARG for each variable will be its name (and any aliases) prefixed by a dash, e.g. '-verbose'. Any CMADRG value specifically set will override this default. ARGCOUNT Some variables are intended to be simple flags that have a false/true (zero/non-zero) value (e.g. the 'verbose' example above) while others may require mandatory arguments (e.g. specifying a file: `"-f filename"'). The ARGCOUNT value is used to determine if an additional argument is expected (`ARGCOUNT => 1') or not (`ARGCOUNT => 0'). When ARGCOUNT is 1, `cfg_file()' passes the rest of the config line (after the opening variable name has been removed) as the argument value and `cmd_line()' passes the next argument from the command line argument list (usually @ARGV). When ARGCOUNT is 0, both functions pass the value 1 to set the variable to a true state. The default ARGCOUNT value is 0. If the GLOBAL ARGCOUNT variable is set (see GLOBAL in `DESCRIPTION' in this node above) then this value will be used as the default ARGCOUNT for each variable unless otherwise specified. NOTE: Although any non-zero value can be used to indicate the presence of an additional argument, this option may be extended in the future to handle multiple arguments. The behaviour associated with any value other than 1 or 0 may change in subsequent versions. EXPAND Variable values specified in a configuration file (see `READING A CONFIGURATION FILE' in this node) may contain environment variables, other App::Config variables and/or users' home directories specified in tilde notation (e.g. ~abw). The EXPAND option specifies if these variables should be replaced with their relevant values. By default EXPAND is set to 1 (expansion) but can be set to 0 to disable the feature. If the GLOBAL EXPAND variable is set (see GLOBAL in above) then this value will be used as the default EXPAND for each variable unless otherwise specified. Items are expanded according to the following rules: * A directory element specified in tilde notation is expanded to the full directory path it represents (e.g. ~abw/lib => /user/abw/lib). A tilde by itself expands to the home directory of the current user (e.g. ~/lib => /users/abw/lib). If a non-existant user is specified or it is not possible to determine the home directory of the user, the tilde notation is left unexpanded (e.g. ~nosuchuser/lib). * A variable enclosed in braces and prefixed with a dollar symbol (e.g. ${HOME}) is assumed to be an environment variable and is expanded as such. A non-existant variable will be replaced by an empty string, as is typical in UNIX shell expansion (e.g. ${DUD}/lib => /lib). * A variable enclosed in parenthesis and prefixed with a dollar symbol (e.g. $(ROOT)) is assumed to refer to another variable defined in the current App::Config object. Case sensitivity is applied as per the current CASE setting and non-existant variables are replaced by an empty string as per environment variables (e.g. $(mipspelt)/lib => /lib). * A variable prefixed with a dollar and with no enclosing braces or parenthesis (e.g. $root/lib) is first interpreted as an App::Config variable and if not resolved, as an environment variable. If the variable cannot be evaluated in either context it is ignored and the original text is left unmodified. VALIDATE Each variable may have a sub-routine or regular expression defined which is used to validate the intended value that is set by `cfg_file()' and `cmd_line()'. If VALIDATE is defined as a simple string, it is applied as a regular expression to the value read from the config file or command line. If the regex matches, the value is set. If not, a warning message is generated. VALIDATE may also be defined as a reference to a sub-routine which takes as its arguments the name of the variable and its intended value. The sub-routine should return 1 or 0 to indicate that the value is valid or invalid, respectively. An invalid value will cause a warning error message to be generated. If the GLOBAL VALIDATE variable is set (see GLOBAL in `DESCRIPTION' in this node above) then this value will be used as the default VALIDATE for each variable unless otherwise specified. ACTION The ACTION option allows a sub-routine to be bound to a variable that is executed whenever the variable is set. The ACTION is passed a reference to the App::Config object, the name of the variable and the value of the variable. The ACTION routine may be used, for example, to post-process variable data, update the value of some other dependant variable, generate a warning message, etc. Example: sub my_notify { my $cfg = shift; my $var = shift; my $val = shift; print "$variable set to $value\n"; } Be aware that calling `$cfg->set()' to update the variable from within the ACTION function will cause a recursive loop as the ACTION function is repeatedly called. This is probably a bug, certainly a limitation. READING AND MODIFYING VARIABLE VALUES ------------------------------------- App::Config defines two methods to manipulate variable values: set($variable, $value); get($variable); Both functions take the variable name as the first parameter and set() takes an additional parameter which is the new value for the variable. set() returns 1 or 0 to indicate successful or unsuccessful update of the variable value. If there is an ACTION routine associated with the named variable, the value returned will be passed back from set(). The get() function returns the current value of the variable. Once defined, variables may be accessed directly as object methods where the method name is the same as the variable name. i.e. $cfg->set("verbose", 1); is equivalent to $cfg->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. $cfg->age(28); $cfg->age(29); # sets 'age' to 29, returns 28 READING A CONFIGURATION FILE ---------------------------- App::Config can be used to read configuration files and automatically update variable values based on the contents of the file. $cfg->cfg_file("$HOME/.myapprc"); The `cfg_file()' function reads each line of the specified configuration file and processes them according to the following rules: * Any lines ending with a backslash '\' are treated as continuation lines. The following line is appended to the current line (and any subsequent continuation lines) before any further processing. * Any blank lines or lines starting with a '#' (i.e. comments) are ignored. * Leading and trailing whitespace is ignored. * The line is separated at the first whitespace character or at the first `'='' character (surrounding whitespace is ignored). * A variable by itself with no corresponding value will be treated as a simple flag if it's ARGCOUNT is 0. In this case, the value for the variable will be set to 1. The following example demonstrates a typical configuration file: # simple flag (same as " verbose 1" or "verbose = 1") verbose # the following lines are all equivalent file /tmp/foobar file = /tmp/foobar file=/tmp/foo PARSING THE COMMAND LINE ------------------------ By specify CMDARG values for defined variables, the `cmd_line()' function can be used to read the command line parameters and automatically set variables. When an command line argument matches a CMDARG value, the variable it relates to is updated. If the variable has an ARGCOUNT of 0, it will be assigned the value 1 (i.e. the flag is set). A variable with an ARGCOUNT of 1 will be set with the next value in the arguments. Users familiar with getopt(3C) will recognise this as equivalent to adding a colon after an option letter (e.g. `"f:"'). An error is generated if the argument starts with a '-'. The special option "-" may be used to delimit the end of the options. `cmd_line()' stops processing if it finds this option. Example variable definition: $cfg->define("verbose", { CMDARG => '-v', ARGCOUNT => 0, # default anyway }); $cfg->define("file", { CMDARG => '-f', ARGCOUNT => 1, # expects an argument }); Command-line options: -v -f foobar Variable values after calling `cmd_line(\@ARGV)': verbose: 1 file: foobar KNOWN BUGS AND LIMITATIONS ========================== The following list represents known limitations or bugs in App::Config or ways in which it may be improved in the future. Please contact the author if you have any suggestions or comments. * An ACTION sub-routine may not update its variable via the $cfg->set() method. This causes the ACTION function to be re-executed, starting a recursive loop. * More extensive variable validation (not using user-defined functions), perhaps by defining standard classes (e.g. numeric, filename, list, etc). Variable validation may be also extended to allow manipulation of the data as well (e.g. splitting a string into a list). * Further extend command line parsing. Maybe allow regexes to be specified for matches (e.g. `"-v(erbose)"') and handle different command line characters other than '-' (e.g. `+flag @file'). This may also tie in with long (-) and short (-) options and defining recognised 'classes' of options. * ARGCOUNT should be able to indicate nargs > 1 and have cmd_line extract them accordingly. Perhaps have types, e.g. boolean, single, multiple. The validate function could additionally take an array ref which contains code refs or regex's to match each arg. Should also be able to handle multiple options that can be specified separately, e.g. `-I/usr/include' `-I/user/abw/include'. * An ACCESS parameter could specify which actions may update a variable: set(), cfg_file() and/or cmd_line(). * Allow variables to have related environment variables which are parsed by an env_vars() function. AUTHOR ====== Andy Wardley, `' Web Technology Group, Canon Research Centre Europe Ltd. App::Config is based in part on the ConfigReader module, v0.5, by Andrew Wilcox (currently untraceable). Thanks to all the people who have reported bugs and made suggestions. Special thanks to those who sent patches: Firestone GLOBAL arguments Blair Zajac getpw*() check for Win32 compatibility REVISION ======== $Revision: 1.9 $ COPYRIGHT ========= Copyright (C) 1997,98 Canon Research Centre Europe Ltd. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the term of the Perl Artistic License. SEE ALSO ======== Andy Wardley's Home Page http://www.kfs.org/~abw/ Canon Research Centre Europe printf(3C) The man page for the printf() function, for a description of the format parameter to the ERROR routine. http://www.cre.canon.co.uk/perl/ The ConfigReader module. The module which provided inspiration and ideas for the development of App::Config.  File: pm.info, Node: App/Manager, Next: AppConfig, Prev: App/Config, Up: Module List Perl module for installing, managing and uninstalling software packages. ************************************************************************ NAME ==== App::Manager - Perl module for installing, managing and uninstalling software packages. SYNOPSIS ======== use App::Manager; # use appman instead DESCRIPTION =========== Oh well ;) Not written yet! The manager program (appman) has documented commandlien switches, though. AUTHOR ====== Marc Lehmann . SEE ALSO ======== perl(1).  File: pm.info, Node: AppConfig, Next: AppConfig/Args, Prev: App/Manager, Up: Module List Perl5 module for reading configuration files and parsing command line arguments. ******************************************************************************** NAME ==== AppConfig - Perl5 module for reading configuration files and parsing command line arguments. SYNOPSIS ======== use AppConfig; # create a new AppConfig object my $config = AppConfig->new(\%cfg); # define a new variable $config->define($varname => \%varopts); # create/define combined my $config = AppConfig->new(\%cfg, $varname => \%varopts, $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); # advanced command line options with Getopt::Long $config->getopt(\@ARGV); OVERVIEW ======== AppConfig is a Perl5 module for managing application configuration information. It maintains the state of any number of variables and provides methods for parsing configuration files and command line arguments. Variables values may be set via configuration files. Variables may be flags (On/Off), take a single value, or take multiple values stored as a a list or hash. The number of arguments a variable expects is determined by its configuration when defined. # flags verbose nohelp debug = On # single value home = /home/abw/ # multiple list value file = /tmp/file1 file = /tmp/file2 # multiple hash value book camel = Programming Perl book llama = Learning Perl The '-' prefix can be used to reset a variable to its default value and the '+' prefix can be used to set it to 1 -verbose +debug Variable, environment variable and tilde (home directory) expansions can be applied (selectively, if necessary) to the values read from configuration files: home = ~ # home directory nntp = ${NNTPSERVER} # environment variable html = $home/html # internal variables img = $html/images Configuration files may be arranged in blocks as per the style of Win32 "INI" files. [file] site = kfs src = ~/websrc/docs/$site lib = ~/websrc/lib dest = ~/public_html/$site [page] header = $lib/header footer = $lib/footer Variables may also be set by parsing command line arguments. myapp -verbose -site kfs -file f1 -file f2 AppConfig provides a simple method (args()) for parsing command line arguments. A second method (getopt()) allows more complex argument processing by delegation to Johan Vroman's Getopt::Long module. PREREQUISITES ============= AppConfig requires Perl 5.004 or later. The AppConfig::Getopt module uses Getopt::Long for advanced command-line option processing and requires version 2.17 or later. There is also a simple internal module (AppConfig::Args) for command line parsing that does not have the flexibility of AppConfig::Getopt but is smaller and incurs less overhead. The Getopt::Long module is not required when this is used. The Makefile.PL specifies Getopt::Long version 2.17 as a pre-requisite. If you wish to use AppConfig without Getopt::Long then comment out the following line in the Makefile.PL: # 'PREREQ_PM' => { 'Getopt::Long' => 2.17 }, No action is necessary if you already have Getopt::Long 2.17 or later installed. Getopt::Long is available from any CPAN site (see below). All AppConfig::* and other modules (e.g. Getopt::Long) are dynamically loaded by the AppConfig module as and when required. 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 unbundled 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: 12) Option, Argument, Parameter and Configuration File Processing The module is available in the following directories: /modules/by-module/AppConfig/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 section 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 test scripts that are run when a 'make test' is run. The 'make install' will install the module on your system. You may need administrator privileges 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; To import constants defined by the AppConfig module, specify the name of one or more of the constant or tag sets as parameters to use: use AppConfig qw(:expand :argcount); See `CONSTANT DEFINITIONS' in this node below for more information on the constant tagsets defined by 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 AppConfig::State object in which to store variable state. All arguments passed into the AppConfig constructor are passed directly to the AppConfig::State constructor. The first (optional) parameter may be a reference to a hash array containing configuration information. my $config = AppConfig->new({ CASE => 1, ERROR => \&my_error, GLOBAL => { DEFAULT => "", ARGCOUNT => ARGCOUNT_ONE, }, }); See *Note AppConfig/State: AppConfig/State, for full details of the configuration options available. These are, in brief: CASE Used to set case sensitivity for variable names (default: off). CREATE Used to indicate that undefined variables should be created automatically (default: off). GLOBAL Reference to a hash array of global values used by default when defining variables. Valid global values are DEFAULT, ARGCOUNT, EXPAND, VALIDATE and ACTION. PEDANTIC Used to indicate that command line and configuration file parsing routines should return immediately on encountering an error. ERROR Used to provide a error handling routine. Arguments as per printf(). Subsequent parameters may be variable definitions. These are passed to the define() method, described below in `DEFINING VARIABLES' in this node. my $config = AppConfig->new("foo", "bar", "baz"); my $config = AppConfig->new({ CASE => 1 }, qw(foo bar baz)); 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() method (delegated to AppConfig::State) is used to pre-declare a variable and specify its configuration. $config->define("foo"); Variables may also be defined directly from the AppConfig new() constructor. my $config = AppConfig->new("foo"); In both simple examples 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', }); Configuration items specified in the GLOBAL option to the module constructor are applied by default when variables are created. e.g. my $config = AppConfig->new({ GLOBAL => { DEFAULT => "", ARGCOUNT => ARGCOUNT_ONE, } }); $config->define("foo"); $config->define("bar", { ARGCOUNT => ARGCOUNT_NONE } ); is eqivalent to: my $config = AppConfig->new(); $config->define("foo", { DEFAULT => "", ARGCOUNT => ARGCOUNT_ONE, }); $config->define("bar", DEFAULT => "", ARGCOUNT => ARGCOUNT_NONE, }); Multiple variables may be defined in the same call to define(). Configuration hashes for variables can be omitted. $config->define("foo", "bar" => { ALIAS = "boozer" }, "baz"); See *Note AppConfig/State: AppConfig/State,) for full details of the configuration options available when defining variables. These are, in brief: DEFAULT The default value for the variable (default: undef). ALIAS One or more (list reference or "list|like|this") alternative names for the variable. ARGCOUNT Specifies the number and type of arguments that the variable expects. Constants in :expand tag set define ARGCOUNT_NONE - simple on/off flag (default), ARGCOUNT_ONE - single value, ARGCOUNT_LIST - multiple values accessed via list reference, ARGCOUNT_HASH - hash table, "key=value", accessed via hash reference. ARGS Used to provide an argument specification string to pass to Getopt::Long via AppConfig::Getopt. E.g. "=i", ":s", "=s@". This can also be used to implicitly set the ARGCOUNT value (`/^!/' = ARGCOUNT_NONE, `/@/' = ARGCOUNT_LIST, `/%/ = ARGCOUNT_HASH, C" The first element indicates the variable name and subsequent ALIAS values may be added, each separated by a vertical bar '|'. The element indicates the ARGCOUNT value and may be one of the following; ! ARGCOUNT_NONE =s ARGCOUNT_ONE =s@ ARGCOUNT_LIST =s% ARGCOUNT_HASH The "=s" element Additional constructs supported by Getopt::Long may be specified instead of the "=s" element (e.g. "=f"). The entire element is stored in the ARGS parameter for the variable and is passed intact to Getopt::Long when the getopt() method is called. The following examples demonstrate use of the comapct format, with their equivalent full specifications: $config->define("foo|bar|baz!"); $config->define( "foo" => { ALIAS => "bar|baz", ARGCOUNT => ARGCOUNT_NONE, }); $config->define("name=s"); $config->define( "name" => { ARGCOUNT => ARGCOUNT_ONE, }); $config->define("file|filelist|f=s@"); $config->define( "file" => { ALIAS => "filelist|f", ARGCOUNT => ARGCOUNT_LIST, }); $config->define("user|u=s%"); $config->define( "user" => { ALIAS => "f", ARGCOUNT => ARGCOUNT_HASH, }); Additional configuration options may be specified by hash reference, as per normal. The compact definition format will override any configuration values provided for ARGS and ARGCOUNT. $config->define("file|filelist|f=s@", { VALIDATE = \&check_file() } ); READING AND MODIFYING VARIABLE VALUES ------------------------------------- AppConfig defines two methods (via AppConfig::State) to manipulate variable values set($variable, $value); get($variable); Once defined, variables may be accessed directly as object methods where the method name is the same as the variable name. i.e. $config->set("verbose", 1); is equivalent to $config->verbose(1); Note that AppConfig defines the following methods: new(); file(); args(); getopt(); And also, through delegation to AppConfig::State: define() get() set() varlist() If you define a variable with one of the above names, you will not be able to access it directly as an object method. i.e. $config->file(); This will call the file() method, instead of returning the value of the 'file' variable. You can work around this by explicitly calling get() and set() on a variable whose name conflicts: $config->get('file'); or by defining a "safe" alias by which the variable can be accessed: $config->define("file", { ALIAS => "fileopt" }); or $config->define("file|fileopt"); ... $config->fileopt(); Without parameters, the current value of the variable is returned. If a parameter is specified, the variable is set to that value and the result of the set() operation is returned. $config->age(29); # sets 'age' to 29, returns 1 (ok) print $config->age(); # prints "29" The varlist() method can be used to extract a number of variables into a hash array. The first parameter should be a regular expression used for matching against the variable names. my %vars = $config->varlist("^file"); # all "file*" variables A second parameter may be specified (any true value) to indicate that the part of the variable name matching the regex should be removed when copied to the target hash. $config->file_name("/tmp/file"); $config->file_path("/foo:/bar:/baz"); my %vars = $config->varlist("^file_", 1); # %vars: # name => /tmp/file # path => "/foo:/bar:/baz" 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($filename); 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($filename, $filehandle, \*STDIN, ...); The file may contain blank lines and comments (prefixed by '#') which are ignored. Continutation lines may be marked by ending the line with a '\'. # this is a comment callsign = alpha bravo camel delta echo foxtrot golf hipowls \ india juliet kilo llama mike november oscar papa \ quebec romeo sierra tango umbrella victor whiskey \ x-ray yankee zebra Variables that are simple flags and do not expect an argument (ARGCOUNT = ARGCOUNT_NONE) can be specified without any value. They will be set with the value 1, with any value explicitly specified (except "0" and "off") being ignored. The variable may also be specified with a "no" prefix to implicitly set the variable to 0. verbose # on (1) verbose = 1 # on (1) verbose = 0 # off (0) verbose off # off (0) verbose on # on (1) verbose mumble # on (1) noverbose # off (0) Variables that expect an argument (ARGCOUNT = ARGCOUNT_ONE) will be set to whatever follows the variable name, up to the end of the current line. An equals sign may be inserted between the variable and value for clarity. room = /home/kitchen room /home/bedroom Each subsequent re-definition of the variable value overwrites the previous value. print $config->room(); # prints "/home/bedroom" Variables may be defined to accept multiple values (ARGCOUNT = ARGCOUNT_LIST). Each subsequent definition of the variable adds the value to the list of previously set values for the variable. drink = coffee drink = tea A reference to a list of values is returned when the variable is requested. my $beverages = $config->drinks(); print join(", ", @$beverages); # prints "coffee, tea" Variables may also be defined as hash lists (ARGCOUNT = ARGCOUNT_HASH). Each subsequent definition creates a new key and value in the hash array. alias l="ls -CF" alias h="history" A reference to the hash is returned when the variable is requested. my $aliases = $config->alias(); foreach my $k (keys %$aliases) { print "$k => $aliases->{ $k }\n"; } The '-' prefix can be used to reset a variable to its default value and the '+' prefix can be used to set it to 1 -verbose +debug Variable, environment variable and tilde (home directory) expansions 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 for each variable or the GLOBAL EXPAND value. 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 *Note AppConfig/State: AppConfig/State, for more information on expanding variable values. The configuration files may have variables arranged in blocks. A block header, consisting of the block name in square brackets, introduces a configuration block. The block name and an underscore are then prefixed to the names of all variables subsequently referenced in that block. The block continues until the next block definition or to the end of the current file. [block1] foo = 10 # block1_foo = 10 [block2] foo = 20 # block2_foo = 20 PARSING COMMAND LINE OPTIONS ---------------------------- There are two methods for processing command line options. The first, args(), is a small and efficient implementation which offers basic functionality. The second, getopt(), offers a more powerful and complete facility by delegating the task to Johan Vroman's Getopt::Long module. The trade-off between args() and getopt() is essentially one of speed/size against flexibility. Use as appropriate. Both implement on-demand loading of modules and incur no overhead until (unless) used. The args() method is used to parse simple 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. The method should be passed a reference to a list of arguments to parse. The @ARGV array is used if args() is called without parameters. $config->args(\@myargs); $config->args(); # uses @ARGV Arguments are read and shifted from the array until the first is encountered that is not prefixed by '-' or '-'. At that point, the method returns 1 to indicate success, leaving the remaining arguments remaining in the list. Each argument should be the name or alias of a variable prefixed by '-' or '-'. Arguments that are not prefixed as such (and are not an additional parameter to a previous argument) will cause a warning to be raised. If the PEDANTIC option is set, the method will return 0 immediately. With PEDANTIC unset (default), the method will continue to parse the rest of the arguments, returning 0 when done. If the variable is a simple flag (ARGCOUNT = ARGCOUNT_NONE) then it is set to the value 1. The variable may be prefixed by "no" to set its value to 0. myprog -verbose --debug -notaste # $config->verbose(1) # $config->debug(1) # $config->taste(0) Variables that expect an additional argument (ARGCOUNT != 0) will be set to the value of the argument following it. myprog -f /tmp/myfile # $config->file('/tmp/file'); Variables that expect multiple values (ARGCOUNT = ARGCOUNT_LIST or ARGCOUNT_HASH) will have sucessive values added each time the option is encountered. myprog -file /tmp/foo -file /tmp/bar # $config->file('/tmp/foo') # $config->file('/tmp/bar') # file => [ '/tmp/foo', '/tmp/bar' ] myprog -door "jim=Jim Morrison" -door "ray=Ray Manzarek" # $config->door("jim=Jim Morrison"); # $config->door("ray=Ray Manzarek"); # door => { 'jim' => 'Jim Morrison', 'ray' => 'Ray Manzarek' } See *Note AppConfig/Args: AppConfig/Args, for further details on parsing command line arguments. The getopt() method provides a way to use the power and flexibility of the Getopt::Long module to parse command line arguments and have the internal values of the AppConfig object updates automatically. The first (non-list reference) parameters may contain a number of configuration string to pass to Getopt::Long::Configure. A reference to a list of arguments may additionally be passed or @ARGV is used by default. $config->getopt(); # uses @ARGV $config->getopt(\@myargs); $config->getopt(qw(auto_abbrev debug)); # uses @ARGV $config->getopt(qw(debug), \@myargs); See Getopt::Long for details of the configuartion options available. The getopt() method constructs a specification string for each internal variable and then initialises Getopt::Long with these values. The specification string is constructed from the name, any aliases (delimited by a vertical bar '|') and the value of the ARGS parameter. $config->define("foo", { ARGS => "=i", ALIAS => "bar|baz", }); # Getopt::Long specification: "foo|bar|baz=i" Errors and warning generated by the Getopt::Long module are trapped and handled by the AppConfig error handler. This may be a user-defined routine installed with the ERROR configuration option. Please note that the AppConfig::Getopt interface is still experimental and may not be 100% operational. This is almost undoubtedly due to problems in AppConfig::Getopt rather than Getopt::Long. CONSTANT DEFINITIONS ==================== A number of constants are defined by the AppConfig module. These may be accessed directly (e.g. AppConfig::EXPAND_VARS) or by first importing them into the caller's package. Constants are imported by specifying their names as arguments to `use AppConfig' or by importing a set of constants identified by its "tag set" name. use AppConfig qw(ARGCOUNT_NONE ARGCOUNT_ONE); use AppConfig qw(:argcount); The following tag sets are defined: :expand The ':expand' tagset defines the following constants: EXPAND_NONE EXPAND_VAR EXPAND_UID EXPAND_ENV EXPAND_ALL # EXPAND_VARS | EXPAND_UIDS | EXPAND_ENVS EXPAND_WARN See AppConfig::File for full details of the use of these constants. :argcount The ':argcount' tagset defines the following constants: ARGCOUNT_NONE ARGCOUNT_ONE ARGCOUNT_LIST ARGCOUNT_HASH See AppConfig::State for full details of the use of these constants. AUTHOR ====== Andy Wardley, `', http://www.kfs.org/~abw/ Web Technology Group, Canon Research Centre Europe Ltd. REVISION ======== $Revision: 1.52 $ 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, AppConfig::Getopt, Getopt::Long