1Config::Model::Value(3)User Contributed Perl DocumentatioCnonfig::Model::Value(3)
2
6 Config::Model::Value - Strongly typed configuration value
7
9 version 2.138
10
12 use Config::Model;
13 # define configuration tree object
15 my $model = Config::Model->new;
16 $model ->create_config_class (
17 name => "MyClass",
18 element => [
20 [qw/foo bar/] => {
22 type => 'leaf',
23 value_type => 'string',
24 description => 'foobar',
25 }
26 ,
27 country => {
28 type => 'leaf',
29 value_type => 'enum',
30 choice => [qw/France US/],
31 description => 'big countries',
32 }
33 ,
34 ],
35 ) ;
36 my $inst = $model->instance(root_class_name => 'MyClass' );
38 my $root = $inst->config_root ;
40 # put data
42 $root->load( steps => 'foo=FOO country=US' );
43 print $root->report ;
45 # foo = FOO
46 # DESCRIPTION: foobar
47 #
48 # country = US
49 # DESCRIPTION: big countries
50
52 This class provides a way to specify configuration value with the
53 following properties:
54 · Strongly typed scalar: the value can either be an enumerated type,
56 a boolean, a number, an integer or a string
57 · default parameter: a value can have a default value specified
59 during the construction. This default value is written in the
60 target configuration file. ("default" parameter)
61 · upstream default parameter: specifies a default value that is used
63 by the application when no information is provided in the
64 configuration file. This upstream_default value is not written in
65 the configuration files. Only the "fetch_standard" method returns
66 the builtin value. This parameter was previously referred as
67 "built_in" value. This may be used for audit purpose.
68 ("upstream_default" parameter)
69 · mandatory value: reading a mandatory value raises an exception if
71 the value is not specified and has no default value.
72 · dynamic change of property: A slave value can be registered to
74 another master value so that the properties of the slave value can
75 change according to the value of the master value. For instance,
76 paper size value can be 'letter' for country 'US' and 'A4' for
77 country 'France'.
78 · A reference to the Id of a hash of list element. In other word, the
80 value is an enumerated type where the possible values (choice) is
81 defined by the existing keys of a has element somewhere in the
82 tree. See "Value Reference".
83
85 There are several kind of default values. They depend on where these
86 values are defined (or found).
87 From the lowest default level to the "highest":
89 · "upstream_default": The value is known in the application, but is
91 not written in the configuration file.
92 · "layered": The value is known by the application through another
94 mean (e.g. an included configuration file), but is not written in
95 the configuration file.
96 · "default": The value is known by the model, but not by the
98 application. This value must be written in the configuration file.
99 · "computed": The value is computed from other configuration
101 elements. This value must be written in the configuration file.
102 · "preset": The value is not known by the model or by the
104 application. But it can be found by an automatic program and stored
105 while the configuration Config::Model::Instance is in preset mode
106 Then there is the value entered by the user. This overrides all kind of
108 "default" value.
109 The fetch_standard function returns the "highest" level of default
111 value, but does not return a custom value, i.e. a value entered by the
112 user.
113
115 Value object should not be created directly.
116
118 A leaf element must be declared with the following parameters:
119 value_type
121 Either "boolean", "enum", "integer", "number", "uniline", "string",
122 "file", "dir". Mandatory. See "Value types".
123 default
125 Specify the default value (optional)
126 upstream_default
128 Specify a built in default value (optional). I.e a value known by
129 the application which does not need to be written in the
130 configuration file.
131 write_as
133 Array ref. Reserved for boolean value. Specify how to write a
134 boolean value. Default is "[0,1]" which may not be the most
135 readable. "write_as" can be specified as "['false','true']" or
136 "['no','yes']".
137 compute
139 Computes a value according to a formula and other values. By
140 default a computed value cannot be set. See
141 Config::Model::ValueComputer for computed value declaration.
142 migrate_from
144 This is a special parameter to cater for smooth configuration
145 upgrade. This parameter can be used to copy the value of a
146 deprecated parameter to its replacement. See "Upgrade" for details.
147 convert => [uc | lc ]
149 When stored, the value is converted to uppercase (uc) or lowercase
150 (lc).
151 min Specify the minimum value (optional, only for integer, number)
153 max Specify the maximum value (optional, only for integer, number)
155 mandatory
157 Set to 1 if the configuration value must be set by the
158 configuration user (default: 0)
159 choice
161 Array ref of the possible value of an enum. Example :
162 choice => [ qw/foo bar/]
164 match
166 Perl regular expression. The value is matched with the regex to
167 assert its validity. Example "match => '^foo'" means that the
168 parameter value must begin with "foo". Valid only for "string" or
169 "uniline" values.
170 warn_if_match
172 Hash ref. Keys are made of Perl regular expression. The value can
173 specify a warning message (leave empty or undefined for a default
174 warning message) and instructions to fix the value. A warning is
175 issued when the value matches the passed regular expression. Valid
176 only for "string" or "uniline" values. The fix instructions is
177 evaluated when apply_fixes is called. $_ contains the value to fix.
178 $_ is stored as the new value once the instructions are done.
179 $self contains the value object. Use with care.
180 In the example below, any value matching 'foo' is converted in
182 uppercase:
183 warn_if_match => {
185 'foo' => {
186 fix => 'uc;',
187 msg => 'value $_ contains foo'
188 },
189 'BAR' => {
190 fix =>'lc;',
191 msg => 'value $_ contains BAR'
192 }
193 },
194 The tests are done in alphabetical order. In the example above,
196 "BAR" test is done before "foo" test.
197 $_ is substituted with the bad value when the message is generated.
199 $std_value is substituted with the standard value (i.e the preset,
200 computed or default value).
201 warn_unless_match
203 Hash ref like above. A warning is issued when the value does not
204 match the passed regular expression. Valid only for "string" or
205 "uniline" values.
206 warn
208 String. Issue a warning to user with the specified string any time
209 a value is set or read.
210 warn_if
212 A bit like "warn_if_match". The hash key is not a regexp but a
213 label to help users. The hash ref contains some Perl code that is
214 evaluated to perform the test. A warning is issued if the given
215 code returns true.
216 $_ contains the value to check. $self contains the
218 "Config::Model::Value" object (use with care).
219 The example below warns if value contains a number:
221 warn_if => {
223 warn_test => {
224 code => 'defined $_ && /\d/;',
225 msg => 'value $_ should not have numbers',
226 fix => 's/\d//g;'
227 }
228 },
229 Hash key is used in warning message when "msg" is not set:
231 warn_if => {
233 'should begin with foo' => {
234 code => 'defined && /^foo/'
235 }
236 }
237 Any operation or check on file must be done with "file" sub
239 (otherwise tests will break). This sub returns a Path::Tiny object
240 that can be used to perform checks. For instance:
241 warn_if => {
243 warn_test => {
244 code => 'not file($_)->exists',
245 msg => 'file $_ should exist'
246 }
247 warn_unless
249 Like "warn_if", but issue a warning when the given "code" returns
250 false.
251 The example below warns unless the value points to an existing
253 directory:
254 warn_unless => {
256 'missing dir' => {
257 code => '-d',
258 fix => "system(mkdir $_);" }
259 }
260 assert
262 Like "warn_if". Except that returned value triggers an error when
263 the given code returns false:
264 assert => {
266 test_nb => {
267 code => 'defined $_ && /\d/;',
268 msg => 'should not have numbers',
269 fix => 's/\d//g;'
270 }
271 },
272 hash key can also be used to generate error message when "msg"
274 parameter is not set.
275 grammar
277 Setup a Parse::RecDescent grammar to perform validation.
278 If the grammar does not start with a "check" rule (i.e does not
280 start with "check: "), the first line of the grammar is modified to
281 add "check" rule and this rules is set up so the entire value must
282 match the passed grammar.
283 I.e. the grammar:
285 token (oper token)(s?)
287 oper: 'and' | 'or'
288 token: 'Apache' | 'CC-BY' | 'Perl'
289 is changed to
291 check: token (oper token)(s?) /^\Z/ {$return = 1;}
293 oper: 'and' | 'or'
294 token: 'Apache' | 'CC-BY' | 'Perl'
295 The rule is called with Value object and a string reference. So, in
297 the actions you may need to define, you can call the value object
298 as $arg[0], store error message in "${$arg[1]}}" and store warnings
299 in "${$arg[2]}}".
300 replace
302 Hash ref. Used for enum to substitute one value with another. This
303 parameter must be used to enable user to upgrade a configuration
304 with obsolete values. For instance, if the value "foo" is obsolete
305 and replaced by "foo_better", you must declare:
306 replace => { foo => 'foo_better' }
308 The hash key can also be a regular expression for wider range
310 replacement. The regexp must match the whole value:
311 replace => ( 'foo.*' => 'better_foo' }
313 In this case, a value is replaced by "better_foo" when the
315 "/^foo.*$/" regexp matches.
316 replace_follow
318 Path specifying a hash of value element in the configuration tree.
319 The hash if used in a way similar to the "replace" parameter. In
320 this case, the replacement is not coded in the model but specified
321 by the configuration.
322 refer_to
324 Specify a path to an id element used as a reference. See Value
325 Reference for details.
326 computed_refer_to
328 Specify a path to an id element used as a computed reference. See
329 "Value Reference" for details.
330 warp
332 See section below: "Warp: dynamic value configuration".
333 help
335 You may provide detailed description on possible values with a hash
336 ref. Example:
337 help => { oui => "French for 'yes'", non => "French for 'no'"}
339 The key of help is used as a regular expression to find the help
341 text applicable to a value. These regexp are tried from the longest
342 to the shortest and are matched from the beginning of the string.
343 The key ""."" or "".*"" are fallback used last.
344 For instance:
346 help => {
348 'foobar' => 'help for values matching /^foobar/',
349 'foo' => 'help for values matching /^foo/ but not /^foobar/ (used above)',
350 '.' => 'help for all other values'
351 }
352 Value types
354 This modules can check several value types:
355 "boolean"
357 Accepts values 1 or 0, "yes" or "no", "true" or "false", and empty
358 string. The value read back is always 1 or 0.
359 "enum"
361 Enum choices must be specified by the "choice" parameter.
362 "integer"
364 Enable positive or negative integer
365 "number"
367 The value can be a decimal number
368 "uniline"
370 A one line string. I.e without "\n" in it.
371 "string"
373 Actually, no check is performed with this type.
374 "reference"
376 Like an "enum" where the possible values (aka choice) is defined by
377 another location if the configuration tree. See "Value Reference".
378 "file"
380 A file name or path. A warning is issued if the file does not
381 exists (or is a directory)
382 "dir"
384 A directory name or path. A warning is issued if the directory does
385 not exists (or is a plain file)
386
388 The Warp functionality enable a "Value" object to change its properties
389 (i.e. default value or its type) dynamically according to the value of
390 another "Value" object locate elsewhere in the configuration tree. (See
391 Config::Model::Warper for an explanation on warp mechanism).
392 For instance if you declare 2 "Value" element this way:
394 $model ->create_config_class (
396 name => "TV_config_class",
397 element => [
398 country => {
399 type => 'leaf',
400 value_type => 'enum',
401 choice => [qw/US Europe Japan/]
402 } ,
403 tv_standard => { # this example is getting old...
404 type => 'leaf',
405 value_type => 'enum',
406 choice => [ qw/PAL NTSC SECAM/ ]
407 warp => {
408 follow => {
409 # this points to the warp master
410 c => '- country'
411 },
412 rules => {
413 '$c eq "US"' => {
414 default => 'NTSC'
415 },
416 '$c eq "France"' => {
417 default => 'SECAM'
418 },
419 '$c eq "Japan"' => {
420 default => 'NTSC'
421 },
422 '$c eq "Europe"' => {
423 default => 'PAL'
424 },
425 }
426 }
427 } ,
428 ]
429 );
430 Setting "country" element to "US" means that "tv_standard" has a
432 default value set to "NTSC" by the warp mechanism.
433 Likewise, the warp mechanism enables you to dynamically change the
435 possible values of an enum element:
436 state => {
438 type => 'leaf',
439 value_type => 'enum', # example is admittedly silly
440 warp => {
441 follow => {
442 c => '- country'
443 },
444 rules => {
445 '$c eq "US"' => {
446 choice => ['Kansas', 'Texas' ]
447 },
448 '$c eq "Europe"' => {
449 choice => ['France', 'Spain' ]
450 },
451 '$c eq "Japan"' => {
452 choice => ['Honshu', 'Hokkaido' ]
453 }
454 }
455 }
456 }
457 Cascaded warping
459 Warping value can be cascaded: "A" can be warped by "B" which can be
460 warped by "C". But this feature should be avoided since it can lead to
461 a model very hard to debug. Bear in mind that:
462 · Warp loops are not detected and end up in "deep recursion
464 subroutine" failures.
465 · avoid "diamond" shaped warp dependencies: the results depends on
467 the order of the warp algorithm which can be unpredictable in this
468 case
469 · The keys declared in the warp rules ("US", "Europe" and "Japan" in
471 the example above) cannot be checked at start time against the warp
472 master "Value". So a wrong warp rule key is silently ignored during
473 start up and fails at run time.
474
476 To set up an enumerated value where the possible choice depends on the
477 key of a Config::Model::AnyId object, you must:
478 · Set "value_type" to "reference".
480 · Specify the "refer_to" or "computed_refer_to" parameter. See
482 refer_to parameter.
483 In this case, a "IdElementReference" object is created to handle the
485 relation between this value object and the referred Id. See
486 Config::Model::IdElementReference for details.
487
489 The following methods returns the current value of the parameter of the
490 value object (as declared in the model unless they were warped):
491 min
493 max
494 mandatory
495 choice
496 convert
497 value_type
498 default
499 upstream_default
500 index_value
501 element_name
502 name
504 Returns the object name.
505 get_type
507 Returns "leaf".
508 can_store
510 Returns true if the value object can be assigned to. Return 0 for a
511 read-only value (i.e. a computed value with no override allowed).
512 get_choice
514 Query legal values (only for enum types). Return an array (possibly
515 empty).
516 get_help
518 With a parameter, returns the help string applicable to the passed
519 value or undef.
520 Without parameter returns a hash ref that contains all the help
522 strings.
523 error_msg
525 Returns the error messages of this object (if any)
526 warning_msg
528 Returns warning concerning this value. Returns a list in list context
529 and a string in scalar context.
530 check_value
532 Parameters: "( value )"
533 Check the consistency of the value.
535 "check_value" also accepts named parameters:
537 value
539 quiet
540 When non null, check does not try to get extra information from the
541 tree. This is required in some cases to avoid loops in check,
542 get_info, get_warp_info, re-check ...
543 In scalar context, return 0 or 1.
545 In array context, return an empty array when no error was found. In
547 case of errors, returns an array of error strings that should be shown
548 to the user.
549 has_fixes
551 Returns the number of fixes that can be applied to the current value.
552 apply_fixes
554 Applies the fixes to suppress the current warnings.
555 check
557 Parameters: "( [ value => foo ] )"
558 Like "check_value".
560 Also displays warnings on STDOUT unless "silent" parameter is set to 1.
562 In this case,user is expected to retrieve them with "warning_msg".
563 Without "value" argument, this method checks the value currently
565 stored.
566 is_bad_mode
568 Accept a mode parameter. This function checks if the mode is accepted
569 by "fetch" method. Returns an error message if not. For instance:
570 if (my $err = $val->is_bad_mode('foo')) {
572 croak "my_function: $err";
573 }
574 This method is intented as a helper to avoid duplicating the list of
576 accepted modes for functions that want to wrap fetch methods (like
577 Config::Model::Dumper or Config::Model::DumpAsData)
578
580 store
581 Parameters: "( $value )" or "value => ..., check => yes|no|skip ),
582 silent => 0|1"
583 Store value in leaf element. "check" parameter can be used to skip
585 validation check (default is 'yes'). "silent" can be used to suppress
586 warnings.
587 Optional "callback" is now deprecated.
589 clear
591 Clear the stored value. Further read returns the default value (or
592 computed or migrated value).
593 load_data
595 Parameters: "( $value )"
596 Called with the same parameters are "store" method.
598 Load scalar data. Data is forwarded to "store" after checking that the
600 passed value is not a reference.
601 fetch_custom
603 Returns the stored value if this value is different from a standard
604 setting or built in setting. In other words, returns undef if the
605 stored value is identical to the default value or the computed value or
606 the built in value.
607 fetch_standard
609 Returns the standard value as defined by the configuration model. The
610 standard value can be either a preset value, a layered value, a
611 computed value, a default value or a built-in default value.
612 has_data
614 Return true if the value contains information different from default or
615 upstream default value.
616 fetch
618 Check and fetch value from leaf element. The method can have one
619 parameter (the fetch mode) or several pairs:
620 mode
622 Whether to fetch default, custom, etc value. See below for details
623 check
625 Whether to check if the value is valid or not before returning it.
626 Default is 'yes'. Possible value are
627 yes Perform check and raise an exception for bad values
629 skip
631 Perform check and return undef for bad values. A warning is
632 issued when a bad value is skipped. Set "check" to "no" to
633 avoid warnings.
634 no Do not check and return values even if bad
636 silent
638 When set to 1, warning are not displayed on STDOUT. User is
639 expected to read warnings with warning_msg method.
640 According to the "mode" parameter, this method returns either:
642 empty mode parameter (default)
644 Value entered by user or default value if the value is different
645 from upstream_default or layered value. Typically this value is
646 written in a configuration file.
647 backend
649 Alias for default mode.
650 custom
652 The value entered by the user (if different from built in, preset,
653 computed or default value)
654 user
656 The value most useful to user: the value that is used by the
657 application.
658 preset
660 The value entered in preset mode
661 standard
663 The preset or computed or default or built in value.
664 default
666 The default value (defined by the configuration model)
667 layered
669 The value found in included files (treated in layered mode: values
670 specified there are handled as upstream default values). E.g. like
671 in multistrap config.
672 upstream_default
674 The upstream_default value. (defined by the configuration model)
675 non_upstream_default
677 The custom or preset or computed or default value. Returns undef if
678 either of this value is identical to the upstream_default value.
679 This feature is useful to reduce data to write in configuration
680 file.
681 allow_undef
683 With this mode, "fetch()" behaves like in "user" mode, but returns
684 "undef" for mandatory values. Normally, trying to fetch an
685 undefined mandatory value leads to an exception.
686 user_value
688 Returns the value entered by the user. Does not use the default or
689 computed value. Returns undef unless a value was actually stored.
690 fetch_preset
692 Returns the value entered in preset mode. Does not use the default or
693 computed value. Returns undef unless a value was actually stored in
694 preset mode.
695 clear_preset
697 Delete the preset value. (Even out of preset mode). Returns true if
698 other data are still stored in the value (layered or user data).
699 Returns false otherwise.
700 fetch_layered
702 Returns the value entered in layered mode. Does not use the default or
703 computed value. Returns undef unless a value was actually stored in
704 layered mode.
705 clear_layered
707 Delete the layered value. (Even out of layered mode). Returns true if
708 other data are still stored in the value (layered or user data).
709 Returns false otherwise.
710 get( path => ..., mode => ... , check => ... )
712 Get a value from a directory like path.
713 set( path , value )
715 Set a value from a directory like path.
716
718 Number with min and max values
719 bounded_number => {
720 type => 'leaf',
721 value_type => 'number',
722 min => 1,
723 max => 4,
724 },
725 Mandatory value
727 mandatory_string => {
728 type => 'leaf',
729 value_type => 'string',
730 mandatory => 1,
731 },
732 mandatory_boolean => {
734 type => 'leaf',
735 value_type => 'boolean',
736 mandatory => 1,
737 },
738 Enum with help associated with each value
740 Note that the help specification is optional.
741 enum_with_help => {
743 type => 'leaf',
744 value_type => 'enum',
745 choice => [qw/a b c/],
746 help => {
747 a => 'a help'
748 }
749 },
750 Migrate old obsolete enum value
752 Legacy values "a1", "c1" and "foo/.*" are replaced with "a", "c" and
753 "foo/".
754 with_replace => {
756 type => 'leaf',
757 value_type => 'enum',
758 choice => [qw/a b c/],
759 replace => {
760 a1 => 'a',
761 c1 => 'c',
762 'foo/.*' => 'foo',
763 },
764 },
765 Enforce value to match a regexp
767 An exception is triggered when the value does not match the "match"
768 regular expression.
769 match => {
771 type => 'leaf',
772 value_type => 'string',
773 match => '^foo\d{2}$',
774 },
775 Enforce value to match a Parse::RecDescent grammar
777 match_with_parse_recdescent => {
778 type => 'leaf',
779 value_type => 'string',
780 grammar => q{
781 token (oper token)(s?)
782 oper: 'and' | 'or'
783 token: 'Apache' | 'CC-BY' | 'Perl'
784 },
785 },
786 Issue a warning if a value matches a regexp
788 Issue a warning if the string contains upper case letters. Propose a
789 fix that translate all capital letters to lower case.
790 warn_if_capital => {
792 type => 'leaf',
793 value_type => 'string',
794 warn_if_match => {
795 '/A-Z/' => {
796 fix => '$_ = lc;'
797 }
798 },
799 },
800 A specific warning can be specified:
802 warn_if_capital => {
804 type => 'leaf',
805 value_type => 'string',
806 warn_if_match => {
807 '/A-Z/' => {
808 fix => '$_ = lc;',
809 mesg => 'NO UPPER CASE PLEASE'
810 }
811 },
812 },
813 Issue a warning if a value does NOT match a regexp
815 warn_unless => {
816 type => 'leaf',
817 value_type => 'string',
818 warn_unless_match => {
819 foo => {
820 msg => '',
821 fix => '$_ = "foo".$_;'
822 }
823 },
824 },
825 Always issue a warning
827 always_warn => {
828 type => 'leaf',
829 value_type => 'string',
830 warn => 'Always warn whenever used',
831 },
832 Computed values
834 See "Examples" in Config::Model::ValueComputer.
835
837 Upgrade is a special case when the configuration of an application has
838 changed. Some parameters can be removed and replaced by another one. To
839 avoid trouble on the application user side, Config::Model offers a
840 possibility to handle the migration of configuration data through a
841 special declaration in the configuration model.
842 This declaration must:
844 · Declare the deprecated parameter with a "status" set to
846 "deprecated"
847 · Declare the new parameter with the instructions to load the
849 semantic content from the deprecated parameter. These instructions
850 are declared in the "migrate_from" parameters (which is similar to
851 the "compute" parameter)
852 Here an example where a URL parameter is changed to a set of 2
854 parameters (host and path):
855 'old_url' => {
857 type => 'leaf',
858 value_type => 'uniline',
859 status => 'deprecated',
860 },
861 'host' => {
862 type => 'leaf',
863 value_type => 'uniline',
864 # the formula must end with '$1' so the result of the capture is used
866 # as the host value
867 migrate_from => {
868 formula => '$old =~ m!http://([\w\.]+)!; $1 ;',
869 variables => {
870 old => '- old_url'
871 },
872 use_eval => 1,
873 },
874 },
875 'path' => {
876 type => 'leaf',
877 value_type => 'uniline',
878 migrate_from => {
879 formula => '$old =~ m!http://[\w\.]+(/.*)!; $1 ;',
880 variables => {
881 old => '- old_url'
882 },
883 use_eval => 1,
884 },
885 },
886
888 When an error is encountered, this module may throw the following
889 exceptions:
890 Config::Model::Exception::Model Config::Model::Exception::Formula
892 Config::Model::Exception::WrongValue
893 Config::Model::Exception::WarpError
894 See Config::Model::Exception for more details.
896
898 Dominique Dumont, (ddumont at cpan dot org)
899
901 Config::Model, Config::Model::Node, Config::Model::AnyId,
902 Config::Model::Warper, Config::Model::Exception
903 Config::Model::ValueComputer,
904
906 Dominique Dumont
907
909 This software is Copyright (c) 2005-2019 by Dominique Dumont.
910 This is free software, licensed under:
912 The GNU Lesser General Public License, Version 2.1, February 1999
914perl v5.30.1 2020-01-29 Config::Model::Value(3)