view release on metacpan or  search on metacpan

lib/Config/Scoped.pod  view on Meta::CPAN

=item *

macro name

=item *

macro value

=item *

include path

=item *

warning name

=back

Any token may be quoted.

Tokens that contain special characters must be quoted. The special characters are

  \s {} [] <> () ; , ' " = # %

B<Config::Scoped> uses the Perl quoting syntax.

Tokens may be quoted with either single or double quotes

  a = 'New York'
  b = "New Jersey\n"

Here-docs are supported

  a = <<EOT
  New York
  New Jersey
  EOT

but generalized quotes (B<q()>, B<qq()>, etc.) are not. Text in here-docs is regarded as single-quoted if the delimiter is enclosed in single quotes, and double-quoted if the delimiter is enclosed in double quotes or unquoted.

Double-quoted tokens are evaluated as Perl strings inside the parser's B<Safe> compartment. They are subject to the usual Perl backslash and variable interpolation, as well as macro expansion. Variables to be interpolated are passed via the B<Safe> c...

An

  eval { ... }

may appear anywhere that a token is expected. For example

  foo {
      eval { 'b' . 'c' } = 1
  }

parses to

    $cfg_hash = { foo => { bc => 1 } }

=head1 DIRECTIVES

B<Config::Scoped> has three directives: B<%macro>, B<%warning>, and B<%include>.

=head2 Macros

B<Config::Scoped> supports macros. A macro is defined with

  %macro name value

Macros may be defined

=over 4

=item *

at file scope

=item *

within anonymous blocks

=item *

within declaration blocks

=item *

within hash blocks

=back

Macros defined within blocks are lexically scoped to those blocks.

Macro substitution occurs

=over 4

=item *

within B<any> double-quoted text

=item *

within the B<entirety> of Perl B<eval> blocks

=item *

nowhere else

=back


=head2 Include files

B<Config::Scoped> supports include files.

To include one config file within another, write

  %include path/to/file

B<%include> directives may appear

=over 4

=item *

at file scope

=item *

within anonymous blocks

=item *

nowhere else

=back

In particular, B<%include> directives may not appear within declaration blocks or hash blocks.

Parameters and macros in include files are imported to the current scope. You can control this scope with an anonymous block

  {
    %include dog.cfg
    dog { }  # sees imports from dog.cfg
  }
  bird { }   # does not see imports from dog.cfg


Warnings are scoped to the included file and do not leak to the parent file.

Pathnames are either

=over 4

lib/Config/Scoped.pod  view on Meta::CPAN

However, B<Config::Scoped> doesn't require as much punctuation as Perl, and config files written from scratch will be cleaner without it

  foo
  {
     a = 1
     b = [ red green blue ]
     c = { x => 5
           y => 6 }
  }


=head2 Anonymous blocks

Don't use anonymous blocks unless you need to restrict the scope of something. In particular, there is no need for a top-level anonymous block around the whole config file

  {             # unnecessary
      foo { }
  }

=head2 Inheritance

Parameters that are outside of a declaration are inherited by B<all> following declarations in their scope. Don't do this unless you mean it

  wheels = 4
  car
  {
      # OK
  }
  cat
  {
      # I can haz weelz?
  }


=head2 Blocks, blocks, we got blocks...

B<Config::Scoped> has four different kinds of blocks

=over 4

=item *

anonymous

=item *

declaration

=item *

eval

=item *

hash

=back

They all look the same, but they aren't, and they have different rules and restrictions. See L</CONFIG FILE FORMAT> for descriptions of each.

=head2 Macros

Macros are evil, and B<Config::Scoped> macros are specially evil, because

=over 4

=item *

they don't respect token boundaries

=item *

where multiple substitutions are possible, the substitution order is undefined

=item *

substituted text may or may not be rescanned for further substitutions

=back

Caveat scriptor.


=head1 SUBCLASSING

B<Config::Scoped> has no formally defined subclass interface. Here are some guidelines for writing subclasses. Implementers who override (or redefine) base class methods may need to read the B<Config::Scoped> sources for more information.

Arbitrary

  $your_key => $value

pairs may be passed to the B<Config::Scoped> constructor. They will be stored in the B<< $cs->{local} >> hashref, and methods may access them with code like

  $cs->{local}{$your_key}

To avoid conflict with existing keys in the B<local> hash, consider distinguishing your keys with a unique prefix.

Arbitrary warning names may be defined, set with B<new> and B<set_warnings>, used in B<%warnings> directives, and tested with B<warnings_on>. Methods can call B<warnings_on> to find out whether a warning is currently enabled.

All methods throw exceptions (B<die>) on error. The exception object should be a subclass of B<Config::Scoped::Error>. You can use one of the classes defined in B<Config::Scoped::Error>, or you can derive your own. This code

    Config::Scoped::Error->throw(
        -file => $cs->_get_file(%args),
        -line => $cs->_get_line(%args),
        -text => $message,
    );

will generate an error message that reports the location in the config file where the error was detected, rather than a location in Perl code.

B<Config::Scoped> performs validation checks on the elements of configuration files (declarations, parameters, macros, etc). Here are the interfaces to the validation methods. Subclasses can override these methods to modify or extend the validation c...

=over 4

=item B<< $macro_value = $cs->macro_validate>(name => $name, value => $value) >>

Called for each B<%macro> directive.

Receives the B<$name> and B<$value> from the directive. The returned B<$macro_value> becomes the actual value of the macro.

If the macro is invalid, throws a B<Config::Scoped::Error::Validate::Macro> exception.


=item B<< $param_value = $cs->parameter_validate>(name => $name, value => $value) >>

Called for each parameter definition.

Receives the B<$name> and B<$value> from the definition. The returned B<$param_value> becomes the actual value of the parameter.

If the parameter is invalid, throws a B<Config::Scoped::Error::Validate::Parameter> exception.


=item B<< $cs->declaration_validate(name => $name, value => $value, tail => $tail) >>

Called for each declaration.

B<$name> is an array ref giving the chain of names for the declaration block. B<$value> is a hash ref containing all the parameters in the declaration block. B<$tail> is a hash ref containing all the parameters in any previously defined declaration w...

For example, the declaration

  foo bar baz { a=1 b=2 }

leads to the call

  $cs->declaration_validate(name  => [ qw(foo bar baz) ],
                                value => { a => '1', b => '2' },
                                tail  => $cs->{local}{config}{foo}{bar}{baz});

The method can test %$tail to discover if there is an existing, non-empty declaration with the same name(s).

The method has no return value. However, the method can alter the contents of %$value. Upon return, the parameters in %$value become the actual contents of the declaration block.

If the declaration is invalid, throws a B<Config::Scoped::Error::Validate::Declaration> exception.


=item B<< $cs->permissions_validate(file => $file, handle => $handle) >>

Called for the config file, each included file, and each retrieved cache file. One of B<$file> or B<$handle> must be non-null.

Throws a B<Config::Scoped::Error::Validate::Permissions> exception if the file is not safe to read.


=back


=head1 SEE ALSO

=over 4

=item *

B<Error>

=item *

B<Safe>

=item *

B<Config::Scoped::Error>