1Config::Model::Node(3)User Contributed Perl DocumentationConfig::Model::Node(3)
2
3
4

NAME

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

VERSION

9       version 2.138
10

SYNOPSIS

12        use Config::Model;
13
14        # define configuration tree object
15        my $model = Config::Model->new;
16        $model->create_config_class(
17           name              => 'OneConfigClass',
18           class_description => "OneConfigClass detailed description",
19
20           element => [
21               [qw/X Y Z/] => {
22                   type       => 'leaf',
23                   value_type => 'enum',
24                   choice     => [qw/Av Bv Cv/]
25               }
26           ],
27
28           status      => [ X => 'deprecated' ],
29           description => [ X => 'X-ray description (can be long)' ],
30           summary     => [ X => 'X-ray' ],
31
32           accept => [
33               'ip.*' => {
34                   type       => 'leaf',
35                   value_type => 'uniline',
36                   summary    => 'ip address',
37               }
38           ]
39        );
40        my $instance = $model->instance (root_class_name => 'OneConfigClass');
41        my $root = $instance->config_root ;
42
43        # X is not shown below because of its deprecated status
44        print $root->describe,"\n" ;
45        # name         value        type         comment
46        # Y            [undef]      enum         choice: Av Bv Cv
47        # Z            [undef]      enum         choice: Av Bv Cv
48
49        # add some data
50        $root->load( steps => 'Y=Av' );
51
52        # add some accepted element, ipA and ipB are created on the fly
53        $root->load( steps => q!ipA=192.168.1.0 ipB=192.168.1.1"! );
54
55        # show also ip* element created in the last "load" call
56        print $root->describe,"\n" ;
57        # name         value        type         comment
58        # Y            Av           enum         choice: Av Bv Cv
59        # Z            [undef]      enum         choice: Av Bv Cv
60        # ipA          192.168.1.0  uniline
61        # ipB          192.168.1.1  uniline
62

DESCRIPTION

64       This class provides the nodes of a configuration tree. When created, a
65       node object gets a set of rules that defines its properties within the
66       configuration tree.
67
68       Each node contain a set of elements. An element can contain:
69
70       ·   A leaf element implemented with Config::Model::Value. A leaf can be
71           plain (unconstrained value) or be strongly typed (values are
72           checked against a set of rules).
73
74       ·   Another node.
75
76       ·   A collection of items: a list element, implemented with
77           Config::Model::ListId. Each item can be another node or a leaf.
78
79       ·   A collection of identified items: a hash element, implemented with
80           Config::Model::HashId.  Each item can be another node or a leaf.
81

Configuration class declaration

83       A class declaration is made of the following parameters:
84
85       name
86           Mandatory "string" parameter. This config class name can be used by
87           a node element in another configuration class.
88
89       class_description
90           Optional "string" parameter. This description is used while
91           generating user interfaces.
92
93       class
94           Optional "string" to specify a Perl class to override the default
95           implementation (Config::Model::Node).  This Perl Class must inherit
96           Config::Model::Node. Use with care.
97
98       element
99           Mandatory "list ref" of elements of the configuration class :
100
101             element => [ foo => { type = 'leaf', ... },
102                          bar => { type = 'leaf', ... }
103                        ]
104
105           Element names can be grouped to save typing:
106
107             element => [ [qw/foo bar/] => { type = 'leaf', ... } ]
108
109           See below for details on element declaration.
110
111       gist
112           String used to construct a summary of the content of a node. This
113           parameter is used by user interface to show users the gist of the
114           content of this node. This parameter has no other effect. This
115           string may contain element values in the form ""{foo} or {bar}"".
116           When constructing the gist, "{foo}" is replaced by the value of
117           element "foo". Likewise for "{bar}".
118
119       level
120           Optional "list ref" of the elements whose level are different from
121           default value ("normal"). Possible values are "important", "normal"
122           or "hidden".
123
124           The level is used to set how configuration data is presented to the
125           user in browsing mode. "Important" elements are shown to the user
126           no matter what. "hidden" elements are explained with the warp
127           notion.
128
129             level  => [ [qw/X Y/] => 'important' ]
130
131       status
132           Optional "list ref" of the elements whose status are different from
133           default value ("standard"). Possible values are "obsolete",
134           "deprecated" or "standard".
135
136           Using a deprecated element issues a warning. Using an obsolete
137           element raises an exception (See Config::Model::Exception.
138
139             status  => [ [qw/X Y/] => 'obsolete' ]
140
141       description
142           Optional "list ref" of element summaries. These summaries may be
143           used when generating user interfaces.
144
145       description
146           Optional "list ref" of element descriptions. These descriptions may
147           be used when generating user interfaces.
148
149       rw_config
150       config_dir
151           Parameters used to load on demand configuration data.  See
152           Config::Model::BackendMgr for details.
153
154       accept
155           Optional list of criteria (i.e. a regular expression to match ) to
156           accept unknown elements. Each criteria has a list of specification
157           that enable "Config::Model" to create a model snippet for the
158           unknown element.
159
160           Example:
161
162            accept => [
163               'list.*' => {
164                   type  => 'list',
165                   cargo => {
166                       type       => 'leaf',
167                       value_type => 'string',
168                   },
169               },
170               'str.*' => {
171                   type       => 'leaf',
172                   value_type => 'uniline'
173               },
174             ]
175
176           All "element" parameters can be used in specifying accepted
177           elements.
178
179           If Text::Levenshtein::Damerau is installed, a warning is issued if
180           an accepted element is too close to an existing element.
181
182           The parameter "accept_after" to specify where to insert the
183           accepted element.  This does not change much the behavior of the
184           tree, but helps generate a more usable user interface.
185
186           Example:
187
188            element => [
189               'Bug' => { type => 'leaf', value_type => 'uniline' } ,
190            ]
191            accept => [
192               'Bug-.*' =>  {
193                    value_type => 'uniline',
194                    type => 'leaf'
195                    accept_after => 'Bug' ,
196               }
197            ]
198
199           The model snippet above ensures that "Bug-Debian" is shown right
200           after "bug".
201

Element declaration

203   Element type
204       Each element is declared with a list ref that contains all necessary
205       information:
206
207         element => [
208                      foo => { ... }
209                    ]
210
211       This most important information from this hash ref is the mandatory
212       type parameter. The type type can be:
213
214       "node"  The element is a node of a tree instantiated from a
215               configuration class (declared with "create_config_class( ... )"
216               in Config::Model).  See "Node element".
217
218       "warped_node"
219               The element is a node whose properties (mostly
220               "config_class_name") can be changed (warped) according to the
221               values of one or more leaf elements in the configuration tree.
222               See Config::Model::WarpedNode for details.
223
224       "leaf"  The element is a scalar value. See "Leaf element"
225
226       "hash"  The element is a collection of nodes or values (default). Each
227               element of this collection is identified by a string (Just like
228               a regular hash, except that you can set up constraint of the
229               keys).  See "Hash element"
230
231       "list"  The element is a collection of nodes or values (default). Each
232               element of this collection is identified by an integer (Just
233               like a regular perl array, except that you can set up
234               constraint of the keys).  See "List element"
235
236       "check_list"
237               The element is a collection of values which are unique in the
238               check_list. See CheckList.
239
240       "class" Override the default class for leaf, list and hash elements.
241               The override class be inherit Config::Model::Value for leaf
242               element, Config::Model::HashId for hash element and
243               Config::Model::ListId for list element.
244
245   Node element
246       When declaring a "node" element, you must also provide a
247       "config_class_name" parameter. For instance:
248
249        $model ->create_config_class
250          (
251          name => "ClassWithOneNode",
252          element => [
253                       the_node => {
254                                     type => 'node',
255                                     config_class_name => 'AnotherClass',
256                                   },
257                     ]
258          ) ;
259
260   Leaf element
261       When declaring a "leaf" element, you must also provide a "value_type"
262       parameter. See Config::Model::Value for more details.
263
264   Hash element
265       When declaring a "hash" element, you must also provide a "index_type"
266       parameter.
267
268       You can also provide a "cargo_type" parameter set to "node" or "leaf"
269       (default).
270
271       See Config::Model::HashId and Config::Model::AnyId for more details.
272
273   List element
274       You can also provide a "cargo_type" parameter set to "node" or "leaf"
275       (default).
276
277       See Config::Model::ListId and Config::Model::AnyId for more details.
278

Constructor

280       The "new" constructor accepts the following parameters:
281
282       config_file
283           Specify configuration file to be used by backend. This parameter
284           may override a file declared in the model. Note that this parameter
285           is not propagated in children nodes.
286

Introspection methods

288   name
289       Returns the location of the node, or its config class name (for root
290       node).
291
292   get_type
293       Returns "node".
294
295   config_model
296       Returns the entire configuration model (Config::Model object).
297
298   model
299       Returns the configuration model of this node (data structure).
300
301   config_class_name
302       Returns the configuration class name of this node.
303
304   instance
305       Returns the instance object containing this node. Inherited from
306       Config::Model::AnyThing
307
308   has_element
309       Parameters: "( name => element_name, [ type => searched_type ] )"
310
311       Returns 1 if the class model has the element declared or if the element
312       name is matched by the optional "accept" parameter. If "type" is
313       specified, the element name must also match the type.
314
315   find_element
316       Parameters: "( element_name , [ case => any ])"
317
318       Returns $name if the class model has the element declared or if the
319       element name is matched by the optional "accept" parameter.
320
321       If "case" is set to any, "has_element" returns the element name who
322       match the passed name in a case-insensitive manner.
323
324       Returns empty if no matching element is found.
325
326   model_searcher
327       Returns an object dedicated to search an element in the configuration
328       model.
329
330       This method returns a Config::Model::SearchElement object. See
331       Config::Model::SearchElement for details on how to handle a search.
332
333       This method is inherited from Config::Model::AnyThing.
334
335   element_model
336       Parameters: "( element_name )"
337
338       Returns model of the element.
339
340   element_type
341       Parameters: "( element_name )"
342
343       Returns the type (e.g. leaf, hash, list, checklist or node) of the
344       element. Also returns the type of a potentially accepted element.  Dies
345       if the element is not known or cannot be accepted.
346
347   element_name
348       Returns the element name that contain this object. Inherited from
349       Config::Model::AnyThing
350
351   index_value
352       See "index_value()" in Config::Model::AnyThing
353
354   parent
355       See "parent" in Config::Model::AnyThing
356
357   root
358       See "root" in Config::Model::AnyThing
359
360   location
361       See "location" in Config::Model::AnyThing
362
363   backend_support_annotation
364       Returns 1 if at least one of the backends attached to self or a parent
365       node support to read and write annotations (aka comments) in the
366       configuration file.
367

Element property management

369   get_element_names
370       Return all available element names, including the element that were
371       accepted.
372
373       Optional parameters are:
374
375       ·   all: Boolean. When set return all element names, even the hidden
376           ones and does not trigger warp mechanism. Defaults to 0. This
377           option should be set to 1 when this method is needed to read
378           configuration data from a backend.
379
380       ·   type: Returns only element of requested type (e.g. "list", "hash",
381           "leaf",...). By default return elements of any type.
382
383       ·   cargo_type: Returns only hash or list elements that contain the
384           requested cargo type.  E.g. if "get_element_names" is called with
385           "cargo_type => 'leaf'", then "get_element_names" returns hash or
386           list elements that contain a leaf object.
387
388       ·   check: "yes", "no" or "skip"
389
390       "type" and "cargo_type" parameters can be specified together. In this
391       case, this method returns parameters that satisfy both conditions. I.e.
392       with "type =>'hash', cargo_type => 'leaf'", this method returns only
393       hash elements that contain leaf objects.
394
395       Returns a list in array context, and a string (e.g. "join(' ',@array)")
396       in scalar context.
397
398   children
399       Like "get_element_names" without parameters. Returns the list of
400       elements. This method is polymorphic for all non-leaf objects of the
401       configuration tree.
402
403   next_element
404       This method provides a way to iterate through the elements of a node.
405       Mandatory parameter is "name". Optional parameter: "status".
406
407       Returns the next element name for status (default "normal").  Returns
408       undef if no next element is available.
409
410   previous_element
411       Parameters: "( name => element_name )"
412
413       This method provides a way to iterate through the elements of a node.
414
415       Returns the previous element name. Returns undef if no previous element
416       is available.
417
418   get_element_property
419       Parameters: "( element => ..., property => ... )"
420
421       Retrieve a property of an element.
422
423       I.e. for a model :
424
425         status     => [ X => 'deprecated' ]
426         element    => [ X => { ... } ]
427
428       This call returns "deprecated":
429
430         $node->get_element_property ( element => 'X', property => 'status' )
431
432   set_element_property
433       Parameters: "( element => ..., property => ... )"
434
435       Set a property of an element.
436
437   reset_element_property
438       Parameters: "( element => ... )"
439
440       Reset a property of an element according to the original model.
441

Information management

443   fetch_element
444       Parameters: "( name => .. , [ check => ..] )"
445
446       Fetch and returns an element from a node.
447
448       check can be set to yes, no or skip. When check is "no" or "skip", can
449       return "undef" when the element is unknown, or 0 if the element is not
450       available (hidden).
451
452   fetch_element_value
453       Parameters: "( name => ... [ check => ...] )"
454
455       Fetch and returns the value of a leaf element from a node.
456
457   fetch_gist
458       Return the gist of the node. See description of "gist" parameter above.
459
460   store_element_value
461       Parameters: "( name, value )"
462
463       Store a value in a leaf element from a node.
464
465       Can be invoked with named parameters (name, value, check). E.g.
466
467        ( name => 'foo', value => 'bar', check => 'skip' )
468
469   is_element_available
470       Parameters: "( name => ...,  )"
471
472       Returns 1 if the element "name" is available and if the element is not
473       "hidden". Returns 0 otherwise.
474
475       As a syntactic sugar, this method can be called with only one
476       parameter:
477
478          is_element_available( 'element_name' ) ;
479
480   accept_element
481       Parameters: "( name )"
482
483       Checks and returns the appropriate model of an acceptable element (i.e.
484       declared as a model "element" or part of an "accept" declaration).
485       Returns undef if the element cannot be accepted.
486
487   accept_regexp
488       Parameters: "( name )"
489
490       Returns the list of regular expressions used to check for acceptable
491       parameters.  Useful for diagnostics.
492
493   element_exists
494       Parameters: "( element_name )"
495
496       Returns 1 if the element is known in the model.
497
498   is_element_defined
499       Parameters: "( element_name )"
500
501       Returns 1 if the element is defined.
502
503   grab
504       See "grab"" in Config::Model::Role::Grab.
505
506   grab_value
507       See "grab_value"" in Config::Model::Role::Grab.
508
509   grab_root
510       See "grab_root" in Config::Model::Role::Grab.
511
512   get
513       Parameters: "( path => ..., mode => ... ,  check => ... , get_obj =>
514       1|0, autoadd => 1|0)"
515
516       Get a value from a directory like path. If "get_obj" is 1, "get"
517       returns a leaf object instead of returning its value.
518
519   set
520       Parameters: "( path  , value)"
521
522       Set a value from a directory like path.
523

Validation

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

data modification

530   migrate
531       Force a read of the configuration and perform all changes regarding
532       deprecated elements or values. Return 1 if data needs to be saved.
533
534   apply_fixes
535       Scan the tree from this node and apply fixes that are attached to
536       warning specifications.  See "warn_if_match" or "warn_unless_match" in
537       "" in Config::Model::Value.
538
539   load
540       Parameters: "( steps => string [ ... ])"
541
542       Load configuration data from the string into the node and its siblings.
543
544       This string follows the syntax defined in Config::Model::Loader.  See
545       "load" in Config::Model::Loader for details on parameters.
546
547       This method can also be called with a single parameter:
548
549         $node->load("some data:to be=loaded");
550
551   load_data
552       Parameters: "( data => hash_ref, [ check => $check, ...  ])"
553
554       Load configuration data with a hash ref. The hash ref key must match
555       the available elements of the node (or accepted element). The hash ref
556       structure must match the structure of the configuration model.
557
558       Use "check => skip" to make data loading more tolerant: bad data are
559       discarded.
560
561       "load_data" can be called with a single hash ref parameter.
562
563   needs_save
564       return 1 if one of the elements of the node's sub-tree has been
565       modified.
566

Serialization

568   dump_tree
569       Dumps the configuration data of the node and its siblings into a
570       string.  See "dump_tree" in Config::Model::Dumper for parameter
571       details.
572
573       This string follows the syntax defined in Config::Model::Loader. The
574       string produced by "dump_tree" can be passed to "load".
575
576   dump_annotations_as_pod
577       Dumps the configuration annotations of the node and its siblings into a
578       string.  See "dump_annotations_as_pod" in Config::Model::Dumper for
579       parameter details.
580
581   describe
582       Parameters: "( [ element => ... ] )"
583
584       Provides a description of the node elements or of one element.
585
586   report
587       Provides a text report on the content of the configuration below this
588       node.
589
590   audit
591       Provides a text audit on the content of the configuration below this
592       node. This audit shows only value different from their default value.
593
594   copy_from
595       Parameters: "( from => another_node_object, [ check => ... ] )"
596
597       Copy configuration data from another node into this node and its
598       siblings. The copy can be made in a tolerant mode where invalid data is
599       discarded with "check => skip". This method can be called with a single
600       argument: "copy_from($another_node)"
601

Help management

603   get_help
604       Parameters: "( [ [ description | summary ] => element_name ] )"
605
606       If called without element, returns the description of the class (Stored
607       in "class_description" attribute of a node declaration).
608
609       If called with an element name, returns the description of the element
610       (Stored in "description" attribute of a node declaration).
611
612       If called with 2 argument, either return the "summary" or the
613       "description" of the element.
614
615       Returns an empty string if no description was found.
616
617   tree_searcher
618       Parameters: "( type => ... )"
619
620       Returns an object able to search the configuration tree.  Parameters
621       are :
622
623       type
624           Where to perform the search. It can be "element", "value", "key",
625           "summary", "description", "help" or "all".
626
627       Then, "search" method must then be called on the object returned by
628       "tree_searcher".
629
630       Returns a Config::Model::TreeSearcher object.
631
632   Lazy load of node data
633       As configuration model are getting bigger, the load time of a tree gets
634       longer. The Config::Model::BackendMgr class provides a way to load the
635       configuration information only when needed.
636

AUTHOR

638       Dominique Dumont, (ddumont at cpan dot org)
639

SEE ALSO

641       Config::Model, Config::Model::Instance, Config::Model::HashId,
642       Config::Model::ListId, Config::Model::CheckList,
643       Config::Model::WarpedNode, Config::Model::Value
644

AUTHOR

646       Dominique Dumont
647
649       This software is Copyright (c) 2005-2019 by Dominique Dumont.
650
651       This is free software, licensed under:
652
653         The GNU Lesser General Public License, Version 2.1, February 1999
654
655
656
657perl v5.30.1                      2020-01-29            Config::Model::Node(3)
Impressum