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

internal package Foswiki::Configure::Value is a Foswiki::Configure::Item

A Value object is a Foswiki::Configure::Item that represents a single entry in a configuration spec i.e. it is the leaf type in a configuration model.

Note that this object does not store the actual value of a configuration item. This object is the model only.

Value Attributes

Values may have attributes associated with them in the .spec file. These attributes are identified by UPPERCASE names and may be either:

• boolean - a single name enables the option, for example EXPERT
• string - a name followed by an equals sign, followed by a quoted string (single or double quotes both supported) for example LABEL="Wibble". (see also &&& below)

The special prefix 'NO' on any attribute name will clear the value of that attributes.

&&& In support of older .spec files, the following are also supported (though their usage is deprecated):

• Single-character attribute H. This is synonymous with HIDDEN.
• Single-character attribute M is ignored.
• Unquoted attribute values - DISPLAY_IF and ENABLE_IF may be followed by a a space, and terminated by /DISPLAY_IF (or /ENABLE_IF) or the end of the string.

Certain attributes define a 'delegate' that allows further parsing of the value of an attribute. A delegate is a ref to a function that performs this parsing. Delegates are responsible for directly modifying the item on which they are run.

Execution of delegates may be supressed by setting $Foswiki::Configure::LoadSpec::RAW_VALS to 1.

Delegates are used to parse 'FEEDBACK' and 'CHECK' values.

ClassMethod new($typename, %options)

• $typename e.g 'STRING', name of one of the Foswiki::Configure::TypeUIs Defaults to 'UNKNOWN' if not given ('', 0 or undef).

Constructor.

IMPORTANT NOTE

When constructing value objects in Pluggables, bear in mind that the default value is stored as an unparsed perl string. This string is checked for valid perl during the .spec load, but otherwise stored verbatim. It must be evaled to get the 'actual' default value.

The presence of the key (tested using 'exists') indicates whether a default is provided or not. undef is a valid default.

ObjectMethod getValueObject($keys)

This is a leaf object, so there's no recursive search to be done; we just return $this if the keys match.

ObjectMethod getRawValue() → $rawval

Get the current value of the key from $Foswiki::cfg. The value returned is not expanded (embedded $Foswiki::cfg references will be intact)

ObjectMethod getExpandedValue() → $expandedval

Get the current value of the key from $Foswiki::cfg. The value returned with embedded $Foswiki::cfg references recursively expanded. If the current value is undef, then undef is returned. Embedded references that evaluate to undef are expanded using the string 'undef'.

ObjectMethod encodeValue($raw_value) → $encoded_value

Encode a "real" cfg value as a string (if necessary) for passing to other tools, such as UIs, in a type-sensitive way.

ObjectMethod decodeValue($encoded_value) → $raw_value

Decode a string that represents the value (e.g a serialised perl structure) and return the 'true' value by applying type rules

ObjectMethod CHECK_option($keyname) → $value

Return the first value of the first CHECK option that contains the key $opt

e.g. if we have CHECK="a b" CHECK="c d=99 e" in the .spec then CHECK_option('c') will return true and CHECK_option('d') will return 99