1Config::Model::Node(3)User Contributed Perl DocumentationConfig::Model::Node(3)
2
6 Config::Model::Node - Class for configuration tree node
7
9 version 2.152
10
12 use Config::Model;
13 # 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 element => [
21 [qw/X Y Z/] => {
22 type => 'leaf',
23 value_type => 'enum',
24 choice => [qw/Av Bv Cv/]
25 }
26 ],
27 status => [ X => 'deprecated' ],
29 description => [ X => 'X-ray description (can be long)' ],
30 summary => [ X => 'X-ray' ],
31 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 # 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 # add some data
50 $root->load( steps => 'Y=Av' );
51 # 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 # 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
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 Each node contain a set of elements. An element can contain:
69 • 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 • Another node.
75 • A collection of items: a list element, implemented with
77 Config::Model::ListId. Each item can be another node or a leaf.
78 • A collection of identified items: a hash element, implemented with
80 Config::Model::HashId. Each item can be another node or a leaf.
81
83 A class declaration is made of the following parameters:
84 name
86 Mandatory "string" parameter. This config class name can be used by
87 a node element in another configuration class.
88 class_description
90 Optional "string" parameter. This description is used while
91 generating user interfaces.
92 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 element
99 Mandatory "list ref" of elements of the configuration class :
100 element => [ foo => { type = 'leaf', ... },
102 bar => { type = 'leaf', ... }
103 ]
104 Element names can be grouped to save typing:
106 element => [ [qw/foo bar/] => { type = 'leaf', ... } ]
108 See below for details on element declaration.
110 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 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 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 level => [ [qw/X Y/] => 'important' ]
130 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 Using a deprecated element issues a warning. Using an obsolete
137 element raises an exception (See Config::Model::Exception.
138 status => [ [qw/X Y/] => 'obsolete' ]
140 description
142 Optional "list ref" of element summaries. These summaries may be
143 used when generating user interfaces.
144 description
146 Optional "list ref" of element descriptions. These descriptions may
147 be used when generating user interfaces.
148 rw_config
150 config_dir
151 Parameters used to load on demand configuration data. See
152 Config::Model::BackendMgr for details.
153 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 Example:
161 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 All "element" parameters can be used in specifying accepted
177 elements.
178 If Text::Levenshtein::Damerau is installed, a warning is issued if
180 an accepted element is too close to an existing element.
181 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 Example:
187 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 The model snippet above ensures that "Bug-Debian" is shown right
200 after "bug".
201
203 Element type
204 Each element is declared with a list ref that contains all necessary
205 information:
206 element => [
208 foo => { ... }
209 ]
210 This most important information from this hash ref is the mandatory
212 type parameter. The type type can be:
213 "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 "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 "leaf" The element is a scalar value. See "Leaf element"
225 "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 "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 "check_list"
237 The element is a collection of values which are unique in the
238 check_list. See CheckList.
239 "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 Node element
246 When declaring a "node" element, you must also provide a
247 "config_class_name" parameter. For instance:
248 $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 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 Hash element
265 When declaring a "hash" element, you must also provide a "index_type"
266 parameter.
267 You can also provide a "cargo_type" parameter set to "node" or "leaf"
269 (default).
270 See Config::Model::HashId and Config::Model::AnyId for more details.
272 List element
274 You can also provide a "cargo_type" parameter set to "node" or "leaf"
275 (default).
276 See Config::Model::ListId and Config::Model::AnyId for more details.
278
280 The "new" constructor accepts the following parameters:
281 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
288 name
289 Returns the location of the node, or its config class name (for root
290 node).
291 get_type
293 Returns "node".
294 config_model
296 Returns the entire configuration model (Config::Model object).
297 model
299 Returns the configuration model of this node (data structure).
300 config_class_name
302 Returns the configuration class name of this node.
303 instance
305 Returns the instance object containing this node. Inherited from
306 Config::Model::AnyThing
307 has_element
309 Arguments: "( name => element_name, [ type => searched_type ], [
310 autoadd => 1 ] )"
311 Returns 1 if the class model has the element declared.
313 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 If "type" is specified, the element name must also match the type.
318 find_element
320 Parameters: "( element_name , [ case => any ])"
321 Returns $name if the class model has the element declared or if the
323 element name is matched by the optional "accept" parameter.
324 If "case" is set to any, "has_element" returns the element name who
326 match the passed name in a case-insensitive manner.
327 Returns empty if no matching element is found.
329 model_searcher
331 Returns an object dedicated to search an element in the configuration
332 model.
333 This method returns a Config::Model::SearchElement object. See
335 Config::Model::SearchElement for details on how to handle a search.
336 This method is inherited from Config::Model::AnyThing.
338 element_model
340 Parameters: "( element_name )"
341 Returns model of the element.
343 element_type
345 Parameters: "( element_name )"
346 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 element_name
352 Returns the element name that contain this object. Inherited from
353 Config::Model::AnyThing
354 index_value
356 See "index_value()" in Config::Model::AnyThing
357 parent
359 See "parent" in Config::Model::AnyThing
360 root
362 See "root" in Config::Model::AnyThing
363 location
365 See "location" in Config::Model::AnyThing
366 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
373 get_element_names
374 Return all available element names, including the element that were
375 accepted.
376 Optional parameters are:
378 • all: 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 • type: Returns only element of requested type (e.g. "list", "hash",
385 "leaf",...). By default return elements of any type.
386 • cargo_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 • check: "yes", "no" or "skip"
393 "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 Returns a list in array context, and a string (e.g. "join(' ',@array)")
400 in scalar context.
401 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 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 Returns the next element name for status (default "normal"). Returns
412 undef if no next element is available.
413 previous_element
415 Parameters: "( name => element_name )"
416 This method provides a way to iterate through the elements of a node.
418 Returns the previous element name. Returns undef if no previous element
420 is available.
421 get_element_property
423 Parameters: "( element => ..., property => ... )"
424 Retrieve a property of an element.
426 I.e. for a model :
428 status => [ X => 'deprecated' ]
430 element => [ X => { ... } ]
431 This call returns "deprecated":
433 $node->get_element_property ( element => 'X', property => 'status' )
435 set_element_property
437 Parameters: "( element => ..., property => ... )"
438 Set a property of an element.
440 reset_element_property
442 Parameters: "( element => ... )"
443 Reset a property of an element according to the original model.
445
447 fetch_element
448 Arguments: "( name => .. , [ check => ..], [ autoadd => 1 ] )"
449 Fetch and returns an element from a node if the class model has the
451 element declared.
452 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 "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 By default, "accepted" elements are automatically created. Set
462 "autoadd" to 0 when this behavior is not wanted.
463 fetch_element_value
465 Parameters: "( name => ... [ check => ...] )"
466 Fetch and returns the value of a leaf element from a node.
468 fetch_gist
470 Return the gist of the node. See description of "gist" parameter above.
471 store_element_value
473 Parameters: "( name, value )"
474 Store a value in a leaf element from a node.
476 Can be invoked with named parameters (name, value, check). E.g.
478 ( name => 'foo', value => 'bar', check => 'skip' )
480 is_element_available
482 Parameters: "( name => ..., )"
483 Returns 1 if the element "name" is available and if the element is not
485 "hidden". Returns 0 otherwise.
486 As a syntactic sugar, this method can be called with only one
488 parameter:
489 is_element_available( 'element_name' ) ;
491 accept_element
493 Parameters: "( name )"
494 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 accept_regexp
500 Parameters: "( name )"
501 Returns the list of regular expressions used to check for acceptable
503 parameters. Useful for diagnostics.
504 element_exists
506 Parameters: "( element_name )"
507 Returns 1 if the element is known in the model.
509 is_element_defined
511 Parameters: "( element_name )"
512 Returns 1 if the element is defined.
514 grab
516 See "grab"" in Config::Model::Role::Grab.
517 grab_value
519 See "grab_value"" in Config::Model::Role::Grab.
520 grab_root
522 See "grab_root" in Config::Model::Role::Grab.
523 get
525 Parameters: "( path => ..., mode => ... , check => ... , get_obj =>
526 1|0, autoadd => 1|0)"
527 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 set
532 Parameters: "( path , value)"
533 Set a value from a directory like path.
535
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
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 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. Return $self since v2.151.
550 load
552 Parameters: "( steps => string [ ... ])"
553 Load configuration data from the string into the node and its siblings.
555 This string follows the syntax defined in Config::Model::Loader. See
557 "load" in Config::Model::Loader for details on parameters.
558 This method can also be called with a single parameter:
560 $node->load("some data:to be=loaded");
562 load_data
564 Parameters: "( data => hash_ref, [ check => $check, ... ])"
565 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 Use "check => skip" to make data loading more tolerant: bad data are
571 discarded.
572 "load_data" can be called with a single hash ref parameter.
574 Returns 1 if some data were saved (instead of skipped).
576 needs_save
578 return 1 if one of the elements of the node's sub-tree has been
579 modified.
580
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 This string follows the syntax defined in Config::Model::Loader. The
588 string produced by "dump_tree" can be passed to "load".
589 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 describe
596 Parameters: "( [ element => ... ] )"
597 Provides a description of the node elements or of one element.
599 report
601 Provides a text report on the content of the configuration below this
602 node.
603 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 copy_from
609 Parameters: "( from => another_node_object, [ check => ... ] )"
610 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
617 get_help
618 Parameters: "( [ [ description | summary ] => element_name ] )"
619 If called without element, returns the description of the class (Stored
621 in "class_description" attribute of a node declaration).
622 If called with an element name, returns the description of the element
624 (Stored in "description" attribute of a node declaration).
625 If called with 2 argument, either return the "summary" or the
627 "description" of the element.
628 Returns an empty string if no description was found.
630 get_info
632 Returns a list of information related to the node. See "get_info" in
633 Config::Model::Value for more details.
634 tree_searcher
636 Parameters: "( type => ... )"
637 Returns an object able to search the configuration tree. Parameters
639 are :
640 type
642 Where to perform the search. It can be "element", "value", "key",
643 "summary", "description", "help" or "all".
644 Then, "search" method must then be called on the object returned by
646 "tree_searcher".
647 Returns a Config::Model::TreeSearcher object.
649 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
656 Dominique Dumont, (ddumont at cpan dot org)
657
659 Config::Model, Config::Model::Instance, Config::Model::HashId,
660 Config::Model::ListId, Config::Model::CheckList,
661 Config::Model::WarpedNode, Config::Model::Value
662
664 Dominique Dumont
665
667 This software is Copyright (c) 2005-2022 by Dominique Dumont.
668 This is free software, licensed under:
670 The GNU Lesser General Public License, Version 2.1, February 1999
672perl v5.36.0 2022-08-10 Config::Model::Node(3)