Sympa::Config - List configuration
use base qw(Sympa::Config);
sub _schema { {...} }
- 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 )
- Instance method. 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 )
- Instance method. 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
( )
- Instance method. Gets all submitted changes.
Note that returned value is the real reference to internal
information. Any modifications might break it.
- get_schema ( [
options, ... ] )
- Instance method. Get configuration schema as hashref.
- keys ( [ $pname ] )
- Instance method. 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 ] )
- Instance method. 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 ]
)
- Instance method. Merges changes set by sbumit() into actual
configuration.
Parameter:
- \@errors
- Arrayref. See \@errors in submit().
Returns:
None. Errors will be stored in arrayref.
Methods child classes should implement
- _schema ( )
- Instance method, mandatory. TBD.
- _init_schema_item ( $pitem, $pnames, $subres, [ key =>
val, ... ] )
- Instance method. TBD.
- _global_validations ( )
- Class or instance method. TBD.
- _local_validations ( )
- Class or instance method. TBD.
Instance of Sympa::Config has following attribute.
- {context}
- Context, Sympa::List instance.
Configuration on the memory is represented by a hashref, with its
keys as node names and values as node values.
Node types
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.
Sympa::Config appeared on Sympa 6.2.33b.2.