Help-Site Computer Manuals
Software
Hardware
Programming
Networking
  Algorithms & Data Structures   Programming Languages   Revision Control
  Protocols
  Cameras   Computers   Displays   Keyboards & Mice   Motherboards   Networking   Printers & Scanners   Storage
  Windows   Linux & Unix   Mac

Config::Generic
Sophisticated Config Parsing Module

Config::Generic - Sophisticated Config Parsing Module


NAME

Config::Generic - Sophisticated Config Parsing Module


SYNOPSIS


 use Config::Generic;

 # load $grammar from somewhere

 $parser = new Config::Generic($grammar);

 # load $text with user configuration

 my $config = $parser->parse($text);

 # Use tied hash interface

 my $chash;

 tie $chash, "Config::Generic::TieWrapper", {

     Config => $config,

     HashNamedSections => 1,

     TiedDirectives => 0 };

 # Read an option

 if($config->{CreateBackups} eq "true") {

     ...

 # Access a section

 my $block = $config->{Colors};

 print $block->{Titlebar};

 print $block->{Background};


ABSTRACT

This module parses and verifies configuration files for you. The format of config files supported by Config::Generic is inspired by the well known apache config format. Additional features are advanced syntactic verification using a specfile, here-documents and flexible access methods.


DESCRIPTION

The new method requires one parameter that must contain a grammar specification to verify the configuration. The parse method parses the given text and ensures the syntax described by the grammarfile. The parse method returns a configuration object of type Config::Generic::UnnamedSection. This object can be used to access the configuration. (see the Config::Generic::Section manpage for details).

Using Config::Generic::TieWrapper you can tie an hash to the configuration. You can than access the configuration is if it were stored in an anonymous hash/array structure instead of the object orientated interface.

The format of config files supported by Config::Generic is inspired by the well known apache config format, in fact, this module is 100% compatible to apache configs, but you can also just use simple name/value pairs in your config files.

In addition to the capabilities of an apache config file it supports some enhancements such as here-documents and syntactic verification based on templates.


METHODS

new($grammar)
This method returns a Config::Generic object, initialized to parse a configuration file conforming to $grammar.

parse(text)
Parses and verifies the given text. Returns a Config::Generic::UnnamedSection Object containing the configuration.

text can also be a scalar reference.

verify($config, $spec)
Verifies the configuration $config using $spec. $spec must be a parsed specification of type Config::Generic::Section.

You should not need to call this method directly, it is called by parse().


CONFIG FILE FORMAT

Lines begining with # and empty lines will be ignored. Whitespace at the begining and the end of a line will also be ignored.

Directives

A directive starts with it's name followed by one or more arguments. An equalsign is optional. The arguments are separated by whitespace and an optimal comma ,. If you need commas or whitespace as part of an argument, you have to quote it using `` or '.

Some possible examples:


 user    max

 password  = mfox

 Sisters = Tina, Hanni, Nanni

 user "second value"

Sections

You can define a section of directives. A section looks much like a section in the wellknown apache config format. It starts with <sectionname> and ends with </sectionname>. An example:


 <database>

    host   = muli

    user   = moare

    dbname = modb

    dbpass = D4r_9Iu

 </database>

Sections can also be nested. Here is a more complicated example:


 user   = hans

 passwd = D3rf$

 <jonas>

        user    = tom

        db      = unknown

        <tablestructure>

                index   int(100000)

                allowed ingram

                allowed joice

        </tablestructure>

 </jonas>

Named Sections

You can also specify sections with an argument, called ``Named Sections'':


 <Directory /usr/frisco>

        Limit Deny

        Options ExecCgi Index

 </Directory>

 <Directory /usr/frik>

        Limit DenyAll

        Options None

 </Directory>

You cannot have more than one named block with the same name and argument.

Named sections are always allowed multiple times -- anything else wouldn't make sense.

Here Documents

You can also define a config value as a so called ``here-document''. You must tell the module an identifier which identicates the end of a here document. An identifier must follow a ``<<''.

Example:


 message <<EOF

   we want to

   remove the

   homedir of

   root.

 EOF

Everything between the two ``EOF'' strings will be in the option message.


THE CONFIG SPECIFICATION

The config specification specifies the format of the configuration file you want to parse. The specification is written in the same language as the configuration itself.

Example:


 SingleDirective user /\w+/

 MultiDirective alias /w+/

 <SingleSection home>

     SingleDirective street /\w+/

     SingleDirective number /\d+/

 </SingleSection>

 RequiredDirectives user

This specification describes a configuration file with 6 allowed elements. On ``top level'' you can use the directives user and alias, both accept one argument conforming to the regular expression \w+. The user directive is allowed only once, the alias directive can be specified multiple times. While the alias directive can be omitted, the user directive is required.

There is also a section named home allowed. It can be specified zero or one times and doesn't accept an argument. Inside the section, the directives street and number are accepted.

Each allowed directive and section in the specification is now explained in detail:

SingleDirective

This directive can be specified anywhere. It describes a directive that is allowed once in the current nesting level.

SingleDirective accepts an unlimited number auf arguments. The first argument is the name of the described directive. The following arguments are regular expressions, one for each required parameter of the described directive (a parameter of the described directive must match the corresponding regular expression).

The special ``re'' optional specifies, that the following arguments can be omitted in the described directive.

The special ``re'' etc specifies, that the following last described argument can be repeated endlessly.

MultiDirective

This directive can be specified anywhere. It describes a directive that is allowed multiple times in the current nesting level.

Look at SingleDirective for a description of the arguments.

RequiredDirectives

This directive can be specified anywhere. It specifies other directives that must be present inside the current nesting level.

RequiredSections

This directive can be specified anywhere. It specifies sections that must be present inside the current nesting level.

<MultiSection name>

This named section specifies an unnamed section name that can be specified multiple times inside the current nesting level.

You can use all described sections and directives except MetaSection inside this section to specify the allowed content of the section.

<SingleSection name>

This named section specifies an unnamed section name that can be specified once inside the current nesting level.

You can use all described sections and directives except MetaSection inside this section to specify the allowed content of the section.

<NamedSection name>

This named section specifies an named section name that can be specified once (or multiple times with different arguments, of course) inside the current nesting level.

You can use all described sections and directives except MetaSection inside this section to specify the allowed content of the section.

<MetaSection name>

This named section specifies a ``meta'' section named name. It must be used top-level, outside from any section. It doesn't specify an element in the described configuration. Instead, the meta section can be referenced inside the specification to avoid duplicate code (when sections with different names must contain the same elements) and to implement recursion.

A meta section can be referenced with MultiSectionRef, SingleSectionRef and NamedSectionRef.

You can use all described sections and directives except MetaSection itself inside this section to specify the allowed content of the section.

Here is an example that specifies two Sections that both must contain one directive with a numeric argument:


 <MetaSection numeric>

     SingleDirective number /\d+/

     RequiredDirectives number

 </MetaSection>

 SingleSectionRef section1 numeric

 SingleSectionRef section2 numeric

And here is an example to allow infinite nesting:


 <MetaSection nested>

     NamedSectionRef section nested

     SingleDirective flag /(true|false)/

 </MetaSection>

 NamedSectionRef section nested

A valid configuration file for this specification could be:


 <section outer>

     flag true

     <section inner1>

         flag false

     </section>

     <section inner2>

         <section deepInside>

              flag true

         </section>

     </section>

 </section>

MultiSectionRef

This directive can be specified anywhere. It specifies an unnamed section that can be used multiple times inside the current nesting level.

While MultiSection uses a Section to define a section, MultiSectionRef expects the name of a meta section as its second argument. The first argument must be the name of the described section.

SingleSectionRef

This directive can be specified anywhere. It specifies an unnamed section that can be used once inside the current nesting level.

While SingleSection uses a Section to define a section, SingleSectionRef expects the name of a meta section as its second argument. The first argument must be the name of the described section.

NamedSectionRef

This directive can be specified anywhere. It specifies a named section that can be used inside the current nesting level.

While NamedSection uses a Section to define a section, NamedSectionRef expects the name of a meta section as its second argument. The first argument must be the name of the described section.

The spec in the spec

The specification format can be expressed in its own. Here it is, be proud when you can understand it :-)


 MultiDirective SingleDirective /\w+/ /(etc|optional|\/.+\/i?)/ etc

 MultiDirective MultiDirective /\w+/ /(etc|optional|\/.+\/i?)/ etc

 SingleDirective RequiredDirectives /w+/ etc

 SingleDirective RequiredSections /w+/ etc

 MultiSectionRef MultiSection section

 MultiSectionRef SingleSection section

 MultiSectionRef NamedSection section

 NamedSectionRef MetaSection section

 <MetaSection section>

     MultiDirective SingleDirective /\w+/ /\/.+\/i?/ optional /(etc|optional|\/.+\/i?)/ etc

     MultiDirective MultiDirective /\w+/ /\/.+\/i?/ optional /(etc|optional|\/.+\/i?)/ etc

     SingleDirective RequiredDirectives /w+/ etc

     SingleDirective RequiredSections /w+/ etc

     MultiSectionRef MultiSection section

     MultiSectionRef SingleSection section

     MultiSectionRef NamedSection section

     MultiDirective MultiSectionRef /w+/ /w+/

     MultiDirective SingleSectionRef /w+/ /w+/

     MultiDirective NamedSectionRef /w+/ /w+/

 </MetaSection>

Ok, there are still some caveeats that are checked ``manually'':

1. Each *SectionRef must have a corresponding MetaSection.

2. The regular expression for identifies (section and directive names) is slightly more complex than shown here.

3. You must not specify etc before <optional> in the parameter specification.

4. You must insert at least one ``regular parameter'' between optional and etc


BUGS

None known yet. But they probably exist because the module is very new and untested. So please report anything suspecious you find.


TODO

Take a look at the sources and fix everything mentioned as TODO in the comments.

Implement more sanity checks of the config specification (the 4 mentioned above aren't checked yet)

Implement references to parameter specifications in the configuration (similar to section references).


SEE ALSO

the Config::Generic::Element manpage, the Config::Generic::Section manpage, the Config::Generic::Directive manpage, the Config::Generic::UnnamedSection manpage, the Config::Generic::NamedSection manpage, the Config::Generic::TieWrapper manpage, the Config::Generic::Parser manpage


AUTHOR

Nikolaus Rath, <Nikolaus@rath.org>


COPYRIGHT AND LICENSE

Copyright 2003 by Nikolaus Rath

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Programminig
Wy
Wy
yW
Wy
Programming
Wy
Wy
Wy
Wy