1Config::Model::AnyId(3pUms)er Contributed Perl DocumentatCioonnfig::Model::AnyId(3pm)
2
6 Config::Model::AnyId - Base class for hash or list element
7
9 version 2.153
10
12 use Config::Model;
13 # 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 $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 # hash boundaries
42 min_index => 1, max_index => 123, max_nb => 2,
43 # 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 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 my $inst = $model->instance( root_class_name => 'MyClass' );
71 my $root = $inst->config_root;
73 # 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 # dump resulting tree
82 print $root->dump_tree;
83
85 This class provides hash or list elements for a Config::Model::Node.
86 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 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".
100 index_type
102 Either "integer" or "string". Mandatory for hash.
103 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 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 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 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 Note that writing hash entries without value may not be supported
128 by all backends. Use with care. Supported only for hash elements.
129 cargo
131 Hash ref specifying the cargo held by the hash of list. This has
132 must contain:
133 type Can be "node" or "leaf" (default).
135 config_class_name
137 Specifies the type of configuration object held in the
138 hash. Only valid when "cargo" "type" is "node".
139 <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 min_index
145 Specify the minimum value (optional, only for hash and for integer
146 index)
147 max_index
149 Specify the maximum value (optional, only for list or for hash with
150 integer index)
151 max_nb
153 Specify the maximum number of indexes. (hash only, optional, may
154 also be used with string index type)
155 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 You can use "default_keys => 'foo'", or "default_keys => ['foo',
162 'bar']".
163 default_with_init
165 To perform special set-up on children nodes you can also use
166 default_with_init => {
168 foo => 'X=Av Y=Bv',
169 bar => 'Y=Av Z=Cv'
170 }
171 When the hash contains leaves, you can also use:
173 default_with_init => {
175 def_1 => 'def_1 stuff',
176 def_2 => 'def_2 stuff'
177 }
178 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 migrate_keys_from => '- another_hash'
186 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 migrate_values_from => '- another_hash_or_list'
194 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 follow_keys_from => '- another_hash'
201 allow_keys
203 Specifies authorized keys:
204 allow_keys => ['foo','bar','baz']
206 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 allow_keys_from => '- another_hash'
213 allow_keys_matching
215 Keys must match the specified regular expression. For instance:
216 allow_keys_matching => '^foo\d\d$'
218 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 Called with "auto_create_keys => ['foo']", or "auto_create_keys =>
225 ['foo', 'bar']".
226 warn_if_key_match
228 Issue a warning if the key matches the specified regular expression
229 warn_unless_key_match
231 Issue a warning unless the key matches the specified regular
232 expression
233 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 convert => [uc | lc ]
240 The hash key are converted to uppercase (uc) or lowercase (lc).
241 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 For instance, with this model:
252 $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 Setting "macro" to "A" means that "warped_hash" can only accept one
280 "Dummy" class item .
281 Setting "macro" to "B" means that "warped_hash" accepts two "Dummy"
283 class items.
284 Like other warped class, a HashId or ListId can have multiple warp
286 masters (See "Warp follow argument" in Config::Model::Warper:
287 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 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 For instance, when a tied hash is created with "auto_create =>
303 [a,b,c]", the hash contains "(a,b,c)".
304 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 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 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 Derived classes can register more global checker with the following
321 method.
322 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 Example:
331 package MyId;
333 use Mouse;
334 extends qw/Config::Model::HashId/;
335 use Scalar::Util qw/weaken/;
336 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 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 get_cargo_type
361 Returns the object type contained by the hash or list (i.e. returns
362 "cargo -> type").
363 get_cargo_info
365 Parameters: "( < what > )"
366 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 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 name
377 Returns the object name. The name finishes with ' id'.
378 config_class_name
380 Returns the config_class_name of collected elements. Valid only for
381 collection of nodes.
382 This method returns undef if "cargo" "type" is not "node".
384 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 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 get
397 Get a value from a directory like path. Parameters are:
398 path
400 Poor man's version of XPath style path. This string is in the form:
401 /foo/bar/4
403 Each word between the '/' is either an element name or a hash key
405 or a list index.
406 mode
408 Either "default", "custom", "user",... See "mode" parameter in
409 <Config::Model::Value/"fetch( ... )">
410 check
412 Either "skip", "no"
413 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 autoadd
419 Whether to create missing keys
420 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 set
429 Parameters: "( path, value )"
430 Set a value with a directory like path.
432 copy
434 Parameters: "( from_index, to_index )"
435 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 fetch_all
441 Returns an array containing all elements held by the hash or list.
442 fetch_value
444 Parameters: "( idx => ..., mode => ..., check => ...)"
445 Returns the value held by the "idx" element of the hash or list. This
447 method is only valid for hash or list containing leaves.
448 See fetch_all_values for "mode" argument documentation and "fetch" in
450 Config::Model::Value for "check" argument documentation.
451 fetch_summary
453 Arguments: "( idx => ..., mode => ..., check => ...)"
454 Like "fetch_value", but returns a truncated value when the value is a
456 string or uniline that is too long to be displayed.
457 fetch_all_values
459 Parameters: "( mode => ..., check => ...)"
460 Returns an array containing all defined values held by the hash or
462 list. (undefined values are simply discarded). This method is only
463 valid for hash or list containing leaves.
464 With "mode" parameter, this method returns either:
466 custom
468 The value entered by the user
469 preset
471 The value entered in preset mode
472 standard
474 The value entered in preset mode or checked by default.
475 default
477 The default value (defined by the configuration model)
478 See "fetch" in Config::Model::Value for "check" argument documentation.
480 fetch
482 Similar to "fetch_all_values", with the same parameters, Returns the
483 result as a string with comma separated list values.
484 fetch_all_indexes
486 Returns an array containing all indexes of the hash or list. Hash keys
487 are sorted alphabetically, except for ordered hashed.
488 children
490 Like fetch_all_indexes. This method is polymorphic for all non-leaf
491 objects of the configuration tree.
492 defined
494 Parameters: "( index )"
495 Returns true if the value held at "index" is defined.
497 exists
499 Parameters: "( index )"
500 Returns true if the value held at "index" exists (i.e the key exists
502 but the value may be undefined). This method may not make sense for
503 list element.
504 has_data
506 Return true if the array or hash is not empty.
507 delete
509 Parameters: "( index )"
510 Delete the "index"ed value
512 clear
514 Delete all values (also delete underlying value or node objects).
515 clear_values
517 Delete all values (without deleting underlying value objects).
518 warning_msg
520 Parameters: "( [index] )"
521 Returns warnings concerning indexes of this hash. Without parameter,
523 returns a string containing all warnings or undef. With an index,
524 return the warnings concerning this index or undef.
525 has_warning
527 Returns the current number of warning.
528 error_msg
530 Returns the error messages of this object (if any)
531
533 Dominique Dumont, ddumont [AT] cpan [DOT] org
534
536 Config::Model, Config::Model::Instance, Config::Model::Node,
537 Config::Model::WarpedNode, Config::Model::HashId,
538 Config::Model::ListId, Config::Model::CheckList, Config::Model::Value
539
541 Dominique Dumont
542
544 This software is Copyright (c) 2005-2022 by Dominique Dumont.
545 This is free software, licensed under:
547 The GNU Lesser General Public License, Version 2.1, February 1999
549perl v5.38.0 2023-07-25 Config::Model::AnyId(3pm)