Provided by: sympa_6.2.70~dfsg-2_amd64 bug

NAME

       Sympa::Config - List configuration

SYNOPSIS

         use base qw(Sympa::Config);

         sub _schema { {...} }

DESCRIPTION

   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 )
           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.

   Attribute
       Instance of Sympa::Config has following attribute.

       {context}
           Context, Sympa::List instance.

   Structure of configuration
       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.

   Filters
       TBD.

   Validations
       TBD.

SEE ALSO

       Sympa::ListDef.

HISTORY

       Sympa::Config appeared on Sympa 6.2.33b.2.

6.2.70                                             2023-01-26                              Sympa::Config(3Sympa)