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.133
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 simple 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       Parameters: "( [ custom | preset | standard | default ] )"
259
260       Returns a hash (or a hash ref) of all items. The boolean value is the
261       value of the hash.
262
263       Example:
264
265        { A => 0, B => 1, C => 0 , D => 1}
266
267       By default, this method returns all items set by the user, or items set
268       in preset mode or checked by default.
269
270       With a parameter, this method returns either:
271
272       custom
273           The list entered by the user. An empty list is returned if the list
274           of checked items is identical to the list of items checked by
275           default. The whole list of checked items is returned as soon as one
276           item is different from standard value.
277
278       preset
279           The list entered in preset mode
280
281       standard
282           The list set in preset mode or checked by default.
283
284       default
285           The default list (defined by the configuration model)
286
287       layered
288           The list specified in layered mode.
289
290       upstream_default
291           The list implemented by upstream project (defined in the
292           configuration model)
293
294       user
295           The set that is active in the application. (ie. set by user or by
296           layered data or preset or default)
297
298   get_checked_list
299       Parameters: "( < mode > )"
300
301       Returns a list (or a list ref) of all checked items (i.e. all items set
302       to 1).
303
304   fetch
305       Parameters: "( < mode > )"
306
307       Returns a string listing the checked items (i.e. "A,B,C")
308
309   get
310       Parameters: "( path  [, < mode> ] )"
311
312       Get a value from a directory like path.
313

Method to check or clear items in the check list

315       All these methods accept an optional "check" parameter that can be:
316
317       yes A wrong item to check trigger an exception (default)
318
319       skip
320           A wrong item trigger a warning
321
322       no  A wrong item is ignored
323
324   set
325       Parameters: "( path, items_to_set, [ check => [ yes | no | skip  ] ] )"
326
327       Set a checklist with a directory like path. Since a checklist is a
328       leaf, the path should be empty.
329
330       The values are a comma separated list of items to set in the check
331       list.
332
333       Example :
334
335         $leaf->set('','A,C,Z');
336         $leaf->set('','A,C,Z', check => 'skip');
337
338   set_checked_list
339       Set all passed items to checked (1). All other available items in the
340       check list are set to 0.
341
342       Example, for a check list that contains A B C and D check items:
343
344         # set cl to A=0 B=1 C=0 D=1
345         $cl->set_checked_list('B','D')
346         $cl->set_checked_list( [ 'B','D' ])
347         $cl->set_checked_list( [ 'B','D' ], check => 'yes')
348
349   store_set
350       Alias to "set_checked_list", so a list and a check_list can use the
351       same store method
352
353   store
354       Set all items listed in a string to checked. The items must be
355       separated by commas. All other available items in the check list are
356       set to 0.
357
358       Example:
359
360         $cl->store('B, D')
361         $cl->store( value => 'B,C' )
362         $cl->store( value => 'B,C', check => 'yes' )
363
364   load
365       Alias to "store".
366
367   set_checked_list_as_hash
368       Set check_list items. Missing items in the given hash of parameters are
369       cleared (i.e. set to undef).
370
371       Example for a check list containing A B C D
372
373         $cl->set_checked_list_as_hash( { A => 1, B => 0} , check => 'yes' )
374         # result A => 1 B => 0 , C and D are undef
375
376   load_data
377       Load items as an array or hash ref. Array is forwarded to
378       set_checked_list , and hash is forwarded to set_checked_list_as_hash.
379
380       Example:
381
382        $cl->load_data(['A','B']) # cannot use check param here
383        $cl->load_data( data => ['A','B'])
384        $cl->load_data( data => ['A','B'], check => 'yes')
385        $cl->load_data( { A => 1, B => 1 } )
386        $cl->load_data( data => { A => 1, B => 1 }, check => 'yes')
387

Ordered checklist methods

389       All the methods below are valid only for ordered checklists.
390

swap

392       Parameters: "( choice_a, choice_b)"
393
394       Swap the 2 given choice in the list. Both choice must be already set.
395

move_up

397       Parameters: "( choice )"
398
399       Move the choice up in the checklist.
400

move_down

402       Parameters: "( choice )"
403
404       Move the choice down in the checklist.
405

AUTHOR

407       Dominique Dumont, (ddumont at cpan dot org)
408

AUTHOR

415       Dominique Dumont
416

COPYRIGHT AND LICENSE

418       This software is Copyright (c) 2005-2018 by Dominique Dumont.
419
420       This is free software, licensed under:
421
422         The GNU Lesser General Public License, Version 2.1, February 1999
423
424
425
426perl v5.28.1                      2019-02-02       Config::Model::CheckList(3)