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