1Config::Model::Value(3)User Contributed Perl DocumentatioCnonfig::Model::Value(3)
2
6 Config::Model::Value - Strongly typed configuration value
7
9 version 1.205
10
12 my $model = Config::Model->new() ;
13 $model ->create_config_class
14 (
15 name => "SomeClass",
16 element => [
17 country => {
18 type => 'leaf',
19 value_type => 'enum',
20 choice => [qw/France US/]
21 },
22 president => {
23 type => 'leaf',
24 value_type => 'string',
25 warp => {
26 follow => { c => '- country'},
27 rules => {
28 '$c eq "France"' => { default => 'Chirac' },
29 '$c eq "US"' => { default => 'Bush' }
30 }
31 },
32 }
33 ]
34 );
35
37 This class provides a way to specify configuration value with the
38 following properties:
39 · Strongly typed scalar: the value can either be an enumerated type,
41 a boolean, a number, an integer or a string
42 · default parameter: a value can have a default value specified
44 during the construction. This default value will be written in the
45 target configuration file. ("default" parameter)
46 · upstream default parameter: specifies a default value that will be
48 used by the application when no information is provided in the
49 configuration file. This upstream_default value will not written in
50 the configuration files. Only the "fetch_standard" method will
51 return the builtin value. This parameter was previously refered as
52 "built_in" value. This may be used for audit purpose.
53 ("upstream_default" parameter)
54 · mandatory value: reading a mandatory value will raise an exception
56 if the value is not specified and has no default value.
57 · dynamic change of property: A slave value can be registered to
59 another master value so that the properties of the slave value can
60 change according to the value of the master value. For instance,
61 paper size value can be 'letter' for country 'US' and 'A4' for
62 country 'France'.
63 · A reference to the Id of a hash of list element. In other word, the
65 value is an enumerated type where the possible values (choice) is
66 defined by the existing keys of a has element somewhere in the
67 tree. See "Value Reference".
68
70 There are several kind of default values. They depend on where these
71 values are defined (or found).
72 From the lowest default level to the "highest":
74 · "upstream_default": The value is knows in the application, but is
76 not written in the configuration file.
77 · "default": The value is known by the model, but not by the
79 application. This value must be written in the configuration file.
80 · "computed": The value is computed from other configuration
82 elements. This value must be written in the configuration file.
83 · "preset": The value is not known by the model or by the
85 application. But it can be found by an automatic program and stored
86 while the configuration Config::Model::Instance is in
87 Config::Model::Instance/"preset_start ()"
88 Then there is the value entered by the user. This will override all
90 kind of "default" value.
91 The fetch_standard function will return the "highest" level of default
93 value, but will not return a custom value, i.e. a value entered by the
94 user.
95
97 Value object should not be created directly.
98
100 A leaf element must be declared with the following parameters:
101 value_type
103 Either "boolean", "enum", "integer", "number", "uniline", "string".
104 Mandatory. See "Value types".
105 default
107 Specify the default value (optional)
108 upstream_default
110 Specify a built in default value (optional)
111 compute
113 Will compute a value according to a formula and other values. By
114 default a computed value cannot be set. See
115 Config::Model::ValueComputer for computed value declaration.
116 migrate_from
118 This is a special parameter to cater for smooth configuration
119 upgrade. This parameter can be used to copy the value of a
120 deprecated parameter to its replacement. See "upgrade"" in " for
121 details.
122 convert => [uc | lc ]
124 When stored, the value will be converted to uppercase (uc) or
125 lowercase (lc).
126 min Specify the minimum value (optional, only for integer, number)
128 max Specify the maximum value (optional, only for integer, number)
130 mandatory
132 Set to 1 if the configuration value must be set by the
133 configuration user (default: 0)
134 choice
136 Array ref of the possible value of an enum. Example :
137 choice => [ qw/foo bar/]
139 match
141 Perl regular expression. The value will be match with the regex to
142 assert its validity. Example "match => '^foo'" means that the
143 parameter value must begin with "foo". Valid only for "string" or
144 "uniline" values.
145 replace
147 Hash ref. Used for enum to substitute one value with another. This
148 parameter must be used to enable user to upgrade a configuration
149 with obsolete values. For instance, if the value "foo" is obsolete
150 and replaced by "foo_better", you will need to declare:
151 replace => { foo => 'foo_better' }
153 refer_to
155 Specify a path to an id element used as a reference. See Value
156 Reference for details.
157 computed_refer_to
159 Specify a pathto an id element used as a computed reference. See
160 "Value Reference" for details.
161 warp
163 See section below: "Warp: dynamic value configuration".
164 help
166 You may provide detailed description on possible values with a hash
167 ref. Example:
168 help => { oui => "French for 'yes'", non => "French for 'no'"}
170 Value types
172 This modules can check several value types:
173 "boolean"
175 Accepts values 1 or 0, "yes" or "no", "true" or "false". The value
176 read back is always 1 or 0.
177 "enum"
179 Enum choices must be specified by the "choice" parameter.
180 "integer"
182 Enable positive or negative integer
183 "number"
185 The value can be a decimal number
186 "uniline"
188 A one line string. I.e without "\n" in it.
189 "string"
191 Actually, no check is performed with this type.
192 "reference"
194 Like an "enum" where the possible values (aka choice) is defined by
195 another location if the configuration tree. See "Value Reference".
196
198 The Warp functionality enable a "Value" object to change its properties
199 (i.e. default value or its type) dynamically according to the value of
200 another "Value" object locate elsewhere in the configuration tree. (See
201 Config::Model::WarpedThing for an explanation on warp mechanism).
202 For instance if you declare 2 "Value" element this way:
204 $model ->create_config_class (
206 name => "TV_config_class",
207 element => [
208 country => {
209 type => 'leaf',
210 value_type => 'enum',
211 choice => [qw/US Europe Japan/]
212 },
213 tv_standard => {
214 type => 'leaf',
215 value_type => 'enum',
216 choice => [qw/PAL NTSC SECAM/]
217 warp => {
218 follow => { c => '- country' }, # this points to the warp master
219 rules => {
220 '$c eq "US"' => { default => 'NTSC' },
221 '$c eq "France"' => { default => 'SECAM' },
222 '$c eq "Japan"' => { default => 'NTSC' },
223 '$c eq "Europe"' => { default => 'PAL' },
224 }
225 }
226 },
227 ]
228 );
229 Setting "country" element to "US" will mean that "tv_standard" has a
231 default value set to "NTSC" by the warp mechanism.
232 Likewise, the warp mechanism enables you to dynamically change the
234 possible values of an enum element:
235 state => {
237 type => 'leaf',
238 value_type => 'enum', # example is admittedly silly
239 warp =>{
240 follow => { c => '- country' },
241 rules => {
242 '$c eq "US"' => { choice => ['Kansas', 'Texas' ]},
243 '$c eq "Europe"' => { choice => ['France', 'Spain' ]},
244 '$c eq "Japan"' => { choice => ['Honshu', 'Hokkaido' ]}
245 }
246 }
247 }
248 Cascaded warping
250 Warping value can be cascaded: "A" can be warped by "B" which can be
251 warped by "C". But this feature should be avoided since it can lead to
252 a model very hard to debug. Bear in mind that:
253 · Warp loop are not detected and will end up in "deep recursion
255 subroutine" failures.
256 · If you declare "diamond" shaped warp dependencies, the results will
258 depend on the order of the warp algorithm and can be unpredictable.
259 · The keys declared in the warp rules ("US", "Europe" and "Japan" in
261 the example above) cannot be checked at start time against the warp
262 master "Value". So a wrong warp rule key will be silently ignored
263 during start up and will fail at run time.
264
266 To set up an enumerated value where the possible choice depends on the
267 key of a Config::Model::AnyId object, you must:
268 · Set "value_type" to "reference".
270 · Specify the "refer_to" or "computed_refer_to" parameter. See
272 refer_to parameter.
273 In this case, a "IdElementReference" object is created to handle the
275 relation between this value object and the refered Id. See
276 Config::Model::IdElementReference for details.
277
279 The following methods returns the current value of the parameter of the
280 value object (as declared in the model unless they were warped):
281 min
283 max
284 mandatory
285 choice
286 convert
287 value_type
288 default
289 upstream_default
290 index_value
291 element_name
292 name()
294 Returns the object name.
295 get_type
297 Returns "leaf".
298 can_store()
300 Returns true if the value object can be assigned to. Return 0 for a
301 read-only value (i.e. a computed value with no override allowed).
302 get_choice()
304 Query legal values (only for enum types). Return an array (possibly
305 empty).
306 get_help ( [ on_value ] )
308 Returns the help strings passed to the constructor.
309 With "on_value" parameter, returns the help string dedicated to the
311 passed value or undef.
312 Without parameter returns a hash ref that contains all the help
314 strings.
315 check_value ( value , [ 0 | 1 ] )
317 Check the consistency of the value. Does not check for undefined
318 mandatory values.
319 When the 2nd parameter is non null, check will not try to get extra
321 information from the tree. This is required in some cases to avoid
322 loops in check, get_info, get_warp_info, re-check ...
323 In scalar context, return 0 or 1.
325 In array context, return an empty array when no error was found. In
327 case of errors, returns an array of error strings that should be shown
328 to the user.
329 check( value , [ 0 | 1 ] )
331 Like "check_value". Also ensure that mandatory value are defined
332
334 store( value )
335 Store value in leaf element.
336 load_data( scalar_value )
338 Load scalar data. Data is simply forwarded to store.
339 fetch_custom
341 Returns the stored value if this value is different from a standard
342 setting or built in seting. In other words, returns undef if the stored
343 value is identical to the default value or the computed value or the
344 built in value.
345 fetch_standard
347 Returns the standard value as defined by the configuration model. The
348 standard value can be either a preset value, a computed value, a
349 default value or a built-in default value.
350 fetch_no_check
352 Fetch value from leaf element without checking the value.
353 fetch( [ custom | preset | standard | default ] )
355 Check and fetch value from leaf element.
356 With a parameter, this method will return either:
358 custom
360 The value entered by the user (if different from built in, preset,
361 computed or default value)
362 preset
364 The value entered in preset mode
365 standard
367 The preset or computed or default or built in value.
368 default
370 The default value (defined by the configuration model)
371 upstream_default
373 The upstream_default value. (defined by the configuration model)
374 non_upstream_default
376 The custom or preset or computed or default value. Will return
377 undef if either of this value is identical to the upstream_default
378 value. This feature is useful to reduce data to write in
379 configuration file.
380 allow_undef
382 This mode will accept to return undef for mandatory values.
383 Normally, trying to fetch an undefined manadatory value leads to an
384 exception.
385 user_value
387 Returns the value entered by the user. Does not use the default or
388 computed value. Returns undef unless a value was actually stored.
389 fetch_preset
391 Returns the value entered in preset mode. Does not use the default or
392 computed value. Returns undef unless a value was actually stored in
393 preset mode.
394 get( path , [ custom | preset | standard | default ])
396 Get a value from a directory like path.
397 set( path , value )
399 Set a value from a directory like path.
400
402 Upgrade is a special case when the configuration of an application has
403 changed. Some parameters can be removed and replaced by another one. To
404 avoid trouble on the application user side, Config::Model offers a
405 possibility to handle the migration of configuration data through a
406 special declaration in the configuration model.
407 This declaration must:
409 · Declare the deprecated parameter with a "status" set to
411 "deprecated"
412 · Declare the new parameter with the intructions to load the semantic
414 content from the deprecated parameter. These instructions are
415 declared in the "migrate_from" parameters (which is similar to the
416 "compute" parameter)
417 Here an example where a url parameter is changed to a set of 2
419 parameters (host and path):
420 'old_url' => { type => 'leaf',
422 value_type => 'uniline',
423 status => 'deprecated',
424 },
425 'host'
426 => { type => 'leaf',
427 value_type => 'uniline',
428 # the formula must end with '$1' so the result of the capture is used
429 # as the host value
430 migrate_from => { formula => '$old =~ m!http://([\w\.]+)!; $1 ;' ,
431 variables => { old => '- old_url' } ,
432 use_eval => 1 ,
433 },
434 },
435 'path' => { type => 'leaf',
436 value_type => 'uniline',
437 migrate_from => { formula => '$old =~ m!http://[\w\.]+(/.*)!; $1 ;',
438 variables => { old => '- old_url' } ,
439 use_eval => 1 ,
440 },
441 },
442
444 When an error is encountered, this module may throw the following
445 exceptions:
446 Config::Model::Exception::Model
448 Config::Model::Exception::Formula
449 Config::Model::Exception::WrongValue
450 Config::Model::Exception::WarpError
451 See Config::Model::Exception for more details.
453
455 Dominique Dumont, (ddumont at cpan dot org)
456
458 Config::Model, Config::Model::Node, Config::Model::AnyId,
459 Config::Model::WarpedThing, Exception::Class
460 Config::Model::ValueComputer,
461perl v5.12.1 2010-08-18 Config::Model::Value(3)