Config::Model::AnyId(3User Contributed Perl DocumentatiConfig::Model::AnyId(3)NAMEConfig::Model::AnyId - Base class for hash or list element
VERSION
version 1.235
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 => "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 $step = '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( step => $step );
# 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> (See "CAVEATS").
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.
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 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' }
migrate_keys_from
Specifies that the keys of the hash or list are copied from another
hash or list in the configuration tree only when the hash is
created.
migrate_keys_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 hash you're creating
will always have 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" will initialize the list with 4 undef
elements. (valid only for list elements)
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::WarpedThing 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" will mean that "warped_hash" can only accept one
instance of "Dummy".
Setting "macro" to "B" will mean that "warped_hash" will accept two
instances of "Dummy".
Like other warped class, a HashId or ListId can have multiple warp
masters (See "Warp follow argument" in Config::Model::WarpedThing:
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 will never remove items that were previously
auto created.
For instance, if a tied hash is created with "auto_create => [a,b,c]",
the hash contains "(a,b,c)".
Then if a warp is applied with "auto_create_keys => [c,d,e]", the hash
will contain "(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 will be raised if a warp leads
to a number of items greater than the max_nb constraint.
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( < 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. Will
return undef if the requested info was 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 will return undef if "cargo" "type" is not "node".
Information management
fetch_with_id ( 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 will be used
as index.
"get( path =" ..., mode => ... , check => ... , get_obj => 1|0, autoadd =>
1|0)>
Get a value from a directory like path.
set( path, value )
Set a value with a directory like path.
copy ( 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_all_values( 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 will return 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)
get_all_indexes()
Returns an array containing all indexes of the hash or list. Hash keys
are sorted alphabetically, except for ordered hashed.
children
Like get_all_indexes. This method is polymorphic for all non-leaf
objects of the configuration tree.
defined ( index )
Returns true if the value held at "index" is defined.
exists ( 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.
delete ( 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 ( [index] )
Returns warnings concerning indexes of this hash. Without parameter,
returns a hash ref or undef. With an index, return the warnings
concerning this index or undef.
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
perl v5.14.1 2011-07-22 Config::Model::AnyId(3)
