internal package Foswiki::Configure::Query

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::Query

Methods used to query and manipulate the configuration spec.

Contract

All the methods take two parameters; a parameter hash, and a reporter. The parameter hash is described for each method, as is the return value, which is always a perl reference.

All methods return undef if they fail badly. $reporter->ERROR is used to describe fatal errors to the caller.

The $reporter should be clear before calling any of these methods, as existing errors in the reporter will be detected as fatal errors and cause the method to fail.

StaticMethod getcfg(\%params, $reporter) → \%response

Retrieve for the value of one or more keys. \%params may include

• keys - array of key names to recover values for.

If there isn't at least one key parameter, returns the entire configuration hash. Values are returned unexpanded (with embedded $Foswiki::cfg references intact.)

The result is a hash containing that subsection of %Foswiki::cfg that has the keys requested.

StaticMethod search(\%params, $reporter) → \@response

• search - text fragment to search for

Search headlines and keys for a fragment of text. The response gives the path(s) to the item(s) matched in an array of arrays, where each entry is a single path.

Searches are case-sensitive.

StaticMethod getspec(\%params, $reporter) → \%response

Use a search to find a configuration item spec. \%params may include:

• get - specifies the search. The following fields can be used in searches:
  • headline - title of a section,
  • typename - type of a leaf spec entry,
  • parent - a structure that will be used to match a parent,
  • keys - keys of a spec entry,
  • desc - descriptive text of a section or entry.
  • depth - matches the depth of a node under the root (which is depth 0)
• depth - specifies the depth of the subtree below matched items to return.

Only exact matches are supported.

For example, { 'get': {'headline':'Store'}} will retrieve the entire spec subtree for the section called 'Store'.

{ 'get' : {'keys' : '{Store}{Implementation}'}} will retrieve the spec for that one entry. You cannot pass a list; if you require the spec for a subsection, retrieve the section title.

{ 'get' : { 'parent' : {'headline' : 'Something'}, 'depth' : 0} will return all specs within the section named Something.

The response is a reference to the spec subtree. Note that this will contained blessed hashes.

StaticMethod check_current_value(\%params, $reporter) → \@response

Runs the server-side check-current_value checkers on a set of keys. The keys to be checked are passed in as key-value pairs. You can also pass in candidate values that will be set before any keys are checked.

• set - hash of key-value pairs that maps the names of keys to the value to be set. Strings in the values are assumed to be unexpanded (i.e. with $Foswiki::cfg references intact).
• keys - array of keys to be checked (or the headline(s) of the sections(s) to be recursively checked. '' checks the root. All keys under the headlined section(s) will be checked). The default is to check everything under the root.
• check_dependencies - if true, check everything that depends on any of the keys being checked. This include dependencies explicitly expressed through CHECK and implicit dependencies found from the value of the checked item.

The results of the check are reported in an array where each entry is a hash with fields keys and reports. reports is an array of reports, each being a hash with keys level (e.g. warnings, errors), and message.

NOTE check_dependencies will look into the values of other keys for $Foswiki::cfg references, for example into the entries in a PERL hash. If a dependency is found, the closest checkable entity (i.e. the PERL key) will be checked, and not the subkey.

StaticMethod wizard(\%params, $reporter) → \%response

Call a configuration wizard.

Configuration wizards are modules that support complex operations on configuration data; for example, auto-configuration of email and complex and time-consuming integrity checks.

• wizard - name of a wizard class to load
• keys - name of a checker to use if wizard is not given
• method - name of the method in the wizard or checker to call

If the wizard method returns an object, that will be passed back as the result of the call. If the wizard method returns undef, the return result is a hash containing the following keys: * report - Error/Warning etc messages, formatted as HTML. Each entry in this array is a hash with keys 'level' (e.g. error, warning) and 'message'.

• changes - This is a hash mapping changed keys to their new values