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

FreeBSD Manual Pages

  
 
  

home | help
Config::Model::Node(3)User Contributed Perl DocumentatioConfig::Model::Node(3)

NAME
       Config::Model::Node - Class for configuration tree node

VERSION
       version 2.140

SYNOPSIS
	use Config::Model;

	# define configuration tree object
	my $model = Config::Model->new;
	$model->create_config_class(
	   name		     =>	'OneConfigClass',
	   class_description =>	"OneConfigClass	detailed description",

	   element => [
	       [qw/X Y Z/] => {
		   type	      => 'leaf',
		   value_type => 'enum',
		   choice     => [qw/Av	Bv Cv/]
	       }
	   ],

	   status      => [ X => 'deprecated' ],
	   description => [ X => 'X-ray	description (can be long)' ],
	   summary     => [ X => 'X-ray' ],

	   accept => [
	       'ip.*' => {
		   type	      => 'leaf',
		   value_type => 'uniline',
		   summary    => 'ip address',
	       }
	   ]
	);
	my $instance = $model->instance	(root_class_name => 'OneConfigClass');
	my $root = $instance->config_root ;

	# X is not shown below because of its deprecated status
	print $root->describe,"\n" ;
	# name	       value	    type	 comment
	# Y	       [undef]	    enum	 choice: Av Bv Cv
	# Z	       [undef]	    enum	 choice: Av Bv Cv

	# add some data
	$root->load( steps => 'Y=Av' );

	# add some accepted element, ipA and ipB are created on	the fly
	$root->load( steps => q!ipA=192.168.1.0	ipB=192.168.1.1"! );

	# show also ip*	element	created	in the last "load" call
	print $root->describe,"\n" ;
	# name	       value	    type	 comment
	# Y	       Av	    enum	 choice: Av Bv Cv
	# Z	       [undef]	    enum	 choice: Av Bv Cv
	# ipA	       192.168.1.0  uniline
	# ipB	       192.168.1.1  uniline

DESCRIPTION
       This class provides the nodes of	a configuration	tree. When created, a
       node object gets	a set of rules that defines its	properties within the
       configuration tree.

       Each node contain a set of elements. An element can contain:

       o   A leaf element implemented with Config::Model::Value. A leaf	can be
	   plain (unconstrained	value) or be strongly typed (values are
	   checked against a set of rules).

       o   Another node.

       o   A collection	of items: a list element, implemented with
	   Config::Model::ListId. Each item can	be another node	or a leaf.

       o   A collection	of identified items: a hash element, implemented with
	   Config::Model::HashId.  Each	item can be another node or a leaf.

Configuration class declaration
       A class declaration is made of the following parameters:

       name
	   Mandatory "string" parameter. This config class name	can be used by
	   a node element in another configuration class.

       class_description
	   Optional "string" parameter.	This description is used while
	   generating user interfaces.

       class
	   Optional "string" to	specify	a Perl class to	override the default
	   implementation (Config::Model::Node).  This Perl Class must inherit
	   Config::Model::Node.	Use with care.

       element
	   Mandatory "list ref"	of elements of the configuration class :

	     element =>	[ foo => { type	= 'leaf', ... },
			  bar => { type	= 'leaf', ... }
			]

	   Element names can be	grouped	to save	typing:

	     element =>	[ [qw/foo bar/]	=> { type = 'leaf', ...	} ]

	   See below for details on element declaration.

       gist
	   String used to construct a summary of the content of	a node.	This
	   parameter is	used by	user interface to show users the gist of the
	   content of this node. This parameter	has no other effect. This
	   string may contain element values in	the form ""{foo} or {bar}"".
	   When	constructing the gist, "{foo}" is replaced by the value	of
	   element "foo". Likewise for "{bar}".

       level
	   Optional "list ref" of the elements whose level are different from
	   default value ("normal"). Possible values are "important", "normal"
	   or "hidden".

	   The level is	used to	set how	configuration data is presented	to the
	   user	in browsing mode. "Important" elements are shown to the	user
	   no matter what. "hidden" elements are explained with	the warp
	   notion.

	     level  => [ [qw/X Y/] => 'important' ]

       status
	   Optional "list ref" of the elements whose status are	different from
	   default value ("standard"). Possible	values are "obsolete",
	   "deprecated"	or "standard".

	   Using a deprecated element issues a warning.	Using an obsolete
	   element raises an exception (See Config::Model::Exception.

	     status  =>	[ [qw/X	Y/] => 'obsolete' ]

       description
	   Optional "list ref" of element summaries. These summaries may be
	   used	when generating	user interfaces.

       description
	   Optional "list ref" of element descriptions.	These descriptions may
	   be used when	generating user	interfaces.

       rw_config
       config_dir
	   Parameters used to load on demand configuration data.  See
	   Config::Model::BackendMgr for details.

       accept
	   Optional list of criteria (i.e. a regular expression	to match ) to
	   accept unknown elements. Each criteria has a	list of	specification
	   that	enable "Config::Model" to create a model snippet for the
	   unknown element.

	   Example:

	    accept => [
	       'list.*'	=> {
		   type	 => 'list',
		   cargo => {
		       type	  => 'leaf',
		       value_type => 'string',
		   },
	       },
	       'str.*' => {
		   type	      => 'leaf',
		   value_type => 'uniline'
	       },
	     ]

	   All "element" parameters can	be used	in specifying accepted
	   elements.

	   If Text::Levenshtein::Damerau is installed, a warning is issued if
	   an accepted element is too close to an existing element.

	   The parameter "accept_after"	to specify where to insert the
	   accepted element.  This does	not change much	the behavior of	the
	   tree, but helps generate a more usable user interface.

	   Example:

	    element => [
	       'Bug' =>	{ type => 'leaf', value_type =>	'uniline' } ,
	    ]
	    accept => [
	       'Bug-.*'	=>  {
		    value_type => 'uniline',
		    type => 'leaf'
		    accept_after => 'Bug' ,
	       }
	    ]

	   The model snippet above ensures that	"Bug-Debian" is	shown right
	   after "bug".

Element	declaration
   Element type
       Each element is declared	with a list ref	that contains all necessary
       information:

	 element => [
		      foo => { ... }
		    ]

       This most important information from this hash ref is the mandatory
       type parameter. The type	type can be:

       "node"  The element is a	node of	a tree instantiated from a
	       configuration class (declared with "create_config_class(	... )"
	       in Config::Model).  See "Node element".

       "warped_node"
	       The element is a	node whose properties (mostly
	       "config_class_name") can	be changed (warped) according to the
	       values of one or	more leaf elements in the configuration	tree.
	       See Config::Model::WarpedNode for details.

       "leaf"  The element is a	scalar value. See "Leaf	element"

       "hash"  The element is a	collection of nodes or values (default). Each
	       element of this collection is identified	by a string (Just like
	       a regular hash, except that you can set up constraint of	the
	       keys).  See "Hash element"

       "list"  The element is a	collection of nodes or values (default). Each
	       element of this collection is identified	by an integer (Just
	       like a regular perl array, except that you can set up
	       constraint of the keys).	 See "List element"

       "check_list"
	       The element is a	collection of values which are unique in the
	       check_list. See CheckList.

       "class" Override	the default class for leaf, list and hash elements.
	       The override class be inherit Config::Model::Value for leaf
	       element,	Config::Model::HashId for hash element and
	       Config::Model::ListId for list element.

   Node	element
       When declaring a	"node" element,	you must also provide a
       "config_class_name" parameter. For instance:

	$model ->create_config_class
	  (
	  name => "ClassWithOneNode",
	  element => [
		       the_node	=> {
				     type => 'node',
				     config_class_name => 'AnotherClass',
				   },
		     ]
	  ) ;

   Leaf	element
       When declaring a	"leaf" element,	you must also provide a	"value_type"
       parameter. See Config::Model::Value for more details.

   Hash	element
       When declaring a	"hash" element,	you must also provide a	"index_type"
       parameter.

       You can also provide a "cargo_type" parameter set to "node" or "leaf"
       (default).

       See Config::Model::HashId and Config::Model::AnyId for more details.

   List	element
       You can also provide a "cargo_type" parameter set to "node" or "leaf"
       (default).

       See Config::Model::ListId and Config::Model::AnyId for more details.

Constructor
       The "new" constructor accepts the following parameters:

       config_file
	   Specify configuration file to be used by backend. This parameter
	   may override	a file declared	in the model. Note that	this parameter
	   is not propagated in	children nodes.

Introspection methods
   name
       Returns the location of the node, or its	config class name (for root
       node).

   get_type
       Returns "node".

   config_model
       Returns the entire configuration	model (Config::Model object).

   model
       Returns the configuration model of this node (data structure).

   config_class_name
       Returns the configuration class name of this node.

   instance
       Returns the instance object containing this node. Inherited from
       Config::Model::AnyThing

   has_element
       Arguments: "( name => element_name, [ type => searched_type ],  [
       autoadd => 1 ] )"

       Returns 1 if the	class model has	the element declared.

       Returns 1 as well if "autoadd" is 1 (i.e. by default) and the element
       name is matched by the optional "accept"	model parameter.

       If "type" is specified, the element name	must also match	the type.

   find_element
       Parameters: "( element_name , [ case => any ])"

       Returns $name if	the class model	has the	element	declared or if the
       element name is matched by the optional "accept"	parameter.

       If "case" is set	to any,	"has_element" returns the element name who
       match the passed	name in	a case-insensitive manner.

       Returns empty if	no matching element is found.

   model_searcher
       Returns an object dedicated to search an	element	in the configuration
       model.

       This method returns a Config::Model::SearchElement object. See
       Config::Model::SearchElement for	details	on how to handle a search.

       This method is inherited	from Config::Model::AnyThing.

   element_model
       Parameters: "( element_name )"

       Returns model of	the element.

   element_type
       Parameters: "( element_name )"

       Returns the type	(e.g. leaf, hash, list,	checklist or node) of the
       element.	Also returns the type of a potentially accepted	element.  Dies
       if the element is not known or cannot be	accepted.

   element_name
       Returns the element name	that contain this object. Inherited from
       Config::Model::AnyThing

   index_value
       See "index_value()" in Config::Model::AnyThing

   parent
       See "parent" in Config::Model::AnyThing

   root
       See "root" in Config::Model::AnyThing

   location
       See "location" in Config::Model::AnyThing

   backend_support_annotation
       Returns 1 if at least one of the	backends attached to self or a parent
       node support to read and	write annotations (aka comments) in the
       configuration file.

