Config::Model::CheckList(3pm)

1Config::Model::CheckLisUts(e3r)Contributed Perl DocumentCaotnifoing::Model::CheckList(3)
2
3
4

NAME

6       Config::Model::CheckList - Handle check list element
7

VERSION

9       version 2.138
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 => "MyClass",
18
19           element => [
20
21               # type check_list uses Config::Model::CheckList
22               my_check_list => {
23                   type   => 'check_list',
24                   choice => [ 'A', 'B', 'C', 'D' ],
25                   help   => {
26                       A => 'A effect is this',
27                       D => 'D does that',
28                   }
29               },
30           ],
31        );
32
33        my $inst = $model->instance( root_class_name => 'MyClass' );
34
35        my $root = $inst->config_root;
36
37        # put data
38        $root->load( steps => 'my_check_list=A' );
39
40        my $obj = $root->grab('my_check_list');
41
42        my $v = $root->grab_value('my_check_list');
43        print "check_list value '$v' with help '", $obj->get_help($v), "'\n";
44
45        # more data
46        $obj->check('D');
47        $v = $root->grab_value('my_check_list');
48        print "check_list new value is '$v'\n";   # prints check_list new value is 'A,D'
49

DESCRIPTION

51       This class provides a check list element for a Config::Model::Node.  In
52       other words, this class provides a list of booleans items. Each item
53       can be set to 1 or 0.
54
55       The available items in the check list can be :
56
57       ·   A fixed list (with the "choice" parameter)
58
59       ·   A dynamic list where the available choice are the keys of another
60           hash of the configuration tree. See "Choice reference" for details.
61

CONSTRUCTOR

63       CheckList object should not be created directly.
64

CheckList model declaration

66       A check list element must be declared with the following parameters:
67
68       type
69           Always "checklist".
70
71       choice
72           A list ref containing the check list items (optional)
73
74       refer_to
75           This parameter is used when the keys of a hash are used to specify
76           the possible choices of the check list. "refer_to" point to a hash
77           or list element in the configuration tree. See "Choice reference"
78           for details. (optional)
79
80       computed_refer_to
81           Like "refer_to", but use a computed value to find the hash or list
82           element in the configuration tree. See "Choice reference" for
83           details. (optional)
84
85       default_list
86           List ref to specify the check list items which are "on" by default.
87           (optional)
88
89       ordered
90           Specify whether the order of checked items must be preserved.
91
92       help
93           Hash ref to provide information on the check list items.
94
95       warp
96           Used to provide dynamic modifications of the check list properties
97           See Config::Model::Warper for details
98
99       For example:
100
101       ·   A check list with help:
102
103            choice_list => {
104                type   => 'check_list',
105                choice => ['A' .. 'Z'],
106                help   => { A => 'A help', E => 'E help' } ,
107            },
108
109       ·   A check list with default values:
110
111            choice_list_with_default => {
112                type => 'check_list',
113                choice     => ['A' .. 'Z'],
114                default_list   => [ 'A', 'D' ],
115            },
116
117       ·   A check list whose available choice and default change depending on
118           the value of the "macro" parameter:
119
120            warped_choice_list => {
121                type => 'check_list',
122                warp => {
123                    follow => '- macro',
124                    rules  => {
125                        AD => {
126                            choice => [ 'A' .. 'D' ],
127                            default_list => ['A', 'B' ]
128                        },
129                        AH => { choice => [ 'A' .. 'H' ] },
130                    }
131                }
132            },
133

Introspection methods

135       The following methods returns the checklist parameter :
136
137       refer_to
138       computed_refer_to
139

Choice reference

