Provided by: libconfig-model-perl_2.047-1_all bug

NAME

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

VERSION

       version 2.047

SYNOPSIS

        use Config::Model;
        use Log::Log4perl qw(:easy);
        Log::Log4perl->easy_init($WARN);

        # 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 $step = '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( step => $step );

        # 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> (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.

       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.

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

       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"
           will initialize the list with 4 undef elements.  (valid only for list elements)

       convert => [uc | lc ]
           The hash key will be 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" 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::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 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_keys => [c,d,e]", the hash will contain
       "(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 will be raised if a warp leads to a number 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".

   has_fixes
       Returns the number of fixes that can be applied to the current value.

Information management

   fetch_with_id ( 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 will be 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( path, value )
       Set a value with a directory like path.

   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( 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 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)

   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 ( 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).

   warning_msg ( [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.

   error_msg
       Returns the error messages of this object (if any)

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

       This is free software, licensed under:

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