appconfig::file(3)

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 configura
tion 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 App Config module and create an AppConfig::File object through the file() method.
AppConfig::File is implemented using object-oriented meth ods. A new AppConfig::File object is created and ini tialised 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 AppCon fig::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 pro cessed all files, the method will return 1 if all files were processed without warning or 0 if one or more warn ings 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 AppCon fig::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 novem; ber oscar papa quebec romeo sierra tango; umbrella victor whiskey x-ray yankee zebra
Variables that are simple flags and do not expect an argu ment (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 clar ity.: room = /home/kitchen
room /home/bedroom
Each subsequent re-definition of the variable value over writes 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 vari able 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 }0;; }
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 EX; PAND_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 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 defini tion or to the end of the current file.: [block1]
foo = 10 # block1_foo = 10; [block2]
foo = 20 # block2_foo = 20

AUTHOR

Andy Wardley, "<abw@cre.canon.co.uk>"

Web Technology Group, Canon Research Centre Europe Ltd.

REVISION

$Revision: 1.52 $

COPYRIGHT

This module is free software; you can redistribute it
and/or modify it under the same terms as Perl itself.

docs.sk

comprehensive documentation repository

In section