NAME

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

SYNOPSIS

 $model ->create_config_class 
  (
   ...
   element 
   => [ 
       bounded_hash 
       => { type => 'hash',                 # hash id
            index_type  => 'integer',

            # hash boundaries
            min => 1, max => 123, max_nb => 2 ,
            cargo_type => 'leaf',
            cargo_args => {value_type => 'string'},
          },
      bounded_list 
       => { type => 'list',                 # list id

            max => 123, 
            cargo_type => 'leaf',
            cargo_args => {value_type => 'string'},
          },
      hash_of_nodes 
      => { type => 'hash',                 # hash id
           index_type  => 'integer',
           cargo_type => 'node',
           config_class_name => 'Foo' ,
         },
      ]
  ) ;

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_type

Specifies the type of cargo held by the hash of list. Can be node or leaf (default).

cargo_args

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.

config_class_name

Specifies the type of configuration object held in the hash. Only valid when cargo_type is node.

min

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

max

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

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'

auto_create

When set, the default parameter (or set of parameters) are used as keys hashes and created automatically.

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

For list, auto_create indicated the number of elements to create. E.g. auto_create => 4 will initialize the list with 4 undef elements.

warp

See "Warp: dynamic value configuration" in section below.

About checking value

By default, value checking is done while setting or reading a value.

You can use push_no_value_check() or pop_no_value_check() from Config::Model::Instance to modify this behavior.

Warp: dynamic value configuration

The Warp functionnality enables an HashId or ListId object to change its default settings (e.g. min, max 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 ListIf can have multiple warp masters (See "Warp follow argument" in Config::Model::WarpedThing:

  warp => { follow => ['- macro1', '- macro2'],
            rules  => [ [ 'A','A2' ]  => { max_nb => 1},
                        [ 'A','B2' ] => { max_nb => 2}
                      ],
          }

Warp and auto_create

When a warp is applied with auto_create 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 => [c,d,e], the hash will contain (a,b,c,d,e). The items created by the first auto_create are not removed.

Warp and max_nb

When a warp is applied, the items that do not fit the constraint (e.g. min, max) are removed.

For the max_nb constraint, an exception will be raised if a warp leads to a nb 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

max

max_nb

index_type

default_keys

default_with_init

auto_create

cargo_type

cargo_class

cargo_args

morph

config_model

get_cargo_type()

Returns the object type contained by the hash or list (i.e. returns cargo_type).

get_default_keys

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

Informations management

fetch_with_id ( index )

Fetch the collected element held by the hash or list.

move ( from_index, to_index )

Move an element within the hash or list.

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 informations are copied from one node to another.

fetch_all()

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

fetch_all_values( [ custom | preset | standard | default ] )

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

With a 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.

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

clear()

Delete all values.

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

cpanm Config::Model

perl -MCPAN -e shell
install Config::Model