Config::Model::Node - Class for configuration tree node
version 2.087
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:
Mandatory string parameter. This config class name can be used by a node element in another configuration class.
string
Optional string parameter. This description is used while generating user interfaces.
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.
Mandatory list ref of elements of the configuration class :
list ref
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.
Optional list ref of the elements whose level are different from default value (normal). Possible values are important, normal or hidden.
normal
important
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.
Important
level => [ [qw/X Y/] => 'important' ]
Optional list ref of the elements whose status are different from default value (standard). Possible values are obsolete, deprecated or standard.
standard
obsolete
deprecated
Using a deprecated element issues a warning. Using an obsolete element raises an exception (See Config::Model::Exception.
status => [ [qw/X Y/] => 'obsolete' ]
Optional list ref of element summaries. These summaries may be used when generating user interfaces.
Optional list ref of element descriptions. These descriptions may be used when generating user interfaces.
Parameters used to load on demand configuration data. See Config::Model::BackendMgr for details.
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.
Config::Model
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.
element
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.
accept_after
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.
Bug-Debian
bug
For more information, see this blog.
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 simple 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.
config_class_name
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.
value_type
When declaring a hash element, you must also provide a index_type parameter.
index_type
You can also provide a cargo_type parameter set to node or leaf (default).
cargo_type
See Config::Model::HashId and Config::Model::AnyId for more details.
See Config::Model::ListId and Config::Model::AnyId for more details.
The new constructor accepts the following parameters:
new
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
Returns 1 if the class model has the element declared or if the element name is matched by the optional accept parameter. If type is specified, the element name must also match the type.
accept
type
Returns $name if the class model has the element declared or if the element name is matched by the optional accept parameter.
$name
If case is set to any, has_element returns the element name who match the passed name in a case-insensitive manner.
case
has_element
Returns empty if no matching element is found.
Returns an object dedicated to search an element in the configuration model (respecting privilege level).
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.
Returns model of the element.
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 elements names available.
Optional parameters are:
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.
get_element_names
cargo_type => 'leaf'
check: yes, no or skip
yes
no
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.
type =>'hash', cargo_type => 'leaf'
Returns a list in array context, and a string (e.g. join(' ',@array)) in scalar context.
join(' ',@array)
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.
name
status
Returns the next element name for status (default normal). Returns undef if no next element is available.
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.
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 a property of an element.
Reset a property of an element according to the original model.
Fetch and returns an element from a node.
check can be set to yes, no or skip. When check is no or skip, can return undef when the element is unknown, or 0 if the element is not available (hidden).
undef
Fetch and returns the value of a leaf element from a node.
Store a value in a leaf element from a node.
Can be invoked with named parameters (name, value, check)
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' ) ;
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.
Returns the list of regular expressions used to check for acceptable parameters. Useful for diagnostics.
Returns 1 if the element is known in the model.
Returns 1 if the element is defined.
See "grab(...)" in Config::Model::AnyThing.
See "grab_value(...)" in Config::Model::AnyThing.
See "grab_root()" in Config::Model::AnyThing.
Get a value from a directory like path. If get_obj is 1, get returns a leaf object instead of returning its value.
get_obj
get
Set a value from a directory like path.
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.
warn_if_match
warn_unless_match
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 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.
check => skip
load_data can be called with a single hash ref parameter.
load_data
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.
dump_tree
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.
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.
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)
copy_from($another_node)
If called without element, returns the description of the class (Stored in class_description attribute of a node declaration).
class_description
If called with an element name, returns the description of the element (Stored in description attribute of a node declaration).
description
If called with 2 argument, either return the summary or the description of the element.
summary
Returns an empty string if no description was found.
Returns an object able to search the configuration tree. Parameters are :
Where to perform the search. It can be element, value, key, summary, description, help or all.
value
key
help
all
Then, search method must then be called on the object returned by tree_searcher.
search
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-2016 by Dominique Dumont.
This is free software, licensed under:
The GNU Lesser General Public License, Version 2.1, February 1999
To install Config::Model, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Config::Model
CPAN shell
perl -MCPAN -e shell install Config::Model
For more information on module installation, please visit the detailed CPAN module installation guide.