Config::Model::Node - Class for configuration tree node
$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/] } ], experience => [ Y => 'beginner', X => 'master' ], status => [ X => 'deprecated' ], description => [ X => 'X-ray description (can be long)' ], summary => [ X => 'X-ray' ], ); my $instance = $model->instance (root_class_name => 'OneConfigClass', instance_name => 'test1'); my $root_node = $instance -> config_root ;
This class provides the nodes of a configuration tree. When created, a node object will get a set of rules that will define 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 will be used when generating user interfaces.
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 experience are different from default value (beginner). Possible values are master, advanced and beginner.
beginner
master
advanced
experience => [ Y => 'beginner', [qw/foo bar/] => 'master' ],
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 will be shown to the user no matter what. hidden elements will be 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 will issue a warning. Using an obsolete element will raise an exception (See Config::Model::Exception.
status => [ [qw/X Y/] => 'obsolete' ]
Optional list ref of element description. These descriptions will be used when generating user interfaces.
Optional list ref of element summray. These descriptions will be used when generating user interfaces or as comment when writing configuration files.
Parameters used to load on demand configuration data. See Config::Model::AutoRead for details.
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 instanciated 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.
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.
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.
Returns an object dedicated to search an element in the configuration model (respecting privilege level).
This method returns a Config::Model::Searcher object. See Config::Model::Searcher 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.
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
Return all elements names available for experience. If no experience is specified, will return all slots available at 'master' level (I.e all elements).
experience
Optional paremeters are:
type: Returns only element of requested type (e.g. list, hash, leaf,...). By default return elements of any type.
cargo_type: Returns only element which contain requested type. E.g. if get_element_name is called with cargo_type => leaf, get_element_name will return simple leaf elements, but also hash or list element that contain leaf object. By default return elements of any type.
get_element_name
cargo_type => leaf
Returns an array in array context, and a string (e.g. join(' ',@array)) in scalar context.
join(' ',@array)
This method provides a way to iterate through the elements of a node.
Returns the next element name for a given experience (default master). Returns undef if no next element is available.
Returns the previous element name for a given experience (default master). Returns undef if no previous element is available.
Retrieve a property of an element.
I.e. for a model :
experience => [ X => 'master'], status => [ X => 'deprecated' ] element => [ X => { ... } ]
This call will return deprecated:
$node->get_element_property ( element => 'X', property => 'status' )
Set a property of an element.
Reset a property of an element according to the model.
Fetch and returns an element from a node.
If user_experience is given, this method will check that the user has enough privilege to access the element. If not, a RestrictedElement exception will be raised.
RestrictedElement
Fetch and returns the value of a leaf element from a node.
Store a value in a leaf element from a node.
Returns 1 if the element name is available for the given experience ('beginner' by default) and if the element is not "hidden". Returns 0 otherwise.
name
As a syntactic sugar, this method can be called with only one parameter:
is_element_available( 'element_name' ) ;
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.
Set a value from a directory like path.
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. experience is 'master' by default.
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. The hash ref structure must match the structure of the configuration model.
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
Provides a decription 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 will show only value different from their default value.
Copy configuration data from another node into this node and its siblings. The copy is made in a tolerant mode where invalid data are simply discarded.
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.
As configuration model are getting bigger, the load time of a tree gets longer. The Config::Model::AutoRead class provides a way to load the configuration information only when needed.
TBD
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
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.