Config::Model::AnyId(3pm)

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

SYNOPSIS

12        $model ->create_config_class
13         (
14          ...
15          element
16          => [
17              bounded_hash
18              => { type => 'hash',                 # hash id
19                   index_type  => 'integer',
20
21                   # hash boundaries
22                   min_index => 1, max_index => 123, max_nb => 2 ,
23
24                   # specify cargo held by hash
25                   cargo => { type => 'leaf',
26                              value_type => 'string'
27                            },
28                 },
29             bounded_list
30              => { type => 'list',                 # list id
31
32                   max_index => 123,
33                   cargo => { type => 'leaf',
34                              value_type => 'string'
35                            },
36                 },
37             hash_of_nodes
38             => { type => 'hash',                 # hash id
39                  index_type  => 'integer',
40                  cargo => { type => 'node',
41                             config_class_name => 'Foo'
42                           },
43                },
44             ]
45         ) ;
46

DESCRIPTION

48       This class provides hash or list elements for a Config::Model::Node.
49
50       The hash index can either be en enumerated type, a boolean, an integer
51       or a string.
52

CONSTRUCTOR

54       AnyId object should not be created directly.
55

Hash or list model declaration

57       A hash or list element must be declared with the following parameters:
58
59       type
60           Mandatory element type. Must be "hash" or "list" to have a
61           collection element.  The actual element type must be specified by
62           "cargo =" type> (See "CAVEATS").
63
64       index_type
65           Either "integer" or "string". Mandatory for hash.
66
67       ordered
68           Whether to keep the order of the hash keys (default no). (a bit
69           like Tie::IxHash).  The hash keys are ordered along their creation.
70           The order can be modified with swap, move_up or move_down.
71
72       cargo
73           Hash ref specifying the cargo held by the hash of list. This has
74           must contain:
75
76           type    Can be "node" or "leaf" (default).
77
78           config_class_name
79                   Specifies the type of configuration object held in the
80                   hash. Only valid when "cargo" "type" is "node".
81
82           <other> Constructor arguments passed to the cargo object. See
83                   Config::Model::Node when "cargo->type" is "node". See
84                   Config::Model::Value when "cargo->type" is "leaf".
85
86       min_index
87           Specify the minimum value (optional, only for hash and for integer
88           index)
89
90       max_index
91           Specify the maximum value (optional, only for integer index)
92
93       max_nb
94           Specify the maximum number of indexes. (hash only, optional, may
95           also be used with string index type)
96
97       default_keys
98           When set, the default parameter (or set of parameters) are used as
99           default keys hashes and created automatically when the keys or
100           exists functions are used on an empty hash.
101
102           You can use "default_keys => 'foo'", or "default_keys => ['foo',
103           'bar']".
104
105       default_with_init
106           To perform special set-up on children nodes you can also use
107
108              default_with_init =>  { 'foo' => 'X=Av Y=Bv'  ,
109                                      'bar' => 'Y=Av Z=Cv' }
110
111       follow_keys_from
112           Specifies that the keys of the hash follow the keys of another hash
113           in the configuration tree. In other words, the hash you're creating
114           will always have the same keys as the other hash.
115
116              follow_keys_from => '- another_hash'
117
118       allow_keys
119           Specifies authorized keys:
120
121             allow_keys => ['foo','bar','baz']
122
123       allow_keys_from
124           A bit like the "follow_keys_from" parameters. Except that the hash
125           pointed to by "allow_keys_from" specified the authorized keys for
126           this hash.
127
128             allow_keys_from => '- another_hash'
129
130       auto_create_keys
131           When set, the default parameter (or set of parameters) are used as
132           keys hashes and created automatically. (valid only for hash
133           elements)
134
135           Called with "auto_create => 'foo'", or "auto_create => ['foo',
136           'bar']".
137
138       auto_create_ids
139           Specifies the number of elements to create automatically. E.g.
140           "auto_create => 4" will initialize the list with 4 undef elements.
141           (valid only for list elements)
142
143       warp
144           See "Warp: dynamic value configuration" below.
145

About checking value

147       By default, value checking is done while setting or reading a value.
148
149       You can use push_no_value_check() or pop_no_value_check() from
150       Config::Model::Instance to modify this behavior.
151

Warp: dynamic value configuration

