Config...ckList(3pm)

💖 Config::Model::CheckList 💖

User Contributed Perl Documentation · this is the manual page for Config::Model::CheckList(3pm), bestie, and we're about to make check lists make sense 💅

---

🌸 NAME 🌸

Config::Model::CheckList — handle check list element ✨

🔢 VERSION 🔢

version 2.166 🫶

🧚 SYNOPSIS 🧚

okay so first, the vibe-setting demo 🎀:

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'

like, look at that last comment — it literally prints check_list new value is 'A,D'. slay 🔥

🦋 DESCRIPTION 🦋

So this class hands you a check list element for a Config::Model::Node. In other words (and ngl this is the whole point): it gives you a list of booleans items. Every single item can be set to 1 or 0. periodt 💅

The available items in the check list can be one of these two things:

• A fixed list (with the choice parameter) — classic, immovable, iconic 👑
• A dynamic list where the available choice are the keys of another hash of the configuration tree. See "Choice reference" for details 🌈

✨ CONSTRUCTOR ✨

Bestie. Do not create a CheckList object directly, okay? The page says: CheckList object should not be created directly. Let Config::Model handle that for you, no cap 🙈

🎀 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, here are the three little showcase snippets:

• 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 (it's giving ✨shape-shifter✨):

warped_choice_list => {
    type => 'check_list',
    warp => {
        follow => { m => '- macro'},
        rules  => [
         {
            when => '$m eq "AD"',
            apply => {
                choice => [ 'A' .. 'D' ],
                default_list => ['A', 'B' ]
            },
         },
         {
            when => '$m eq "AH"',
            apply => { 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 (the page itself says this example is admittedly convoluted, and honestly? respect for the honesty 😭):

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

Okay bestie, listen up — all of these methods take an optional check parameter, and here's what it can be 👇

• yes — a wrong item to check triggers an exception (this is the default, so if you say nothing, you get the drama 💀)
• skip — a wrong item triggers a warning instead
• no — a wrong item is just... ignored, we move on, no thoughts 🫶

---

✨ set

Parameters: ( path, items_to_set, [ check => [ yes | no | skip ] ] )

Sets a checklist with a directory-like path. Spoiler alert: since a checklist is a leaf, the path should just be empty. It's giving "no path, only vibes" ✨

The values you pass 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

Sets all the passed items to checked (1). Every other available item in the check list gets set to 0. Periodt.

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

An alias to set_checked_list — that way a list and a check_list can share the same store method and nobody has to feel left out 🫶

✨ store

Sets all items listed in a string to checked. The items must be separated by commas. Every other available item in the check list gets set to 0.

Example:

$cl->store('B, D')
$cl->store( value => 'B,C' )
$cl->store( value => 'B,C', check => 'yes' )

✨ load

An alias to store. Same energy, different name 💅

✨ set_checked_list_as_hash

Sets check_list items. Any missing items in the hash of parameters you hand over get cleared — that means set to undef. So if you forget someone, they're gone. Not me being dramatic, that's just the rule 😭

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

Loads items as an array or a hash ref. An array gets forwarded to set_checked_list, and a hash gets forwarded to set_checked_list_as_hash. iykyk 🌈

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

Takes a mode parameter. This function checks whether the mode is accepted by the fetch method, and returns an error message if it isn't. For instance:

if (my $err = $val->is_bad_mode('foo')) {
   croak "my_function: $err";
}

This method is meant as a little helper so you don't have to duplicate the list of accepted modes for functions that want to wrap fetch methods (like Config::Model::Dumper or Config::Model::DumpAsData). Efficiency, bestie 💅

---

🎀 Ordered checklist methods

Heads up: everything below is valid only for ordered checklists. No ordered list, no service 🚫

🌟 swap

Parameters: ( choice_a, choice_b)

Swaps the 2 given choice in the list. Both choice must already be set, or it's not happening.

🌟 move_up

Parameters: ( choice )

Moves the choice up in the checklist. Main character rising ⬆️

🌟 move_down

Parameters: ( choice )

Moves the choice down in the checklist. Sometimes you gotta humble yourself ⬇️

---

👑 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

---

And that's a wrap, bestie 🎀✨ This page came from perl v5.42.3 and it's dated 2026-07-23 — go forth and check those lists, you absolute icon 💖🦋