1Config::Model::Value(3pUms)er Contributed Perl DocumentatCioonnfig::Model::Value(3pm)
2
6 Config::Model::Value - Strongly typed configuration value
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 => "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 (i.e is "undef" or empty string) and has
72 no default value.
73 • dynamic change of property: A slave value can be registered to
75 another master value so that the properties of the slave value can
76 change according to the value of the master value. For instance,
77 paper size value can be 'letter' for country 'US' and 'A4' for
78 country 'France'.
79 • A reference to the Id of a hash of list element. In other word, the
81 value is an enumerated type where the possible values (choice) is
82 defined by the existing keys of a has element somewhere in the
83 tree. See "Value Reference".
84
86 There are several kind of default values. They depend on where these
87 values are defined (or found).
88 From the lowest default level to the "highest":
90 • "upstream_default": The value is known in the application, but is
92 not written in the configuration file.
93 • "layered": The value is known by the application through another
95 mean (e.g. an included configuration file), but is not written in
96 the configuration file.
97 • "default": The value is known by the model, but not by the
99 application. This value must be written in the configuration file.
100 • "computed": The value is computed from other configuration
102 elements. This value must be written in the configuration file.
103 • "preset": The value is not known by the model or by the
105 application. But it can be found by an automatic program and stored
106 while the configuration Config::Model::Instance is in preset mode
107 Then there is the value entered by the user. This overrides all kind of
109 "default" value.
110 The fetch_standard function returns the "highest" level of default
112 value, but does not return a custom value, i.e. a value entered by the
113 user.
114
116 Value object should not be created directly.
117
119 A leaf element must be declared with the following parameters:
120 value_type
122 Either "boolean", "enum", "integer", "number", "uniline", "string",
123 "file", "dir". Mandatory. See "Value types".
124 default
126 Specify the default value (optional)
127 upstream_default
129 Specify a built in default value (optional). I.e a value known by
130 the application which does not need to be written in the
131 configuration file.
132 write_as
134 Array ref. Reserved for boolean value. Specify how to write a
135 boolean value. Default is "[0,1]" which may not be the most
136 readable. "write_as" can be specified as "['false','true']" or
137 "['no','yes']".
138 compute
140 Computes a value according to a formula and other values. By
141 default a computed value cannot be set. See
142 Config::Model::ValueComputer for computed value declaration.
143 migrate_from
145 This is a special parameter to cater for smooth configuration
146 upgrade. This parameter can be used to copy the value of a
147 deprecated parameter to its replacement. See "Upgrade" for details.
148 convert => [uc | lc ]
150 When stored, the value is converted to uppercase (uc) or lowercase
151 (lc).
152 min Specify the minimum value (optional, only for integer, number)
154 max Specify the maximum value (optional, only for integer, number)
156 mandatory
158 Set to 1 if the configuration value must be set by the
159 configuration user (default: 0)
160 choice
162 Array ref of the possible value of an enum. Example :
163 choice => [ qw/foo bar/]
165 match
167 Perl regular expression. The value is matched with the regex to
168 assert its validity. Example "match => '^foo'" means that the
169 parameter value must begin with "foo". Valid only for "string" or
170 "uniline" values.
171 warn_if_match
173 Hash ref. Keys are made of Perl regular expression. The value can
174 specify a warning message (leave empty or undefined for a default
175 warning message) and instructions to fix the value. A warning is
176 issued when the value matches the passed regular expression. Valid
177 only for "string" or "uniline" values. The fix instructions is
178 evaluated when apply_fixes is called. $_ contains the value to fix.
179 $_ is stored as the new value once the instructions are done.
180 $self contains the value object. Use with care.
181 In the example below, any value matching 'foo' is converted in
183 uppercase:
184 warn_if_match => {
186 'foo' => {
187 fix => 'uc;',
188 msg => 'value $_ contains foo'
189 },
190 'BAR' => {
191 fix =>'lc;',
192 msg => 'value $_ contains BAR'
193 }
194 },
195 The tests are done in alphabetical order. In the example above,
197 "BAR" test is done before "foo" test.
198 $_ is substituted with the bad value when the message is generated.
200 $std_value is substituted with the standard value (i.e the preset,
201 computed or default value).
202 warn_unless_match
204 Hash ref like above. A warning is issued when the value does not
205 match the passed regular expression. Valid only for "string" or
206 "uniline" values.
207 warn
209 String. Issue a warning to user with the specified string any time
210 a value is set or read.
211 warn_if
213 A bit like "warn_if_match". The hash key is not a regexp but a
214 label to help users. The hash ref contains some Perl code that is
215 evaluated to perform the test. A warning is issued if the given
216 code returns true.
217 $_ contains the value to check. $self contains the
219 "Config::Model::Value" object (use with care).
220 The example below warns if value contains a number:
222 warn_if => {
224 warn_test => {
225 code => 'defined $_ && /\d/;',
226 msg => 'value $_ should not have numbers',
227 fix => 's/\d//g;'
228 }
229 },
230 Hash key is used in warning message when "msg" is not set:
232 warn_if => {
234 'should begin with foo' => {
235 code => 'defined && /^foo/'
236 }
237 }
238 Any operation or check on file must be done with "file" sub
240 (otherwise tests will break). This sub returns a Path::Tiny object
241 that can be used to perform checks. For instance:
242 warn_if => {
244 warn_test => {
245 code => 'not file($_)->exists',
246 msg => 'file $_ should exist'
247 }
248 warn_unless
250 Like "warn_if", but issue a warning when the given "code" returns
251 false.
252 The example below warns unless the value points to an existing
254 directory:
255 warn_unless => {
257 'missing dir' => {
258 code => '-d',
259 fix => "system(mkdir $_);" }
260 }
261 assert
263 Like "warn_if". Except that returned value triggers an error when
264 the given code returns false:
265 assert => {
267 test_nb => {
268 code => 'defined $_ && /\d/;',
269 msg => 'should not have numbers',
270 fix => 's/\d//g;'
271 }
272 },
273 hash key can also be used to generate error message when "msg"
275 parameter is not set.
276 grammar
278 Setup a Parse::RecDescent grammar to perform validation.
279 If the grammar does not start with a "check" rule (i.e does not
281 start with "check: "), the first line of the grammar is modified to
282 add "check" rule and this rules is set up so the entire value must
283 match the passed grammar.
284 I.e. the grammar:
286 token (oper token)(s?)
288 oper: 'and' | 'or'
289 token: 'Apache' | 'CC-BY' | 'Perl'
290 is changed to
292 check: token (oper token)(s?) /^\Z/ {$return = 1;}
294 oper: 'and' | 'or'
295 token: 'Apache' | 'CC-BY' | 'Perl'
296 The rule is called with Value object and a string reference. So, in
298 the actions you may need to define, you can call the value object
299 as $arg[0], store error message in "${$arg[1]}}" and store warnings
300 in "${$arg[2]}}".
301 replace
303 Hash ref. Used for enum to substitute one value with another. This
304 parameter must be used to enable user to upgrade a configuration
305 with obsolete values. For instance, if the value "foo" is obsolete
306 and replaced by "foo_better", you must declare:
307 replace => { foo => 'foo_better' }
309 The hash key can also be a regular expression for wider range
311 replacement. The regexp must match the whole value:
312 replace => ( 'foo.*' => 'better_foo' }
314 In this case, a value is replaced by "better_foo" when the
316 "/^foo.*$/" regexp matches.
317 replace_follow
319 Path specifying a hash of value element in the configuration tree.
320 The hash if used in a way similar to the "replace" parameter. In
321 this case, the replacement is not coded in the model but specified
322 by the configuration.
323 refer_to
325 Specify a path to an id element used as a reference. See Value
326 Reference for details.
327 computed_refer_to
329 Specify a path to an id element used as a computed reference. See
330 "Value Reference" for details.
331 warp
333 See section below: "Warp: dynamic value configuration".
334 help
336 You may provide detailed description on possible values with a hash
337 ref. Example:
338 help => { oui => "French for 'yes'", non => "French for 'no'"}
340 The key of help is used as a regular expression to find the help
342 text applicable to a value. These regexp are tried from the longest
343 to the shortest and are matched from the beginning of the string.
344 The key ""."" or "".*"" are fallback used last.
345 For instance:
347 help => {
349 'foobar' => 'help for values matching /^foobar/',
350 'foo' => 'help for values matching /^foo/ but not /^foobar/ (used above)',
351 '.' => 'help for all other values'
352 }
353 Value types
355 This modules can check several value types:
356 "boolean"
358 Accepts values 1 or 0, "yes" or "no", "true" or "false", and empty
359 string. The value read back is always 1 or 0.
360 "enum"
362 Enum choices must be specified by the "choice" parameter.
363 "integer"
365 Enable positive or negative integer
366 "number"
368 The value can be a decimal number
369 "uniline"
371 A one line string. I.e without "\n" in it.
372 "string"
374 Actually, no check is performed with this type.
375 "reference"
377 Like an "enum" where the possible values (aka choice) is defined by
378 another location if the configuration tree. See "Value Reference".
379 "file"
381 A file name or path. A warning is issued if the file does not
382 exists (or is a directory)
383 "dir"
385 A directory name or path. A warning is issued if the directory does
386 not exists (or is a plain file)
387
389 The Warp functionality enable a "Value" object to change its properties
390 (i.e. default value or its type) dynamically according to the value of
391 another "Value" object locate elsewhere in the configuration tree. (See
392 Config::Model::Warper for an explanation on warp mechanism).
393 For instance if you declare 2 "Value" element this way:
395 $model ->create_config_class (
397 name => "TV_config_class",
398 element => [
399 country => {
400 type => 'leaf',
401 value_type => 'enum',
402 choice => [qw/US Europe Japan/]
403 } ,
404 tv_standard => { # this example is getting old...
405 type => 'leaf',
406 value_type => 'enum',
407 choice => [ qw/PAL NTSC SECAM/ ]
408 warp => {
409 follow => {
410 # this points to the warp master
411 c => '- country'
412 },
413 rules => {
414 '$c eq "US"' => {
415 default => 'NTSC'
416 },
417 '$c eq "France"' => {
418 default => 'SECAM'
419 },
420 '$c eq "Japan"' => {
421 default => 'NTSC'
422 },
423 '$c eq "Europe"' => {
424 default => 'PAL'
425 },
426 }
427 }
428 } ,
429 ]
430 );
431 Setting "country" element to "US" means that "tv_standard" has a
433 default value set to "NTSC" by the warp mechanism.
434 Likewise, the warp mechanism enables you to dynamically change the
436 possible values of an enum element:
437 state => {
439 type => 'leaf',
440 value_type => 'enum', # example is admittedly silly
441 warp => {
442 follow => {
443 c => '- country'
444 },
445 rules => {
446 '$c eq "US"' => {
447 choice => ['Kansas', 'Texas' ]
448 },
449 '$c eq "Europe"' => {
450 choice => ['France', 'Spain' ]
451 },
452 '$c eq "Japan"' => {
453 choice => ['Honshu', 'Hokkaido' ]
454 }
455 }
456 }
457 }
458 Cascaded warping
460 Warping value can be cascaded: "A" can be warped by "B" which can be
461 warped by "C". But this feature should be avoided since it can lead to
462 a model very hard to debug. Bear in mind that:
463 • Warp loops are not detected and end up in "deep recursion
465 subroutine" failures.
466 • avoid "diamond" shaped warp dependencies: the results depends on
468 the order of the warp algorithm which can be unpredictable in this
469 case
470 • The keys declared in the warp rules ("US", "Europe" and "Japan" in
472 the example above) cannot be checked at start time against the warp
473 master "Value". So a wrong warp rule key is silently ignored during
474 start up and fails at run time.
475
477 To set up an enumerated value where the possible choice depends on the
478 key of a Config::Model::AnyId object, you must:
479 • Set "value_type" to "reference".
481 • Specify the "refer_to" or "computed_refer_to" parameter. See
483 refer_to parameter.
484 In this case, a "IdElementReference" object is created to handle the
486 relation between this value object and the referred Id. See
487 Config::Model::IdElementReference for details.
488
490 The following methods returns the current value of the parameter of the
491 value object (as declared in the model unless they were warped):
492 min
494 max
495 mandatory
496 choice
497 convert
498 value_type
499 default
500 upstream_default
501 index_value
502 element_name
503 name
505 Returns the object name.
506 get_type
508 Returns "leaf".
509 can_store
511 Returns true if the value object can be assigned to. Return 0 for a
512 read-only value (i.e. a computed value with no override allowed).
513 get_choice
515 Query legal values (only for enum types). Return an array (possibly
516 empty).
517 get_help
519 With a parameter, returns the help string applicable to the passed
520 value or undef.
521 Without parameter returns a hash ref that contains all the help
523 strings.
524 get_info
526 Returns a list of information related to the value, like value type,
527 default value. This should be used to provide some debug information to
528 the user.
529 For instance, "$val-"get-info> may return:
531 [ 'type: string', 'mandatory: yes' ]
533 error_msg
535 Returns the error messages of this object (if any)
536 warning_msg
538 Returns warning concerning this value. Returns a list in list context
539 and a string in scalar context.
540 check_value
542 Parameters: "( value )"
543 Check the consistency of the value.
545 "check_value" also accepts named parameters:
547 value
549 quiet
550 When non null, check does not try to get extra information from the
551 tree. This is required in some cases to avoid loops in check,
552 get_info, get_warp_info, re-check ...
553 In scalar context, return 0 or 1.
555 In array context, return an empty array when no error was found. In
557 case of errors, returns an array of error strings that should be shown
558 to the user.
559 has_fixes
561 Returns the number of fixes that can be applied to the current value.
562 apply_fixes
564 Applies the fixes to suppress the current warnings.
565 check
567 Parameters: "( [ value => foo ] )"
568 Like "check_value".
570 Also displays warnings on STDOUT unless "silent" parameter is set to 1.
572 In this case,user is expected to retrieve them with "warning_msg".
573 Without "value" argument, this method checks the value currently
575 stored.
576 is_bad_mode
578 Accept a mode parameter. This function checks if the mode is accepted
579 by "fetch" method. Returns an error message if not. For instance:
580 if (my $err = $val->is_bad_mode('foo')) {
582 croak "my_function: $err";
583 }
584 This method is intented as a helper to avoid duplicating the list of
586 accepted modes for functions that want to wrap fetch methods (like
587 Config::Model::Dumper or Config::Model::DumpAsData)
588
590 store
591 Parameters: "( $value )" or "value => ..., check => yes|no|skip ),
592 silent => 0|1"
593 Store value in leaf element. "check" parameter can be used to skip
595 validation check (default is 'yes'). "silent" can be used to suppress
596 warnings.
597 Optional "callback" is now deprecated.
599 clear
601 Clear the stored value. Further read returns the default value (or
602 computed or migrated value).
603 load_data
605 Parameters: "( $value )"
606 Called with the same parameters are "store" method.
608 Load scalar data. Data is forwarded to "store" after checking that the
610 passed value is not a reference.
611 fetch_custom
613 Returns the stored value if this value is different from a standard
614 setting or built in setting. In other words, returns undef if the
615 stored value is identical to the default value or the computed value or
616 the built in value.
617 fetch_standard
619 Returns the standard value as defined by the configuration model. The
620 standard value can be either a preset value, a layered value, a
621 computed value, a default value or a built-in default value.
622 has_data
624 Return true if the value contains information different from default or
625 upstream default value.
626 fetch
628 Check and fetch value from leaf element. The method can have one
629 parameter (the fetch mode) or several pairs:
630 mode
632 Whether to fetch default, custom, etc value. See below for details
633 check
635 Whether to check if the value is valid or not before returning it.
636 Default is 'yes'. Possible value are
637 yes Perform check and raise an exception for bad values
639 skip
641 Perform check and return undef for bad values. A warning is
642 issued when a bad value is skipped. Set "check" to "no" to
643 avoid warnings.
644 no Do not check and return values even if bad
646 silent
648 When set to 1, warning are not displayed on STDOUT. User is
649 expected to read warnings with warning_msg method.
650 According to the "mode" parameter, this method returns either:
652 empty mode parameter (default)
654 Value entered by user or default value if the value is different
655 from upstream_default or layered value. Typically this value is
656 written in a configuration file.
657 backend
659 Alias for default mode.
660 custom
662 The value entered by the user (if different from built in, preset,
663 computed or default value)
664 user
666 The value most useful to user: the value that is used by the
667 application.
668 preset
670 The value entered in preset mode
671 standard
673 The preset or computed or default or built in value.
674 default
676 The default value (defined by the configuration model)
677 layered
679 The value found in included files (treated in layered mode: values
680 specified there are handled as upstream default values). E.g. like
681 in multistrap config.
682 upstream_default
684 The upstream_default value. (defined by the configuration model)
685 non_upstream_default
687 The custom or preset or computed or default value. Returns undef if
688 either of this value is identical to the upstream_default value.
689 This feature is useful to reduce data to write in configuration
690 file.
691 allow_undef
693 With this mode, fetch() behaves like in "user" mode, but returns
694 "undef" for mandatory values. Normally, trying to fetch an
695 undefined mandatory value leads to an exception.
696 fetch_summary
698 Returns a truncated value when the value is a string or uniline that is
699 too long to be displayed.
700 user_value
702 Returns the value entered by the user. Does not use the default or
703 computed value. Returns undef unless a value was actually stored.
704 fetch_preset
706 Returns the value entered in preset mode. Does not use the default or
707 computed value. Returns undef unless a value was actually stored in
708 preset mode.
709 clear_preset
711 Delete the preset value. (Even out of preset mode). Returns true if
712 other data are still stored in the value (layered or user data).
713 Returns false otherwise.
714 fetch_layered
716 Returns the value entered in layered mode. Does not use the default or
717 computed value. Returns undef unless a value was actually stored in
718 layered mode.
719 clear_layered
721 Delete the layered value. (Even out of layered mode). Returns true if
722 other data are still stored in the value (layered or user data).
723 Returns false otherwise.
724 get( path => ..., mode => ... , check => ... )
726 Get a value from a directory like path.
727 set( path , value )
729 Set a value from a directory like path.
730
732 Number with min and max values
733 bounded_number => {
734 type => 'leaf',
735 value_type => 'number',
736 min => 1,
737 max => 4,
738 },
739 Mandatory value
741 mandatory_string => {
742 type => 'leaf',
743 value_type => 'string',
744 mandatory => 1,
745 },
746 mandatory_boolean => {
748 type => 'leaf',
749 value_type => 'boolean',
750 mandatory => 1,
751 },
752 Enum with help associated with each value
754 Note that the help specification is optional.
755 enum_with_help => {
757 type => 'leaf',
758 value_type => 'enum',
759 choice => [qw/a b c/],
760 help => {
761 a => 'a help'
762 }
763 },
764 Migrate old obsolete enum value
766 Legacy values "a1", "c1" and "foo/.*" are replaced with "a", "c" and
767 "foo/".
768 with_replace => {
770 type => 'leaf',
771 value_type => 'enum',
772 choice => [qw/a b c/],
773 replace => {
774 a1 => 'a',
775 c1 => 'c',
776 'foo/.*' => 'foo',
777 },
778 },
779 Enforce value to match a regexp
781 An exception is triggered when the value does not match the "match"
782 regular expression.
783 match => {
785 type => 'leaf',
786 value_type => 'string',
787 match => '^foo\d{2}$',
788 },
789 Enforce value to match a Parse::RecDescent grammar
791 match_with_parse_recdescent => {
792 type => 'leaf',
793 value_type => 'string',
794 grammar => q{
795 token (oper token)(s?)
796 oper: 'and' | 'or'
797 token: 'Apache' | 'CC-BY' | 'Perl'
798 },
799 },
800 Issue a warning if a value matches a regexp
802 Issue a warning if the string contains upper case letters. Propose a
803 fix that translate all capital letters to lower case.
804 warn_if_capital => {
806 type => 'leaf',
807 value_type => 'string',
808 warn_if_match => {
809 '/A-Z/' => {
810 fix => '$_ = lc;'
811 }
812 },
813 },
814 A specific warning can be specified:
816 warn_if_capital => {
818 type => 'leaf',
819 value_type => 'string',
820 warn_if_match => {
821 '/A-Z/' => {
822 fix => '$_ = lc;',
823 mesg => 'NO UPPER CASE PLEASE'
824 }
825 },
826 },
827 Issue a warning if a value does NOT match a regexp
829 warn_unless => {
830 type => 'leaf',
831 value_type => 'string',
832 warn_unless_match => {
833 foo => {
834 msg => '',
835 fix => '$_ = "foo".$_;'
836 }
837 },
838 },
839 Always issue a warning
841 always_warn => {
842 type => 'leaf',
843 value_type => 'string',
844 warn => 'Always warn whenever used',
845 },
846 Computed values
848 See "Examples" in Config::Model::ValueComputer.
849
851 Upgrade is a special case when the configuration of an application has
852 changed. Some parameters can be removed and replaced by another one. To
853 avoid trouble on the application user side, Config::Model offers a
854 possibility to handle the migration of configuration data through a
855 special declaration in the configuration model.
856 This declaration must:
858 • Declare the deprecated parameter with a "status" set to
860 "deprecated"
861 • Declare the new parameter with the instructions to load the
863 semantic content from the deprecated parameter. These instructions
864 are declared in the "migrate_from" parameters (which is similar to
865 the "compute" parameter)
866 Here an example where a URL parameter is changed to a set of 2
868 parameters (host and path):
869 'old_url' => {
871 type => 'leaf',
872 value_type => 'uniline',
873 status => 'deprecated',
874 },
875 'host' => {
876 type => 'leaf',
877 value_type => 'uniline',
878 # the formula must end with '$1' so the result of the capture is used
880 # as the host value
881 migrate_from => {
882 formula => '$old =~ m!http://([\w\.]+)!; $1 ;',
883 variables => {
884 old => '- old_url'
885 },
886 use_eval => 1,
887 },
888 },
889 'path' => {
890 type => 'leaf',
891 value_type => 'uniline',
892 migrate_from => {
893 formula => '$old =~ m!http://[\w\.]+(/.*)!; $1 ;',
894 variables => {
895 old => '- old_url'
896 },
897 use_eval => 1,
898 },
899 },
900
902 When an error is encountered, this module may throw the following
903 exceptions:
904 Config::Model::Exception::Model Config::Model::Exception::Formula
906 Config::Model::Exception::WrongValue
907 Config::Model::Exception::WarpError
908 See Config::Model::Exception for more details.
910
912 Dominique Dumont, (ddumont at cpan dot org)
913
915 Config::Model, Config::Model::Node, Config::Model::AnyId,
916 Config::Model::Warper, Config::Model::Exception
917 Config::Model::ValueComputer,
918
920 Dominique Dumont
921
923 This software is Copyright (c) 2005-2022 by Dominique Dumont.
924 This is free software, licensed under:
926 The GNU Lesser General Public License, Version 2.1, February 1999
928perl v5.38.0 2023-07-25 Config::Model::Value(3pm)