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

FreeBSD Manual Pages


home | help
Config::Model::AnyId(3User Contributed Perl DocumentatiConfig::Model::AnyId(3)

       Config::Model::AnyId - Base class for hash or list element

       version 2.140

	use Config::Model;

	# define configuration tree object
	my $model = Config::Model->new;
	   name	   => "Foo",
	   element => [
	       [qw/foo bar/] =>	{
		   type	      => 'leaf',
		   value_type => 'string'

	   name	   => "MyClass",
	   element => [
	       plain_hash => {
		   type	      => 'hash',
		   index_type => 'string',
		   cargo      => {
		       type	  => 'leaf',
		       value_type => 'string',
	       bounded_hash => {
		   type	      => 'hash',      #	hash id
		   index_type => 'integer',

		   # hash boundaries
		   min_index =>	1, max_index =>	123, max_nb => 2,

		   # specify cargo held	by hash
		   cargo => {
		       type	  => 'leaf',
		       value_type => 'string'
	       bounded_list => {
		   type	=> 'list',    #	list id

		   max_index =>	123,
		   cargo     =>	{
		       type	  => 'leaf',
		       value_type => 'string'
	       hash_of_nodes =>	{
		   type	      => 'hash',     # hash id
		   index_type => 'string',
		   cargo      => {
		       type		 => 'node',
		       config_class_name => 'Foo'

	my $inst = $model->instance( root_class_name =>	'MyClass' );

	my $root = $inst->config_root;

	# put data
	my $steps = 'plain_hash:foo=boo	bounded_list=foo,bar,baz
	  bounded_hash:3=foo bounded_hash:30=baz
	  hash_of_nodes:"foo node" foo="in foo node" -
	  hash_of_nodes:"bar node" bar="in bar node" ';
	$root->load( steps => $steps );

	# dump resulting tree
	print $root->dump_tree;

       This class provides hash	or list	elements for a Config::Model::Node.

       The hash	index can either be en enumerated type,	a boolean, an integer
       or a string.

       AnyId object should not be created directly.

Hash or	list model declaration
       A hash or list element must be declared with the	following parameters:

	   Mandatory element type. Must	be "hash" or "list" to have a
	   collection element.	The actual element type	must be	specified by
	   "cargo => type".

	   Either "integer" or "string". Mandatory for hash.

	   Whether to keep the order of	the hash keys (default no). (a bit
	   like	Tie::IxHash).  The hash	keys are ordered along their creation.
	   The order can be modified with swap,	move_up	or move_down.

	   Specify the policy regarding	duplicated values stored in the	list
	   or as hash values (valid only when cargo type is "leaf"). The
	   policy can be "allow" (default), "suppress",	"warn" (which offers
	   the possibility to apply a fix), "forbid". Note that	duplicates
	   check cannot	be performed when the duplicated value is stored: this
	   happens outside of this object. Duplicates can be check only	after
	   when	the value is read.

	   By default, hash entries without data are not saved in
	   configuration files.	Without	data means the cargo of	the hash key
	   is empty: either its	value is undef or all the values of the
	   contained node are also empty.

	   Set this parameter to 1 if the key must be saved in the
	   configuration file even if the hash contains	no value for that key.

	   Note	that writing hash entries without value	may not	be supported
	   by all backends. Use	with care. Supported only for hash elements.

	   Hash	ref specifying the cargo held by the hash of list. This	has
	   must	contain:

	   type	   Can be "node" or "leaf" (default).

		   Specifies the type of configuration object held in the
		   hash. Only valid when "cargo" "type"	is "node".

	   <other> Constructor arguments passed	to the cargo object. See
		   Config::Model::Node when "cargo->type" is "node". See
		   Config::Model::Value	when "cargo->type" is "leaf".

	   Specify the minimum value (optional,	only for hash and for integer

	   Specify the maximum value (optional,	only for list or for hash with
	   integer index)

	   Specify the maximum number of indexes. (hash	only, optional,	may
	   also	be used	with string index type)

	   When	set, the default parameter (or set of parameters) are used as
	   default keys	hashes and created automatically when the "keys" or
	   "exists" functions are used on an empty hash.

	   You can use "default_keys =>	'foo'",	or "default_keys => ['foo',

	   To perform special set-up on	children nodes you can also use

	      default_with_init	=>  {
		 foo =>	'X=Av Y=Bv',
		 bar =>	'Y=Av Z=Cv'

	   When	the hash contains leaves, you can also use:

	      default_with_init	=> {
		  def_1	=> 'def_1 stuff',
		  def_2	=> 'def_2 stuff'

	   Specifies that the keys of the hash are copied from another hash in
	   the configuration tree only when the	hash is	read for the first
	   time	after initial load (i.e. once the configuration	files are
	   completely read).

	      migrate_keys_from	=> '- another_hash'

	   Specifies that the values of	the hash (or list) are copied from
	   another hash	(or list) in the configuration tree only when the hash
	   (or list) is	read for the first time	after initial load (i.e. once
	   the configuration files are completely read).

	      migrate_values_from => '-	another_hash_or_list'

	   Specifies that the keys of the hash follow the keys of another hash
	   in the configuration	tree. In other words, the created hash always
	   has the same	keys as	the other hash.

	      follow_keys_from => '- another_hash'

	   Specifies authorized	keys:

	     allow_keys	=> ['foo','bar','baz']

	   A bit like the "follow_keys_from" parameters. Except	that the hash
	   pointed to by "allow_keys_from" specified the authorized keys for
	   this	hash.

	     allow_keys_from =>	'- another_hash'

	   Keys	must match the specified regular expression. For instance:

	     allow_keys_matching => '^foo\d\d$'

	   When	set, the default parameter (or set of parameters) are used as
	   keys	hashes and created automatically. (valid only for hash

	   Called with "auto_create_keys => ['foo']", or "auto_create_keys =>
	   ['foo', 'bar']".

	   Issue a warning if the key matches the specified regular expression

	   Issue a warning unless the key matches the specified	regular

	   Specifies the number	of elements to create automatically. E.g.
	   "auto_create_ids => 4" initializes the list with 4 undef elements.
	   (valid only for list	elements)

       convert => [uc |	lc ]
	   The hash key	are converted to uppercase (uc)	or lowercase (lc).

	   See "Warp: dynamic value configuration" below.

Warp: dynamic value configuration
       The Warp	functionality enables an HashId	or ListId object to change its
       default settings	(e.g. "min_index", "max_index" or "max_nb" parameters)
       dynamically according to	the value of another "Value" object. (See
       Config::Model::Warper for explanation on	warp mechanism)

       For instance, with this model:

	$model ->create_config_class
	  name => 'Root',
	  => [
	      macro => { type => 'leaf',
			 value_type => 'enum',
			 name	    => 'macro',
			 choice	    => [qw/A B C/],
	      warped_hash => { type => 'hash',
			       index_type => 'integer',
			       max_nb	  => 3,
			       warp	  => {
					      follow =>	'- macro',
					      rules => { A => {	max_nb => 1 },
							 B => {	max_nb => 2 }
			       cargo =>	{ type => 'node',
					  config_class_name => 'Dummy'

       Setting "macro" to "A" means that "warped_hash" can only	accept one
       "Dummy" class item .

       Setting "macro" to "B" means that "warped_hash" accepts two "Dummy"
       class items.

       Like other warped class,	a HashId or ListId can have multiple warp
       masters (See "Warp follow argument" in Config::Model::Warper:

	 warp => { follow => { m1 => '-	macro1',
			       m2 => '-	macro2'
		   rules  => [ '$m1 eq "A" and $m2 eq "A2"' => { max_nb	=> 1},
			       '$m1 eq "A" and $m2 eq "B2"' => { max_nb	=> 2}

   Warp	and auto_create_ids or auto_create_keys
       When a warp is applied with "auto_create_keys" or "auto_create_ids"
       parameter, the auto_created items are created if	they are not already
       present.	But this warp never removes items that were previously auto

       For instance, when a tied hash is created with "auto_create =>
       [a,b,c]", the hash contains "(a,b,c)".

       Then, once a warp with "auto_create_keys	=> [c,d,e]" is applied,	the
       hash then contains "(a,b,c,d,e)". The items created by the first
       auto_create_keys	are not	removed.

   Warp	and max_nb
       When a warp is applied, the items that do not fit the constraint	(e.g.
       min_index, max_index) are removed.

       For the max_nb constraint, an exception is raised if a warp leads to a
       number of items greater than the	max_nb constraint.

Content	check
       By default, this	class provides an optional content check that checks
       for duplicated values (when "duplicates"	parameter is set).

       Derived classes can register more global	checker	with the following

       This method expects a sub ref with signature "( $self, $error, $warn,
       $apply_fix )".  Where $error and	$warn are array	ref. You can push
       error or	warning	messages there.	 $apply_fix is a boolean. When set to
       1, the passed method can	fix the	warning	or the error. Please make sure
       to weaken $self to avoid	memory cycles.


	package	MyId;
	use Mouse;
	extends	qw/Config::Model::HashId/;
	use Scalar::Util qw/weaken/;

	sub setup {
	   my $self = shift;
	   $self-> add_check_content( sub { $self->check_usused_licenses(@_);} )

Introspection methods
       The following methods returns the current value stored in the Id	object
       (as declared in the model unless	they were warped):


       Returns the object type contained by the	hash or	list (i.e. returns
       "cargo -> type").

       Parameters: "( <	what > )"

       Returns more info on the	cargo contained	by the hash or list. "what"
       may be "value_type" or any other	cargo info stored in the model.
       Returns undef if	the requested info is not provided in the model.

       Returns a list (or a list ref) of the current default keys. These keys
       can be set by the "default_keys"	or "default_with_init" parameters or
       by the other hash pointed by "follow_keys_from" parameter.

       Returns the object name.	The name finishes with ' id'.

       Returns the config_class_name of	collected elements. Valid only for
       collection of nodes.

       This method returns undef if "cargo" "type" is not "node".

       Returns the number of fixes that	can be applied to the current value.

Information management
       Parameters: "( index => $idx , [	check => 'no' ])"

       Fetch the collected element held	by the hash or list. Index check is
       'yes' by	default.  Can be called	with one parameter which is used as

       Get a value from	a directory like path. Parameters are:

	   Poor	man's version of XPath style path. This	string is in the form:


	   Each	word between the '/' is	either an element name or a hash key
	   or a	list index.

	   Either "default", "custom", "user",...  See "mode" parameter	in
	   <Config::Model::Value/"fetch( ... )">

	   Either "skip", "no"

	   If the path leads to	a leaf,	this parameter tell whether to return
	   the stored value or the value object.

	   Whether to create missing keys

	   When	the hash key used contains '/',	(for instance a	directory
	   value), the key cannot be used as is	with this method. Because '/'
	   is already used to separate configuration items (this is also
	   important with Config::Model::FuseUI). This parameter specifies how
	   the forbidden '/' char is shown in the path.	Default	is "<slash>"

       Parameters: "( path, value )"

       Set a value with	a directory like path.

       Parameters: "( from_index, to_index )"

       Deep copy an element within the hash or list. If	the element contained
       by the hash or list is a	node, all configuration	information is copied
       from one	node to	another.

       Returns an array	containing all elements	held by	the hash or list.

       Parameters: "( idx => ..., mode => ..., check =>	...)"

       Returns the value held by the "idx" element of the hash or list.	This
       method is only valid for	hash or	list containing	leaves.

       See fetch_all_values for	"mode" argument	documentation and "fetch" in
       Config::Model::Value for	"check"	argument documentation.

       Arguments: "( idx => ..., mode => ..., check => ...)"

       Like "fetch_value", but returns a truncated value when the value	is a
       string or uniline that is too long to be	displayed.

       Parameters: "( mode => ..., check => ...)"

       Returns an array	containing all defined values held by the hash or
       list. (undefined	values are simply discarded). This method is only
       valid for hash or list containing leaves.

       With "mode" parameter, this method returns either:

	   The value entered by	the user

	   The value entered in	preset mode

	   The value entered in	preset mode or checked by default.

	   The default value (defined by the configuration model)

       See "fetch" in Config::Model::Value for "check" argument	documentation.

       Similar to "fetch_all_values", with the same parameters,	Returns	the
       result as a string with comma separated list values.

       Returns an array	containing all indexes of the hash or list. Hash keys
       are sorted alphabetically, except for ordered hashed.

       Like fetch_all_indexes. This method is polymorphic for all non-leaf
       objects of the configuration tree.

       Parameters: "( index )"

       Returns true if the value held at "index" is defined.

       Parameters: "( index )"

       Returns true if the value held at "index" exists	(i.e the key exists
       but the value may be undefined).	This method may	not make sense for
       list element.

       Return true if the array	or hash	is not empty.

       Parameters: "( index )"

       Delete the "index"ed value

       Delete all values (also delete underlying value or node objects).

       Delete all values (without deleting underlying value objects).

       Parameters: "( [index] )"

       Returns warnings	concerning indexes of this hash.  Without parameter,
       returns a string	containing all warnings	or undef. With an index,
       return the warnings concerning this index or undef.

       Returns the current number of warning.

       Returns the error messages of this object (if any)

       Dominique Dumont, ddumont [AT] cpan [DOT] org

       Config::Model, Config::Model::Instance, Config::Model::Node,
       Config::Model::WarpedNode, Config::Model::HashId,
       Config::Model::ListId, Config::Model::CheckList,	Config::Model::Value

       Dominique Dumont

       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::AnyId(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | CONSTRUCTOR | Hash or list model declaration | Warp: dynamic value configuration | Content check | Introspection methods | Information management | AUTHOR | SEE ALSO | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:

home | help