141       The choice items of a check_list can be given by another configuration
142       element. This other element can be:
143
144       ·   The keys of a hash
145
146       ·   Another checklist. In this case only the checked items of the other
147           checklist are available.
148
149       This other hash or other checklist is indicated by the "refer_to" or
150       "computed_refer_to" parameter. "refer_to" uses the syntax of the
151       "steps" parameter of grab(...)
152
153       See refer_to parameter.
154
155   Reference examples
156       ·   A check list where the available choices are the keys of "my_hash"
157           configuration parameter:
158
159            refer_to_list => {
160                type => 'check_list',
161                refer_to => '- my_hash'
162            },
163
164       ·   A check list where the available choices are the checked items of
165           "other_check_list" configuration parameter:
166
167            other_check_list => {
168                type => 'check_list',
169                choice => [qw/A B C/]
170            },
171            refer_to_list => {
172                type => 'check_list',
173                refer_to => '- other_check_list'
174            },
175
176       ·   A check list where the available choices are the keys of "my_hash"
177           and "my_hash2" and "my_hash3" configuration parameter:
178
179            refer_to_3_lists => {
180                type => 'check_list',
181                refer_to => '- my_hash + - my_hash2   + - my_hash3'
182            },
183
184       ·   A check list where the available choices are the specified choice
185           and the choice of "refer_to_3_lists" and a hash whose name is
186           specified by the value of the "indirection" configuration parameter
187           (this example is admittedly convoluted):
188
189            refer_to_check_list_and_choice => {
190                type => 'check_list',
191                computed_refer_to => {
192                    formula => '- refer_to_2_list + - $var',
193                    variables => {
194                        var => '- indirection '
195                    }
196                },
197                choice  => [qw/A1 A2 A3/],
198            },
199

Methods

201   get_type
202       Returns "check_list".
203
204   cargo_type
205       Returns 'leaf'.
206
207   check
208       Set choice. Parameter is either a list of choices to set or a list ref
209       and some optional parameter. I.e:
210
211         check (\@list, check => 'skip') ;
212
213       "check" parameter decide on behavior in case of invalid choice value:
214       either die (if yes) or discard bad value (if skip)
215
216   uncheck
217       Unset choice. Parameter is either a list of choices to unset or a list
218       ref and some optional parameter. I.e:
219
220         uncheck (\@list, check => 'skip') ;
221
222       "check" parameter decide on behavior in case of invalid choice value:
223       either die (if yes) or discard bad value (if skip)
224
225   is_checked
226       Parameters: "( choice, [ check => yes|skip ] , [ mode => ... ])"
227
228       Return 1 if the given "choice" was set. Returns 0 otherwise.
229
230       "check" parameter decide on behavior in case of invalid choice value:
231       either die (if yes) or discard bad value (if skip)
232
233       "mode" is either: custom standard preset default layered
234       upstream_default
235
236   has_data
237       Return true if the check_list contains a set of checks different from
238       default or upstream default set of check.
239
240   get_choice
241       Returns an array of all items names that can be checked (i.e.  that can
242       have value 0 or 1).
243
244   get_help
245       Parameters: "(choice_value)"
246
247       Return the help string on this choice value
248
249   clear
250       Reset the check list (can also be called as "clear_values")
251
252   clear_item
253       Parameters: "(choice_value)"
254
255       Reset an element of the checklist.
256
257   get_checked_list_as_hash
258       Accept a parameter (referred below as "mode" parameter) similar to
259       "mode" in "fetch" in Config::Model::Value.
260
261       Returns a hash (or a hash ref) of all items. The boolean value is the
262       value of the hash.
263
264       Example:
265
266        { A => 0, B => 1, C => 0 , D => 1}
267
268       By default, this method returns all items set by the user, or items set
269       in preset mode or checked by default.
270
271       With a "mode" parameter set to a value from the list below, this method
272       returns:
273
274       backend
275           The value written in config file, (ie. set by user or by layered
276           data or preset or default)
277
278       custom
279           The list entered by the user. An empty list is returned if the list
280           of checked items is identical to the list of items checked by
281           default. The whole list of checked items is returned as soon as one
282           item is different from standard value.
283
284       preset
285           The list entered in preset mode
286
287       standard
288           The list set in preset mode or checked by default.
289
290       default
291           The default list (defined by the configuration model)
292
293       layered
294           The list specified in layered mode.
295
296       upstream_default
297           The list implemented by upstream project (defined in the
298           configuration model)
299
300       user
301           The set that is active in the application. (ie. set by user or by
302           layered data or preset or default or upstream_default)
303
304       non_upstream_default
305           The choice set by user or by layered data or preset or default.
306
307   get_checked_list
308       Parameters: "( < mode > )"
309
310       Returns a list (or a list ref) of all checked items (i.e. all items set
311       to 1).
312
313   fetch
314       Parameters: "( < mode > )"
315
316       Returns a string listing the checked items (i.e. "A,B,C")
317
318   get
319       Parameters: "( path  [, < mode> ] )"
320
321       Get a value from a directory like path.
322

