.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Sympa::Config 3Sympa"
.TH Sympa::Config 3Sympa "2021-02-07" "6.2.60" "sympa 6.2.60"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Sympa::Config \- List configuration
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use base qw(Sympa::Config);
\&  
\&  sub _schema { {...} }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
.SS "Methods"
.IX Subsection "Methods"
.ie n .IP "new ( $that, [ config => $initial_config ], [ copy => 1 ], [ \fIkey\fR => \fIval\fR, ... ] )" 4
.el .IP "new ( \f(CW$that\fR, [ config => \f(CW$initial_config\fR ], [ copy => 1 ], [ \fIkey\fR => \fIval\fR, ... ] )" 4
.IX Item "new ( $that, [ config => $initial_config ], [ copy => 1 ], [ key => val, ... ] )"
\&\fIConstructor\fR.
Creates new instance of Sympa::Config object.
.Sp
Parameters:
.RS 4
.ie n .IP "$that" 4
.el .IP "\f(CW$that\fR" 4
.IX Item "$that"
Context.  An instance of Sympa::List class, Robot or Site.
.ie n .IP "config => $initial_config" 4
.el .IP "config => \f(CW$initial_config\fR" 4
.IX Item "config => $initial_config"
Initial configuration.
.RS 4
.IP "\(bu" 4
When the context object will be initially created,
\&\f(CW\*(C`undef\*(C'\fR must be specified explicitly
so that default parameter values will be completed.
.IP "\(bu" 4
When existing list will be instantiated and config will be loaded,
\&\f(CW\*(C`{}\*(C'\fR (default) would be specified
so that default parameter values except optional ones
(with occurrence \f(CW\*(Aq0\-1\*(Aq\fR or \f(CW\*(Aq0\-n\*(Aq\fR) will be completed.
.IP "\(bu" 4
Otherwise, default parameter values are completed
only when the new paragraph node will be added by \fBsubmit()\fR.
.RE
.RS 4
.Sp
Note that initial configuration will never be sanitized.
.RE
.IP "copy => 1" 4
.IX Item "copy => 1"
Uses deep copy of initial configuration (see \*(L"config\*(R")
instead of real reference.
.RE
.RS 4
.RE
.ie n .IP "get ( $ppath )" 4
.el .IP "get ( \f(CW$ppath\fR )" 4
.IX Item "get ( $ppath )"
\&\fIInstance method\fR.
Gets copy of current value of parameter.
.Sp
Parameter:
.RS 4
.ie n .IP "$ppath" 4
.el .IP "\f(CW$ppath\fR" 4
.IX Item "$ppath"
Parameter path,
e.g.: \f(CW\*(Aqowner.0.email\*(Aq\fR specifies \*(L"email\*(R" parameter of
the first \*(L"owner\*(R" paragraph;
\&\f(CW\*(Aqowner.0\*(Aq\fR specifies the first \*(L"owner\*(R" paragraph;
\&\f(CW\*(Aqowner\*(Aq\fR specifies the array of all \*(L"owner\*(R" paragraph.
.RE
.RS 4
.Sp
Returns:
.Sp
Value of parameter.
If parameter or value does not exist, returns \f(CW\*(C`undef\*(C'\fR in scalar context
and an empty list in array context.
.RE
.ie n .IP "get_change ( $ppath )" 4
.el .IP "get_change ( \f(CW$ppath\fR )" 4
.IX Item "get_change ( $ppath )"
\&\fIInstance method\fR.
Gets copy of submitted change on parameter.
.Sp
Parameter:
.RS 4
.ie n .IP "$ppath" 4
.el .IP "\f(CW$ppath\fR" 4
.IX Item "$ppath"
Parameter path.
See also \fBget()\fR.
.RE
.RS 4
.Sp
Returns:
.Sp
If value won't be changed, returns empty list in array context
and \f(CW\*(C`undef\*(C'\fR in scalar context.
If value would be deleted, returns \f(CW\*(C`undef\*(C'\fR.
.Sp
Changes on the array are given by hashref
with keys as affected indexes of the array.
.RE
.IP "get_changeset ( )" 4
.IX Item "get_changeset ( )"
\&\fIInstance method\fR.
Gets all submitted changes.
.Sp
Note that returned value is the real reference to internal information.
Any modifications might break it.
.IP "get_schema ( [ \fIoptions\fR, ... ] )" 4
.IX Item "get_schema ( [ options, ... ] )"
\&\fIInstance method\fR.
Get configuration schema as hashref.
.ie n .IP "keys ( [ $pname ] )" 4
.el .IP "keys ( [ \f(CW$pname\fR ] )" 4
.IX Item "keys ( [ $pname ] )"
\&\fIInstance method\fR.
Gets parameter keys in order defined by schema.
.Sp
Parameter:
.RS 4
.ie n .IP "$pname" 4
.el .IP "\f(CW$pname\fR" 4
.IX Item "$pname"
Full parameter name, e.g. \f(CW\*(Aqowner\*(Aq\fR.
If omitted or false value,
returns keys of top-level parameters.
.RE
.RS 4
.Sp
Returns:
.Sp
List of keys.
If parameter does not exist or it does not have sub-parameters,
i.e. it is not the paragraph, empty list.
.RE
.ie n .IP "submit ( $new, $user, \e@errors, [ no_global_validations => 1 ] )" 4
.el .IP "submit ( \f(CW$new\fR, \f(CW$user\fR, \e@errors, [ no_global_validations => 1 ] )" 4
.IX Item "submit ( $new, $user, @errors, [ no_global_validations => 1 ] )"
\&\fIInstance method\fR.
Submits change and verifies it.
Submission is done by:
.RS 4
.IP "\(bu" 4
Sanitizing changes:
.Sp
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 \*(L"Filters\*(R"),
and omits identical changes.
.IP "\(bu" 4
Verifying changes:
.Sp
Omits removal of mandatory parameters,
checks format of inputs,
and performs additional validations (see \*(L"Validations\*(R").
.RE
.RS 4
.Sp
Parameters:
.ie n .IP "$new" 4
.el .IP "\f(CW$new\fR" 4
.IX Item "$new"
Changes to be submitted, hashref.
.ie n .IP "$user" 4
.el .IP "\f(CW$user\fR" 4
.IX Item "$user"
Email of the user requesting submission.
.IP "\e@errors" 4
.IX Item "@errors"
If errors occur, they will be pushed in this arrayref.
Each element is arrayref \f(CW\*(C`[ \f(CItype\f(CW, \f(CIerror\f(CW, \f(CIinfo\f(CW ]\*(C'\fR:
.IP "no_global_validations => 1" 4
.IX Item "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 \*(L"_global_validations\*(R".
.RS 4
.IP "\fItype\fR" 4
.IX Item "type"
One of \f(CW\*(Aquser\*(Aq\fR (failure), \f(CW\*(Aqintern\*(Aq\fR (internal failure)
and \f(CW\*(Aqnotice\*(Aq\fR (successful notice).
.IP "\fIerror\fR" 4
.IX Item "error"
A keyword to determine error.
.IP "\fIinfo\fR" 4
.IX Item "info"
Optional hashref with keys:
\&\f(CW\*(C`p_info\*(C'\fR for schema item of parameter;
\&\f(CW\*(C`p_paths\*(C'\fR for elements of parameter path;
\&\f(CW\*(C`value\*(C'\fR for erroneous value (optional).
.RE
.RS 4
.RE
.RE
.RS 4
.Sp
Returns:
.Sp
If no changes found (or all changes were omitted), an empty string \f(CW\*(Aq\*(Aq\fR.
If any errors found in input, \f(CW\*(Aqinvalid\*(Aq\fR.
Otherwise, \f(CW\*(Aqvalid\*(Aq\fR.
.Sp
In case any changes are submitted,
changeset may be accessible by \fBget_change()\fR or \fBget_changeset()\fR.
.RE
.IP "commit ( [ \e@errors ] )" 4
.IX Item "commit ( [ @errors ] )"
\&\fIInstance method\fR.
Merges changes set by \fBsbumit()\fR into actual configuration.
.Sp
Parameter:
.RS 4
.IP "\e@errors" 4
.IX Item "@errors"
Arrayref.
See \e@errors in \fBsubmit()\fR.
.RE
.RS 4
.Sp
Returns:
.Sp
None.
Errors will be stored in arrayref.
.RE
.PP
\fIMethods child classes should implement\fR
.IX Subsection "Methods child classes should implement"
.IP "_schema ( )" 4
.IX Item "_schema ( )"
\&\fIInstance method\fR, \fImandatory\fR.
\&\s-1TBD.\s0
.ie n .IP "_init_schema_item ( $pitem, $pnames, $subres, [ \fIkey\fR => \fIval\fR, ... ] )" 4
.el .IP "_init_schema_item ( \f(CW$pitem\fR, \f(CW$pnames\fR, \f(CW$subres\fR, [ \fIkey\fR => \fIval\fR, ... ] )" 4
.IX Item "_init_schema_item ( $pitem, $pnames, $subres, [ key => val, ... ] )"
\&\fIInstance method\fR.
\&\s-1TBD.\s0
.IP "_global_validations ( )" 4
.IX Item "_global_validations ( )"
\&\fIClass or instance method\fR.
\&\s-1TBD.\s0
.IP "_local_validations ( )" 4
.IX Item "_local_validations ( )"
\&\fIClass or instance method\fR.
\&\s-1TBD.\s0
.SS "Attribute"
.IX Subsection "Attribute"
Instance of Sympa::Config has following attribute.
.IP "{context}" 4
.IX Item "{context}"
Context, Sympa::List instance.
.SS "Structure of configuration"
.IX Subsection "Structure of configuration"
Configuration on the memory is represented by a hashref,
with its keys as node names and values as node values.
.PP
\fINode types\fR
.IX Subsection "Node types"
.PP
Each node of configuration has one of following four types.
Some of them can include other type of nodes recursively.
.IP "Set (multiple enumerated values)" 4
.IX Item "Set (multiple enumerated values)"
Arrayref.
In the schema, defined with:
.RS 4
.IP "\(bu" 4
{occurrence}: \f(CW\*(Aq0\-n\*(Aq\fR or \f(CW\*(Aq1\-n\*(Aq\fR.
.IP "\(bu" 4
{format}: Arrayref.
.RE
.RS 4
.Sp
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.
.RE
.IP "Array (multiple values)" 4
.IX Item "Array (multiple values)"
Arrayref.
In the schema, defined with:
.RS 4
.IP "\(bu" 4
{occurrence}: \f(CW\*(Aq0\-n\*(Aq\fR or \f(CW\*(Aq1\-n\*(Aq\fR.
.IP "\(bu" 4
{format}: Regexp or hashref.
.RE
.RS 4
.Sp
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.
.RE
.IP "Paragraph (structured value)" 4
.IX Item "Paragraph (structured value)"
Hashref.
In the schema, defined with:
.RS 4
.IP "\(bu" 4
{occurrence}: If the node is an item of array, \f(CW\*(Aq0\-n\*(Aq\fR or \f(CW\*(Aq1\-n\*(Aq\fR.
Otherwise, \f(CW\*(Aq0\-1\*(Aq\fR or \f(CW\*(Aq1\*(Aq\fR.
.IP "\(bu" 4
{format}: Hashref.
.RE
.RS 4
.Sp
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.
.RE
.IP "Leaf (simple value)" 4
.IX Item "Leaf (simple value)"
Scalar, or hashref for special value (scenario or task).
In the schema, defined with:
.RS 4
.IP "\(bu" 4
{occurrence}: If the node is an item of array, \f(CW\*(Aq0\-n\*(Aq\fR or \f(CW\*(Aq1\-n\*(Aq\fR.
Otherwise, \f(CW\*(Aq0\-1\*(Aq\fR or \f(CW\*(Aq1\*(Aq\fR.
.IP "\(bu" 4
{format}: If the node is an item of array, regexp.
Otherwise, regexp or arrayref.
.RE
.RS 4
.Sp
Scalar or special value (scenario or task).
Leaf cannot contain any other nodes.
.RE
.SS "Filters"
.IX Subsection "Filters"
\&\s-1TBD.\s0
.SS "Validations"
.IX Subsection "Validations"
\&\s-1TBD.\s0
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Sympa::ListDef.
.SH "HISTORY"
.IX Header "HISTORY"
Sympa::Config appeared on Sympa 6.2.33b.2.