internal package Foswiki::Configure::LoadSpec

See PublishedAPI for packages intended to be used by Plugin and Contrib authors, or browse all packages.
See also Developing plugins, Developer's Bible, Technical Overview

Perl Module:

Child packagesChild packages

internal package Foswiki::Configure::LoadSpec

This is a parser for configuration declaration files, such as Foswiki.spec, and the Config.spec files in extensions.

The supported syntax in declaration files is as follows:

cfg ::= ( setting | section | extension )* ;
setting ::= BOL typespec EOL comment* BOL def ;
typespec ::= "**" typeid options "**" ;
def ::= "$" ["Foswiki::"] "cfg" keys "=" value ";" ;
keys ::= ( "{" id "}" )+ ;
value is any perl value not including ";"
comment ::= BOL "#" string EOL ;
section ::= BOL "#--+" string ( "--" options )? EOL comment* ;
extension ::= BOL " *" id "*"
EOL ::= end of line
BOL ::= beginning of line
typeid ::= id ;
id ::= a \w+ word (legal Perl bareword)

A section is simply a divider used to create blocks. It can have varying depth depending on the number of + signs and may have options after -- e.g. #---+ Section -- TABS EXPERT

A setting is the sugar required for the setting of a single configuration value.

An extension is a pluggable UI extension that supports some extra UI functionality, such as the menu of languages or the menu of plugins.

Each setting has a typespec and a def.

The typespec consists of a type id and some options.

A def is a specification of a field in the $Foswiki::cfg hash, together with a perl value for that hash. Each field can have an associated Checker which is loaded from the Foswiki::Configure::Checkers hierarchy. Checkers are responsible for specific checks on the value of that variable. For example, the checker for $Foswiki::cfg{Banana}{Republic} will be expected to be found in Foswiki::Configure::Checkers::Banana::Republic. Checkers are subclasses of Foswiki::Configure::Checker. See that class for more details.

An extension is a placeholder for a Foswiki::Configure::Pluggable.

Global $RAW_VALS

Set true to suppress parsing of attribute values (FEEDBACK and CHECK strings) and simply store them as strings. This is useful for performance, when these items are not required. Default behaviour is to parse the strings.

StaticMethod readSpec($root, $reporter)

Load the configuration declarations. The core set is defined in Foswiki.spec, which must be found on the @INC path and is always loaded first. Then find all settings for extensions in their .spec files.

This only reads type specifications, it does not read values. For that, use Foswiki::Configure::Load::readConfig.

• $root - Foswiki::Configure::Root of the model

StaticMethod parse($file, $root, $reporter [, $cant_enhance])

Parse the config declaration $file and add it to a $root node for the configuration it describes. If $cant_enhance, don't report ENHANCE failures (which may be due to a missing root spec; which is OK when installing a package)

StaticMethod protectKeys($keystring) → $keystring

Process a key string {Like}{This} and make sure that each key is safe for use in an eval.

StaticMethod protectKey($keystring) → $keystring

Process a key string (a hash index) and make sure that it is safe for use as a perl hash index.

StaticMethod addSpecDefaultsToCfg($spec, \%cfg, \%added)

• $spec - ref to a Foswiki::Configure::Item
• \%cfg ref to a cfg hash e.g. Foswiki::cfg
• \%added (optional) ref to a hash to receive keys that were added

For each key in the $spec missing from the %cfg passed, add the default (unexpanded) from the spec to the %cfg, if it exists.

StaticMethod addCfgValuesToSpec(\%cfg, $spec)

• \%cfg ref to a cfg hash e.g. Foswiki::cfg
• $spec - ref to a Foswiki::Configure::Item

For each key in the spec add the current value from the %cfg as current_value. If the key is not set in the %cfg, then set it to the default. Note that the %cfg should contain unexpanded values.