This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: AppConfig/Args, Next: AppConfig/File, Prev: AppConfig, Up: Module List Perl5 module for reading command line arguments. ************************************************ NAME ==== AppConfig::Args - Perl5 module for reading command line arguments. SYNOPSIS ======== use AppConfig::Args; my $state = AppConfig::State->new(\%cfg); my $cfgargs = AppConfig::Args->new($state); $cfgargs->parse(\@args); # read args OVERVIEW ======== AppConfig::Args is a Perl5 module which reads command line arguments and uses the options therein to update variable values in an AppConfig::State object. AppConfig::File is distributed as part of the AppConfig bundle. DESCRIPTION =========== USING THE AppConfig::Args MODULE -------------------------------- To import and use the AppConfig::Args module the following line should appear in your Perl script: use AppConfig::Args; AppConfig::Args is used automatically if you use the AppConfig module and create an AppConfig::Args object through the parse() method. AppConfig::File is implemented using object-oriented methods. A new AppConfig::Args object is created and initialised using the new() method. This returns a reference to a new AppConfig::File object. A reference to an AppConfig::State object should be passed in as the first parameter: my $state = AppConfig::State->new(); my $cfgargs = AppConfig::Args->new($state); This will create and return a reference to a new AppConfig::Args object. PARSING COMMAND LINE ARGUMENTS ------------------------------ The parse() method is used to read a list of command line arguments and update the STATE accordingly. A reference to the list of arguments should be passed in. $cfgargs->parse(\@ARGV); If the method is called without a reference to an argument list then it will examine and manipulate @ARGV. If the PEDANTIC option is turned off in the AppConfig::State object, any parsing errors (invalid variables, unvalidated values, etc) will generate warnings, but not cause the method to return. Having processed all arguments, the method will return 1 if processed without warning or 0 if one or more warnings were raised. When the PEDANTIC option is turned on, the method generates a warning and immediately returns a value of 0 as soon as it encounters any parsing error. The method continues parsing arguments until it detects the first one that does not start with a leading dash, '-'. Arguments that constitute values for other options are not examined in this way. FUTURE DEVELOPMENT ================== This module was developed to provide backwards compatibility (to some degree) with the preceeding App::Config module. The argument parsing it provides is basic but offers a quick and efficient solution for those times when simple option handling is all that is required. If you require more flexibility in parsing command line arguments, then you should consider using the AppConfig::Getopt module. This is loaded and used automatically by calling the AppConfig getopt() method. The AppConfig::Getopt module provides considerably extended functionality over the AppConfig::Args module by delegating out the task of argument parsing to Johan Vromans' Getopt::Long module. For advanced command-line parsing, this module (either Getopt::Long by itself, or in conjunction with AppConfig::Getopt) is highly recommended. AUTHOR ====== Andy Wardley, `' Web Technology Group, Canon Research Centre Europe Ltd. REVISION ======== $Revision: 1.50 $ 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, AppConfig::State, AppConfig::Getopt, Getopt::Long  File: pm.info, Node: AppConfig/File, Next: AppConfig/Getopt, Prev: AppConfig/Args, Up: Module List Perl5 module for reading configuration files. ********************************************* NAME ==== AppConfig::File - Perl5 module for reading configuration files. SYNOPSIS ======== use AppConfig::File; my $state = AppConfig::State->new(\%cfg1); my $cfgfile = AppConfig::File->new($state, $file); $cfgfile->parse($file); # read config file OVERVIEW ======== AppConfig::File is a Perl5 module which reads configuration files and use the contents therein to update variable values in an AppConfig::State object. AppConfig::File is distributed as part of the AppConfig bundle. DESCRIPTION =========== USING THE AppConfig::File MODULE -------------------------------- To import and use the AppConfig::File module the following line should appear in your Perl script: use AppConfig::File; AppConfig::File is used automatically if you use the AppConfig module and create an AppConfig::File object through the file() method. AppConfig::File is implemented using object-oriented methods. A new AppConfig::File object is created and initialised using the AppConfig::File->new() method. This returns a reference to a new AppConfig::File object. A reference to an AppConfig::State object should be passed in as the first parameter: my $state = AppConfig::State->new(); my $cfgfile = AppConfig::File->new($state); This will create and return a reference to a new AppConfig::File object. READING CONFIGURATION FILES --------------------------- The parse() method is used to read a configuration file and have the contents update the STATE accordingly. $cfgfile->parse($file); Multiple files maye be specified and will be read in turn. $cfgfile->parse($file1, $file2, $file3); The method will return an undef value if it encounters any errors opening the files. It will return immediately without processing any further files. By default, the PEDANTIC option in the AppConfig::State object, $self->{ STATE }, is turned off and any parsing errors (invalid variables, unvalidated values, etc) will generated warnings, but not cause the method to return. Having processed all files, the method will return 1 if all files were processed without warning or 0 if one or more warnings were raised. When the PEDANTIC option is turned on, the method generates a warning and immediately returns a value of 0 as soon as it encounters any parsing error. Variables values in the configuration files may be expanded depending on the value of their EXPAND option, as determined from the App::State object. See *Note AppConfig/State: AppConfig/State, for more information on variable expansion. CONFIGURATION FILE FORMAT ------------------------- 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 AUTHOR ====== Andy Wardley, `' 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, AppConfig::State  File: pm.info, Node: AppConfig/Getopt, Next: AppConfig/MyFile, Prev: AppConfig/File, Up: Module List Perl5 module for processing command line arguments via delegation to Getopt::Long. ********************************************************************************** NAME ==== AppConfig::Getopt - Perl5 module for processing command line arguments via delegation to Getopt::Long. SYNOPSIS ======== use AppConfig::Getopt; my $state = AppConfig::State->new(\%cfg); my $getopt = AppConfig::Getopt->new($state); $getopt->parse(\@args); # read args OVERVIEW ======== AppConfig::Getopt is a Perl5 module which delegates to Johan Vroman's Getopt::Long module to parse command line arguments and update values in an AppConfig::State object accordingly. AppConfig::Getopt is distributed as part of the AppConfig bundle. DESCRIPTION =========== USING THE AppConfig::Getopt MODULE ---------------------------------- To import and use the AppConfig::Getopt module the following line should appear in your Perl script: use AppConfig::Getopt; AppConfig::Getopt is used automatically if you use the AppConfig module and create an AppConfig::Getopt object through the getopt() method. AppConfig::Getopt is implemented using object-oriented methods. A new AppConfig::Getopt is implemented using object-oriented methods. A new AppConfig::Getopt object is created and initialised using the new() method. This returns a reference to a new AppConfig::Getopt object. A reference to an AppConfig::State object should be passed in as the first parameter: my $state = AppConfig::State->new(); my $getopt = AppConfig::Getopt->new($state); This will create and return a reference to a new AppConfig::Getopt object. PARSING COMMAND LINE ARGUMENTS ------------------------------ The parse() method is used to read a list of command line arguments and update the state accordingly. The first (non-list reference) parameters may contain a number of configuration strings to pass to Getopt::Long::Configure. A reference to a list of arguments may additionally be passed or @ARGV is used by default. $getopt->parse(); # uses @ARGV $getopt->parse(\@myargs); $getopt->parse(qw(auto_abbrev debug)); # uses @ARGV $getopt->parse(qw(debug), \@myargs); See Getopt::Long for details of the configuartion options available. A Getopt::Long specification string is constructed for each variable defined in the AppConfig::State. This consists of the name, any aliases and the ARGS value for the variable. These specification string are then passed to Getopt::Long, the arguments are parsed and the values in the AppConfig::State updated. See AppConfig for information about using the AppConfig::Getopt module via the getopt() method. AUTHOR ====== Andy Wardley, `' Web Technology Group, Canon Research Centre Europe Ltd. ACKNOWLEDGMENTS =============== Many thanks are due to Johan Vromans for the Getopt::Long module. He was kind enough to offer assistance and access to early releases of his code to enable this module to be written. REVISION ======== $Revision: 1.51 $ 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, AppConfig::State, AppConfig::Args, Getopt::Long  File: pm.info, Node: AppConfig/MyFile, Next: AppConfig/State, Prev: AppConfig/Getopt, Up: Module List Perl5 module for reading configuration files. ********************************************* NAME ==== AppConfig::MyFile - Perl5 module for reading configuration files. SYNOPSIS ======== use AppConfig; my $appconfig = AppConfig->new(\%cfg); $appconfig->myfile($file, [$file...]) OVERVIEW ======== AppConfig::MyFile is a Perl5 module which... DESCRIPTION =========== USING THE AppConfig::File MODULE -------------------------------- To import and use the AppConfig::File module the following line should appear in your Perl script: use AppConfig::File; my $appconfig = AppConfig->new(); $appconfig->myfile($file); AUTHOR ====== Andy Wardley, `' Web Technology Group, Canon Research Centre Europe Ltd. REVISION ======== $Revision$ 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, AppConfig::State  File: pm.info, Node: AppConfig/State, Next: AppConfig/Std, Prev: AppConfig/MyFile, Up: Module List Perl5 module for maintaining the state of an application configuration. *********************************************************************** NAME ==== AppConfig::State - Perl5 module for maintaining the state of an application configuration. SYNOPSIS ======== use AppConfig::State; my $state = AppConfig::State->new(\%cfg); $state->define("foo"); # very simple variable definition $state->define("bar", \%varcfg); # variable specific configuration $state->define("foo|bar=i@"); # compact format $state->set("foo", 123); # trivial set/get examples $state->get("foo"); $state->foo(); # shortcut variable access $state->foo(456); # shortcut variable update OVERVIEW ======== AppConfig::State 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 other AppConfig::* modules. AppConfig::State is distributed as part of the AppConfig bundle. DESCRIPTION =========== USING THE AppConfig::State MODULE --------------------------------- To import and use the AppConfig::State module the following line should appear in your Perl script: use AppConfig::State; The AppConfig::State module is loaded automatically by the new() constructor of the AppConfig module. AppConfig::State is implemented using object-oriented methods. A new AppConfig::State object is created and initialised using the new() method. This returns a reference to a new AppConfig::State object. my $state = AppConfig::State->new(); This will create a reference to a new AppConfig::State with all configuration options set to their default values. You can initialise the object by passing a reference to a hash array containing configuration options: $state = AppConfig::State->new( { CASE => 1, ERROR => \&my_error, } ); The new() constructor of the AppConfig module automatically passes all parameters to the AppConfig::State new() constructor. Thus, any global configuration values and variable definitions for AppConfig::State are also applicable to AppConfig. The following configuration options may be specified. 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". CREATE By default, CREATE is turned off meaning that all variables accessed via set() (which includes access via shortcut such as `$state->variable($value)' which delegates to set()) must previously have been defined via define(). When CREATE is set to 1, calling set($variable, $value) on a variable that doesn't exist will cause it to be created automatically. When CREATE is set to any other non-zero value, it is assumed to be a regular expression pattern. If the variable name matches the regex, the variable is created. This can be used to specify configuration file blocks in which variables should be created, for example: $state = AppConfig::State->new( { CREATE => '^define_', } ); In a config file: [define] name = fred # define_name gets created automatically [other] name = john # other_name doesn't - warning raised Note that a regex pattern specified in CREATE is applied to the real variable name rather than any alias by which the variables may be accessed. PEDANTIC The PEDANTIC option determines what action the configuration file (AppConfig::File) or argument parser (AppConfig::Args) should take on encountering a warning condition (typically caused when trying to set an undeclared variable). If PEDANTIC is set to any true value, the parsing methods will immediately return a value of 0 on encountering such a condition. If PEDANTIC is not set, the method will continue to parse the remainder of the current file(s) or arguments, returning 0 when complete. If no warnings or errors are encountered, the method returns 1. In the case of a system error (e.g. unable to open a file), the method returns undef immediately, regardless of the PEDANTIC option. ERROR Specifies a user-defined error handling routine. When the handler is called, a format string is passed as the first parameter, followed by any additional values, as per printf(3C). DEBUG Turns debugging on or off when set to 1 or 0 accordingly. Debugging may also be activated by calling _debug() as an object method (`$state->_debug(1)') or as a package function (`AppConfig::State::_debug(1)'), passing in a true/false value to set the debugging state accordingly. The package variable $AppConfig::State::DEBUG can also be set directly. The _debug() method returns the current debug value. If a new value is passed in, the internal value is updated, but the previous value is returned. Note that any AppConfig::File or App::Config::Args objects that are instantiated with a reference to an App::State will inherit the DEBUG (and also PEDANTIC) values of the state at that time. Subsequent changes to the AppConfig::State debug value will not affect them. GLOBAL The GLOBAL option allows default values to be set for the DEFAULT, ARGCOUNT, EXPAND, VALIDATE and ACTION options for any subsequently defined variables. $state = AppConfig::State->new({ GLOBAL => { DEFAULT => '', # default value for new vars ARGCOUNT => 1, # vars expect an argument ACTION => \&my_set_var, # callback when vars get set } }); Any attributes specified explicitly when a variable is defined will override any GLOBAL values. See `DEFINING VARIABLES' in this node below which describes these options in detail. DEFINING VARIABLES ------------------ The define() function is used to pre-declare a variable and specify its configuration. $state->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: $state->define("foo", { DEFAULT => 99, ALIAS => 'metavar1', }); Any variable-wide GLOBAL values passed to the new() constructor in the configuration hash will also be applied. Values explicitly specified in a variable's define() configuration will override the respective GLOBAL values. The following configuration options may be specified DEFAULT The DEFAULT value is used to initialise the variable. $state->define("drink", { DEFAULT => 'coffee', }); print $state->drink(); # prints "coffee" 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 can be specified as a reference to an array of alternatives or as a string of names separated by vertical bars, '|'. e.g.: $state->define("name", { ALIAS => 'person', }); or $state->define("name", { ALIAS => [ 'person', 'user', 'uid' ], }); or $state->define("name", { ALIAS => 'person|user|uid', }); $state->user('abw'); # equivalent to $state->name('abw'); ARGCOUNT The ARGCOUNT option specifies the number of arguments that should be supplied for this variable. By default, no additional arguments are expected for variables (ARGCOUNT_NONE). The ARGCOUNT_* constants can be imported from the AppConfig module: use AppConfig ':argcount'; $state->define('foo', { ARGCOUNT => ARGCOUNT_ONE }); or can be accessed directly from the AppConfig package: use AppConfig; $state->define('foo', { ARGCOUNT => AppConfig::ARGCOUNT_ONE }); The following values for ARGCOUNT may be specified. ARGCOUNT_NONE (0) Indicates that no additional arguments are expected. If the variable is identified in a confirguration file or in the command line arguments, it is set to a value of 1 regardless of whatever arguments follow it. ARGCOUNT_ONE (1) Indicates that the variable expects a single argument to be provided. The variable value will be overwritten with a new value each time it is encountered. ARGCOUNT_LIST (2) Indicates that the variable expects multiple arguments. The variable value will be appended to the list of previous values each time it is encountered. ARGCOUNT_HASH (3) Indicates that the variable expects multiple arguments and that each argument is of the form "key=value". The argument will be split into a key/value pair and inserted into the hash of values each time it is encountered. ARGS The ARGS option can also be used to specify advanced command line options for use with AppConfig::Getopt, which itself delegates to Getopt::Long. See those two modules for more information on the format and meaning of these options. $state->define("name", { ARGS => "=i@", }); EXPAND The EXPAND option specifies how the AppConfig::File processor should expand embedded variables in the configuration file values it reads. By default, EXPAND is turned off (EXPAND_NONE) and no expansion is made. The EXPAND_* constants can be imported from the AppConfig module: use AppConfig ':expand'; $state->define('foo', { EXPAND => EXPAND_VAR }); or can be accessed directly from the AppConfig package: use AppConfig; $state->define('foo', { EXPAND => AppConfig::EXPAND_VAR }); The following values for EXPAND may be specified. Multiple values should be combined with vertical bars , '|', e.g. `EXPAND_UID | EXPAND_VAR'). EXPAND_NONE Indicates that no variable expansion should be attempted. EXPAND_VAR Indicates that variables embedded as $var or $(var) should be expanded to the values of the relevant AppConfig::State variables. EXPAND_UID Indicates that '~' or '~uid' patterns in the string should be expanded to the current users ($<), or specified user's home directory. EXPAND_ENV Inidicates that variables embedded as ${var} should be expanded to the value of the relevant environment variable. EXPAND_ALL Equivalent to `EXPAND_VARS | EXPAND_UIDS | EXPAND_ENVS'). EXPAND_WARN Indicates that embedded variables that are not defined should raise a warning. If PEDANTIC is set, this will cause the read() method to return 0 immediately. VALIDATE Each variable may have a sub-routine or regular expression defined which is used to validate the intended value for a variable before it is set. If VALIDATE is defined as a regular expression, it is applied to the value and deemed valid if the pattern matches. In this case, the variable is then set to the new value. A warning message is generated if the pattern match fails. 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. $state->define("age", { VALIDATE => '\d+', }); $state->define("pin", { VALIDATE => \&check_pin, }); ACTION The ACTION option allows a sub-routine to be bound to a variable as a callback that is executed whenever the variable is set. The ACTION is passed a reference to the AppConfig::State 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: $state->define("foo", { ACTION => \&my_notify }); sub my_notify { my $state = shift; my $var = shift; my $val = shift; print "$variable set to $value"; } $state->foo(42); # prints "foo set to 42" Be aware that calling `$state->set()' to update the same variable from within the ACTION function will cause a recursive loop as the ACTION function is repeatedly called. DEFINING VARIABLES USING THE COMPACT FORMAT ------------------------------------------- Variables may be defined in a compact format which allows any ALIAS and ARGS values to be specified as part of the variable name. This is designed to mimic the behaviour of Johan Vromans' Getopt::Long module. Aliases for a variable should be specified after the variable name, separated by vertical bars, '|'. Any ARGS parameter should be appended after the variable name(s) and/or aliases. The following examples are equivalent: $state->define("foo", { ALIAS => [ 'bar', 'baz' ], ARGS => '=i', }); $state->define("foo|bar|baz=i"); READING AND MODIFYING VARIABLE VALUES ------------------------------------- AppConfig::State 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. $state->set("verbose", 1); is equivalent to $state->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 result of the set() operation is returned. $state->age(29); # sets 'age' to 29, returns 1 (ok) INTERNAL METHODS ---------------- The interal (private) methods of the AppConfig::State class are listed below. They aren't intended for regular use and potential users should consider the fact that nothing about the internal implementation is guaranteed to remain the same. Having said that, the AppConfig::State class is intended to co-exist and work with a number of other modules and these are considered "friend" classes. These methods are provided, in part, as services to them. With this acknowledged co-operation in mind, it is safe to assume some stability in this core interface. The _varname() method can be used to determine the real name of a variable from an alias: $varname->_varname($alias); Note that all methods that take a variable name, including those listed below, can accept an alias and automatically resolve it to the correct variable name. There is no need to call _varname() explicitly to do alias expansion. The _varname() method will fold all variables names to lower case unless CASE sensititvity is set. The _exists() method can be used to check if a variable has been defined: $state->_exists($varname); The _default() method can be used to reset a variable to its default value: $state->_default($varname); The _expand() method can be used to determine the EXPAND value for a variable: print "$varname EXPAND: ", $state->_expand($varname), "\n"; The _argcount() method returns the value of the ARGCOUNT attribute for a variable: print "$varname ARGCOUNT: ", $state->_argcount($varname), "\n"; The _validate() method can be used to determine if a new value for a variable meets any validation criteria specified for it. The variable name and intended value should be passed in. The methods returns a true/false value depending on whether or not the validation succeeded: print "OK\n" if $state->_validate($varname, $value); The _pedantic() method can be called to determine the current value of the PEDANTIC option. print "pedantic mode is ", $state->_pedantic() ? "on" ; "off", "\n"; The _debug() method can be used to turn debugging on or off (pass 1 or 0 as a parameter). It can also be used to check the debug state, returning the current internal value of $AppConfig::State::DEBUG. If a new debug value is provided, the debug state is updated and the previous state is returned. $state->_debug(1); # debug on, returns previous value The _dump_var($varname) and _dump() methods may also be called for debugging purposes. $state->_dump_var($varname); # show variable state $state->_dump(); # show internal state and all vars AUTHOR ====== Andy Wardley, `' 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, AppConfig::File, AppConfig::Args, AppConfig::Getopt  File: pm.info, Node: AppConfig/Std, Next: AppConfig/Sys, Prev: AppConfig/State, Up: Module List subclass of AppConfig which provides standard options ***************************************************** NAME ==== AppConfig::Std - subclass of AppConfig which provides standard options SYNOPSIS ======== use AppConfig::Std; $config = AppConfig::Std->new(); # all AppConfig methods supported $config->define('foo'); # define variable foo $config->set('foo', 25); # setting a variable $val = $config->get('foo'); # getting variable $val = $config->foo(); # shorthand for getting $config->args(\@ARGV); # parse command-line $config->file(".myconfigrc") # read config file DESCRIPTION =========== *AppConfig::Std* is a Perl5 module which provides a set of standard configuration variables and command-line switches. It is implemented as a subclass of AppConfig, which provides a general mechanism for handling global configuration variables. The features provided by AppConfig::Std are: * Standard command-line arguments: -help, -doc, -version, -verbose, and -debug. These are described below. * The ARGCOUNT default is set to 1. This means that by default all switches are expected to take a value. To change this, set the ARGCOUNT parameter when defining the variable: $config->define('verbose', { ARGCOUNT => 0 } ); Please read the copious documentation for AppConfig to find out what else you can do with this module. STANDARD OPTIONS ================ The module adds five standard configuration variables and command-line switches. You can define additional variables as you would with AppConfig. HELP ---- The *-help* switch will result in a short help message. This is generated using Pod::Usage, which displays the OPTIONS section of your pod. The script will exit with an exit value of 0. DOC --- The *-doc* switch will result in the entire documentation being formatted to the screen. This is also done with Pod::Usage. The script will exit with an exit value of 0. VERSION ------- The *-version* switch will display the version of the invoking script. This assumes that you have defined $VERSION in your script with something like the following: use vars qw( $VERSION ); $VERSION = sprintf("%d.%02d", q$Revision: 1.3 $ =~ /(\d+)\.(\d+)/); The script will exit with an exit value of 0. DEBUG ----- The *-debug* switch just sets the debug variable. This is useful for displaying information in debug mode: $foobar->dump() if $config->debug; VERBOSE ------- The *-verbose* switch just sets the verbose variable. This is useful for displaying verbose information as a script runs: print STDERR "Running foobar\n" if $config->verbose; TODO ==== Please let me know if you have ideas for additional switches, or other modifications. Things currently being mulled: * Support brief switches, such as -h as well as *-help*. * Test-suite. * Include a sample script called *mkscript*, which would create a template script along with Makefile.PL, MANIFEST, etc. Kinda of a h2xs for scripts. EXAMPLE ======= The following is the outline of a simple script which illustrates use of the AppConfig::Std module: #!/usr/bin/perl -w use strict; use AppConfig::Std; use vars qw( $VERSION ); $VERSION = '1.0'; my $config = AppConfig::Std->new(); # parse command-line and handle std switches $config->args(\@ARGV); exit 0; __END__ =head1 NAME standard pod format documentation The pod documentation is expected to have the NAME, SYNOPSIS, DESCRIPTION, and OPTIONS sections. See the documentation for pod2man for more details. SEE ALSO ======== AppConfig Andy Wardley's module for unifying command-line switches and cofiguration files into the notion of configuration variables. AppConfig::Std requires version 1.52+ of the module, which is available from CPAN: http://www.cpan.org/modules/by-module/AppConfig/ Pod::Usage Brad Appleton's module for extracting usage information out of a file's pod. This is used for the *-doc* and *-help* switches. Available from CPAN: http://www.cpan.org/modules/by-module/Pod/ perlpod Documentation from the perl distribution which describes the pod format. pod2man Particularly the section in the documentation titled *Anatomy of a Proper Man Page*. AppConfig::Std uses Pod::Usage, which assumes well-formed pod. AUTHOR ====== Neil Bowers COPYRIGHT ========= Copyright (c) 1998-2001 Canon Research Centre Europe. All rights reserved. This script is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: AppConfig/Sys, Next: AppleII/Disk, Prev: AppConfig/Std, Up: Module List Perl5 module defining platform-specific information and methods for other AppConfig::* modules. *********************************************************************************************** NAME ==== AppConfig::Sys - Perl5 module defining platform-specific information and methods for other AppConfig::* modules. SYNOPSIS ======== use AppConfig::Sys; my $sys = AppConfig::Sys->new(); @fields = $sys->getpwuid($userid); @fields = $sys->getpwnam($username); OVERVIEW ======== AppConfig::Sys is a Perl5 module provides platform-specific information and operations as required by other AppConfig::* modules. AppConfig::Sys is distributed as part of the AppConfig bundle. DESCRIPTION =========== USING THE AppConfig::State MODULE --------------------------------- To import and use the AppConfig::Sys module the following line should appear in your Perl script: use AppConfig::Sys; AppConfig::Sys is implemented using object-oriented methods. A new AppConfig::Sys object is created and initialised using the AppConfig::Sys->new() method. This returns a reference to a new AppConfig::Sys object. my $sys = AppConfig::Sys->new(); This will attempt to detect your operating system and create a reference to a new AppConfig::Sys object that is applicable to your platform. You may explicitly specify an operating system name to override this automatic detection: $unix_sys = AppConfig::Sys->new("Unix"); Alternatively, the package variable $AppConfig::Sys::OS can be set to an operating system name. The valid operating system names are: Win, VMS, Mac, OS2 and Unix. They are not case-specific. AppConfig::Sys METHODS ---------------------- AppConfig::Sys defines the following methods: getpwnam() Calls the system function getpwnam() if available and returns the result. Returns undef if not available. The can_getpwnam() method can be called to determine if this function is available. getpwuid() Calls the system function getpwuid() if available and returns the result. Returns undef if not available. The can_getpwuid() method can be called to determine if this function is available. AUTHOR ====== Andy Wardley, `' Web Technology Group, Canon Research Centre Europe Ltd. REVISION ======== $Revision: 1.50 $ 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 term of the Perl Artistic License. SEE ALSO ======== AppConfig, AppConfig::File  File: pm.info, Node: AppleII/Disk, Next: AppleII/ProDOS, Prev: AppConfig/Sys, Up: Module List Block-level access to Apple II disk image files *********************************************** NAME ==== AppleII::Disk - Block-level access to Apple II disk image files SYNOPSIS ======== use AppleII::Disk; my $disk = AppleII::Disk->new('image.dsk'); my $data = $disk->read_block(1); # Read block 1 $disk->write_block(1, $data); # And write it back :-) DESCRIPTION =========== `AppleII::Disk' provides block-level access to the Apple II disk image files used by most Apple II emulators. (For information about Apple II emulators, try the Apple II Emulator Page at `http:' in this node.) For a higher-level interface, use the *Note AppleII/ProDOS: AppleII/ProDOS, module. `AppleII::Disk' provides the following methods: $disk = AppleII::Disk->new($filename, [$mode]) Constructs a new `AppleII::Disk' object. $filename is the name of the image file. The optional $mode is a string specifying how to open the image. It can consist of the following characters (*case sensitive*): r Allow reads (this is actually ignored; you can always read) w Allow writes d Disk image is in DOS 3.3 order p Disk image is in ProDOS order If you don't specify 'd' or 'p', then the format is guessed from the filename. '.PO' and '.HDV' files are ProDOS order, and anything else is assumed to be DOS 3.3 order. If you specify 'w' to allow writes, then the image file is created if it doesn't already exist. $size = $disk->blocks([$newsize]) Gets or sets the size of the disk in blocks. `$newsize' is the new size of the disk in blocks. If `$newsize' is omitted, then the size is not changed. Returns the size of the disk image in blocks. This refers to the *logical* size of the disk image. Blocks outside the physical size of the disk image read as all zeros. Writing to such a block will expand the image file. When you create a new image file, you must use blocks to set its size before writing to it. $contents = $disk->read_block($block) Reads one block from the disk image. $block is the block number to read. $contents = $disk->read_blocks(\@blocks) Reads a sequence of blocks from the disk image. `\@blocks' is a reference to an array of block numbers. $contents = $disk->read_sector($track, $sector) Reads one sector from the disk image. $track is the track number, and `$sector' is the DOS 3.3 logical sector number. This is currently implemented only for DOS 3.3 order images. $disk->write_block($block, $contents, [$pad]) Writes one block to the disk image. $block is the block number to write. $contents is the data to write. The optional `$pad' is a character to pad the block with (out to 512 bytes). If `$pad' is omitted or null, then $contents must be exactly 512 bytes. $disk->write_blocks(\@blocks, $contents, [$pad]) Writes a sequence of blocks to the disk image. `\@blocks' is a reference to an array of block numbers to write. $contents is the data to write. It is broken up into 512 byte chunks and written to the blocks. The optional `$pad' is a character to pad the data with (out to a multiple of 512 bytes). If `$pad' is omitted or null, then $contents must be exactly 512 bytes times the number of blocks. $disk->write_sector($track, $sector, $contents, [$pad]) Writes one sector to the disk image. $track is the track number, and `$sector' is the DOS 3.3 logical sector number. $contents is the data to write. The optional `$pad' is a character to pad the sector with (out to 256 bytes). If `$pad' is omitted or null, then $contents must be exactly 256 bytes. This is currently implemented only for DOS 3.3 order images. $padded = AppleII::Disk->pad_block($data, [$pad, [$length]]) Pads $data out to $length bytes with `$pad'. Returns the padded string; the original is not altered. Dies if $data is longer than $length. The default `$pad' is "\0", and the default $length is 512 bytes. If `$pad' is the null string (not undef), just checks to make sure that $data is exactly $length bytes and returns the original string. Dies if $data is not exactly $length bytes. `pad_block' can be called either as `AppleII::Disk->pad_block' or `$disk->pad_block'. AUTHOR ====== Christopher J. Madsen <`ac608@yfn.ysu.edu'>  File: pm.info, Node: AppleII/ProDOS, Next: Archive/Tar, Prev: AppleII/Disk, Up: Module List Access files on Apple II ProDOS disk images ******************************************* NAME ==== AppleII::ProDOS - Access files on Apple II ProDOS disk images SYNOPSIS ======== use AppleII::ProDOS; my $vol = AppleII::ProDOS->open('image.dsk'); # Open an existing disk print $vol->catalog; # List files in volume directory my $file = $vol->get_file('Startup'); # Read file from disk $vol->path('Subdir'); # Move into a subdirectory $vol->put_file($file); # And write it back there DESCRIPTION =========== `AppleII::ProDOS' provides high-level access to ProDOS volumes stored in the disk image files used by most Apple II emulators. (For information about Apple II emulators, try the Apple II Emulator Page at `http:' in this node.) It uses the *Note AppleII/Disk: AppleII/Disk, module to handle low-level access to image files. All the following classes have two constructors. Constructors named open are for creating an object to represent existing data in the image file. Constructors named new are for creating a new object to be added to an image file. `AppleII::ProDOS' ----------------- `AppleII::ProDOS' is the primary interface to ProDOS volumes. It provides the following methods: $vol = AppleII::ProDOS->new($volume, $size, $filename, [$mode]) Constructs a new image file and an `AppleII::ProDOS' object to access it. $volume is the volume name. $size is the size in blocks. $filename is the name of the image file. The optional $mode is a string specifying how to open the image (see the open method for details). You always receive read and write access. $vol = AppleII::ProDOS->open($filename, [$mode]) Constructs an `AppleII::ProDOS' object to access an existing image file. $filename is the name of the image file. The optional $mode is a string specifying how to open the image. It can consist of the following characters (*case sensitive*): r Allow reads (this is actually ignored; you can always read) w Allow writes d Disk image is in DOS 3.3 order p Disk image is in ProDOS order $vol = AppleII::ProDOS->open($disk) Constructs an `AppleII::ProDOS' object to access an existing image file. $disk is the `AppleII::Disk' object representing the image file. $bitmap = $vol->bitmap Returns the volume bitmap as an `AppleII::ProDOS::Bitmap' object. $dir = $vol->dir Returns the current directory as an AppleII::ProDOS::Directory object. $disk = $vol->disk Returns the `AppleII::ProDOS::Disk' object which represents the image file. $disk = $vol->disk_size Returns the size of the volume in blocks. This is the logical size of the ProDOS volume, which is not necessarily the same as the actual size of the image file. $name = $vol->name Returns the volume name. $path = $vol->path([$newpath]) Gets or sets the current path. `$newpath' is the new pathname, which may be either relative or absolute. `..' may be used to specify the parent directory, but this must occur at the beginning of the path (`../../dir' is valid, but `../dir/..' is not). If c<$newpath>> is omitted, then the current path is not changed. Returns the current path as a string beginning and ending with /. $catalog = $vol->catalog $file = $vol->get_file($filename) $entry = $vol->new_dir($name) $vol->put_file($file) These methods are passed to the current directory. See `AppleII::ProDOS::Directory' for details. `AppleII::ProDOS::Directory' ---------------------------- `AppleII::ProDOS::Directory' represents a ProDOS directory. It provides the following methods: $dir = AppleII::ProDOS::Directory->new($name, $disk, $blocks, $bitmap, [$parent, $parentNum]) Constructs a new `AppleII::ProDOS::Directory' object. $name is the name of the directory. $disk is the `AppleII::Disk' to create it on. `$blocks' is a block number or an array of block numbers to store the directory in. $bitmap is the `AppleII::ProDOS::Bitmap' representing the volume bitmap. For a subdirectory, `$parent' must be the block number in the parent directory where the subdirectory is listed, and `$parentNum' is the entry number in that block (with 1 being the first entry). $dir = AppleII::ProDOS->open($disk, $block, $bitmap) Constructs an `AppleII::ProDOS::Directory' object to access an existing directory in the image file. $disk is the `AppleII::Disk' object representing the image file. $block is the block number where the directory begins. $bitmap is the `AppleII::ProDOS::Bitmap' representing the volume bitmap. $catalog = $dir->catalog Returns the directory listing in ProDOS format with free space information. @entries = $dir->entries Returns the contents of the directory as a list of `AppleII::ProDOS::DirEntry' objects. $entry = $dir->find_entry($filename) Returns the `AppleII::ProDOS::DirEntry' object for $filename, or undef if the specified file does not exist. $file = $dir->get_file($filename) Retrieves a file from the directory. $filename may be either a filename or an `AppleII::ProDOS::DirEntry' object. Returns a new `AppleII::ProDOS::File' object. @entries = $dir->list_matches($pattern, [$filter]) Returns a list of the `AppleII::ProDOS::DirEntry' objects matching the regexp `$pattern'. If `$filter' is specified, it is either a subroutine reference or one of the strings 'DIR' or '!DIR'. 'DIR' matches only directories, and '!DIR' matches only regular files. If `$filter' is a subroutine, it is called (as `\&$filter($entry)') for each entry. It should return true if the entry is acceptable (the entry's name must still match `$pattern'). Returns the null list if there are no matching entries. $entry = $dir->new_dir($name) Creates a new subdirectory in the directory. $name is the name of the new subdirectory. Returns the `AppleII::ProDOS::DirEntry' object representing the new subdirectory entry. $entry = $dir->open_dir($dirname) Opens a subdirectory of the directory. `$dirname' may be either a subdirectory name or an `AppleII::ProDOS::DirEntry' object. Returns a new `AppleII::ProDOS::Directory' object. $dir->put_file($file) Stores a file in the directory. $file must be an `AppleII::ProDOS::File' object. $dir->add_entry($entry) Adds a new entry to the directory. $entry is an `AppleII::ProDOS::DirEntry' object. $dir->read_disk Rereads the directory contents from the image file. You can use this to undo changes to a directory before they have been written to the image file. $dir->write_disk Writes the current directory contents to the image file. You must use this if you alter the directory contents in any way except the high-level methods `new_dir' and put_file, which do this automatically. `AppleII::ProDOS::DirEntry' --------------------------- `AppleII::ProDOS::DirEntry' provides access to directory entries. It provides the following methods: $entry = AppleII::ProDOS::DirEntry->new([$num, $entry]) Constructs a new `AppleII::ProDOS::DirEntry' object. $num is the entry number in the directory, and $entry is the packed directory entry. If $num and $entry are omitted, then a blank directory entry is created. This is a low-level function; you shouldn't need to explicitly construct DirEntry objects. $packed_entry = $entry->packed($key_block) Return the directory entry in packed format. `$key_block' is the starting block number of the directory containing this entry. $access = $entry->access([$new]) Gets or sets the access attributes. This is a bitfield with the following entries: 0x80 File can be deleted 0x40 File can be renamed 0x20 File has changed since last backup 0x02 File can be written to 0x01 File can be read Normal values are 0xC3 or 0xE3 for an unlocked file, and 0x01 for a locked file. $auxtype = $entry->auxtype([$new]) Gets or sets the auxiliary type. This is a number between 0x0000 and 0xFFFF. Its meaning depends on the filetype. $creation_date = $entry->created([$date]) Gets or sets the creation date and time in ProDOS format. $modification_date = $entry->modified([$date]) Gets or sets the modification date and time in ProDOS format. $name = $entry->name([$new]) Gets or sets the filename. $type = $entry->type([$new]) Gets or sets the filetype. This is a number between 0x00 and 0xFF. Use `parse_type' to convert it to a more meaningful abbreviation. $type = $entry->short_type Returns the standard abbreviation for the filetype. It is equivalent to calling `AppleII::ProDOS::parse_type($entry->type)'. The following methods allow access to read-only fields. They can be used to initialize a DirEntry object created with new, but raise an exception if the field already has a value. $block = $entry->block([$new]) Gets or sets the key block for the file. $used = $entry->blks_used([$new]) Gets or sets the number of blocks used by the file. $entry_num = $entry->num([$new]) Gets or sets the entry number in the directory. $size = $entry->size([$new]) Gets or sets the size of the file in bytes. $storage = $entry->storage([$new]) Gets or sets the storage type. NOTE ==== This is the point where I ran out of steam in documentation writing. :-) If I get at least one email from someone who'd actually read the rest of this documentation, I'll try to finish it. `AppleII::ProDOS::File' ----------------------- `AppleII::ProDOS::File' represents a file's data and other attributes. `AppleII::ProDOS::Bitmap' ------------------------- `AppleII::ProDOS::Bitmap' represents the volume bitmap. `AppleII::ProDOS::Index' ------------------------ `AppleII::ProDOS::Index' represents an index block. BUGS ==== * This document isn't finished yet. I haven't been working on it recently, so I decided I might as well just release what I have. If somebody writes me, I'm more likely to finish. (That's a hint, folks.) * Mixed case filenames (ala GS/OS) are not supported. All filenames are converted to upper case. AUTHOR ====== Christopher J. Madsen <`ac608@yfn.ysu.edu'>