Provided by: libconfig-model-perl_2.047-1_all bug

NAME

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

VERSION

       version 2.047

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::BackendMgr
           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.

           The parameter "accept_after" to specify where to insert the accepted element.  This
           will not change much the behavior of the tree, but it will help generate user
           interface easier to use.

           Example:

            element => [
               'Bug' => { type => 'leaf', value_type => 'uniline' } ,
            ]
            accept => [
               'Bug-.*' =>  {
                    value_type => 'uniline',
                    type => 'leaf'
                    accept_after => 'Bug' ,
               }
            ]

           The model snippet above will ensure that "Bug-Debian" will be shown right after "bug".

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.

   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

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 ( ... )
       This method provides a way to iterate through the elements of a node.  Mandatory parameter
       is "name". Optional parameters are "experience" and "status".

       Returns the next element name for a given experience (default "master") and status
       (default "normal").  Returns undef if no next element is available.

   previous_element ( name => element_name, [ experience => min_experience ] )
       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. 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.

       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.

data modification

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

Serialization

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

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.

   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.

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

AUTHOR

       Dominique Dumont

COPYRIGHT AND LICENSE

       This software is Copyright (c) 2013 by Dominique Dumont.

       This is free software, licensed under:

         The GNU Lesser General Public License, Version 2.1, February 1999