NAME

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

VERSION

version 2.154

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 indexed 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

AUTHOR

Dominique Dumont

COPYRIGHT AND LICENSE

This is free software, licensed under:

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

To install Config::Model, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Config::Model

CPAN shell

perl -MCPAN -e shell
install Config::Model

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

DESCRIPTION

CONSTRUCTOR

Hash or list model declaration

Warp: dynamic value configuration

Warp and auto_create_ids or auto_create_keys

Warp and max_nb

Content check

add_check_content

Introspection methods

get_cargo_type

get_cargo_info

get_default_keys

name

config_class_name

has_fixes

Information management

fetch_with_id

get

set

copy

fetch_all

fetch_value

fetch_summary

fetch_all_values

fetch

fetch_all_indexes

children

defined

exists

has_data

delete

clear

clear_values

warning_msg

has_warning

error_msg

AUTHOR

SEE ALSO

AUTHOR

COPYRIGHT AND LICENSE

Module Install Instructions