.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Config::Model::CheckList 3pm"
.TH Config::Model::CheckList 3pm "2023-08-19" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Config::Model::CheckList \- Handle check list element
.SH "VERSION"
.IX Header "VERSION"
version 2.153
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& 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   => \*(Aqcheck_list\*(Aq,
\&            choice => [ \*(AqA\*(Aq, \*(AqB\*(Aq, \*(AqC\*(Aq, \*(AqD\*(Aq ],
\&            help   => {
\&                A => \*(AqA effect is this\*(Aq,
\&                D => \*(AqD does that\*(Aq,
\&            }
\&        },
\&    ],
\& );
\&
\& my $inst = $model\->instance( root_class_name => \*(AqMyClass\*(Aq );
\&
\& my $root = $inst\->config_root;
\&
\& # put data
\& $root\->load( steps => \*(Aqmy_check_list=A\*(Aq );
\&
\& my $obj = $root\->grab(\*(Aqmy_check_list\*(Aq);
\&
\& my $v = $root\->grab_value(\*(Aqmy_check_list\*(Aq);
\& print "check_list value \*(Aq$v\*(Aq with help \*(Aq", $obj\->get_help($v), "\*(Aq\en";
\&
\& # more data
\& $obj\->check(\*(AqD\*(Aq);
\& $v = $root\->grab_value(\*(Aqmy_check_list\*(Aq);
\& print "check_list new value is \*(Aq$v\*(Aq\en";   # prints check_list new value is \*(AqA,D\*(Aq
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.PP
The available items in the check list can be :
.IP "\(bu" 4
A fixed list (with the \f(CW\*(C`choice\*(C'\fR parameter)
.IP "\(bu" 4
A dynamic list where the available choice are the keys of another hash
of the configuration tree. See \*(L"Choice reference\*(R" for details.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
CheckList object should not be created directly.
.SH "CheckList model declaration"
.IX Header "CheckList model declaration"
A check list element must be declared with the following parameters:
.IP "type" 4
.IX Item "type"
Always \f(CW\*(C`checklist\*(C'\fR.
.IP "choice" 4
.IX Item "choice"
A list ref containing the check list items (optional)
.IP "refer_to" 4
.IX Item "refer_to"
This parameter is used when the keys of a hash are used to specify the
possible choices of the check list. \f(CW\*(C`refer_to\*(C'\fR point to a hash or list
element in the configuration tree. See \*(L"Choice reference\*(R" for
details. (optional)
.IP "computed_refer_to" 4
.IX Item "computed_refer_to"
Like \f(CW\*(C`refer_to\*(C'\fR, but use a computed value to find the hash or list
element in the configuration tree. See \*(L"Choice reference\*(R" for
details. (optional)
.IP "default_list" 4
.IX Item "default_list"
List ref to specify the check list items which are \*(L"on\*(R" by default.
(optional)
.IP "ordered" 4
.IX Item "ordered"
Specify whether the order of checked items must be preserved.
.IP "help" 4
.IX Item "help"
Hash ref to provide information on the check list items.
.IP "warp" 4
.IX Item "warp"
Used to provide dynamic modifications of the check list properties
See Config::Model::Warper for details
.PP
For example:
.IP "\(bu" 4
A check list with help:
.Sp
.Vb 5
\& choice_list => {
\&     type   => \*(Aqcheck_list\*(Aq,
\&     choice => [\*(AqA\*(Aq .. \*(AqZ\*(Aq],
\&     help   => { A => \*(AqA help\*(Aq, E => \*(AqE help\*(Aq } ,
\& },
.Ve
.IP "\(bu" 4
A check list with default values:
.Sp
.Vb 5
\& choice_list_with_default => {
\&     type => \*(Aqcheck_list\*(Aq,
\&     choice     => [\*(AqA\*(Aq .. \*(AqZ\*(Aq],
\&     default_list   => [ \*(AqA\*(Aq, \*(AqD\*(Aq ],
\& },
.Ve
.IP "\(bu" 4
A check list whose available choice and default change depending on
the value of the \f(CW\*(C`macro\*(C'\fR parameter:
.Sp
.Vb 10
\& warped_choice_list => {
\&     type => \*(Aqcheck_list\*(Aq,
\&     warp => {
\&         follow => \*(Aq\- macro\*(Aq,
\&         rules  => {
\&             AD => {
\&                 choice => [ \*(AqA\*(Aq .. \*(AqD\*(Aq ],
\&                 default_list => [\*(AqA\*(Aq, \*(AqB\*(Aq ]
\&             },
\&             AH => { choice => [ \*(AqA\*(Aq .. \*(AqH\*(Aq ] },
\&         }
\&     }
\& },
.Ve
.SH "Introspection methods"
.IX Header "Introspection methods"
The following methods returns the checklist parameter :
.IP "refer_to" 4
.IX Item "refer_to"
.PD 0
.IP "computed_refer_to" 4
.IX Item "computed_refer_to"
.PD
.SH "Choice reference"
.IX Header "Choice reference"
The choice items of a check_list can be given by another configuration
element. This other element can be:
.IP "\(bu" 4
The keys of a hash
.IP "\(bu" 4
Another checklist. In this case only the checked items of the other
checklist are available.
.PP
This other hash or other checklist is indicated by the \f(CW\*(C`refer_to\*(C'\fR or
\&\f(CW\*(C`computed_refer_to\*(C'\fR parameter. \f(CW\*(C`refer_to\*(C'\fR uses the syntax of the
\&\f(CW\*(C`steps\*(C'\fR parameter of grab(...)
.PP
See refer_to parameter.
.SS "Reference examples"
.IX Subsection "Reference examples"
.IP "\(bu" 4
A check list where the available choices are the keys of \f(CW\*(C`my_hash\*(C'\fR
configuration parameter:
.Sp
.Vb 4
\& refer_to_list => {
\&     type => \*(Aqcheck_list\*(Aq,
\&     refer_to => \*(Aq\- my_hash\*(Aq
\& },
.Ve
.IP "\(bu" 4
A check list where the available choices are the checked items of
\&\f(CW\*(C`other_check_list\*(C'\fR configuration parameter:
.Sp
.Vb 8
\& other_check_list => {
\&     type => \*(Aqcheck_list\*(Aq,
\&     choice => [qw/A B C/]
\& },
\& refer_to_list => {
\&     type => \*(Aqcheck_list\*(Aq,
\&     refer_to => \*(Aq\- other_check_list\*(Aq
\& },
.Ve
.IP "\(bu" 4
A check list where the available choices are the keys of \f(CW\*(C`my_hash\*(C'\fR
and \f(CW\*(C`my_hash2\*(C'\fR and \f(CW\*(C`my_hash3\*(C'\fR configuration parameter:
.Sp
.Vb 4
\& refer_to_3_lists => {
\&     type => \*(Aqcheck_list\*(Aq,
\&     refer_to => \*(Aq\- my_hash + \- my_hash2   + \- my_hash3\*(Aq
\& },
.Ve
.IP "\(bu" 4
A check list where the available choices are the specified choice and
the choice of \f(CW\*(C`refer_to_3_lists\*(C'\fR and a hash whose name is specified
by the value of the \f(CW\*(C`indirection\*(C'\fR configuration parameter (this
example is admittedly convoluted):
.Sp
.Vb 10
\& refer_to_check_list_and_choice => {
\&     type => \*(Aqcheck_list\*(Aq,
\&     computed_refer_to => {
\&         formula => \*(Aq\- refer_to_2_list + \- $var\*(Aq,
\&         variables => {
\&             var => \*(Aq\- indirection \*(Aq
\&         }
\&     },
\&     choice  => [qw/A1 A2 A3/],
\& },
.Ve
.SH "Methods"
.IX Header "Methods"
.SS "get_type"
.IX Subsection "get_type"
Returns \f(CW\*(C`check_list\*(C'\fR.
.SS "cargo_type"
.IX Subsection "cargo_type"
Returns 'leaf'.
.SS "check"
.IX Subsection "check"
Set choice. Parameter is either a list of choices to set or 
a list ref and some optional parameter. I.e:
.PP
.Vb 1
\&  check (\e@list, check => \*(Aqskip\*(Aq) ;
.Ve
.PP
\&\f(CW\*(C`check\*(C'\fR parameter decide on behavior in case of invalid
choice value: either die (if yes) or discard bad value (if skip)
.SS "uncheck"
.IX Subsection "uncheck"
Unset choice. Parameter is either a list of choices to unset or 
a list ref and some optional parameter. I.e:
.PP
.Vb 1
\&  uncheck (\e@list, check => \*(Aqskip\*(Aq) ;
.Ve
.PP
\&\f(CW\*(C`check\*(C'\fR parameter decide on behavior in case of invalid
choice value: either die (if yes) or discard bad value (if skip)
.SS "is_checked"
.IX Subsection "is_checked"
Parameters: \f(CW\*(C`( choice, [ check => yes|skip ] , [ mode => ... ])\*(C'\fR
.PP
Return 1 if the given \f(CW\*(C`choice\*(C'\fR was set. Returns 0 otherwise.
.PP
\&\f(CW\*(C`check\*(C'\fR parameter decide on behavior in case of invalid
choice value: either die (if yes) or discard bad value (if skip)
.PP
\&\f(CW\*(C`mode\*(C'\fR is either: custom standard preset default layered upstream_default
.SS "has_data"
.IX Subsection "has_data"
Return true if the check_list contains a set of checks different from default
or upstream default set of check.
.SS "get_choice"
.IX Subsection "get_choice"
Returns an array of all items names that can be checked (i.e.
that can have value 0 or 1).
.SS "get_help"
.IX Subsection "get_help"
Parameters: \f(CW\*(C`(choice_value)\*(C'\fR
.PP
Return the help string on this choice value
.SS "get_info"
.IX Subsection "get_info"
Returns a list of information related to the check list. See
\&\*(L"get_info\*(R" in Config::Model::Value for more details.
.SS "clear"
.IX Subsection "clear"
Reset the check list (can also be called as \f(CW\*(C`clear_values\*(C'\fR)
.SS "clear_item"
.IX Subsection "clear_item"
Parameters: \f(CW\*(C`(choice_value)\*(C'\fR
.PP
Reset an element of the checklist.
.SS "get_checked_list_as_hash"
.IX Subsection "get_checked_list_as_hash"
Accept a parameter (referred below as \f(CW\*(C`mode\*(C'\fR parameter) similar to
\&\f(CW\*(C`mode\*(C'\fR in \*(L"fetch\*(R" in Config::Model::Value.
.PP
Returns a hash (or a hash ref) of all items. The boolean value is the
value of the hash.
.PP
Example:
.PP
.Vb 1
\& { A => 0, B => 1, C => 0 , D => 1}
.Ve
.PP
By default, this method returns all items set by the user, or
items set in preset mode or checked by default.
.PP
With a \f(CW\*(C`mode\*(C'\fR parameter set to a value from the list below, this method
returns:
.IP "backend" 4
.IX Item "backend"
The value written in config file, (ie. set by user or by layered data
or preset or default)
.IP "custom" 4
.IX Item "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 \fBone\fR item is different
from standard value.
.IP "preset" 4
.IX Item "preset"
The list entered in preset mode
.IP "standard" 4
.IX Item "standard"
The list set in preset mode or checked by default.
.IP "default" 4
.IX Item "default"
The default list (defined by the configuration model)
.IP "layered" 4
.IX Item "layered"
The list specified in layered mode.
.IP "upstream_default" 4
.IX Item "upstream_default"
The list implemented by upstream project (defined in the configuration
model)
.IP "user" 4
.IX Item "user"
The set that is active in the application. (ie. set by user or
by layered data or preset or default or upstream_default)
.IP "non_upstream_default" 4
.IX Item "non_upstream_default"
The choice set by user or by layered data or preset or default.
.SS "get_checked_list"
.IX Subsection "get_checked_list"
Parameters: \f(CW\*(C`( < mode > )\*(C'\fR
.PP
Returns a list (or a list ref) of all checked items (i.e. all items
set to 1).
.SS "fetch"
.IX Subsection "fetch"
Parameters: \f(CW\*(C`( < mode > )\*(C'\fR
.PP
Returns a string listing the checked items (i.e. \*(L"A,B,C\*(R")
.SS "get"
.IX Subsection "get"
Parameters: \f(CW\*(C`( path  [, < mode> ] )\*(C'\fR
.PP
Get a value from a directory like path.
.SH "Method to check or clear items in the check list"
.IX Header "Method to check or clear items in the check list"
All these methods accept an optional \f(CW\*(C`check\*(C'\fR parameter that can be:
.IP "yes" 4
.IX Item "yes"
A wrong item to check trigger an exception (default)
.IP "skip" 4
.IX Item "skip"
A wrong item trigger a warning
.IP "no" 4
.IX Item "no"
A wrong item is ignored
.SS "set"
.IX Subsection "set"
Parameters: \f(CW\*(C`( path, items_to_set, [ check => [ yes | no | skip  ] ] )\*(C'\fR
.PP
Set a checklist with a directory like path. Since a checklist is a leaf, the path
should be empty.
.PP
The values are a comma separated list of items to set in the check list.
.PP
Example :
.PP
.Vb 2
\&  $leaf\->set(\*(Aq\*(Aq,\*(AqA,C,Z\*(Aq);
\&  $leaf\->set(\*(Aq\*(Aq,\*(AqA,C,Z\*(Aq, check => \*(Aqskip\*(Aq);
.Ve
.SS "set_checked_list"
.IX Subsection "set_checked_list"
Set all passed items to checked (1). All other available items
in the check list are set to 0.
.PP
Example, for a check list that contains A B C and D check items:
.PP
.Vb 4
\&  # set cl to A=0 B=1 C=0 D=1
\&  $cl\->set_checked_list(\*(AqB\*(Aq,\*(AqD\*(Aq)
\&  $cl\->set_checked_list( [ \*(AqB\*(Aq,\*(AqD\*(Aq ])
\&  $cl\->set_checked_list( [ \*(AqB\*(Aq,\*(AqD\*(Aq ], check => \*(Aqyes\*(Aq)
.Ve
.SS "store_set"
.IX Subsection "store_set"
Alias to \*(L"set_checked_list\*(R", so a list and a check_list can use the same store method
.SS "store"
.IX Subsection "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.
.PP
Example:
.PP
.Vb 3
\&  $cl\->store(\*(AqB, D\*(Aq)
\&  $cl\->store( value => \*(AqB,C\*(Aq )
\&  $cl\->store( value => \*(AqB,C\*(Aq, check => \*(Aqyes\*(Aq )
.Ve
.SS "load"
.IX Subsection "load"
Alias to \*(L"store\*(R".
.SS "set_checked_list_as_hash"
.IX Subsection "set_checked_list_as_hash"
Set check_list items. Missing items in the given hash of parameters
are cleared (i.e. set to undef).
.PP
Example for a check list containing A B C D
.PP
.Vb 2
\&  $cl\->set_checked_list_as_hash( { A => 1, B => 0} , check => \*(Aqyes\*(Aq )
\&  # result A => 1 B => 0 , C and D are undef
.Ve
.SS "load_data"
.IX Subsection "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.
.PP
Example:
.PP
.Vb 5
\& $cl\->load_data([\*(AqA\*(Aq,\*(AqB\*(Aq]) # cannot use check param here
\& $cl\->load_data( data => [\*(AqA\*(Aq,\*(AqB\*(Aq])
\& $cl\->load_data( data => [\*(AqA\*(Aq,\*(AqB\*(Aq], check => \*(Aqyes\*(Aq)
\& $cl\->load_data( { A => 1, B => 1 } )
\& $cl\->load_data( data => { A => 1, B => 1 }, check => \*(Aqyes\*(Aq)
.Ve
.SS "is_bad_mode"
.IX Subsection "is_bad_mode"
Accept a mode parameter. This function checks if the mode is accepted
by \*(L"fetch\*(R" method. Returns an error message if not. For instance:
.PP
.Vb 3
\& if (my $err = $val\->is_bad_mode(\*(Aqfoo\*(Aq)) {
\&    croak "my_function: $err";
\& }
.Ve
.PP
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)
.SH "Ordered checklist methods"
.IX Header "Ordered checklist methods"
All the methods below are valid only for ordered checklists.
.SS "swap"
.IX Subsection "swap"
Parameters: \f(CW\*(C`( choice_a, choice_b)\*(C'\fR
.PP
Swap the 2 given choice in the list. Both choice must be already set.
.SS "move_up"
.IX Subsection "move_up"
Parameters: \f(CW\*(C`( choice )\*(C'\fR
.PP
Move the choice up in the checklist.
.SS "move_down"
.IX Subsection "move_down"
Parameters: \f(CW\*(C`( choice )\*(C'\fR
.PP
Move the choice down in the checklist.
.SH "AUTHOR"
.IX Header "AUTHOR"
Dominique Dumont, (ddumont at cpan dot org)
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Config::Model,
Config::Model::Instance,
Config::Model::Node,
Config::Model::AnyId,
Config::Model::ListId,
Config::Model::HashId,
Config::Model::Value
.SH "AUTHOR"
.IX Header "AUTHOR"
Dominique Dumont
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is Copyright (c) 2005\-2022 by Dominique Dumont.
.PP
This is free software, licensed under:
.PP
.Vb 1
\&  The GNU Lesser General Public License, Version 2.1, February 1999
.Ve