NAME¶

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

VERSION¶

version 2.152

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:

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}
                      ],
          }

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.

 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

Information management¶

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-2022 by Dominique Dumont.

This is free software, licensed under:

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