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.138
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 Parameters: "( name => element_name, [ type => searched_type ] )"
310 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 find_element
316 Parameters: "( element_name , [ case => any ])"
317 Returns $name if the class model has the element declared or if the
319 element name is matched by the optional "accept" parameter.
320 If "case" is set to any, "has_element" returns the element name who
322 match the passed name in a case-insensitive manner.
323 Returns empty if no matching element is found.
325 model_searcher
327 Returns an object dedicated to search an element in the configuration
328 model.
329 This method returns a Config::Model::SearchElement object. See
331 Config::Model::SearchElement for details on how to handle a search.
332 This method is inherited from Config::Model::AnyThing.
334 element_model
336 Parameters: "( element_name )"
337 Returns model of the element.
339 element_type
341 Parameters: "( element_name )"
342 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 element_name
348 Returns the element name that contain this object. Inherited from
349 Config::Model::AnyThing
350 index_value
352 See "index_value()" in Config::Model::AnyThing
353 parent
355 See "parent" in Config::Model::AnyThing
356 root
358 See "root" in Config::Model::AnyThing
359 location
361 See "location" in Config::Model::AnyThing
362 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
369 get_element_names
370 Return all available element names, including the element that were
371 accepted.
372 Optional parameters are:
374 · 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 · type: Returns only element of requested type (e.g. "list", "hash",
381 "leaf",...). By default return elements of any type.
382 · 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 · check: "yes", "no" or "skip"
389 "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 Returns a list in array context, and a string (e.g. "join(' ',@array)")
396 in scalar context.
397 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 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 Returns the next element name for status (default "normal"). Returns
408 undef if no next element is available.
409 previous_element
411 Parameters: "( name => element_name )"
412 This method provides a way to iterate through the elements of a node.
414 Returns the previous element name. Returns undef if no previous element
416 is available.
417 get_element_property
419 Parameters: "( element => ..., property => ... )"
420 Retrieve a property of an element.
422 I.e. for a model :
424 status => [ X => 'deprecated' ]
426 element => [ X => { ... } ]
427 This call returns "deprecated":
429 $node->get_element_property ( element => 'X', property => 'status' )
431 set_element_property
433 Parameters: "( element => ..., property => ... )"
434 Set a property of an element.
436 reset_element_property
438 Parameters: "( element => ... )"
439 Reset a property of an element according to the original model.
441
443 fetch_element
444 Parameters: "( name => .. , [ check => ..] )"
445 Fetch and returns an element from a node.
447 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 fetch_element_value
453 Parameters: "( name => ... [ check => ...] )"
454 Fetch and returns the value of a leaf element from a node.
456 fetch_gist
458 Return the gist of the node. See description of "gist" parameter above.
459 store_element_value
461 Parameters: "( name, value )"
462 Store a value in a leaf element from a node.
464 Can be invoked with named parameters (name, value, check). E.g.
466 ( name => 'foo', value => 'bar', check => 'skip' )
468 is_element_available
470 Parameters: "( name => ..., )"
471 Returns 1 if the element "name" is available and if the element is not
473 "hidden". Returns 0 otherwise.
474 As a syntactic sugar, this method can be called with only one
476 parameter:
477 is_element_available( 'element_name' ) ;
479 accept_element
481 Parameters: "( name )"
482 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 accept_regexp
488 Parameters: "( name )"
489 Returns the list of regular expressions used to check for acceptable
491 parameters. Useful for diagnostics.
492 element_exists
494 Parameters: "( element_name )"
495 Returns 1 if the element is known in the model.
497 is_element_defined
499 Parameters: "( element_name )"
500 Returns 1 if the element is defined.
502 grab
504 See "grab"" in Config::Model::Role::Grab.
505 grab_value
507 See "grab_value"" in Config::Model::Role::Grab.
508 grab_root
510 See "grab_root" in Config::Model::Role::Grab.
511 get
513 Parameters: "( path => ..., mode => ... , check => ... , get_obj =>
514 1|0, autoadd => 1|0)"
515 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 set
520 Parameters: "( path , value)"
521 Set a value from a directory like path.
523
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
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 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 load
540 Parameters: "( steps => string [ ... ])"
541 Load configuration data from the string into the node and its siblings.
543 This string follows the syntax defined in Config::Model::Loader. See
545 "load" in Config::Model::Loader for details on parameters.
546 This method can also be called with a single parameter:
548 $node->load("some data:to be=loaded");
550 load_data
552 Parameters: "( data => hash_ref, [ check => $check, ... ])"
553 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 Use "check => skip" to make data loading more tolerant: bad data are
559 discarded.
560 "load_data" can be called with a single hash ref parameter.
562 needs_save
564 return 1 if one of the elements of the node's sub-tree has been
565 modified.
566
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 This string follows the syntax defined in Config::Model::Loader. The
574 string produced by "dump_tree" can be passed to "load".
575 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 describe
582 Parameters: "( [ element => ... ] )"
583 Provides a description of the node elements or of one element.
585 report
587 Provides a text report on the content of the configuration below this
588 node.
589 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 copy_from
595 Parameters: "( from => another_node_object, [ check => ... ] )"
596 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
603 get_help
604 Parameters: "( [ [ description | summary ] => element_name ] )"
605 If called without element, returns the description of the class (Stored
607 in "class_description" attribute of a node declaration).
608 If called with an element name, returns the description of the element
610 (Stored in "description" attribute of a node declaration).
611 If called with 2 argument, either return the "summary" or the
613 "description" of the element.
614 Returns an empty string if no description was found.
616 tree_searcher
618 Parameters: "( type => ... )"
619 Returns an object able to search the configuration tree. Parameters
621 are :
622 type
624 Where to perform the search. It can be "element", "value", "key",
625 "summary", "description", "help" or "all".
626 Then, "search" method must then be called on the object returned by
628 "tree_searcher".
629 Returns a Config::Model::TreeSearcher object.
631 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
638 Dominique Dumont, (ddumont at cpan dot org)
639
641 Config::Model, Config::Model::Instance, Config::Model::HashId,
642 Config::Model::ListId, Config::Model::CheckList,
643 Config::Model::WarpedNode, Config::Model::Value
644
646 Dominique Dumont
647
649 This software is Copyright (c) 2005-2019 by Dominique Dumont.
650 This is free software, licensed under:
652 The GNU Lesser General Public License, Version 2.1, February 1999
654perl v5.30.1 2020-01-29 Config::Model::Node(3)