Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Config::Model::CheckLiUser)Contributed Perl DocumenConfig::Model::CheckList(3)

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

VERSION
       version 2.140

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 :

       o   A fixed list	(with the "choice" parameter)

       o   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:

       o   A check list	with help:

	    choice_list	=> {
		type   => 'check_list',
		choice => ['A' .. 'Z'],
		help   => { A => 'A help', E =>	'E help' } ,
	    },

       o   A check list	with default values:

	    choice_list_with_default =>	{
		type =>	'check_list',
		choice	   => ['A' .. 'Z'],
		default_list   => [ 'A', 'D' ],
	    },

       o   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:

       o   The keys of a hash

       o   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
       o   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'
	    },

       o   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'
	    },

       o   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'
	    },

       o   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-2020	by Dominique Dumont.

       This is free software, licensed under:

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

perl v5.32.0			  2020-08-28	   Config::Model::CheckList(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | CONSTRUCTOR | CheckList model declaration | Introspection methods | Choice reference | Methods | Method to check or clear items in the check list | Ordered checklist methods | AUTHOR | SEE ALSO | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Config::Model::CheckList&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help