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.

3 files changed, 320 insertions, 20 deletions

diff --git a/lib/Config/Parser.pm b/lib/Config/Parser.pm
index 7d20aa2..17a3cd0 100644
--- a/lib/Config/Parser.pm
+++ b/lib/Config/Parser.pm
@@ -31,14 +31,19 @@ sub new {
     } else {
         $self->lexicon({ '*' => '*' });
         my $subs = Class::Inspector->subclasses(__PACKAGE__);
+        my $dict;
         if ($subs) {
             foreach my $c (@$subs) {
                 if (my ($file, $line, $data) = $c->findsynt) {
-                    $self->loadsynt($file, $line, $data);
+                    my $d = $self->loadsynt($file, $line, $data);
+                    if ($d) {
+                        $dict = { %{$dict // {}}, %$d }
+                    }
                 }
                 last if $c eq $class;
             }
         }
+        $self->lexicon($dict) if $dict;
     }
 
     $self->init;
@@ -85,16 +90,14 @@ sub loadsynt {
                  line => $line)
         or croak "Failed to parse template at $file:$line";
     close $fh;
-    $self->lexicon({
-        %{$self->lexicon // {}},
-        %{$self->as_hash(sub {
+
+    my @sections;
+    my $lex = $self->as_hash(sub {
             my ($what, $name, $val) = @_;
             $name = '*' if $name eq 'ANY';
             if ($what eq 'section') {
                 $val->{section} = {};
-                if ($name =~ s/:mandatory$//) {
-                    $val->{mandatory} = 1;
-                }
+                push @sections, $val;
                 ($name, $val->{section});
             } else {
                 my @words = parse_line('\s+', 0, $val);
@@ -103,12 +106,12 @@ sub loadsynt {
 
                 if ($val eq 'STRING') {
                     # nothing
-                } elsif ($val eq 'NUMBER') {
-                    $ret->{re} = '\d+';
+                } elsif ($val eq 'NUMBER' || $val eq 'DECIMAL') {
+                    $ret->{re} = '^\d+$';
                 } elsif ($val eq 'OCTAL') {
-                    $ret->{re} = '[0-7]+';
+                    $ret->{re} = '^[0-7]+$';
                 } elsif ($val eq 'HEX') {
-                    $ret->{re} = '([0-9][A-Fa-f])+';
+                    $ret->{re} = '^([0-9][A-Fa-f])+$';
                 } else {
                     unshift @words, $val;
                 }
@@ -127,7 +130,16 @@ sub loadsynt {
                 }
                 ($name, $ret);
             }
-      })->{section}}});
+      })->{section};
+    # Process eventual __options__ keywords
+    foreach my $s (@sections) {
+        if (exists($s->{section}{__options__})) {
+            @{$s}{keys %{$s->{section}{__options__}}}
+                       = values %{$s->{section}{__options__}};
+            delete $s->{section}{__options__};
+        }
+    }
+    return $lex;
 }
 
 1;
@@ -143,7 +155,7 @@ parsers.  It is an intermediate layer between the abstract syntax tree
 (B<Config::AST>) and implementation of a parser for a particular
 configuration file format.
 
-It takes a I<define by example> approach.  That means that the implementor
+It takes a I<define by example> approach.  That means that the implementer
 creates a derived class that implements a parser on top of B<Config::Parser>.
 Application writers write an example of configuration file in the B<__DATA__>
 section of their application, which defines the statements that are allowed
@@ -158,11 +170,12 @@ delimited by newlines.  Leading and trailing whitespace characters on a line
 are ignored as well as are empty lines.  Comments begin with a hash sign and
 end with a newline.
 
-You create the class B<Config::Parser::KV> based on B<Config::Parser>.  The
-method B<parser> in this class implements the actual parser.
+You create the class, say B<Config::Parser::KV>, inherited from
+B<Config::Parser>.  The method B<parser> in this class implements the actual
+parser.
 
 Application writer decides what keywords are allowed in a valid configuration
-file and what are their values and puts them forth in the B<__DATA__> section
+file and what are their values and describes them in the B<__DATA__> section
 of his program (normally in a class derived from B<Config::Parser::KV>, in
 the same format as the actual configuration file.  For example:
 
@@ -216,7 +229,9 @@ Creates a new parser object.  Keyword arguments are:
 
 =item B<filename>
 
-Name of the file to parse.  This keyword must be present.
+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>
 
@@ -239,13 +254,13 @@ the B<Config::AST> constructor for details.
 
 =head1 USER HOOKS
 
-These are the methods provided for implementors to do any implementation-
+These are the methods provided for implementers to do any implementation-
 specific tasks.  Default implementations are empty placeholders.
 
 =head2 $cfg->init
 
 Called after creation of the base object, when parsing of the syntax
-definition has finished.  Implementors can use it to do any
+definition has finished.  Implementers can use it to do any
 implementation-specific initialization.
 
 =head2 $cfg->mangle
@@ -283,6 +298,116 @@ Finalizes the syntax tree.  Returns true on success, and false on errors.
 
 =head1 SYNTAX DEFINITION
 
+Syntax definition is a textual description of statements allowed in
+a configuration file.  It is written in the format of the configuration
+file itself and is parsed using the same object (derivative of
+B<Config::Parser>) that will be used later to parse the actual configuration.
+
+Syntax definitions are gathered from the B<__DATA__> blocks of 
+subclasses of B<Config::Parser>.
+
+In a syntax definition the value of each statement consists of optional
+data type followed by zero or more options delimited with whitespace.
+
+Valid data types are:
+
+=over 4
+
+=item B<STRING>
+
+String value.
+
+=item B<NUMBER> or B<DECIMAL>
+
+Decimal number.
+
+=item B<OCTAL>
+
+Octal number.
+
+=item B<HEX>
+
+Hex number.
+
+=back
+
+If the data type is omitted, no checking is performed unless specified
+otherwise by other options (see the B<:re> and B<:check> options below).
+
+Options are special names prefixed with a colon.  Option names follow
+the keywords from the B<Config::AST> keyword lexicon value.  An option 
+can be followed by an equals sign and its value.  If an option is used
+without arguments, the value B<1> is implied.
+
+Any word not recognized as an option or its value starts the I<default
+value>.
+
+Available options are described below:
+
+=over 4
+
+=item B<:mandatory>
+
+Marks the statement as a mandatory one.  If such a statement is missing from
+the configuration file, the parser action depends on whether the default value
+is supplied.  If it is, the statement will be inserted in the parse tree with
+the default value.  Otherwise, a diagnostic message will be printed and the
+constructor will return B<undef>.
+
+=item B<:default>
+