1Config::Model::AnyId(3)User Contributed Perl DocumentatioCnonfig::Model::AnyId(3)
2
3
4
6 Config::Model::AnyId - Base class for hash or list element
7
9 version 2.129
10
12 use Config::Model;
13
14 # define configuration tree object
15 my $model = Config::Model->new;
16 $model->create_config_class(
17 name => "Foo",
18 element => [
19 [qw/foo bar/] => {
20 type => 'leaf',
21 value_type => 'string'
22 },
23 ]
24 );
25
26 $model->create_config_class(
27 name => "MyClass",
28 element => [
29 plain_hash => {
30 type => 'hash',
31 index_type => 'string',
32 cargo => {
33 type => 'leaf',
34 value_type => 'string',
35 },
36 },
37 bounded_hash => {
38 type => 'hash', # hash id
39 index_type => 'integer',
40
41 # hash boundaries
42 min_index => 1, max_index => 123, max_nb => 2,
43
44 # specify cargo held by hash
45 cargo => {
46 type => 'leaf',
47 value_type => 'string'
48 },
49 },
50 bounded_list => {
51 type => 'list', # list id
52
53 max_index => 123,
54 cargo => {
55 type => 'leaf',
56 value_type => 'string'
57 },
58 },
59 hash_of_nodes => {
60 type => 'hash', # hash id
61 index_type => 'string',
62 cargo => {
63 type => 'node',
64 config_class_name => 'Foo'
65 },
66 },
67 ],
68 );
69
70 my $inst = $model->instance( root_class_name => 'MyClass' );
71
72 my $root = $inst->config_root;
73
74 # put data
75 my $steps = 'plain_hash:foo=boo bounded_list=foo,bar,baz
76 bounded_hash:3=foo bounded_hash:30=baz
77 hash_of_nodes:"foo node" foo="in foo node" -
78 hash_of_nodes:"bar node" bar="in bar node" ';
79 $root->load( steps => $steps );
80
81 # dump resulting tree
82 print $root->dump_tree;
83
85 This class provides hash or list elements for a Config::Model::Node.
86
87 The hash index can either be en enumerated type, a boolean, an integer
88 or a string.
89
91 AnyId object should not be created directly.
92
94 A hash or list element must be declared with the following parameters:
95
96 type
97 Mandatory element type. Must be "hash" or "list" to have a
98 collection element. The actual element type must be specified by
99 "cargo =" type> (See "CAVEATS").
100
101 index_type
102 Either "integer" or "string". Mandatory for hash.
103
104 ordered
105 Whether to keep the order of the hash keys (default no). (a bit
106 like Tie::IxHash). The hash keys are ordered along their creation.
107 The order can be modified with swap, move_up or move_down.
108
109 duplicates
110 Specify the policy regarding duplicated values stored in the list
111 or as hash values (valid only when cargo type is "leaf"). The
112 policy can be "allow" (default), "suppress", "warn" (which offers
113 the possibility to apply a fix), "forbid". Note that duplicates
114 check cannot be performed when the duplicated value is stored: this
115 happens outside of this object. Duplicates can be check only after
116 when the value is read.
117
118 write_empty_value
119 By default, hash entries without data are not saved in
120 configuration files. Without data means the cargo of the hash key
121 is empty: either its value is undef or all the values of the
122 contained node are also empty.
123
124 Set this parameter to 1 if the key must be saved in the
125 configuration file even if the hash contains no value for that key.
126
127 Note that writing hash entries without value may not be supported
128 by all backends. Use with care. Supported only for hash elements.
129
130 cargo
131 Hash ref specifying the cargo held by the hash of list. This has
132 must contain:
133
134 type Can be "node" or "leaf" (default).
135
136 config_class_name
137 Specifies the type of configuration object held in the
138 hash. Only valid when "cargo" "type" is "node".
139
140 <other> Constructor arguments passed to the cargo object. See
141 Config::Model::Node when "cargo->type" is "node". See
142 Config::Model::Value when "cargo->type" is "leaf".
143
144 min_index
145 Specify the minimum value (optional, only for hash and for integer
146 index)
147
148 max_index
149 Specify the maximum value (optional, only for list or for hash with
150 integer index)
151
152 max_nb
153 Specify the maximum number of indexes. (hash only, optional, may
154 also be used with string index type)
155
156 default_keys
157 When set, the default parameter (or set of parameters) are used as
158 default keys hashes and created automatically when the "keys" or
159 "exists" functions are used on an empty hash.
160
161 You can use "default_keys => 'foo'", or "default_keys => ['foo',
162 'bar']".
163
164 default_with_init
165 To perform special set-up on children nodes you can also use
166
167 default_with_init => {
168 foo => 'X=Av Y=Bv',
169 bar => 'Y=Av Z=Cv'
170 }
171
172 When the hash contains leaves, you can also use:
173
174 default_with_init => {
175 def_1 => 'def_1 stuff',
176 def_2 => 'def_2 stuff'
177 }
178
179 migrate_keys_from
180 Specifies that the keys of the hash are copied from another hash in
181 the configuration tree only when the hash is read for the first
182 time after initial load (i.e. once the configuration files are
183 completely read).
184
185 migrate_keys_from => '- another_hash'
186
187 migrate_values_from
188 Specifies that the values of the hash (or list) are copied from
189 another hash (or list) in the configuration tree only when the hash
190 (or list) is read for the first time after initial load (i.e. once
191 the configuration files are completely read).
192
193 migrate_values_from => '- another_hash_or_list'
194
195 follow_keys_from
196 Specifies that the keys of the hash follow the keys of another hash
197 in the configuration tree. In other words, the created hash always
198 has the same keys as the other hash.
199
200 follow_keys_from => '- another_hash'
201
202 allow_keys
203 Specifies authorized keys:
204
205 allow_keys => ['foo','bar','baz']
206
207 allow_keys_from
208 A bit like the "follow_keys_from" parameters. Except that the hash
209 pointed to by "allow_keys_from" specified the authorized keys for
210 this hash.
211
212 allow_keys_from => '- another_hash'
213
214 allow_keys_matching
215 Keys must match the specified regular expression. For instance:
216
217 allow_keys_matching => '^foo\d\d$'
218
219 auto_create_keys
220 When set, the default parameter (or set of parameters) are used as
221 keys hashes and created automatically. (valid only for hash
222 elements)
223
224 Called with "auto_create_keys => ['foo']", or "auto_create_keys =>
225 ['foo', 'bar']".
226
227 warn_if_key_match
228 Issue a warning if the key matches the specified regular expression
229
230 warn_unless_key_match
231 Issue a warning unless the key matches the specified regular
232 expression
233
234 auto_create_ids
235 Specifies the number of elements to create automatically. E.g.
236 "auto_create_ids => 4" initializes the list with 4 undef elements.
237 (valid only for list elements)
238
239 convert => [uc | lc ]
240 The hash key are converted to uppercase (uc) or lowercase (lc).
241
242 warp
243 See "Warp: dynamic value configuration" below.
244
246 The Warp functionality enables an HashId or ListId object to change its
247 default settings (e.g. "min_index", "max_index" or "max_nb" parameters)
248 dynamically according to the value of another "Value" object. (See
249 Config::Model::Warper for explanation on warp mechanism)
250
251 For instance, with this model:
252
253 $model ->create_config_class
254 (
255 name => 'Root',
256 'element'
257 => [
258 macro => { type => 'leaf',
259 value_type => 'enum',
260 name => 'macro',
261 choice => [qw/A B C/],
262 },
263 warped_hash => { type => 'hash',
264 index_type => 'integer',
265 max_nb => 3,
266 warp => {
267 follow => '- macro',
268 rules => { A => { max_nb => 1 },
269 B => { max_nb => 2 }
270 }
271 },
272 cargo => { type => 'node',
273 config_class_name => 'Dummy'
274 }
275 },
276 ]
277 );
278
279 Setting "macro" to "A" means that "warped_hash" can only accept one
280 instance of "Dummy".
281
282 Setting "macro" to "B" means that "warped_hash" accepts two instances
283 of "Dummy".
284
285 Like other warped class, a HashId or ListId can have multiple warp
286 masters (See "Warp follow argument" in Config::Model::Warper:
287
288 warp => { follow => { m1 => '- macro1',
289 m2 => '- macro2'
290 },
291 rules => [ '$m1 eq "A" and $m2 eq "A2"' => { max_nb => 1},
292 '$m1 eq "A" and $m2 eq "B2"' => { max_nb => 2}
293 ],
294 }
295
296 Warp and auto_create_ids or auto_create_keys
297 When a warp is applied with "auto_create_keys" or "auto_create_ids"
298 parameter, the auto_created items are created if they are not already
299 present. But this warp never removes items that were previously auto
300 created.
301
302 For instance, when a tied hash is created with "auto_create =>
303 [a,b,c]", the hash contains "(a,b,c)".
304
305 Then, once a warp with "auto_create_keys => [c,d,e]" is applied, the
306 hash then contains "(a,b,c,d,e)". The items created by the first
307 auto_create_keys are not removed.
308
309 Warp and max_nb
310 When a warp is applied, the items that do not fit the constraint (e.g.
311 min_index, max_index) are removed.
312
313 For the max_nb constraint, an exception is raised if a warp leads to a
314 number of items greater than the max_nb constraint.
315
317 By default, this class provides an optional content check that checks
318 for duplicated values (when "duplicates" parameter is set).
319
320 Derived classes can register more global checker with the following
321 method.
322
323 add_check_content
324 This method expects a sub ref with signature "( $self, $error, $warn,
325 $apply_fix )". Where $error and $warn are array ref. You can push
326 error or warning messages there. $apply_fix is a boolean. When set to
327 1, the passed method can fix the warning or the error. Please make sure
328 to weaken $self to avoid memory cycles.
329
330 Example:
331
332 package MyId;
333 use Mouse;
334 extends qw/Config::Model::HashId/;
335 use Scalar::Util qw/weaken/;
336
337 sub setup {
338 my $self = shift;
339 weaken($self);
340 $self-> add_check_content( sub { $self->check_usused_licenses(@_);} )
341 }
342
344 The following methods returns the current value stored in the Id object
345 (as declared in the model unless they were warped):
346
347 min_index
348 max_index
349 max_nb
350 index_type
351 default_keys
352 default_with_init
353 follow_keys_from
354 auto_create_ids
355 auto_create_keys
356 ordered
357 morph
358 config_model
359
360 get_cargo_type
361 Returns the object type contained by the hash or list (i.e. returns
362 "cargo -> type").
363
364 get_cargo_info
365 Parameters: "( < what > )"
366
367 Returns more info on the cargo contained by the hash or list. "what"
368 may be "value_type" or any other cargo info stored in the model.
369 Returns undef if the requested info is not provided in the model.
370
371 get_default_keys
372 Returns a list (or a list ref) of the current default keys. These keys
373 can be set by the "default_keys" or "default_with_init" parameters or
374 by the other hash pointed by "follow_keys_from" parameter.
375
376 name
377 Returns the object name. The name finishes with ' id'.
378
379 config_class_name
380 Returns the config_class_name of collected elements. Valid only for
381 collection of nodes.
382
383 This method returns undef if "cargo" "type" is not "node".
384
385 has_fixes
386 Returns the number of fixes that can be applied to the current value.
387
389 fetch_with_id
390 Parameters: "( index => $idx , [ check => 'no' ])"
391
392 Fetch the collected element held by the hash or list. Index check is
393 'yes' by default. Can be called with one parameter which is used as
394 index.
395
396 get
397 Get a value from a directory like path. Parameters are:
398
399 path
400 Poor man's version of XPath style path. This string is in the form:
401
402 /foo/bar/4
403
404 Each word between the '/' is either an element name or a hash key
405 or a list index.
406
407 mode
408 Either "default", "custom", "user",... See "mode" parameter in
409 <Config::Model::Value/"fetch( ... )">
410
411 check
412 Either "skip", "no"
413
414 get_obj
415 If the path leads to a leaf, this parameter tell whether to return
416 the stored value or the value object.
417
418 autoadd
419 Whether to create missing keys
420
421 dir_char_mockup
422 When the hash key used contains '/', (for instance a directory
423 value), the key cannot be used as is with this method. Because '/'
424 is already used to separate configuration items (this is also
425 important with Config::Model::FuseUI). This parameter specifies how
426 the forbidden '/' char is shown in the path. Default is "<slash>"
427
428 set
429 Parameters: "( path, value )"
430
431 Set a value with a directory like path.
432
433 copy
434 Parameters: "( from_index, to_index )"
435
436 Deep copy an element within the hash or list. If the element contained
437 by the hash or list is a node, all configuration information is copied
438 from one node to another.
439
440 fetch_all
441 Returns an array containing all elements held by the hash or list.
442
443 fetch_all_values
444 Parameters: "( mode => ..., check => ...)"
445
446 Returns an array containing all defined values held by the hash or
447 list. (undefined values are simply discarded). This method is only
448 valid for hash or list containing leaves.
449
450 With "mode" parameter, this method returns either:
451
452 custom
453 The value entered by the user
454
455 preset
456 The value entered in preset mode
457
458 standard
459 The value entered in preset mode or checked by default.
460
461 default
462 The default value (defined by the configuration model)
463
464 fetch
465 Similar to "fetch_all_values", with the same parameters, Returns the
466 result as a string with comma separated list values.
467
468 fetch_all_indexes
469 Returns an array containing all indexes of the hash or list. Hash keys
470 are sorted alphabetically, except for ordered hashed.
471
472 children
473 Like fetch_all_indexes. This method is polymorphic for all non-leaf
474 objects of the configuration tree.
475
476 defined
477 Parameters: "( index )"
478
479 Returns true if the value held at "index" is defined.
480
481 exists
482 Parameters: "( index )"
483
484 Returns true if the value held at "index" exists (i.e the key exists
485 but the value may be undefined). This method may not make sense for
486 list element.
487
488 has_data
489 Return true if the array or hash is not empty.
490
491 delete
492 Parameters: "( index )"
493
494 Delete the "index"ed value
495
496 clear
497 Delete all values (also delete underlying value or node objects).
498
499 clear_values
500 Delete all values (without deleting underlying value objects).
501
502 warning_msg
503 Parameters: "( [index] )"
504
505 Returns warnings concerning indexes of this hash. Without parameter,
506 returns a string containing all warnings or undef. With an index,
507 return the warnings concerning this index or undef.
508
509 has_warning
510 Returns the current number of warning.
511
512 error_msg
513 Returns the error messages of this object (if any)
514
516 Dominique Dumont, ddumont [AT] cpan [DOT] org
517
519 Config::Model, Config::Model::Instance, Config::Model::Node,
520 Config::Model::WarpedNode, Config::Model::HashId,
521 Config::Model::ListId, Config::Model::CheckList, Config::Model::Value
522
524 Dominique Dumont
525
527 This software is Copyright (c) 2005-2018 by Dominique Dumont.
528
529 This is free software, licensed under:
530
531 The GNU Lesser General Public License, Version 2.1, February 1999
532
533
534
535perl v5.28.1 2018-12-07 Config::Model::AnyId(3)