plucky (3) Config::Model::Node.3pm.gz

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

NAME

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

VERSION

       version 2.155

SYNOPSIS

        use Config::Model;

        # 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/]
               }
           ],

           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( steps => 'Y=Av' );

        # add some accepted element, ipA and ipB are created on the fly
        $root->load( steps => 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 gets a set of rules
       that defines 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 is used while generating user interfaces.

       class
           Optional "string" to specify a Perl class to override the default implementation
           (Config::Model::Node).  This Perl Class must inherit Config::Model::Node. Use with care.

       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.

       gist
           String used to construct a summary of the content of a node. This parameter is used by user interface
           to show users the gist of the content of this node. This parameter has no other effect. This string
           may contain element values in the form ""{foo} or {bar}"". When constructing the gist, "{foo}" is
           replaced by the value of element "foo". Likewise for "{bar}".

       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 are shown to the user no matter what. "hidden" elements are 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 issues a warning. Using an obsolete element raises an exception (See
           Config::Model::Exception.

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

       description
           Optional "list ref" of element summaries. These summaries may be used when generating user
           interfaces.

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

       rw_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 elements. Each
           criteria has a list of specification that 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 elements.

           If Text::Levenshtein::Damerau is installed, a warning is issued if an accepted element is too close
           to an existing element.

           The parameter "accept_after" to specify where to insert the accepted element.  This does not change
           much the behavior of the tree, but helps generate a more usable user interface.

           Example:

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

           The model snippet above ensures that "Bug-Debian" is 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 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.

Constructor

       The "new" constructor accepts the following parameters:

       config_file
           Specify configuration file to be used by backend. This parameter may override a file declared in the
           model. Note that this parameter is not propagated in children nodes.

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
       Arguments: "( name => element_name, [ type => searched_type ],  [ autoadd => 1 ] )"

       Returns 1 if the class model has the element declared.

       Returns 1 as well if "autoadd" is 1 (i.e. by default) and the element name is matched by the optional
       "accept" model parameter.

       If "type" is specified, the element name must also match the type.

   find_element
       Parameters: "( 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" returns 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.

       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
       Parameters: "( element_name )"

       Returns model of the element.

   element_type
       Parameters: "( element_name )"

       Returns the type (e.g. leaf, hash, list, checklist or node) of the element. Also returns the type of a
       potentially accepted element.  Dies if the element is not known or cannot be accepted.

   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.

Element property management

   get_element_names
       Return all available element names, including the element that were accepted.

       Optional parameters are:

       •   all: Boolean. When set return all element names, even the hidden ones and does not trigger warp
           mechanism. Defaults to 0. This option should be set to 1 when this method is needed to read
           configuration data from a backend.

       •   type: Returns only element of requested type (e.g. "list", "hash", "leaf",...). By default return
           elements of any type.

       •   cargo_type: Returns only hash or list elements that contain the requested cargo type.  E.g. if
           "get_element_names" is called with "cargo_type => 'leaf'", then "get_element_names" returns hash or
           list elements that contain a leaf object.

       •   check: "yes", "no" or "skip"

       "type" and "cargo_type" parameters can be specified together. In this case, this method returns
       parameters that satisfy both conditions. I.e. with "type =>'hash', cargo_type => 'leaf'", this method
       returns only hash elements that contain leaf objects.

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

   children
       Like "get_element_names" 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
       Parameters: "( 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
       Parameters: "( element => ..., property => ... )"

       Retrieve a property of an element.

       I.e. for a model :

         status     => [ X => 'deprecated' ]
         element    => [ X => { ... } ]

       This call returns "deprecated":

         $node->get_element_property ( element => 'X', property => 'status' )

   set_element_property
       Parameters: "( element => ..., property => ... )"

       Set a property of an element.

   reset_element_property
       Parameters: "( element => ... )"

       Reset a property of an element according to the original model.

Information management

   fetch_element
       Arguments: "( name => .. , [ check => ..], [ autoadd => 1 ] )"

       Fetch and returns an element from a node if the class model has the element declared.

       Also fetch and returns an element from a node if "autoadd" is 1 (i.e. by default) and the element name is
       matched by the optional "accept" model parameter.

       "check" can be set to "yes", "no" or "skip".  When "check" is "no" or "skip", this method returns "undef"
       when the element is unknown, or 0 if the element is not available (hidden).

       By default, "accepted" elements are automatically created. Set "autoadd" to 0 when this behavior is not
       wanted.

   fetch_element_value
       Parameters: "( name => ... [ check => ...] )"

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

   fetch_gist
       Return the gist of the node. See description of "gist" parameter above.

   store_element_value
       Parameters: "( name, value )"

       Store a value in a leaf element from a node.

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

        ( name => 'foo', value => 'bar', check => 'skip' )

   is_element_available
       Parameters: "( 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
       Parameters: "( name )"

       Checks and returns the appropriate model of an acceptable element (i.e. declared as a model "element" or
       part of an "accept" declaration).  Returns undef if the element cannot be accepted.

   accept_regexp
       Parameters: "( name )"

       Returns the list of regular expressions used to check for acceptable parameters.  Useful for diagnostics.

   element_exists
       Parameters: "( element_name )"

       Returns 1 if the element is known in the model.

   is_element_defined
       Parameters: "( element_name )"

       Returns 1 if the element is defined.

   grab
       See "grab"" in Config::Model::Role::Grab.

   grab_value
       See "grab_value"" in Config::Model::Role::Grab.

   grab_root
       See "grab_root" in Config::Model::Role::Grab.

   get
       Parameters: "( path => ..., mode => ... ,  check => ... , get_obj => 1|0, autoadd => 1|0)"

       Get a value from a directory like path. If "get_obj" is 1, "get" returns a leaf object instead of
       returning its value.

   set
       Parameters: "( path  , value)"

       Set a value from a directory like path.

Validation

   deep_check
       Scan the tree and deep check on all elements that support this. Currently only hash or list element have
       this feature.

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. Return $self since v2.151.

   load
       Parameters: "( steps => 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
       Parameters: "( 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 are discarded.

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

       Returns 1 if some data were saved (instead of skipped).

   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
       Parameters: "( [ 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 shows only value
       different from their default value.

   copy_from
       Parameters: "( 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
       Parameters: "( [ [ 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.

   get_info
       Returns a list of information related to the node. See "get_info" in Config::Model::Value for more
       details.

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

       Then, "search" method must then be called on the object returned by "tree_searcher".

       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

       This software is Copyright (c) 2005-2022 by Dominique Dumont.

       This is free software, licensed under:

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