--- name: "Config::Model::CheckList" section: "3pm" platform: "linux" package: "libconfig-model-perl" version: "2.155-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Config::Model::CheckList" --- # Config::Model::CheckList(3pm) Handle check list element ## NAME Config::Model::CheckList - Handle check list element ## VERSION version 2.155 ## SYNOPSIS ``` use Config::Model; # define configuration tree object my $model = Config::Model->new; $model->create_config_class( name => "MyClass", element => [ # type check_list uses Config::Model::CheckList my_check_list => { type => 'check_list', choice => [ 'A', 'B', 'C', 'D' ], help => { A => 'A effect is this', D => 'D does that', } }, ], ); my $inst = $model->instance( root_class_name => 'MyClass' ); my $root = $inst->config_root; # put data $root->load( steps => 'my_check_list=A' ); my $obj = $root->grab('my_check_list'); my $v = $root->grab_value('my_check_list'); print "check_list value '$v' with help '", $obj->get_help($v), "'\n"; # more data $obj->check('D'); $v = $root->grab_value('my_check_list'); print "check_list new value is '$v'\n"; # prints check_list new value is 'A,D' ``` ## DESCRIPTION This class provides a check list element for a Config::Model::Node. In other words, this class provides a list of booleans items. Each item can be set to 1 or 0. The available items in the check list can be : - • A fixed list (with the `"choice"` parameter) - • A dynamic list where the available choice are the keys of another hash of the configuration tree. See "Choice reference" for details. ## CONSTRUCTOR CheckList object should not be created directly. ## CheckList model declaration A check list element must be declared with the following parameters: - type Always `"checklist"`. - choice A list ref containing the check list items (optional) - refer\_to This parameter is used when the keys of a hash are used to specify the possible choices of the check list. `"refer_to"` point to a hash or list element in the configuration tree. See "Choice reference" for details. (optional) - computed\_refer\_to Like `"refer_to"`, but use a computed value to find the hash or list element in the configuration tree. See "Choice reference" for details. (optional) - default\_list List ref to specify the check list items which are "on" by default. (optional) - ordered Specify whether the order of checked items must be preserved. - help Hash ref to provide information on the check list items. - warp Used to provide dynamic modifications of the check list properties See Config::Model::Warper for details For example: - • A check list with help: ``` choice_list => { type => 'check_list', choice => ['A' .. 'Z'], help => { A => 'A help', E => 'E help' } , }, ``` - • A check list with default values: ``` choice_list_with_default => { type => 'check_list', choice => ['A' .. 'Z'], default_list => [ 'A', 'D' ], }, ``` - • A check list whose available choice and default change depending on the value of the `"macro"` parameter: ``` warped_choice_list => { type => 'check_list', warp => { follow => '- macro', rules => { AD => { choice => [ 'A' .. 'D' ], default_list => ['A', 'B' ] }, AH => { choice => [ 'A' .. 'H' ] }, } } }, ``` ## Introspection methods The following methods returns the checklist parameter : - refer\_to - computed\_refer\_to ## Choice reference The choice items of a check\_list can be given by another configuration element. This other element can be: - • The keys of a hash - • Another checklist. In this case only the checked items of the other checklist are available. This other hash or other checklist is indicated by the `"refer_to"` or `"computed_refer_to"` parameter. `"refer_to"` uses the syntax of the `"steps"` parameter of grab(...) See refer\_to parameter. ### Reference examples - • A check list where the available choices are the keys of `"my_hash"` configuration parameter: ``` refer_to_list => { type => 'check_list', refer_to => '- my_hash' }, ``` - • A check list where the available choices are the checked items of `"other_check_list"` configuration parameter: ``` other_check_list => { type => 'check_list', choice => [qw/A B C/] }, refer_to_list => { type => 'check_list', refer_to => '- other_check_list' }, ``` - • A check list where the available choices are the keys of `"my_hash"` and `"my_hash2"` and `"my_hash3"` configuration parameter: ``` refer_to_3_lists => { type => 'check_list', refer_to => '- my_hash + - my_hash2 + - my_hash3' }, ``` - • A check list where the available choices are the specified choice and the choice of `"refer_to_3_lists"` and a hash whose name is specified by the value of the `"indirection"` configuration parameter (this example is admittedly convoluted): ``` refer_to_check_list_and_choice => { type => 'check_list', computed_refer_to => { formula => '- refer_to_2_list + - $var', variables => { var => '- indirection ' } }, choice => [qw/A1 A2 A3/], }, ``` ## Methods ### get\_type Returns `"check_list"`. ### cargo\_type Returns 'leaf'. ### check Set choice. Parameter is either a list of choices to set or a list ref and some optional parameter. I.e: ``` check (\@list, check => 'skip') ; ``` `"check"` parameter decide on behavior in case of invalid choice value: either die (if yes) or discard bad value (if skip) ### uncheck Unset choice. Parameter is either a list of choices to unset or a list ref and some optional parameter. I.e: ``` uncheck (\@list, check => 'skip') ; ``` `"check"` parameter decide on behavior in case of invalid choice value: either die (if yes) or discard bad value (if skip) ### is\_checked Parameters: `"( choice, [ check => yes|skip ] , [ mode => ... ])"` Return 1 if the given `"choice"` was set. Returns 0 otherwise. `"check"` parameter decide on behavior in case of invalid choice value: either die (if yes) or discard bad value (if skip) `"mode"` is either: custom standard preset default layered upstream\_default ### has\_data Return true if the check\_list contains a set of checks different from default or upstream default set of check. ### get\_choice Returns an array of all items names that can be checked (i.e. that can have value 0 or 1). ### get\_help Parameters: `"(choice_value)"` Return the help string on this choice value ### get\_info Returns a list of information related to the check list. See "get\_info" in Config::Model::Value for more details. ### clear Reset the check list (can also be called as `"clear_values"`) ### clear\_item Parameters: `"(choice_value)"` Reset an element of the checklist. ### get\_checked\_list\_as\_hash Accept a parameter (referred below as `"mode"` parameter) similar to `"mode"` in "fetch" in Config::Model::Value. Returns a hash (or a hash ref) of all items. The boolean value is the value of the hash. Example: ``` { A => 0, B => 1, C => 0 , D => 1} ``` By default, this method returns all items set by the user, or items set in preset mode or checked by default. With a `"mode"` parameter set to a value from the list below, this method returns: - backend The value written in config file, (ie. set by user or by layered data or preset or default) - custom The list entered by the user. An empty list is returned if the list of checked items is identical to the list of items checked by default. The whole list of checked items is returned as soon as **one** item is different from standard value. - preset The list entered in preset mode - standard The list set in preset mode or checked by default. - default The default list (defined by the configuration model) - layered The list specified in layered mode. - upstream\_default The list implemented by upstream project (defined in the configuration model) - user The set that is active in the application. (ie. set by user or by layered data or preset or default or upstream\_default) - non\_upstream\_default The choice set by user or by layered data or preset or default. ### get\_checked\_list Parameters: `"( < mode > )"` Returns a list (or a list ref) of all checked items (i.e. all items set to 1). ### fetch Parameters: `"( < mode > )"` Returns a string listing the checked items (i.e. "A,B,C") ### get Parameters: `"( path [, < mode> ] )"` Get a value from a directory like path. ## Method to check or clear items in the check list All these methods accept an optional `"check"` parameter that can be: - yes A wrong item to check trigger an exception (default) - skip A wrong item trigger a warning - no A wrong item is ignored ### set Parameters: `"( path, items_to_set, [ check => [ yes | no | skip ] ] )"` Set a checklist with a directory like path. Since a checklist is a leaf, the path should be empty. The values are a comma separated list of items to set in the check list. Example : ``` $leaf->set('','A,C,Z'); $leaf->set('','A,C,Z', check => 'skip'); ``` ### set\_checked\_list Set all passed items to checked (1). All other available items in the check list are set to 0. Example, for a check list that contains A B C and D check items: ``` # set cl to A=0 B=1 C=0 D=1 $cl->set_checked_list('B','D') $cl->set_checked_list( [ 'B','D' ]) $cl->set_checked_list( [ 'B','D' ], check => 'yes') ``` ### store\_set Alias to "set\_checked\_list", so a list and a check\_list can use the same store method ### store Set all items listed in a string to checked. The items must be separated by commas. All other available items in the check list are set to 0. Example: ``` $cl->store('B, D') $cl->store( value => 'B,C' ) $cl->store( value => 'B,C', check => 'yes' ) ``` ### load Alias to "store". ### set\_checked\_list\_as\_hash Set check\_list items. Missing items in the given hash of parameters are cleared (i.e. set to undef). Example for a check list containing A B C D ``` $cl->set_checked_list_as_hash( { A => 1, B => 0} , check => 'yes' ) # result A => 1 B => 0 , C and D are undef ``` ### load\_data Load items as an array or hash ref. Array is forwarded to set\_checked\_list , and hash is forwarded to set\_checked\_list\_as\_hash. Example: ``` $cl->load_data(['A','B']) # cannot use check param here $cl->load_data( data => ['A','B']) $cl->load_data( data => ['A','B'], check => 'yes') $cl->load_data( { A => 1, B => 1 } ) $cl->load_data( data => { A => 1, B => 1 }, check => 'yes') ``` ### is\_bad\_mode Accept a mode parameter. This function checks if the mode is accepted by "fetch" method. Returns an error message if not. For instance: ``` if (my $err = $val->is_bad_mode('foo')) { croak "my_function: $err"; } ``` This method is intented as a helper ti avoid duplicating the list of accepted modes for functions that want to wrap fetch methods (like Config::Model::Dumper or Config::Model::DumpAsData) ## Ordered checklist methods All the methods below are valid only for ordered checklists. ### swap Parameters: `"( choice_a, choice_b)"` Swap the 2 given choice in the list. Both choice must be already set. ### move\_up Parameters: `"( choice )"` Move the choice up in the checklist. ### move\_down Parameters: `"( choice )"` Move the choice down in the checklist. ## AUTHOR Dominique Dumont, (ddumont at cpan dot org) ## SEE ALSO Config::Model, Config::Model::Instance, Config::Model::Node, Config::Model::AnyId, Config::Model::ListId, Config::Model::HashId, Config::Model::Value ## AUTHOR Dominique Dumont ## COPYRIGHT AND LICENSE This software is Copyright (c) 2005-2022 by Dominique Dumont. This is free software, licensed under: ``` The GNU Lesser General Public License, Version 2.1, February 1999 ```