Method to check or clear items in the check list

324       All these methods accept an optional "check" parameter that can be:
325
326       yes A wrong item to check trigger an exception (default)
327
328       skip
329           A wrong item trigger a warning
330
331       no  A wrong item is ignored
332
333   set
334       Parameters: "( path, items_to_set, [ check => [ yes | no | skip  ] ] )"
335
336       Set a checklist with a directory like path. Since a checklist is a
337       leaf, the path should be empty.
338
339       The values are a comma separated list of items to set in the check
340       list.
341
342       Example :
343
344         $leaf->set('','A,C,Z');
345         $leaf->set('','A,C,Z', check => 'skip');
346
347   set_checked_list
348       Set all passed items to checked (1). All other available items in the
349       check list are set to 0.
350
351       Example, for a check list that contains A B C and D check items:
352
353         # set cl to A=0 B=1 C=0 D=1
354         $cl->set_checked_list('B','D')
355         $cl->set_checked_list( [ 'B','D' ])
356         $cl->set_checked_list( [ 'B','D' ], check => 'yes')
357
358   store_set
359       Alias to "set_checked_list", so a list and a check_list can use the
360       same store method
361
362   store
363       Set all items listed in a string to checked. The items must be
364       separated by commas. All other available items in the check list are
365       set to 0.
366
367       Example:
368
369         $cl->store('B, D')
370         $cl->store( value => 'B,C' )
371         $cl->store( value => 'B,C', check => 'yes' )
372
373   load
374       Alias to "store".
375
376   set_checked_list_as_hash
377       Set check_list items. Missing items in the given hash of parameters are
378       cleared (i.e. set to undef).
379
380       Example for a check list containing A B C D
381
382         $cl->set_checked_list_as_hash( { A => 1, B => 0} , check => 'yes' )
383         # result A => 1 B => 0 , C and D are undef
384
385   load_data
386       Load items as an array or hash ref. Array is forwarded to
387       set_checked_list , and hash is forwarded to set_checked_list_as_hash.
388
389       Example:
390
391        $cl->load_data(['A','B']) # cannot use check param here
392        $cl->load_data( data => ['A','B'])
393        $cl->load_data( data => ['A','B'], check => 'yes')
394        $cl->load_data( { A => 1, B => 1 } )
395        $cl->load_data( data => { A => 1, B => 1 }, check => 'yes')
396
397   is_bad_mode
398       Accept a mode parameter. This function checks if the mode is accepted
399       by "fetch" method. Returns an error message if not. For instance:
400
401        if (my $err = $val->is_bad_mode('foo')) {
402           croak "my_function: $err";
403        }
404
405       This method is intented as a helper ti avoid duplicating the list of
406       accepted modes for functions that want to wrap fetch methods (like
407       Config::Model::Dumper or Config::Model::DumpAsData)
408

Ordered checklist methods

410       All the methods below are valid only for ordered checklists.
411
412   swap
413       Parameters: "( choice_a, choice_b)"
414
415       Swap the 2 given choice in the list. Both choice must be already set.
416
417   move_up
418       Parameters: "( choice )"
419
420       Move the choice up in the checklist.
421
422   move_down
423       Parameters: "( choice )"
424
425       Move the choice down in the checklist.
426

AUTHOR

428       Dominique Dumont, (ddumont at cpan dot org)
429

AUTHOR

436       Dominique Dumont
437

COPYRIGHT AND LICENSE

439       This software is Copyright (c) 2005-2019 by Dominique Dumont.
440
441       This is free software, licensed under:
442
443         The GNU Lesser General Public License, Version 2.1, February 1999
444
445
446
447perl v5.30.1                      2020-01-29       Config::Model::CheckList(3)