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.150
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       Arguments: "( name => element_name, [ type => searched_type ],  [
310       autoadd => 1 ] )"
311
312       Returns 1 if the class model has the element declared.
313
314       Returns 1 as well if "autoadd" is 1 (i.e. by default) and the element
315       name is matched by the optional "accept" model parameter.
316
317       If "type" is specified, the element name must also match the type.
318
319   find_element
320       Parameters: "( element_name , [ case => any ])"
321
322       Returns $name if the class model has the element declared or if the
323       element name is matched by the optional "accept" parameter.
324
325       If "case" is set to any, "has_element" returns the element name who
326       match the passed name in a case-insensitive manner.
327
328       Returns empty if no matching element is found.
329
330   model_searcher
331       Returns an object dedicated to search an element in the configuration
332       model.
333
334       This method returns a Config::Model::SearchElement object. See
335       Config::Model::SearchElement for details on how to handle a search.
336
337       This method is inherited from Config::Model::AnyThing.
338
339   element_model
340       Parameters: "( element_name )"
341
342       Returns model of the element.
343
344   element_type
345       Parameters: "( element_name )"
346
347       Returns the type (e.g. leaf, hash, list, checklist or node) of the
348       element. Also returns the type of a potentially accepted element.  Dies
349       if the element is not known or cannot be accepted.
350
351   element_name
352       Returns the element name that contain this object. Inherited from
353       Config::Model::AnyThing
354
355   index_value
356       See "index_value()" in Config::Model::AnyThing
357
358   parent
359       See "parent" in Config::Model::AnyThing
360
361   root
362       See "root" in Config::Model::AnyThing
363
364   location
365       See "location" in Config::Model::AnyThing
366
367   backend_support_annotation
368       Returns 1 if at least one of the backends attached to self or a parent
369       node support to read and write annotations (aka comments) in the
370       configuration file.
371

Element property management

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

Information management

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

Validation

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

data modification

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

Serialization

582   dump_tree
583       Dumps the configuration data of the node and its siblings into a
584       string.  See "dump_tree" in Config::Model::Dumper for parameter
585       details.
586
587       This string follows the syntax defined in Config::Model::Loader. The
588       string produced by "dump_tree" can be passed to "load".
589
590   dump_annotations_as_pod
591       Dumps the configuration annotations of the node and its siblings into a
592       string.  See "dump_annotations_as_pod" in Config::Model::Dumper for
593       parameter details.
594
595   describe
596       Parameters: "( [ element => ... ] )"
597
598       Provides a description of the node elements or of one element.
599
600   report
601       Provides a text report on the content of the configuration below this
602       node.
603
604   audit
605       Provides a text audit on the content of the configuration below this
606       node. This audit shows only value different from their default value.
607
608   copy_from
609       Parameters: "( from => another_node_object, [ check => ... ] )"
610
611       Copy configuration data from another node into this node and its
612       siblings. The copy can be made in a tolerant mode where invalid data is
613       discarded with "check => skip". This method can be called with a single
614       argument: "copy_from($another_node)"
615

Help management

617   get_help
618       Parameters: "( [ [ description | summary ] => element_name ] )"
619
620       If called without element, returns the description of the class (Stored
621       in "class_description" attribute of a node declaration).
622
623       If called with an element name, returns the description of the element
624       (Stored in "description" attribute of a node declaration).
625
626       If called with 2 argument, either return the "summary" or the
627       "description" of the element.
628
629       Returns an empty string if no description was found.
630
631   get_info
632       Returns a list of information related to the node. See "get_info" in
633       Config::Model::Value for more details.
634
635   tree_searcher
636       Parameters: "( type => ... )"
637
638       Returns an object able to search the configuration tree.  Parameters
639       are :
640
641       type
642           Where to perform the search. It can be "element", "value", "key",
643           "summary", "description", "help" or "all".
644
645       Then, "search" method must then be called on the object returned by
646       "tree_searcher".
647
648       Returns a Config::Model::TreeSearcher object.
649
650   Lazy load of node data
651       As configuration model are getting bigger, the load time of a tree gets
652       longer. The Config::Model::BackendMgr class provides a way to load the
653       configuration information only when needed.
654

AUTHOR

656       Dominique Dumont, (ddumont at cpan dot org)
657

SEE ALSO

659       Config::Model, Config::Model::Instance, Config::Model::HashId,
660       Config::Model::ListId, Config::Model::CheckList,
661       Config::Model::WarpedNode, Config::Model::Value
662

AUTHOR

664       Dominique Dumont
665
667       This software is Copyright (c) 2005-2022 by Dominique Dumont.
668
669       This is free software, licensed under:
670
671         The GNU Lesser General Public License, Version 2.1, February 1999
672
673
674
675perl v5.34.1                      2022-05-09            Config::Model::Node(3)
Impressum