NAME¶
Config::Model::AnyId - Base class for hash or list element
VERSION¶
version 2.061
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.
- 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.
- 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 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)
- convert => [uc | lc ]
- The hash key will be 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" 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::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 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".
has_fixes¶
Returns the number of fixes that can be applied to the current value.
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(...)¶
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( 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)
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 ( 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
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) 2014 by Dominique Dumont.
This is free software, licensed under:
The GNU Lesser General Public License, Version 2.1, February 1999