Config::Model::Node(3pm)

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 1.205
10

SYNOPSIS

12        $model->create_config_class
13         (
14          name              => 'OneConfigClass',
15          class_description => "OneConfigClass detailed description",
16
17          element           => [
18                                 [qw/X Y Z/]
19                                 => {
20                                      type => 'leaf',
21                                      value_type => 'enum',
22                                      choice     => [qw/Av Bv Cv/]
23                                    }
24                               ],
25
26          experience        => [ Y => 'beginner',
27                                 X => 'master'
28                               ],
29          status            => [ X => 'deprecated' ],
30          description       => [ X => 'X-ray description (can be long)' ],
31          summary           => [ X => 'X-ray' ],
32
33         );
34
35        my $instance = $model->instance (root_class_name => 'OneConfigClass',
36                                         instance_name => 'test1');
37        my $root_node = $instance -> config_root ;
38

DESCRIPTION

40       This class provides the nodes of a configuration tree. When created, a
41       node object will get a set of rules that will define its properties
42       within the configuration tree.
43
44       Each node contain a set of elements. An element can contain:
45
46       ·   A leaf element implemented with Config::Model::Value. A leaf can be
47           plain (unconstrained value) or be strongly typed (values are
48           checked against a set of rules).
49
50       ·   Another node.
51
52       ·   A collection of items: a list element, implemented with
53           Config::Model::ListId. Each item can be another node or a leaf.
54
55       ·   A collection of identified items: a hash element, implemented with
56           Config::Model::HashId.  Each item can be another node or a leaf.
57

Configuration class declaration

