1Config::Model::AnyId(3)User Contributed Perl DocumentatioCnonfig::Model::AnyId(3)
2
3
4

NAME

6       Config::Model::AnyId - Base class for hash or list element
7

VERSION

9       version 2.152
10

SYNOPSIS

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

DESCRIPTION

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

CONSTRUCTOR

91       AnyId object should not be created directly.
92

Hash or list model declaration

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".
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

Warp: dynamic value configuration

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       "Dummy" class item .
281
282       Setting "macro" to "B" means that "warped_hash" accepts two "Dummy"
283       class items.
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

Content check

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

Introspection methods

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

Information management

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_value
444       Parameters: "( idx => ..., mode => ..., check => ...)"
445
446       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
449       See fetch_all_values for "mode" argument documentation and "fetch" in
450       Config::Model::Value for "check" argument documentation.
451
452   fetch_summary
453       Arguments: "( idx => ..., mode => ..., check => ...)"
454
455       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
458   fetch_all_values
459       Parameters: "( mode => ..., check => ...)"
460
461       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
465       With "mode" parameter, this method returns either:
466
467       custom
468           The value entered by the user
469
470       preset
471           The value entered in preset mode
472
473       standard
474           The value entered in preset mode or checked by default.
475
476       default
477           The default value (defined by the configuration model)
478
479       See "fetch" in Config::Model::Value for "check" argument documentation.
480
481   fetch
482       Similar to "fetch_all_values", with the same parameters, Returns the
483       result as a string with comma separated list values.
484
485   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
489   children
490       Like fetch_all_indexes. This method is polymorphic for all non-leaf
491       objects of the configuration tree.
492
493   defined
494       Parameters: "( index )"
495
496       Returns true if the value held at "index" is defined.
497
498   exists
499       Parameters: "( index )"
500
501       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
505   has_data
506       Return true if the array or hash is not empty.
507
508   delete
509       Parameters: "( index )"
510
511       Delete the "index"ed value
512
513   clear
514       Delete all values (also delete underlying value or node objects).
515
516   clear_values
517       Delete all values (without deleting underlying value objects).
518
519   warning_msg
520       Parameters: "( [index] )"
521
522       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
526   has_warning
527       Returns the current number of warning.
528
529   error_msg
530       Returns the error messages of this object (if any)
531

AUTHOR

533       Dominique Dumont, ddumont [AT] cpan [DOT] org
534

SEE ALSO

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

AUTHOR

541       Dominique Dumont
542
544       This software is Copyright (c) 2005-2022 by Dominique Dumont.
545
546       This is free software, licensed under:
547
548         The GNU Lesser General Public License, Version 2.1, February 1999
549
550
551
552perl v5.36.0                      2023-01-20           Config::Model::AnyId(3)
Impressum