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->read($file); # read config fileOVERVIEW
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 read() method is used to read a configuration file and have the contents update the STATE accordingly.
$cfgfile->read($file);Multiple files maye be specified and will be read in turn.
$cfgfile->read($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 AppConfig::State for more information on variable expansion.
CONFIGURATION FILE FORMAT
# TODO: describe
BLOCK DEFINITIONS
The AppConfig::File module supports the use of blocks within the configuration files it reads. 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 = 20AUTHOR
Andy Wardley, <abw@cre.canon.co.uk>
Web Technology Group, Canon Research Centre Europe Ltd.
REVISION
$Revision: 0.1 $
COPYRIGHT
Copyright (C) 1998 Canon Research Centre Europe Ltd. All Rights Reserved.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
SEE ALSO
AppConfig, AppConfig::State, AppConfig:Args, :AppConfig::Const