/ 
Config-Parser-1.05
River stage one • 3 direct dependents • 3 total dependents
/ Config::Parser::Ini

NAME

Config::Parser::Ini - configuration file parser for ini-style files

SYNOPSIS

$cfg = new Config::Parser::Ini($filename);

$val = $cfg->get('dir', 'tmp');

print $val->value;

print $val->locus;

$val = $cfg->tree->Dir->Tmp;

DESCRIPTION

An ini-style configuration file is a textual file consisting of settings grouped into one or more sections. A setting has the form

KEYWORD = VALUE

where KEYWORD is the setting name and VALUE is its value. Syntactically, VALUE is anything to the right of the equals sign and up to the linefeed character terminating the line (ASCII 10), not including the leading and trailing whitespace characters.

Each setting occupies one line. Very long lines can be split over several physical lines by ending each line fragment except the last with a backslash character appearing right before the linefeed character.

A section begins with a section declaration in the following form:

[NAME NAME...]

Here, square brackets form part of the syntax. Any number of NAMEs can be present inside the square brackets. The first NAME must follow the usual rules for a valid identifier name. Rest of NAMEs can contain any characters, provided that any NAME that includes non-alphanumeric characters is enclosed in a pair of double-quotes. Any double-quotes and backslash characters appearing within the quoted string must be escaped by prefixing them with a single backslash.

The Config::Parser::Ini module is a framework for parsing such files.

In the simplest case, the usage of this module is as simple as in the following fragment:

use Config::Parser::Ini;
my $cf = new Config::Parser::Ini(filename => "config.ini");

On success, this returns a valid Config::Parser::Ini object. On error, the diagnostic message is issued using the error method (see the description of the method in Config::AST(3)) and the module croaks.

This usage, although simple, has one major drawback - no checking is performed on the input file, except for the syntax check. To fix this, you can supply a dictionary (or lexicon) of allowed keywords along with their values. Such a dictionary is itself a valid ini file, where the value of each keyword describes its properties. The dictionary is placed in the __DATA__ section of the source file which invokes the Config::Parser::Ini constructor.

Expanding the example above:

use Config::Parser::Ini;
my $cf = new Config::Parser::Ini(filename => "config.ini");

__DATA__
[core]
   root = STRING :default /
   umask = OCTAL
[user]
   uid = NUMBER
   gid = NUMBER

This code specifies that the configuration file can contain at most two sections: [core] and [user]. Two keywords are defined within each section. Data types are specified for each keyword, so the parser will bail out in case of type mismatches. If the core.root setting is not present in the configuration, the default one will be created with the value /.

It is often advisable to create a subclass of Config::Parser::Ini and use it for parsing. For instance:

package App::MyConf;
use Config::Parser::Ini;
1;
__DATA__
[core]
   root = STRING :default /
   umask = OCTAL
[user]
   uid = NUMBER
   gid = NUMBER

Then, to parse the configuration file, it will suffice to do:

$cf = my App::MyConf(filename => "config.ini");

One advantage of this approach is that it will allow you to install additional validation for the configuration statements using the :check option. The argument to this option is the name of a method which will be invoked after parsing the statement in order to verify its value. It is described in detail below (see the section SYNTAX DEFINITION in the documentation of Config::Parser). For example, if you wish to ensure that the value of the root setting in core section points to an existing directory, you would do:

package App::MyConf;
use Config::Parser::Ini;

sub dir_exists {
    my ($self, $valref, $prev_value, $locus) = @_;

    unless (-d $$valref) {
        $self->error("$$valref: directory does not exist",
                     locus => $locus);
        return 0;
    }
    return 1;
}
1;
__DATA__
[core]
   root = STRING :default / :check=dir_exists
   umask = OCTAL
[user]
   uid = NUMBER
   gid = NUMBER

CONSTRUCTOR

$cfg = new Config::Parser::Ini(%opts)

Creates a new parser object. Keyword arguments are:

filename

Name of the file to parse. If not supplied, you will have to call the $cfg->parse method explicitly after you are returned a valid $cfg.

line

Optional line where the configuration starts in filename. It is used to keep track of statement location in the file for correct diagnostics. If not supplied, 1 is assumed.

fh

File handle to read from. If it is not supplied, new handle will be created by using open on the supplied filename.

lexicon

Dictionary of allowed configuration statements in the file. You will not need this parameter. It is listed here for completeness sake. Refer to the Config::AST constructor for details.

METHODS

All methods are inherited from Config::Parser. Please see its documentation for details.

SEE ALSO

Config::Parser(3), Config::AST(3).