153       The Warp functionality enables an HashId or ListId object to change its
154       default settings (e.g. "min_index", "max_index" or "max_nb" parameters)
155       dynamically according to the value of another "Value" object. (See
156       Config::Model::WarpedThing for explanation on warp mechanism)
157
158       For instance, with this model:
159
160        $model ->create_config_class
161         (
162          name => 'Root',
163          'element'
164          => [
165              macro => { type => 'leaf',
166                         value_type => 'enum',
167                         name       => 'macro',
168                         choice     => [qw/A B C/],
169                       },
170              warped_hash => { type => 'hash',
171                               index_type => 'integer',
172                               max_nb     => 3,
173                               warp       => {
174                                              follow => '- macro',
175                                              rules => { A => { max_nb => 1 },
176                                                         B => { max_nb => 2 }
177                                                       }
178                                             },
179                               cargo => { type => 'node',
180                                          config_class_name => 'Dummy'
181                                        }
182                             },
183            ]
184         );
185
186       Setting "macro" to "A" will mean that "warped_hash" can only accept one
187       instance of "Dummy".
188
189       Setting "macro" to "B" will mean that "warped_hash" will accept two
190       instances of "Dummy".
191
192       Like other warped class, a HashId or ListId can have multiple warp
193       masters (See "Warp follow argument" in Config::Model::WarpedThing:
194
195         warp => { follow => { m1 => '- macro1',
196                               m2 => '- macro2'
197                             },
198                   rules  => [ '$m1 eq "A" and $m2 eq "A2"' => { max_nb => 1},
199                               '$m1 eq "A" and $m2 eq "B2"' => { max_nb => 2}
200                             ],
201                 }
202
203   Warp and auto_create_ids or auto_create_keys
204       When a warp is applied with "auto_create_keys" or "auto_create_ids"
205       parameter, the auto_created items are created if they are not already
206       present. But this warp will never remove items that were previously
207       auto created.
208
209       For instance, if a tied hash is created with "auto_create => [a,b,c]",
210       the hash contains "(a,b,c)".
211
212       Then if a warp is applied with "auto_create => [c,d,e]", the hash will
213       contain "(a,b,c,d,e)". The items created by the first auto_create are
214       not removed.
215
216   Warp and max_nb
217       When a warp is applied, the items that do not fit the constraint (e.g.
218       min_index, max_index) are removed.
219
220       For the max_nb constraint, an exception will be raised if a warp leads
221       to a nb of items greater than the max_nb constraint.
222

Introspection methods

224       The following methods returns the current value stored in the Id object
225       (as declared in the model unless they were warped):
226
227       min_index
228       max_index
229       max_nb
230       index_type
231       default_keys
232       default_with_init
233       follow_keys_from
234       auto_create_ids
235       auto_create_keys
236       ordered
237       morph
238       config_model
239
240   get_cargo_type()
241       Returns the object type contained by the hash or list (i.e. returns
242       "cargo -> type").
243
244   get_cargo_info( < what > )
245       Returns more info on the cargo contained by the hash or list. "what"
246       may be "value_type" or any other cargo info stored in the model. Will
247       return undef if the requested info was not provided in the model.
248
249   get_default_keys
250       Returns a list (or a list ref) of the current default keys. These keys
251       can be set by the "default_keys" or "default_with_init" parameters or
252       by the other hash pointed by "follow_keys_from" parameter.
253
254   name()
255       Returns the object name. The name finishes with ' id'.
256
257   config_class_name()
258       Returns the config_class_name of collected elements. Valid only for
259       collection of nodes.
260
261       This method will return undef if "cargo" "type" is not "node".
262

Informations management

264   fetch_with_id ( index )
265       Fetch the collected element held by the hash or list.
266
267   get( path,  [ custom | preset | standard | default ])
268       Get a value from a directory like path.
269
270   set( path, value )
271       Set a value with a directory like path.
272
273   move ( from_index, to_index )
274       Move an element within the hash or list.
275
276   copy ( from_index, to_index )
277       Deep copy an element within the hash or list. If the element contained
278       by the hash or list is a node, all configuration information is copied
279       from one node to another.
280
281   fetch_all()
282       Returns an array containing all elements held by the hash or list.
283
284   fetch_all_values( [ custom | preset | standard | default ] )
285       Returns an array containing all defined values held by the hash or
286       list. (undefined values are simply discarded)
287
288       With a parameter, this method will return either:
289
290       custom
291           The value entered by the user
292
293       preset
294           The value entered in preset mode
295
296       standard
297           The value entered in preset mode or checked by default.
298
299       default
300           The default value (defined by the configuration model)
301
302   get_all_indexes()
303       Returns an array containing all indexes of the hash or list. Hash keys
304       are sorted alphabetically, except for ordered hashed.
305
306   defined ( index )
307       Returns true if the value held at "index" is defined.
308
309   exists ( index )
310       Returns true if the value held at "index" exists (i.e the key exists
311       but the value may be undefined). This method may not make sense for
312       list element.
313
314   delete ( index )
315       Delete the "index"ed value
316
317   clear()
318       Delete all values (also delete underlying value or node objects).
319
320   clear_values()
321       Delete all values (without deleting underlying value objects).
322

AUTHOR

324       Dominique Dumont, ddumont [AT] cpan [DOT] org
325