Config::Model::Node

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.

"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.

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.

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.

model_searcher ()

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.

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

backend_support_annotation

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.

get_element_name ( ... )

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

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.

previous_element ( 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.

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

Retrieve a property of an element.

I.e. for a model :

  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.

fetch_element ( name => .. , [ check => ..] )

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

fetch_element_value ( name => ... [ check => ...] )

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

store_element_value ( name, value )

Store a value in a leaf element from a node.

Can be invoked with named parameters (name, value, check)

is_element_available( 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' ) ;

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.

migrate

Force a read of the configuration and perform all changes regarding deprecated elements or values. Return 1 if data needs to be saved.

apply_fixes

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.

load ( step => 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");

load_data ( 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 will be discarded.

"load_data" can be called with a single hash ref parameter.

needs_save

return 1 if one of the elements of the node's sub-tree has been modified.

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 ( 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)"

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.

tree_searcher( 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".

Typically, you will have to call "search" on this object.

Returns a Config::Model::TreeSearcher object.

Lazy load of node data

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.