summaryrefslogtreecommitdiffabout
path: root/lib/Config/Parser
authorSergey Poznyakoff <gray@gnu.org.ua>2019-08-20 13:02:08 (GMT)
committer Sergey Poznyakoff <gray@gnu.org.ua>2019-08-20 13:02:08 (GMT)
commitb3d1cf2fb648f77a6ea432486ba2a8f026068f11 (patch) (side-by-side diff)
tree97e6450c863b478ec62bb25134e86e6434705e1a /lib/Config/Parser
parente9f110af920cf4e6642bc3301340b23a7a2a6589 (diff)
downloadconfig-parser-b3d1cf2fb648f77a6ea432486ba2a8f026068f11.tar.gz
config-parser-b3d1cf2fb648f77a6ea432486ba2a8f026068f11.tar.bz2
Provide a way for supplying options to section definition. Improve the docs
* lib/Config/Parser.pm (loadsynt): Return a reference to the reference hash. Process eventual __options__ keywords in sections. Finish documentation. * lib/Config/Parser/Ini.pm: Add documentation * t/ConfigSpec2.pm: Use the __options__ keyword.
Diffstat (limited to 'lib/Config/Parser') (more/less context) (ignore whitespace changes)
-rw-r--r--lib/Config/Parser/Ini.pm174
1 files changed, 174 insertions, 0 deletions
diff --git a/lib/Config/Parser/Ini.pm b/lib/Config/Parser/Ini.pm
index 0ea632c..79d231e 100644
--- a/lib/Config/Parser/Ini.pm
+++ b/lib/Config/Parser/Ini.pm
@@ -94,3 +94,177 @@ sub _readconfig {
1;
+=head1 NAME
+
+Config::Parser::Ini - configuration file parser for ini-style files
+
+=head1 SYNOPSIS
+
+$cfg = new Config::Parser::Ini($filename);
+
+$val = $cfg->get('dir', 'tmp');
+
+print $val->value;
+print $val->locus;
+
+$val = $cfg->tree->Dir->Tmp;
+
+=head1 DESCRIPTION
+
+An I<ini-style configuration file> is a textual file consisting of settings
+grouped into one or more sections. A I<setting> has the form
+
+ KEYWORD = VALUE
+
+where I<KEYWORD> is the setting name and I<VALUE> is its value.
+Syntactically, I<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 I<section> begins with a section declaration in the following form:
+
+ [NAME NAME...]
+
+Here, square brackets form part of the syntax. Any number of I<NAME>s
+can be present inside the square brackets. The first I<NAME> must follow the
+usual rules for a valid identifier name. Rest of I<NAME>s can contain any
+characters, provided that any I<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 B<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 B<Config::Parser::Ini> object. On error,
+the diagnostic message is issued using the B<error> method (see the description
+of the method in B<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 I<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 B<__DATA__>
+section of the source file which invokes the B<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: C<[core]> and C<[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 B<core.root> setting is not
+present in the configuration, the default one will be created with the
+value C</>.
+
+It is often advisable to create a subclass of B<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
+B<: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
+B<SYNTAX DEFINITION> in the documentation of B<Config::Parser>).
+For example, if you wish to ensure that the value of the C<root> setting
+in C<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
+
+=head1 CONSTRUCTOR
+
+ $cfg = new Config::Parser::Ini(%opts)
+
+Creates a new parser object. Keyword arguments are:
+
+=over 4
+
+=item B<filename>
+
+Name of the file to parse. If not supplied, you will have to
+call the B<$cfg-E<gt>parse> method explicitly after you are returned a
+valid B<$cfg>.
+
+=item B<line>
+
+Optional line where the configuration starts in B<filename>. It is used to
+keep track of statement location in the file for correct diagnostics. If
+not supplied, B<1> is assumed.
+
+=item B<fh>
+
+File handle to read from. If it is not supplied, new handle will be
+created by using B<open> on the supplied filename.
+
+=item B<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 B<Config::AST> constructor for details.
+
+=back
+
+=head1 METHODS
+
+All methods are inferited from B<Config::Parser>. Please see its
+documentation for details.
+
+=head1 SEE ALSO
+
+B<Config::Parser>(3), B<Config::AST>(3).
+
+=cut

Return to:

Send suggestions and report system problems to the System administrator.