internal package Foswiki::Configure::FoswikiCfg

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::FoswikiCfg is a Foswiki::Configure::Visitor

This is both a parser for configuration declaration files, such as FoswikiCfg.spec, and a serialisation visitor for writing out changes to LocalSite.cfg

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. Types are loaded by type id from the Foswiki::Configure::Types hierachy - for example, type BOOLEAN is defined by Foswiki::Configure::Types::BOOLEAN. Each type is a subclass of Foswiki::Configure::Type - see that class for more details of what is supported.

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 pluggable UI module (a class in Foswiki::Configure::Checkers::UIs)

ClassMethod new()

Used in saving, when we need a callback. Otherwise the methods here are all static.

StaticMethod load($root, $haveLSC)

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.

SEE ALSO Foswiki::Configure::Load::readDefaults

• $root Foswiki::Configure::Root of the model
• $haveLSC if we have a LocalSite.cfg

If we don't have a LocalSite.cfg, only Foswiki.spec will be loaded (Config.spec files from extensions will be skipped) and only the first section of Config.spec will be loaded. This means that checkers will only be built and run for that first section.

StaticMethod save($root, $valuer, $logger, $insane)

• $root is a Foswiki::Configure::Root
• $valuer is a Foswiki::Configure::Valuer
• $logger an object that implements a logChange($keys,$value) method, called to record the changes.
• $insane set to true if existing LocalSite.cfg should be overwritten

Generate .cfg file format output