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
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.
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.
The default implementation just visits this item, and returns 1 if
both the startVisit and the endVisit returned true.
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).