Config::Model::Node(3)User Contributed Perl DocumentatioConfig::Model::Node(3)NAMEConfig::Model::Node - Class for configuration tree node
VERSION
version 1.235
SYNOPSIS
use Config::Model;
use Log::Log4perl qw(:easy);
Log::Log4perl->easy_init($WARN);
# 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/]
}
],
experience => [
Y => 'beginner',
X => 'master'
],
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( step => 'Y=Av' );
# add some accepted element, ipA and ipB are created on the fly
$root->load( step => 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 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.
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 will be used when
generating user interfaces.
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.
experience
Optional "list ref" of the elements whose experience are different
from default value ("beginner"). Possible values are "master",
"advanced" and "beginner".
experience => [ Y => 'beginner',
[qw/foo bar/] => 'master'
],
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 will be shown to the
user no matter what. "hidden" elements will be 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 will issue a warning. Using an obsolete
element will raise an exception (See Config::Model::Exception.
status => [ [qw/X Y/] => 'obsolete' ]
description
Optional "list ref" of element description. These descriptions will
be used when generating user interfaces.
description
Optional "list ref" of element summary. These descriptions will be
used when generating user interfaces or as comment when writing
configuration files.
read_config
write_config
config_dir
Parameters used to load on demand configuration data. See
Config::Model::AutoRead for details.
accept
Optional list of criteria (i.e. a regular expression to match ) to
accept unknown parameters. Each criteria will have a list of
specification that will 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
parameters.
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 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.
"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.
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.
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 ( name => element_name, [ type => searched_type ] )
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.
find_element ( 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 will return the element name who
match the passed name in a case-insensitive manner.
Returns empty if no matching element is found.
searcher ()
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.
element_model ( element_name )
Returns model of the element.
element_type ( element_name )
Returns the type (e.g. leaf, hash, list, checklist or node) of the
element.
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
Element property management
get_element_name ( for => <experience>, ... )
Return all elements names available for "experience". If no experience
is specified, will return all elements available at 'master' level (I.e
all elements).
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 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.
· check: "yes", "no" or "skip"
Returns an array in array context, and a string (e.g. "join('
',@array)") in scalar context.
children
Like get_element_name without parameters. Returns the list of elements.
This method is polymorphic for all non-leaf objects of the
configuration tree.
next_element ( element_name, [ experience_index ] )
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.
previous_element ( element_name, [ experience_index ] )
This method provides a way to iterate through the elements of a node.
Returns the previous element name for a given experience (default
"master"). Returns undef if no previous element is available.
get_element_property ( element => ..., property => ... )
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_element_property ( element => ..., property => ... )
Set a property of an element.
reset_element_property ( element => ... )
Reset a property of an element according to the original model.
Information management
fetch_element ( name => .. [ , user_experience => .. ] , [ check => ..] )
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.
check can be set to yes, no or skip
fetch_element_value ( name => ... [ check => ...] )
Fetch and returns the value of a leaf 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.
store_element_value ( name, value )
Store a value in a leaf element from a node.
Can be invoked with named parameters (name, value, experience, check)
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.
is_element_available( name => ..., experience => ... )
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.
As a syntactic sugar, this method can be called with only one
parameter:
is_element_available( 'element_name' ) ;
accept_element( name )
Checks and returns the appropriate model of an acceptable element (be
it explicitly declared, or part of an "accept" declaration). Returns
undef if the element cannot be accepted.
accept_regexp( name )
Returns the list of regular expressions used to check for acceptable
parameters. Useful for diagnostics.
element_exists( element_name )
Returns 1 if the element is known in the model.
is_element_defined( element_name )
Returns 1 if the element is defined.
grab(...)
See "grab(...)" in Config::Model::AnyThing.
grab_value(...)
See "grab_value(...)" in Config::Model::AnyThing.
grab_root()
See "grab_root()" in Config::Model::AnyThing.
get( path => ..., mode => ... , check => ... , get_obj => 1|0, autoadd =>
1|0)
Get a value from a directory like path. If "get_obj" is 1, "get" will
return leaf object instead of returning their value.
set( path , value)
Set a value from a directory like path.
Serialization
load ( step => string [, experience => ... ] )
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_data ( hash_ref, [ $check ])
Load configuration data with a hash ref (first parameter). The hash ref
key must match the available elements of the node. The hash ref
structure must match the structure of the configuration model.
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 ( [ 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 will show only value different from their default
value.
copy_from ( another_node_object )
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.
Help management
get_help ( [ [ 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.
AutoRead nodes
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.
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
perl v5.14.1 2011-07-22 Config::Model::Node(3)
