Retrieves the $config hash from a file that was created by store_cache.

The first form reads $config_file.dump The second form reads $cache_file.

If $config_file was not provided to the constructor, the first form dies.

The stored file is subject to digests and permissions checks.

$cs->set_warnings

$cs->set_warnings(name => $name, switch => 'on|off');

Change warning for $name after construction.

$cs->warnings_on

$on = $cs->warnings_on(name => $name);

Returns true if warning $name is on. This is useful primarily for subclassing.

EXCEPTIONS

All methods die on error.

Config::Scoped::Error defines a hierarchy of classes that represent Config::Scoped errors. When a method detects an error, it creates an instance of the corresponding class and throws it. The error classes are all subclasses of Config::Scoped::Error. See Config::Scoped::Error for the complete list.

If the exception is not caught, the program terminates, and Config::Scoped prints the config file name and line number where the error was detected to STDERR.

The result is always a hash ref. We'll call this the config hash, and its contents for the example file above is:

$cfg_hash = {
host => {
name => 'cpan.org',
port => 22,
}
}

Config files and config strings

As described, Config::Scoped can obtain a configuration from a $config_file, passed to the constructor, or from a $config_string, passed to the parse method. For simplicity, we'll talk about parsing configuration files, distinguishing configuration strings only when necessary.

File layout

Config files are free-form text files. Comments begin with #, and extend to the end of the line.

Declarations

The top-level elements of a config file are called declarations. A declaration consists of a name, followed by a block

foo {
}
bar {
}

The declaration names become keys in the config hash. The value of each key is another hash ref. The config shown above parses to

$cfg_hash = {
foo => {},
bar => {},
}

You can create additional levels in the config hash simply by listing successive declaration names before the block. This config

dog hound {
}
dog beagle {
}
cat {
}

parses to

$cfg_hash = {
dog => {
hound => {},
beagle => {},
},
cat => {}
}

Declarations may not be nested.

Parameters

The ultimate purpose of a configuration file is to provide data values for a program. These values are specified by parameters.

Parameters have the form

name = value

and go inside declaration blocks. The

name = value

parameters in a spec file become key and value pairs inside the declaration hashes in Perl code.

The Config::Scoped data syntax is similar to the Perl data syntax, and Config::Scoped will parse many Perl data structures. In general, Config::Scoped requires less punctuation that Perl. Note that Config::Scoped allows arrow (=>) or equals (=) between hash keys and values, but not comma (,)

Only global variables can be shared with a compartment; lexical variables cannot.

perl_code is a synonym for eval.

Tokens and quoting

A token is a

declaration name

parameter name

hash key

scalar value

macro name

macro value

include path

warning name

Any token may be quoted.

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

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

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 (q(), 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 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 Safe compartment, as shown above in "Perl code evaluation". If you need a literal $ or @ in a double-quoted string, be sure to escape it with a backslash (\) to suppress interpolation.

An

eval { ... }

may appear anywhere that a token is expected. For example

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

parses to

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

DIRECTIVES

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

Macros

Config::Scoped supports macros. A macro is defined with

%macro name value

Macros may be defined

at file scope

within anonymous blocks

within declaration blocks

within hash blocks

Macros defined within blocks are lexically scoped to those blocks.

Macro substitution occurs

within any double-quoted text

within the entirety of Perl eval blocks

nowhere else

Include files

Config::Scoped supports include files.

To include one config file within another, write

%include path/to/file

%include directives may appear

at file scope

within anonymous blocks

nowhere else

In particular, %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

Perl data

However, 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 }
}

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 { }
}

Inheritance

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

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

Blocks, blocks, we got blocks...

Config::Scoped has four different kinds of blocks

anonymous

declaration

eval

hash

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

Macros

Macros are evil, and Config::Scoped macros are specially evil, because

they don't respect token boundaries

where multiple substitutions are possible, the substitution order is undefined

substituted text may or may not be rescanned for further substitutions

Caveat scriptor.

SUBCLASSING

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 Config::Scoped sources for more information.

Arbitrary

$your_key => $value

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

$cs->{local}{$your_key}

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

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

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

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.

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 checks.

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

Called for each %macro directive.

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

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

$name is an array ref giving the chain of names for the declaration block. $value is a hash ref containing all the parameters in the declaration block. $tail is a hash ref containing all the parameters in any previously defined declaration with the same name(s).