Methods
new ( $that, [ config => $initial_config ], [ copy => 1 ], [ key => val, ... ] )
Constructor. Creates new instance of Sympa::Config object.
Parameters:
$that
Context. An instance of Sympa::List class, Robot or Site.
config => $initial_config
Initial configuration.
• When the context object will be initially created, "undef" must be specified explicitly so
that default parameter values will be completed.
• When existing list will be instantiated and config will be loaded, "{}" (default) would be
specified so that default parameter values except optional ones (with occurrence '0-1' or
'0-n') will be completed.
• Otherwise, default parameter values are completed only when the new paragraph node will be
added by submit().
Note that initial configuration will never be sanitized.
copy => 1
Uses deep copy of initial configuration (see "config") instead of real reference.
get ( $ppath )
Instancemethod. Gets copy of current value of parameter.
Parameter:
$ppath
Parameter path, e.g.: 'owner.0.email' specifies "email" parameter of the first "owner" paragraph;
'owner.0' specifies the first "owner" paragraph; 'owner' specifies the array of all "owner"
paragraph.
Returns:
Value of parameter. If parameter or value does not exist, returns "undef" in scalar context and an
empty list in array context.
get_change ( $ppath )
Instancemethod. Gets copy of submitted change on parameter.
Parameter:
$ppath
Parameter path. See also get().
Returns:
If value won't be changed, returns empty list in array context and "undef" in scalar context. If
value would be deleted, returns "undef".
Changes on the array are given by hashref with keys as affected indexes of the array.
get_changeset ( )
Instancemethod. Gets all submitted changes.
Note that returned value is the real reference to internal information. Any modifications might
break it.
get_schema ( [ options, ... ] )
Instancemethod. Get configuration schema as hashref.
keys ( [ $pname ] )
Instancemethod. Gets parameter keys in order defined by schema.
Parameter:
$pname
Full parameter name, e.g. 'owner'. If omitted or false value, returns keys of top-level
parameters.
Returns:
List of keys. If parameter does not exist or it does not have sub-parameters, i.e. it is not the
paragraph, empty list.
submit ( $new, $user, \@errors, [ no_global_validations => 1 ] )
Instancemethod. Submits change and verifies it. Submission is done by:
• Sanitizing changes:
Omits unknown parameters, resolves parameter aliases, omits malformed change information, omits
obsoleted parameters, omits changes on unwritable parameters, removes nodes under which required
children nodes will be removed, resolves synonym of input values, canonicalizes inputs (see
"Filters"), and omits identical changes.
• Verifying changes:
Omits removal of mandatory parameters, checks format of inputs, and performs additional
validations (see "Validations").
Parameters:
$new
Changes to be submitted, hashref.
$user
Email of the user requesting submission.
\@errors
If errors occur, they will be pushed in this arrayref. Each element is arrayref "[ type, error,
info ]":
no_global_validations => 1
If set, global validations are disabled. Global validations examine the entire configuration for
semantic errors or requirements that can't be detected within a single paragraph. See also
"_global_validations".
type
One of 'user' (failure), 'intern' (internal failure) and 'notice' (successful notice).
error
A keyword to determine error.
info
Optional hashref with keys: "p_info" for schema item of parameter; "p_paths" for elements of
parameter path; "value" for erroneous value (optional).
Returns:
If no changes found (or all changes were omitted), an empty string ''. If any errors found in input,
'invalid'. Otherwise, 'valid'.
In case any changes are submitted, changeset may be accessible by get_change() or get_changeset().
commit ( [ \@errors ] )
Instancemethod. Merges changes set by sbumit() into actual configuration.
Parameter:
\@errors
Arrayref. See \@errors in submit().
Returns:
None. Errors will be stored in arrayref.
Methodschildclassesshouldimplement
_schema ( )
Instancemethod, mandatory. TBD.
_init_schema_item ( $pitem, $pnames, $subres, [ key => val, ... ] )
Instancemethod. TBD.
_global_validations ( )
Classorinstancemethod. TBD.
_local_validations ( )
Classorinstancemethod. TBD.
Attribute
Instance of Sympa::Config has following attribute.
{context}
Context, Sympa::List instance.
Structureofconfiguration
Configuration on the memory is represented by a hashref, with its keys as node names and values as node
values.
Nodetypes
Each node of configuration has one of following four types. Some of them can include other type of nodes
recursively.
Set (multiple enumerated values)
Arrayref. In the schema, defined with:
• {occurrence}: '0-n' or '1-n'.
• {format}: Arrayref.
List of unique items not considering order. Items are scalars, and cannot be special values
(scenario or task). The set cannot contain paragraphs, sets or arrays.
Array (multiple values)
Arrayref. In the schema, defined with:
• {occurrence}: '0-n' or '1-n'.
• {format}: Regexp or hashref.
List of the same type of nodes in order. Type of all nodes can be one of paragraph, scalar or
special value (scenario or task). The array cannot contain sets or arrays.
Paragraph (structured value)
Hashref. In the schema, defined with:
• {occurrence}: If the node is an item of array, '0-n' or '1-n'. Otherwise, '0-1' or '1'.
• {format}: Hashref.
Compound node of one or more named nodes. Paragraph can contain any type of nodes, and each of their
names and types are defined as member of {format} item in schema.
Leaf (simple value)
Scalar, or hashref for special value (scenario or task). In the schema, defined with:
• {occurrence}: If the node is an item of array, '0-n' or '1-n'. Otherwise, '0-1' or '1'.
• {format}: If the node is an item of array, regexp. Otherwise, regexp or arrayref.
Scalar or special value (scenario or task). Leaf cannot contain any other nodes.
Filters
TBD.
Validations
TBD.
Install Now
PNG Icons
