Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Sympa::Config(3Sympa)		 sympa 6.2.56		 Sympa::Config(3Sympa)

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.

	       o   When	the context object will	be initially created, "undef"
		   must	be specified explicitly	so that	default	parameter
		   values will be completed.

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

	       o   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:

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

	   o   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:

	   o   {occurrence}: '0-n' or '1-n'.

	   o   {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:

	   o   {occurrence}: '0-n' or '1-n'.

	   o   {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:

	   o   {occurrence}: If	the node is an item of array, '0-n' or '1-n'.
	       Otherwise, '0-1'	or '1'.

	   o   {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:

	   o   {occurrence}: If	the node is an item of array, '0-n' or '1-n'.
	       Otherwise, '0-1'	or '1'.

	   o   {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.56				  2020-05-24		 Sympa::Config(3Sympa)

NAME | SYNOPSIS | DESCRIPTION | SEE ALSO | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Sympa::Config&sektion=3sympa&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help