NAME¶
Config::Model::CheckList - Handle check list element
VERSION¶
version 2.021
SYNOPSIS¶
use Config::Model;
use Log::Log4perl qw(:easy);
Log::Log4perl->easy_init($WARN);
# define configuration tree object
my $model = Config::Model->new;
$model->create_config_class(
name => "MyClass",
element => [
# type check_list will use 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( step => '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::WarpedThing for details
For example:
- •
- A simple 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 will be 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 "step" 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( 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
get_choice¶
Returns an array of all items names that can be checked (i.e. that can have
value 0 or 1).
get_help (choice_value)¶
Return the help string on this choice value
clear¶
Reset the check list (all items are set to 0) (can also be called as
"clear_values")
get_checked_list_as_hash ( [ custom | preset | standard | default
] )¶
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 will return all items set by the user, or items set in
preset mode or checked by default.
With a parameter, this method will return either:
- custom
- The list entered by the user
- 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)
get_checked_list ( < mode > )¶
Returns a list (or a list ref) of all checked items (i.e. all items set to 1).
fetch ( < mode > )¶
Returns a string listing the checked items (i.e. "A,B,C")
get( path [, < mode> ] )¶
Get a value from a directory like path.
set( path , values )¶
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 checked items.
Example : "$leaf->set('','A,C,Z') ;"
set_checked_list ( item1, item2, ..)¶
Set all passed items to checked (1). All other available items in the check list
are set to 0.
Example:
# set cl to A=0 B=1 C=0 D=1
$cl->set_checked_list('B','D')
set_checked_list_as_hash ( A => 1, B => 1 )¶
Set check_list items. Missing items in the given list of parameters are set to
0.
The example ( A => 1, B => 1 ) above will give :
A = 1 , B = 1, C = 0 , D = 0
load_data ( list_ref )¶
Load check_list as an array ref. Data is simply forwarded to set_checked_list.
Ordered checklist methods¶
All the methods below are valid only for ordered checklists.
swap ( choice_a, choice_b)¶
Swap the 2 given choice in the list. Both choice must be already set.
move_up ( choice )¶
Move the choice up in the checklist.
move_down ( 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