Element	property management
   get_element_names
       Return all available element names, including the element that were
       accepted.

       Optional	parameters are:

       o   all:	Boolean. When set return all element names, even the hidden
	   ones	and does not trigger warp mechanism. Defaults to 0. This
	   option should be set	to 1 when this method is needed	to read
	   configuration data from a backend.

       o   type: Returns only element of requested type	(e.g. "list", "hash",
	   "leaf",...).	By default return elements of any type.

       o   cargo_type: Returns only hash or list elements that contain the
	   requested cargo type.  E.g. if "get_element_names" is called	with
	   "cargo_type => 'leaf'", then	"get_element_names" returns hash or
	   list	elements that contain a	leaf object.

       o   check: "yes", "no" or "skip"

       "type" and "cargo_type" parameters can be specified together. In	this
       case, this method returns parameters that satisfy both conditions. I.e.
       with "type =>'hash', cargo_type => 'leaf'", this	method returns only
       hash elements that contain leaf objects.

       Returns a list in array context,	and a string (e.g. "join(' ',@array)")
       in scalar context.

   children
       Like "get_element_names"	without	parameters. Returns the	list of
       elements. This method is	polymorphic for	all non-leaf objects of	the
       configuration tree.

   next_element
       This method provides a way to iterate through the elements of a node.
       Mandatory parameter is "name". Optional parameter: "status".

       Returns the next	element	name for status	(default "normal").  Returns
       undef if	no next	element	is available.

   previous_element
       Parameters: "( name => element_name )"

       This method provides a way to iterate through the elements of a node.

       Returns the previous element name. Returns undef	if no previous element
       is available.

   get_element_property
       Parameters: "( element => ..., property => ... )"

       Retrieve	a property of an element.

       I.e. for	a model	:

	 status	    => [ X => 'deprecated' ]
	 element    => [ X => {	... } ]

       This call returns "deprecated":

	 $node->get_element_property ( element => 'X', property	=> 'status' )

   set_element_property
       Parameters: "( element => ..., property => ... )"

       Set a property of an element.

   reset_element_property
       Parameters: "( element => ... )"

       Reset a property	of an element according	to the original	model.

