view release on metacpan or  search on metacpan

lib/App/Glacier/Config.pm  view on Meta::CPAN

will be loaded from the cache (using B<Storable>(3)), avoiding parsing
overhead.  Otherwise, the cached data will be discarded, and the source file
will be parsed as usual.

The destructor will first check if the configuration was updated, and if
so will recreate the cache file prior to destructing the object instance.    

=item B<rw> => B<0> | B<1>

Whether or not the configuration is read-write.  This setting is in effect
only if B<cachefile> is also set.
    
If set to B<0> (the default) any local changes to the configuration (using
B<set> and B<unset> methods), will not be saved to the cache file upon
exiting.  Otherwise, the eventual modifications will be stored in the cache.    
    
=back    

=head3 Syntax hash

The hash passed via the B<parameters> keyword defines the keywords and
sections allowed within a configuration file.  In a simplest case, a
keyword is described as

    name => 1

This means that B<name> is a valid keyword, but does not imply anything
more about it or its value.  A most complex declaration is possible, in
which the value is a hash reference, containing on or more of the following
keywords:

=over 4

=item mandatory => 0 | 1

Whether or not this setting is mandatory.

=item array => 0 | 1

If B<1>, the value of the setting is an array.  Each subsequent occurrence
of the statement appends its value to the end of the array.

=item re => I<regexp>

Defines a regular expression to which must be matched by the value of the
setting, otherwise a syntax error will be reported.

=item select => I<coderef>

Points to a function to be called to decide whether to apply this hash to
a particular configuration setting.  The function is called as

    &{$coderef}($vref, @path)

where $vref is a reference to the setting (use $vref->{-value}, to obtain
the actual value), and @path is its patname.    
    
=item check => I<coderef>

Defines a code which will be called after parsing the statement in order to
verify its value.  The I<coderef> is called as

    $err = &{$coderef}($valref, $prev_value)

where B<$valref> is a reference to its value, and B<$prev_value> is the value
of the previous instance of this setting.  The function must return B<undef>
if the value is OK for that setting.  In that case, it is allowed to modify
the value, referenced by B<$varlref>.  If the value is erroneous, the function
must return a textual error message, which will be printed using B<$cfg->error>.
    
=back    

To define a section, use the B<section> keyword, e.g.:

    core => {
        section => {
            pidfile => {
               mandatory => 1
            },
            verbose => {
               re => qr/^(?:on|off)/i
            }
        }
    }

This says that a section B<[core]> can have two variables: B<pidfile>, which
is mandatory, and B<verbose>, whose value must be B<on>, or B<off> (case-    
insensitive).

To allow for arbitrary keywords, use B<*>.  For example, the following
declares the B<[code]> section, which must have the B<pidfile> setting
and is allowed to have any other settings as well.    
 
    code => {
       section => {
           pidfile => { mandatory => 1 },
           '*' => 1
       }
    }

Everything said above applies to the B<'*'> as well.  E.g. the following
example declares the B<[code]> section, which must have the B<pidfile>
setting and is allowed to have I<subsections> with arbitrary settings.

    code => {
       section => {
           pidfile = { mandatory => 1 },
           '*' => {
               section => {
                   '*' => 1
               }
           }
       }
    }

The special entry

    '*' => '*'

means "any settings and any subsections".