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.140
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   get_info
250       Returns a list of information related to the check list. See "get_info"
251       in Config::Model::Value for more details.
252
253   clear
254       Reset the check list (can also be called as "clear_values")
255
256   clear_item
257       Parameters: "(choice_value)"
258
259       Reset an element of the checklist.
260
261   get_checked_list_as_hash
262       Accept a parameter (referred below as "mode" parameter) similar to
263       "mode" in "fetch" in Config::Model::Value.
264
265       Returns a hash (or a hash ref) of all items. The boolean value is the
266       value of the hash.
267
268       Example:
269
270        { A => 0, B => 1, C => 0 , D => 1}
271
272       By default, this method returns all items set by the user, or items set
273       in preset mode or checked by default.
274
275       With a "mode" parameter set to a value from the list below, this method
276       returns:
277
278       backend
279           The value written in config file, (ie. set by user or by layered
280           data or preset or default)
281
282       custom
283           The list entered by the user. An empty list is returned if the list
284           of checked items is identical to the list of items checked by
285           default. The whole list of checked items is returned as soon as one
286           item is different from standard value.
287
288       preset
289           The list entered in preset mode
290
291       standard
292           The list set in preset mode or checked by default.
293
294       default
295           The default list (defined by the configuration model)
296
297       layered
298           The list specified in layered mode.
299
300       upstream_default
301           The list implemented by upstream project (defined in the
302           configuration model)
303
304       user
305           The set that is active in the application. (ie. set by user or by
306           layered data or preset or default or upstream_default)
307
308       non_upstream_default
309           The choice set by user or by layered data or preset or default.
310
311   get_checked_list
312       Parameters: "( < mode > )"
313
314       Returns a list (or a list ref) of all checked items (i.e. all items set
315       to 1).
316
317   fetch
318       Parameters: "( < mode > )"
319
320       Returns a string listing the checked items (i.e. "A,B,C")
321
322   get
323       Parameters: "( path  [, < mode> ] )"
324
325       Get a value from a directory like path.
326

Method to check or clear items in the check list

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

Ordered checklist methods

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

AUTHOR

432       Dominique Dumont, (ddumont at cpan dot org)
433

AUTHOR

440       Dominique Dumont
441

COPYRIGHT AND LICENSE

443       This software is Copyright (c) 2005-2020 by Dominique Dumont.
444
445       This is free software, licensed under:
446
447         The GNU Lesser General Public License, Version 2.1, February 1999
448
449
450
451perl v5.32.0                      2020-08-02       Config::Model::CheckList(3)