Information management
   fetch_element
       Arguments: "( name => ..	, [ check => ..], [ autoadd => 1 ] )"

       Fetch and returns an element from a node	if the class model has the
       element declared.

       Also fetch and returns an element from a	node if	"autoadd" is 1 (i.e.
       by default) and the element name	is matched by the optional "accept"
       model parameter.

       "check" can be set to "yes", "no" or "skip".  When "check" is "no" or
       "skip", this method returns "undef" when	the element is unknown,	or 0
       if the element is not available (hidden).

       By default, "accepted" elements are automatically created. Set
       "autoadd" to 0 when this	behavior is not	wanted.

   fetch_element_value
       Parameters: "( name => ... [ check => ...] )"

       Fetch and returns the value of a	leaf element from a node.

   fetch_gist
       Return the gist of the node. See	description of "gist" parameter	above.

   store_element_value
       Parameters: "( name, value )"

       Store a value in	a leaf element from a node.

       Can be invoked with named parameters (name, value, check). E.g.

	( name => 'foo', value => 'bar', check => 'skip' )

   is_element_available
       Parameters: "( name => ...,  )"

       Returns 1 if the	element	"name" is available and	if the element is not
       "hidden". Returns 0 otherwise.

       As a syntactic sugar, this method can be	called with only one
       parameter:

	  is_element_available(	'element_name' ) ;

   accept_element
       Parameters: "( name )"

       Checks and returns the appropriate model	of an acceptable element (i.e.
       declared	as a model "element" or	part of	an "accept" declaration).
       Returns undef if	the element cannot be accepted.

   accept_regexp
       Parameters: "( name )"

       Returns the list	of regular expressions used to check for acceptable
       parameters.  Useful for diagnostics.

   element_exists
       Parameters: "( element_name )"

       Returns 1 if the	element	is known in the	model.

   is_element_defined
       Parameters: "( element_name )"

       Returns 1 if the	element	is defined.

   grab
       See "grab"" in Config::Model::Role::Grab.

   grab_value
       See "grab_value"" in Config::Model::Role::Grab.

   grab_root
       See "grab_root" in Config::Model::Role::Grab.

   get
       Parameters: "( path => ..., mode	=> ... ,  check	=> ... , get_obj =>
       1|0, autoadd => 1|0)"

       Get a value from	a directory like path. If "get_obj" is 1, "get"
       returns a leaf object instead of	returning its value.

   set
       Parameters: "( path  , value)"

       Set a value from	a directory like path.

