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.

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