AppConfig::File(3) User Contributed Perl Documentation 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 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 App-
Config::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 PEDAN-
TIC 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 AppConfig::State for
more information on variable expansion.
CONFIGURATION FILE FORMAT
A configuration file may contain blank lines and comments which are ignored. Comments
begin with a '#' as the first character on a line or following one or more whitespace
tokens, and continue to the end of the line.
# this is a comment
foo = bar # so is this
url = index.html#hello # this too, but not the '#welcome'
Notice how the '#welcome' part of the URL is not treated as a comment because a whitespace
character doesn't precede it.
Long lines can be continued onto the next line by ending the first line with a '\'.
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 spec-
ified 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 fol-
lows 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 sub-
sequent 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";
}
A large chunk of text can be defined using Perl's "heredoc" quoting style.
scalar = <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, <>
COPYRIGHT
Copyright (C) 1997-2007 Andy Wardley. 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
perl v5.8.8 2007-05-30 AppConfig::File(3)
|