Validation
   deep_check
       Scan the	tree and deep check on all elements that support this.
       Currently only hash or list element have	this feature.

data modification
   migrate
       Force a read of the configuration and perform all changes regarding
       deprecated elements or values. Return 1 if data needs to	be saved.

   apply_fixes
       Scan the	tree from this node and	apply fixes that are attached to
       warning specifications.	See "warn_if_match" or "warn_unless_match" in
       "" in Config::Model::Value.

   load
       Parameters: "( steps => string [	... ])"

       Load configuration data from the	string into the	node and its siblings.

       This string follows the syntax defined in Config::Model::Loader.	 See
       "load" in Config::Model::Loader for details on parameters.

       This method can also be called with a single parameter:

	 $node->load("some data:to be=loaded");

   load_data
       Parameters: "( data => hash_ref,	[ check	=> $check, ...	])"

       Load configuration data with a hash ref.	The hash ref key must match
       the available elements of the node (or accepted element). The hash ref
       structure must match the	structure of the configuration model.

       Use "check => skip" to make data	loading	more tolerant: bad data	are
       discarded.

       "load_data" can be called with a	single hash ref	parameter.

   needs_save
       return 1	if one of the elements of the node's sub-tree has been
       modified.

Serialization
   dump_tree
       Dumps the configuration data of the node	and its	siblings into a
       string.	See "dump_tree"	in Config::Model::Dumper for parameter
       details.

       This string follows the syntax defined in Config::Model::Loader.	The
       string produced by "dump_tree" can be passed to "load".

   dump_annotations_as_pod
       Dumps the configuration annotations of the node and its siblings	into a
       string.	See "dump_annotations_as_pod" in Config::Model::Dumper for
       parameter details.

   describe
       Parameters: "( [	element	=> ... ] )"

       Provides	a description of the node elements or of one element.

   report
       Provides	a text report on the content of	the configuration below	this
       node.

   audit
       Provides	a text audit on	the content of the configuration below this
       node. This audit	shows only value different from	their default value.

   copy_from
       Parameters: "( from => another_node_object, [ check => ... ] )"

       Copy configuration data from another node into this node	and its
       siblings. The copy can be made in a tolerant mode where invalid data is
       discarded with "check =>	skip". This method can be called with a	single
       argument: "copy_from($another_node)"

