PerlDoc

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

package Foswiki::Configure::Item

Abstract base class of all nodes in a configuration spec tree. Item is the base class for all of Section (collection) Value (an individual value).

Objects of this class are intended to form a tree with references in both directions, circular references ahead.

IMPORTANT: there are some naming conventions for fields that apply to all subclasses of this class:

• All internal attributes of this class are named [a-z][a-z_]* i.e. lowercase alphabetic
• All internal attributes that must not be serialised (such as tree pointers) are named _[a-z][a-z_]* i.e. with a leading underscore.
• All attributes read dynamically from the .spec must be [A-Z][A-Z_]+

ObjectMethod set(@what) / set(%what)

• @what array of key-value pairs for attributes to set e.g. set(typename=> 'BLAH'). The array may be interpreted as a hash, so must be even-sized.

Add options. The default implementation supports setting keys directly, and also supports a special 'opts' key, which defines a string that is parsed according to the .spec standard for options. Subclasses define ATTRSPEC to declare attribute types valid for the entity, used while parsing this string.

Note that all internal fields of this class use a leading underscore naming convention, while all dynamically-read attributes are all upper case with no leading underscore.

Note that the global $RAW_VALS=1 will supress calling of the parsers responsible to expanding attribute values.

When the same option is set twice in the parameters, the second value will take precedence. This allows the caller to declare defaults early in the list before appending options from other sources.

ObjectMethod clear(%what)

Delete attributes set by set.

ObjectMethod append($key, $str)

Concatenate $str to the string value of $key.

ObjectMethod hasDeep($attrname) → $boolean

Determine if this item (or any sub-item if this is a collection) has the given boolean attribute

ObjectMethod getAllValueKeys() → @list

Return a list of all the keys for value objects under this node.

ObjectMethod find_also_dependencies([$root])

Find 'also' dependencies by scanning values.

'also' dependencies are checker dependencies that are inferred from the values of DISPLAY_IF and ENABLE_IF attributes. Some 'also' dependencies may 'also' be explicitly declared in the CHECK clause of an item.

'also' dependencies are used to trigger checks of other items when the value of an item they depend on changes.

• $root - root used to getValueObject for keys found

ObjectMethod getPath() → @list

Get the path down to a configuration item. The path is a list of titles (headlines and keys).

ObjectMethod unparent()

Unparent a configuration item. This only clears the parent of the node, it does not remove the node from the parent. After removing parents only the top-down structure remains, and methods that use the parent, such as getPath, will not work any more, so use with great caution.

The main purpose of this method is to prepare a spec node for isolated use (e.g. serialisation).

ObjectMethod prune($depth)

Prunes the subtree under $this to a maximum depth of $depth, discarding children under that point.

$depth = 0 will prune immediate children $depth = 1 will prune children-of-children

etc.

ObjectMethod getSectionObject($head, $depth) → $item

This gets the section object that has the heading $head and $this->{depth} == $depth below this item. If $depth is not given, will return the first headline that matches.

Subclasses must provide an implementation.

find(%search) → @result

Find the first item that matches the search keys given in %search. For example, find(keys => '{Keys}') or find(headline => 'Section'). Searches recursively. You can use the pseudo-key parent to look up the tree, and depth to match the depth (the spec root is at depth 0).

An empty search matches the first thing found. If there are search terms, then the entire subtree is searched, but the shallowest matching node is returned. All search terms must be matched.

ObjectMethod find(\%match) → @nodes

Get a list of nodes that match the given search template. The template is a node structure with a subset of fields filled in that must be matched in a node for it to be returned.

Any fields can be used in searches and will match using eq, for example:

• headline - title of a section,
• typename - type of a leaf spec entry,
• 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)

Fields starting with _ are assumed to refer to another Foswiki::Configure::Item

• parent - a structure that will be used to match a parent (the value should be another match hash that will match the parent),

ObjectMethod search($re) → @nodes

Get a list of nodes that match the given RE. Sections match on the headline, Values on the keys.

ObjectMethod promoteSetting($setting) → $boolean

If all children of this node are tagged with the boolean attribute, then tag me too. Return true if the attribute is on us, false otherwise.

ObjectMethod getValueObject($keys) → $value

Get the first Foswiki::Configure::Value object (leaf configuration item) associated with this Item. If this Item is a Value object, it will just return 'this'. if it is a Section, it will search the section (and it's subsections) for the value object with matching keys.

Subclasses must define this method.

ObjectMethod visit($visitor) → $boolean

Start a visit over this item.

• $visitor - an object that implements Foswiki::Configure::Visitor

The default implementation just visits this item, and returns 1 if both the startVisit and the endVisit returned true.

ObjectMethod TO_JSON

Provided so the JSON module can serialise blessed objects. Creates a copy of the object without internal pointers that is suitable for serialisation. Subclasses that add fields that need to be serialised MUST implement this method (by modifying the object returned by SUPER::TO_JSON to remove internal fields).