/ 
config-model-0.504
/ Config::Model::AnyId

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 ,
           collected_type => 'leaf',
           element_args => {value_type => 'string'},
         },
     bounded_list 
      => { type => 'list',                 # list id

           max => 123, 
           collected_type => 'leaf',
           element_args => {value_type => 'string'},
         },
     ]
 ) ;

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 collected_type (See </"CAVEATS">).

index_type

Either integer or string. Mandatory for hash.

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

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.

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

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'].

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 }
                                               }
                                     },
                       collected_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 of the Id object (as declared in the model unless they were warped):

min
max
max_nb
index_type
default
auto_create
collected_type
element_class
element_args morph
config_model

name()

Returns the object name. The name finishes with ' id'.

Informations management

fetch_with_id ( index )

Fetch the collected element held by the hash or list.

fetch_all()

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

get_all_indexes()

Returns an array containing all indexes of the hash or list.

defined ( index )

Returns true of the value held at index is defined.

exists ( index )

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

CAVEATS

The argument that specified the type of the element stored in the hash or list is name collected_type. This name sounds lame. If a native english speaker can suggest a better name, I'll be glad to change it.

AUTHOR

Dominique Dumont, domi@komarr.grenoble.hp.com

SEE ALSO

Config::Model::Model, Config::Model::Instance, Config::Model::HashId, Config::Model::ListId, Config::Model::WarpedNode, Config::Model::Value