Help management
   get_help
       Parameters: "( [	[ description |	summary	] => element_name ] )"

       If called without element, returns the description of the class (Stored
       in "class_description" attribute	of a node declaration).

       If called with an element name, returns the description of the element
       (Stored in "description"	attribute of a node declaration).

       If called with 2	argument, either return	the "summary" or the
       "description" of	the element.

       Returns an empty	string if no description was found.

   get_info
       Returns a list of information related to	the node. See "get_info" in
       Config::Model::Value for	more details.

   tree_searcher
       Parameters: "( type => ... )"

       Returns an object able to search	the configuration tree.	 Parameters
       are :

       type
	   Where to perform the	search.	It can be "element", "value", "key",
	   "summary", "description", "help" or "all".

       Then, "search" method must then be called on the	object returned	by
       "tree_searcher".

       Returns a Config::Model::TreeSearcher object.

   Lazy	load of	node data
       As configuration	model are getting bigger, the load time	of a tree gets
       longer. The Config::Model::BackendMgr class provides a way to load the
       configuration information only when needed.

AUTHOR
       Dominique Dumont, (ddumont at cpan dot org)

SEE ALSO
       Config::Model, Config::Model::Instance, Config::Model::HashId,
       Config::Model::ListId, Config::Model::CheckList,
       Config::Model::WarpedNode, Config::Model::Value

AUTHOR
       Dominique Dumont

COPYRIGHT AND LICENSE
       This software is	Copyright (c) 2005-2020	by Dominique Dumont.

       This is free software, licensed under:

	 The GNU Lesser	General	Public License,	Version	2.1, February 1999

perl v5.32.0			  2020-08-28		Config::Model::Node(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | Configuration class declaration | Element declaration | Constructor | Introspection methods | Element property management | Information management | Validation | data modification | Serialization | Help management | AUTHOR | SEE ALSO | AUTHOR | COPYRIGHT AND LICENSE

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

home | help