59       A class declaration is made of the following parameters:
60
61       name
62           Mandatory "string" parameter. This config class name can be used by
63           a node element in another configuration class.
64
65       class_description
66           Optional "string" parameter. This description will be used when
67           generating user interfaces.
68
69       element
70           Mandatory "list ref" of elements of the configuration class :
71
72             element => [ foo => { type = 'leaf', ... },
73                          bar => { type = 'leaf', ... }
74                        ]
75
76           Element names can be grouped to save typing:
77
78             element => [ [qw/foo bar/] => { type = 'leaf', ... } ]
79
80           See below for details on element declaration.
81
82       experience
83           Optional "list ref" of the elements whose experience are different
84           from default value ("beginner"). Possible values are "master",
85           "advanced" and "beginner".
86
87             experience   => [ Y => 'beginner',
88                               [qw/foo bar/] => 'master'
89                             ],
90
91       level
92           Optional "list ref" of the elements whose level are different from
93           default value ("normal"). Possible values are "important", "normal"
94           or "hidden".
95
96           The level is used to set how configuration data is presented to the
97           user in browsing mode. "Important" elements will be shown to the
98           user no matter what. "hidden" elements will be explained with the
99           warp notion.
100
101             level  => [ [qw/X Y/] => 'important' ]
102
103       status
104           Optional "list ref" of the elements whose status are different from
105           default value ("standard"). Possible values are "obsolete",
106           "deprecated" or "standard".
107
108           Using a deprecated element will issue a warning. Using an obsolete
109           element will raise an exception (See Config::Model::Exception.
110
111             status  => [ [qw/X Y/] => 'obsolete' ]
112
113       description
114           Optional "list ref" of element description. These descriptions will
115           be used when generating user interfaces.
116
117       description
118           Optional "list ref" of element summray. These descriptions will be
119           used when generating user interfaces or as comment when writing
120           configuration files.
121
122       read_config
123       write_config
124       config_dir
125           Parameters used to load on demand configuration data.  See
126           Config::Model::AutoRead for details.
127

Element declaration

129   Element type
130       Each element is declared with a list ref that contains all necessary
131       information:
132
133         element => [
134                      foo => { ... }
135                    ]
136
137       This most important information from this hash ref is the mandatory
138       type parameter. The type type can be:
139
140       "node"  The element is a simple node of a tree instanciated from a
141               configuration class (declared with "create_config_class( ... )"
142               in Config::Model).  See "Node element".
143
144       "warped_node"
145               The element is a node whose properties (mostly
146               "config_class_name") can be changed (warped) according to the
147               values of one or more leaf elements in the configuration tree.
148               See Config::Model::WarpedNode for details.
149
150       "leaf"  The element is a scalar value. See "Leaf element"
151
152       "hash"  The element is a collection of nodes or values (default). Each
153               element of this collection is identified by a string (Just like
154               a regular hash, except that you can set up constraint of the
155               keys).  See "Hash element"
156
157       "list"  The element is a collection of nodes or values (default). Each
158               element of this collection is identified by an integer (Just
159               like a regular perl array, except that you can set up
160               constraint of the keys).  See "List element"
161
162       "check_list"
163               The element is a collection of values which are unique in the
164               check_list. See CheckList.
165
166   Node element
167       When declaring a "node" element, you must also provide a
168       "config_class_name" parameter. For instance:
169
170        $model ->create_config_class
171          (
172          name => "ClassWithOneNode",
173          element => [
174                       the_node => {
175                                     type => 'node',
176                                     config_class_name => 'AnotherClass',
177                                   },
178                     ]
179          ) ;
180
181   Leaf element
182       When declaring a "leaf" element, you must also provide a "value_type"
183       parameter. See Config::Model::Value for more details.
184
185   Hash element
186       When declaring a "hash" element, you must also provide a "index_type"
187       parameter.
188
189       You can also provide a "cargo_type" parameter set to "node" or "leaf"
190       (default).
191
192       See Config::Model::HashId and Config::Model::AnyId for more details.
193
194   List element
195       You can also provide a "cargo_type" parameter set to "node" or "leaf"
196       (default).
197
198       See Config::Model::ListId and Config::Model::AnyId for more details.
199

Introspection methods

201   name
202       Returns the location of the node, or its config class name (for root
203       node).
204
205   get_type
206       Returns "node".
207
208   config_model
209       Returns the entire configuration model (Config::Model object).
210
211   model
212       Returns the configuration model of this node (data structure).
213
214   config_class_name
215       Returns the configuration class name of this node.
216
217   instance
218       Returns the instance object containing this node. Inherited from
219       Config::Model::AnyThing
220
221   has_element ( element_name )
222       Returns 1 if the class model has the element declared.
223
224   searcher ()
225       Returns an object dedicated to search an element in the configuration
226       model (respecting privilege level).
227
228       This method returns a Config::Model::Searcher object. See
229       Config::Model::Searcher for details on how to handle a search.
230
231       This method is inherited from Config::Model::AnyThing.
232
233   element_model ( element_name )
234       Returns model of the element.
235
236   element_type ( element_name )
237       Returns the type (e.g. leaf, hash, list, checklist or node) of the
238       element.
239
240   element_name()
241       Returns the element name that contain this object. Inherited from
242       Config::Model::AnyThing
243
244   index_value()
245       See "index_value()" in Config::Model::AnyThing
246
247   parent()
248       See "parent()" in Config::Model::AnyThing
249
250   root()
251       See "root()" in Config::Model::AnyThing
252
253   location()
254       See "location()" in Config::Model::AnyThing
255

Element property management

257   get_element_name ( for => <experience>, ...  )
258       Return all elements names available for "experience".  If no experience
259       is specified, will return all slots available at 'master' level (I.e
260       all elements).
261
262       Optional paremeters are:
263
264       ·   type: Returns only element of requested type (e.g. "list", "hash",
265           "leaf",...). By default return elements of any type.
266
267       ·   cargo_type: Returns only element which contain requested type.
268           E.g. if "get_element_name" is called with "cargo_type => leaf",
269           "get_element_name" will return simple leaf elements, but also hash
270           or list element that contain leaf object. By default return
271           elements of any type.
272
273       Returns an array in array context, and a string (e.g. "join('
274       ',@array)") in scalar context.
275
276   next_element ( element_name, [ experience_index ] )
277       This method provides a way to iterate through the elements of a node.
278
279       Returns the next element name for a given experience (default
280       "master").  Returns undef if no next element is available.
281
282   previous_element ( element_name, [ experience_index ] )
283       This method provides a way to iterate through the elements of a node.
284
285       Returns the previous element name for a given experience (default
286       "master").  Returns undef if no previous element is available.
287
288   get_element_property ( element => ..., property => ... )
289       Retrieve a property of an element.
290
291       I.e. for a model :
292
293         experience => [ X => 'master'],
294         status     => [ X => 'deprecated' ]
295         element    => [ X => { ... } ]
296
297       This call will return "deprecated":
298
299         $node->get_element_property ( element => 'X', property => 'status' )
300
301   set_element_property ( element => ..., property => ... )
302       Set a property of an element.
303
304   reset_element_property ( element => ... )
305       Reset a property of an element according to the model.
306

Information management

308   fetch_element ( name  [ , user_experience ])
309       Fetch and returns an element from a node.
310
311       If user_experience is given, this method will check that the user has
312       enough privilege to access the element. If not, a "RestrictedElement"
313       exception will be raised.
314
315   fetch_element_value ( name  [ , user_experience ])
316       Fetch and returns the value of a leaf element from a node.
317
318       If user_experience is given, this method will check that the user has
319       enough privilege to access the element. If not, a "RestrictedElement"
320       exception will be raised.
321
322   store_element_value ( name, value  [ , user_experience ])
323       Store a value in a leaf element from a node.
324
325       If user_experience is given, this method will check that the user has
326       enough privilege to access the element. If not, a "RestrictedElement"
327       exception will be raised.
328
329   is_element_available( name => ...,  experience => ... )
330       Returns 1 if the element "name" is available for the given "experience"
331       ('beginner' by default) and if the element is not "hidden". Returns 0
332       otherwise.
333
334       As a syntactic sugar, this method can be called with only one
335       parameter:
336
337          is_element_available( 'element_name' ) ;
338
339   element_exists( element_name )
340       Returns 1 if the element is known in the model.
341
342   is_element_defined( element_name )
343       Returns 1 if the element is defined.
344
345   grab(...)
346       See "grab(...)" in Config::Model::AnyThing.
347
348   grab_value(...)
349       See "grab_value(...)" in Config::Model::AnyThing.
350
351   grab_root()
352       See "grab_root()" in Config::Model::AnyThing.
353
354   get( path  [ custom | preset | standard | default ])
355       Get a value from a directory like path.
356
357   set( path  , value)
358       Set a value from a directory like path.
359

Serialisation

361   load ( step => string [, experience => ... ] )
362       Load configuration data from the string into the node and its siblings.
363
364       This string follows the syntax defined in Config::Model::Loader.  See
365       "load ( ... )" in Config::Model::Loader for details on parameters.
366       "experience" is 'master' by default.
367
368       This method can also be called with a single parameter:
369
370         $node->load("some data:to be=loaded");
371
372   load_data ( hash_ref )
373       Load configuration data with a hash ref. The hash ref key must match
374       the available elements of the node. The hash ref structure must match
375       the structure of the configuration model.
376
377   dump_tree ( ... )
378       Dumps the configuration data of the node and its siblings into a
379       string.  See "dump_tree" in Config::Model::Dumper for parameter
380       details.
381
382       This string follows the syntax defined in Config::Model::Loader. The
383       string produced by "dump_tree" can be passed to "load".
384
385   describe ( [ element => ... ] )
386       Provides a decription of the node elements or of one element.
387
388   report ()
389       Provides a text report on the content of the configuration below this
390       node.
391
392   audit ()
393       Provides a text audit on the content of the configuration below this
394       node. This audit will show only value different from their default
395       value.
396
397   copy_from ( another_node_object )
398       Copy configuration data from another node into this node and its
399       siblings. The copy is made in a tolerant mode where invalid data are
400       simply discarded.
401

Help management

403   get_help ( [ [ description | summary ] => element_name ] )
404       If called without element, returns the description of the class (Stored
405       in "class_description" attribute of a node declaration).
406
407       If called with an element name, returns the description of the element
408       (Stored in "description" attribute of a node declaration).
409
410       If called with 2 argument, either return the "summary" or the
411       "description" of the element.
412
413       Returns an empty string if no description was found.
414
415   AutoRead nodes
416       As configuration model are getting bigger, the load time of a tree gets
417       longer. The Config::Model::AutoRead class provides a way to load the
418       configuration information only when needed.
419
420       TBD
421

AUTHOR

423       Dominique Dumont, (ddumont at cpan dot org)
424