Config::Model::Node - Class for configuration tree node
version 2.152
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
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:
- •
- 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).
- •
- Another node.
- •
- A collection of items: a list element, implemented with
Config::Model::ListId. Each item can be another node or a leaf.
- •
- A collection of identified items: a hash element,
implemented with Config::Model::HashId. Each item can be another node or a
leaf.
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".
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.
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',
},
]
) ;
When declaring a "leaf" element, you must also provide a
"value_type" parameter. See Config::Model::Value for more details.
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.
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.
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.
Returns the location of the node, or its config class name (for root node).
Returns "node".
Returns the
entire configuration model (Config::Model object).
Returns the configuration model of this node (data structure).
Returns the configuration class name of this node.
Returns the instance object containing this node. Inherited from
Config::Model::AnyThing
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.
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.
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.
Parameters: "( element_name )"
Returns model of the element.
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.
Returns the element name that contain this object. Inherited from
Config::Model::AnyThing
See "
index_value()" in Config::Model::AnyThing
See "parent" in Config::Model::AnyThing
See "root" in Config::Model::AnyThing
See "location" in Config::Model::AnyThing
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.
Return all available element names, including the element that were accepted.
Optional parameters are:
- •
-
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.
- •
-
type: Returns only element of requested type (e.g.
"list", "hash", "leaf",...). By default
return elements of any type.
- •
-
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.
- •
-
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.
Like "get_element_names" without parameters. Returns the list of
elements. This method is polymorphic for all non-leaf objects of the
configuration tree.
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.
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.
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' )
Parameters: "( element => ..., property => ... )"
Set a property of an element.
Parameters: "( element => ... )"
Reset a property of an element according to the original model.
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.
Parameters: "( name => ... [ check => ...] )"
Fetch and returns the
value of a leaf element from a node.
Return the gist of the node. See description of "gist" parameter
above.
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' )
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' ) ;
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.
Parameters: "( name )"
Returns the list of regular expressions used to check for acceptable parameters.
Useful for diagnostics.
Parameters: "( element_name )"
Returns 1 if the element is known in the model.
Parameters: "( element_name )"
Returns 1 if the element is defined.
See "grab"" in Config::Model::Role::Grab.
See "grab_value"" in Config::Model::Role::Grab.
See "grab_root" in Config::Model::Role::Grab.
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.
Parameters: "( path , value)"
Set a value from a directory like path.
Scan the tree and deep check on all elements that support this. Currently only
hash or list element have this feature.
Force a read of the configuration and perform all changes regarding deprecated
elements or values. Return 1 if data needs to be saved.
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. Return $self since v2.151.
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");
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.
Returns 1 if some data were saved (instead of skipped).
return 1 if one of the elements of the node's sub-tree has been modified.
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".
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.
Parameters: "( [ element => ... ] )"
Provides a description of the node elements or of one element.
Provides a text report on the content of the configuration below this node.
Provides a text audit on the content of the configuration below this node. This
audit shows only value different from their default value.
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)"
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.
Returns a list of information related to the node. See "get_info" in
Config::Model::Value for more details.
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.
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.
Dominique Dumont, (ddumont at cpan dot org)
Config::Model, Config::Model::Instance, Config::Model::HashId,
Config::Model::ListId, Config::Model::CheckList, Config::Model::WarpedNode,
Config::Model::Value
Dominique Dumont
This software is Copyright (c) 2005-2022 by Dominique Dumont.
This is free software, licensed under:
The GNU Lesser General Public License, Version 2.1, February 1999