Provided by: libconfig-model-perl_2.047-1_all bug

NAME

       Config::Model::CheckList - Handle check list element

VERSION

       version 2.047

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::Warper 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 (can also be called as "clear_values")

   clear_item (choice_value)
       Reset an element of the checklist.

   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)

       user
           The list set that will be active in the application. (ie. set by user or by layered
           data or preset or default)

   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 ()
       Set check_list items. Missing items in the given list of parameters are cleared (i.e. set
       to undef).

   load_data ( ref )
       Load check_list as an array or hash ref. Array is forwarded to set_checked_list , and hash
       is forwarded to set_checked_list_as_hash.

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

AUTHOR

       Dominique Dumont

COPYRIGHT AND LICENSE

       This software is Copyright (c) 2013 by Dominique Dumont.

       This is free software, licensed under:

         The GNU Lesser General Public License, Version 2.1, February 1999