NAME

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

SYNOPSIS

 $model->create_config_class 
  (
   name              => 'OneConfigClass',
   element           => [
                          [qw/X Y Z/] 
                          => {
                               type => 'leaf',
                               value_type => 'enum',
                               choice     => [qw/Av Bv Cv/]
                             }
                        ],
   permission        => [ Y => 'intermediate', 
                          X => 'master' 
                        ],
   status            => [ X => 'deprecated' ],
   description       => [ X => 'X-ray' ],
   class_description => "OneConfigClass detailed description",

  );

 my $instance = $model->instance (root_class_name => 'OneConfigClass', 
                                  instance_name => 'test1');
 my $root_node = $instance -> config_root ;

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 the Config::Model::Value manpage. 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 the Config::Model::ListId manpage. Each item can be another node or a leaf.

• A collection of identified items: a hash element, implemented with the Config::Model::HashId manpage. 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.

permission

Optional list ref of the elements whose permission are different from default value (intermediate). Possible values are master, advanced and intermediate.

  permission   => [ Y => 'intermediate', 
                    [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 the Config::Model::Exception manpage.

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

description

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

read_config

write_config

config_dir

Parameters used to load on demand configuration data. See the Config::Model::AutoRead manpage for details.

Element declaration

Element type

Each element is declared with a list ref that contains all necessary informations:

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

This most important informations 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 the Config::Model manpage). 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 the Config::Model::WarpedNode manpage 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 the Config::Model::Value manpage 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 the Config::Model::HashId manpage and the Config::Model::AnyId manpage for more details.

List element

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

See the Config::Model::ListId manpage and the Config::Model::AnyId manpage 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.

model

Returns the configuration model of this node.

config_class_name

Returns the configuration class name of this node.

instance

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

has_element ( element_name )

Returns 1 if the class model has the element declared.

searcher ()

Returns an object dedicated to search an element in the configuration model (respecting privilege level).

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

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

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 the Config::Model::AnyThing manpage

index_value()

See index_value() in the Config::Model::AnyThing manpage

parent()

See parent() in the Config::Model::AnyThing manpage

root()

See root() in the Config::Model::AnyThing manpage

location()

See location() in the Config::Model::AnyThing manpage

Element property management

get_element_name ( for => <permission>, ... )

Return all elements names available for permission. If no permission is specified, will return all slots available at 'master' level (I.e all elements).

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.

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

next_element ( element_name, [ permission_index ] )

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

Returns the next element name for a given permission (default master). Returns undef if no next element is available.

get_element_property ( element => ..., property => ... )

Retrieve a property of an element.

I.e. for a model :

  permission => [ 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 model.

Information management

fetch_element ( name [ , user_permission ])

Fetch and returns an element from a node.

If user_permission is given, this method will check that the user has enough privilege to access the element. If not, a RestrictedElement exception will be raised.

fetch_element_value ( name [ , user_permission ])

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

If user_permission 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 [ , user_permission ])

Store a value in a leaf element from a node.

If user_permission 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 => ..., permission => ... )

Returns 1 if the element name is available for the given permission ('intermediate' by default). Returns 0 otherwise.

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

   is_element_available( 'element_name' ) ;

is_element_defined( element_name )

Returns 1 if the element is defined.

grab(...)

See grab(...) in the Config::Model::AnyThing manpage.

grab_value(...)

See grab_value(...) in the Config::Model::AnyThing manpage.

grab_root()

See grab_root() in the Config::Model::AnyThing manpage.

Serialisation

load ( step => string [, permission => ... ] )

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

This string follows the syntax defined in the Config::Model::Loader manpage. See load ( ... ) in the Config::Model::Loader manpage for details on parameters. permission 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 )

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.

dump_tree ( [ mode => custom | full ] )

Dumps the configuration data of the node and its siblings into a string.

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

dump_as_data ( )

Dumps the configuration data of the node and its siblings into a perl data structure.

Returns a hash ref containing the data.

describe ()

Provides a decription of the node elements.

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 ( [ 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).

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 the Config::Model::AutoRead manpage class provides a way to load the configuration informations only when needed.

TBD

AUTHOR

Dominique Dumont, (ddumont at cpan dot org)

SEE ALSO

the Config::Model manpage, the Config::Model::Instance manpage, the Config::Model::HashId manpage, the Config::Model::ListId manpage, the Config::Model::CheckList manpage, the Config::Model::WarpedNode manpage, the Config::Model::Value manpage