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

FreeBSD Manual Pages

  
 
  

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

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

VERSION
       version 2.140

SYNOPSIS
	use Config::Model;

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

	$model->create_config_class(
	   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;

DESCRIPTION
       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.

CONSTRUCTOR
       AnyId object should not be created directly.

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

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

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

       ordered
	   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.

       duplicates
	   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.

       write_empty_value
	   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.

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

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

	   config_class_name
		   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".

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

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

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

       default_keys
	   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',
	   'bar']".

       default_with_init
	   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'
	      }

       migrate_keys_from
	   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'

       migrate_values_from
	   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'

       follow_keys_from
	   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'

       allow_keys
	   Specifies authorized	keys:

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

       allow_keys_from
	   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'

       allow_keys_matching
	   Keys	must match the specified regular expression. For instance:

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

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

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

       warn_if_key_match
	   Issue a warning if the key matches the specified regular expression

       warn_unless_key_match
	   Issue a warning unless the key matches the specified	regular
	   expression

       auto_create_ids
	   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).

       warp
	   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',
	  'element'
	  => [
	      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
       created.

       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
       method.

   add_check_content
       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.

       Example:

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

	sub setup {
	   my $self = shift;
	   weaken($self);
	   $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):

       min_index
       max_index
       max_nb
       index_type
       default_keys
       default_with_init
       follow_keys_from
       auto_create_ids
       auto_create_keys
       ordered
       morph
       config_model

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

   get_cargo_info
       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.

   get_default_keys
       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.

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

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

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

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

Information management
   fetch_with_id
       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
       index.

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

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

	    /foo/bar/4

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

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

       check
	   Either "skip", "no"

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

       autoadd
	   Whether to create missing keys

       dir_char_mockup
	   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>"

   set
       Parameters: "( path, value )"

       Set a value with	a directory like path.

   copy
       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.

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

   fetch_value
       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.

   fetch_summary
       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.

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

       custom
	   The value entered by	the user

       preset
	   The value entered in	preset mode

       standard
	   The value entered in	preset mode or checked by default.

       default
	   The default value (defined by the configuration model)

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

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

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

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

   defined
       Parameters: "( index )"

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

   exists
       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.

   has_data
       Return true if the array	or hash	is not empty.

   delete
       Parameters: "( index )"

       Delete the "index"ed value

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

   clear_values
       Delete all values (without deleting underlying value objects).

   warning_msg
       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.

   has_warning
       Returns the current number of warning.

   error_msg
       Returns the error messages of this object (if any)

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

SEE ALSO
       Config::Model, Config::Model::Instance, Config::Model::Node,
       Config::Model::WarpedNode, Config::Model::HashId,
       Config::Model::ListId, Config::Model::CheckList,	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::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:
<https://www.freebsd.org/cgi/man.cgi?query=Config::Model::AnyId&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help