Linux Certif

Toute la documentation sur la certification Linux LPI

Config::Model::AnyId.3pm

NAME

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

VERSION

version 1.205

SYNOPSIS

  $model ->create_config_class 
   (
    ...
    element 
    => [ 
        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  => '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

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 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_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 => 'foo'", or "auto_create => ['foo', 'bar']".

auto_create_ids

Specifies the number of elements to create automatically. E.g. "auto_create => 4" will initialize the list with 4 undef elements. (valid only for list elements)

warp

See ``Warp: dynamic value configuration'' 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 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::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 ListId can have multiple warp masters (See ``Warp follow argument'' in Config::Model::WarpedThing:

   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 => [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_index, max_index) 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_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".

Informations management

fetch_with_id ( index )

Fetch the collected element held by the hash or list.

get( path, [ custom | preset | standard | default ])

Get a value from a directory like path.

set( path, value )

Set a value with a directory like path.

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 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( [ custom | preset | standard | default ] )

Returns an array containing all defined values held by the hash or list. (undefined values are simply discarded)

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 "index"ed value

clear()

Delete all values (also delete underlying value or node objects).

clear_values()

Delete all values (without deleting underlying value objects).

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