Config...:AnyId(3pm)

📦

version 2.166 · 8 versions

Config::Model::AnyId(3pm) ✨

User Contributed Perl Documentation — hiii bestie, welcome to the manual page for Config::Model::AnyId. It's giving base-class energy for hash and list elements, and we're gonna get through every single detail together. 🫶

NAME 💅

Config::Model::AnyId — Base class for hash or list element. Periodt.

VERSION 🌟

version 2.166 — yes bestie, that's the number.

SYNOPSIS 🧚

Okay so here's the vibe in code. Do not skip it, every line matters:

use Config::Model;

# define configuration tree object
my $model = Config::Model->new;
$model->create_config_class(
   name    => "Foo",
   element => [
       foo => {
           type       => 'leaf',
           value_type => 'string'
       },
       bar => '*foo',
   ]
);

$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 an enumerated type, a boolean, an integer or a string. Slay. ✨

CONSTRUCTOR 🙈

AnyId object should not be created directly.

So like, don't new it yourself, bestie. It's not that kind of party. 💅

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

With a list, you must use numeric keys:

default_with_init => {
    0 => 'def_1 stuff',
    1 => '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 => '- macro'
        },
        rules => [
          {
            apply => { max_nb => 2 },
            when => '$macro eq "B"'
          },
          {
            apply => { max_nb => 1 },
            when => '$macro eq "A"'
          }
        ]
      },
      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 => [
    {
      apply => { max_nb => 1 },
      when => '$m1 eq "A" and $m2 eq "A2"'
    },
    {
      apply => { max_nb => 2 },
      when => '$m1 eq "A" and $m2 eq "B2"'
    }
  ]
},

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 never removes items that were previously auto created.

For instance, when a tied hash is created with auto_create => [a,b,c], the hash contains (a,b,c).

Then, once a warp with auto_create_keys => [c,d,e] is applied, the hash then contains (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 is raised if a warp leads to a number of items greater than the max_nb constraint.

Content check 💖

So like, by default this class gives you an optional content check that sniffs out duplicated values — but only when the "duplicates" parameter is set, bestie. Keeping tabs on that.

And if you're building a derived class, you can register even more global checkers with this method right here. 👇

`add_check_content`

This one wants a sub ref with the signature ( $error, $warn, $apply_fix ). Where $error and $warn are array refs — you just push your error or warning messages right in there. And $apply_fix? That's a boolean. When it's set to 1, the method you passed in is allowed to actually fix the warning or the error. Slay. ✨

Let's look at an example, no cap:

package MyId;
use Mouse;
extends qw/Config::Model::HashId/;
use Scalar::Util qw/weaken/;

sub my_check ($self, $error, $warn, $apply_fix) {
    # check => 'no' is required to avoid deep recursion
    my @values = $self->fetch_all_values(check => 'no');

    return if $my_condition; # up to you

    if ($apply_fix) {
        $self->fix_this(); # to be defined by you
    }
    else {
        push $warn->@*, "this data needs to be fixed because bla bla bla.";
        $self->inc_fixes;
    }
    return;
}

sub BUILD ($self, $) {
   # $self to avoid memory cycles.
   weaken($self);
   $self-> add_check_content( sub { $self->my_check(@_);} )
}

Introspection methods 🔍✨

These methods hand you back the current value chillin' inside the Id object (exactly as declared in the model, unless they got warped, ofc):

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 — like, it literally returns "cargo -> type". 💅

`get_cargo_info`

Parameters: ( < what > )

Gives you more info on the cargo held by the hash or list. < what > can be "value_type" or any other cargo info stored up in the model. And if the model doesn't have the info you're asking for? It returns undef. Sorry babe. 🫶

`get_default_keys`

Returns a list (or a list ref) of the current default keys — iconic. These keys can be set by the "default_keys" or "default_with_init" parameters, or by that other hash pointed to by the "follow_keys_from" parameter.

`name`

Returns the object name. Fair warning bestie: the name wraps up with ' id'. Noted. 👑

`config_class_name`

Returns the config_class_name of collected elements. Valid only for a collection of nodes, okay?

And this method returns undef if "cargo" "type" isn't "node". Simple as that. 🌸

`has_fixes`

Returns the number of fixes that can be applied to the current value. That's the whole vibe. ✨

Information management 📋💖

`fetch_with_id`

Parameters: ( index => $idx , [ check => 'no' ])

Fetch the collected element held by the hash or list. Index check is 'yes' by default, fyi. And you can totally call it with just one parameter — that param gets used as the index. cute. 🎀

`get`

Get a value from a directory like path. The parameters are:

path — Poor man's version of an XPath style path. This string comes in the form:

/foo/bar/4

Each word between the '/' is either an element name, a hash key, or a list index. iykyk.

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 decides whether you get back the stored value or the value object.
autoadd — Whether to create missing keys. 🌱
dir_char_mockup — When the hash key you're using has a '/' in it (say, a directory value), that key can't be used as-is with this method, because '/' is already doing double duty separating configuration items (this also matters with Config::Model::FuseUI, lowkey important). This parameter says how the forbidden '/' char gets shown in the path. Default is "<slash>".

`set`

Parameters: ( path, value )

Sets a value with a directory like path. done and dusted. 💅

`copy`

Parameters: ( from_index, to_index )

Deep copies an element within the hash or list. And if the element held by the hash or list is a node? Then like, all the configuration information gets copied from one node to another. full glow-up transfer. ✨

`fetch_all`

Returns an array containing all elements held by the hash or list. everything, all at once. 🦋

`fetch_size`

Returns the number of elements of the array, or the number of keys of the hash. (from v2.157, marking that down 📝)

`fetch_value`

Parameters: ( idx => ..., mode => ..., check => ...)

Returns the value held by the "idx" element of the hash or list. Heads up: this method is only valid for hash or list containing leaves. 🍓

And for the "mode" argument documentation, go look at fetch_all_values, and for the "check" argument documentation, see "fetch" in Config::Model::Value.

`fetch_summary`

Arguments: ( idx => ..., mode => ..., check => ...)

Like "fetch_value", but it returns a truncated value whenever the value is a string or uniline that's too long to fit on the display. a lil cliffnotes moment, we love that. 💖

`fetch_all_values`

Parameters: ( mode => ..., check => ...)

Returns an array containing all defined values held by the hash or list. (Undefined values are simply discarded, no hard feelings.) This method is only valid for hash or list containing leaves.

With the "mode" parameter, this method returns 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)

And for the "check" argument documentation, see "fetch" in Config::Model::Value. 👑

`fetch`

Similar to "fetch_all_values", with the same parameters — returns the result as a string with comma separated list values. 🎀

`fetch_all_indexes`

Returns an array containing all indexes of the hash or list. Hash keys are sorted alphabetically — except for ordered hashed. noted bestie. 📝

`children`

Like fetch_all_indexes. This method is polymorphic for all non-leaf objects of the configuration tree. main character energy fr. 🌈

`defined`

Parameters: ( index )

Returns true if the value held at "index" is defined. that's it, that's the whole method. ✅

`exists`

Parameters: ( index )

Returns true if the value held at "index" exists (i.e the key exists but the value may be undefined). Quick note: this method may not make sense for a list element. 🙈

`has_data`

Return true if the array or hash is not empty. simple king behaviour. 👑

`delete`

Parameters: ( index )

Deletes the "index"ed value. gone, blocked, deleted. 💀

`clear`

Deletes all values (and also deletes the underlying value or node objects). scorched earth, we love to see it.

`clear_values`

Deletes all values — but without deleting the underlying value objects. very "leave the furniture, take the stuff" of it. 🎀

`warning_msg`

Parameters: ( [index] )

With an index parameter, this function returns warnings concerning that index — for instance a warning about an index greater than max_nb.

Without a parameter, it returns a string containing warnings about the content of a hash or list — for instance a missing value is a list.

And if no warnings are found? You get an empty string back. peace. ✨

`has_warning`

Returns the current number of warning. (yes, singular, that's how it's written, i don't make the rules 💅)

`error_msg`

Returns the error messages of this object (if any). if any, bestie, if any. 😭

AUTHOR 🌸

Dominique Dumont, ddumont [AT] cpan [DOT] org

AUTHOR 💖

Dominique Dumont

COPYRIGHT AND LICENSE 👑

This is free software, licensed under:

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

and that's the whole page bestie, you ate that 🫶 this lil doc ships as perl v5.42.3, dated 2026-07-23, under the name Config...:AnyId(3pm) — go be iconic with it, periodt. ✨💅

📦 where this page comes from

ubuntu stonking: libconfig-model-perl 2.166-1 · LGPL-2.1-only
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms

Config...:AnyId(3pm)

Config::Model::AnyId(3pm) ✨

NAME 💅

VERSION 🌟

SYNOPSIS 🧚

DESCRIPTION 🌸

CONSTRUCTOR 🙈

Hash or list model declaration 🎀

Warp: dynamic value configuration 🌈

Warp and auto_create_ids or auto_create_keys 🦋

Warp and max_nb 🔥

Content check 💖

add_check_content

Introspection methods 🔍✨

get_cargo_type

get_cargo_info

get_default_keys

name

config_class_name

has_fixes

Information management 📋💖

fetch_with_id

get

set

copy

fetch_all

fetch_size

fetch_value

fetch_summary

fetch_all_values

fetch

fetch_all_indexes

children

defined

exists

has_data

delete

clear

clear_values

warning_msg

has_warning

error_msg

AUTHOR 🌸

SEE ALSO 🦋

AUTHOR 💖

COPYRIGHT AND LICENSE 👑

`add_check_content`

`get_cargo_type`

`get_cargo_info`

`get_default_keys`

`name`

`config_class_name`

`has_fixes`

`fetch_with_id`

`get`

`set`

`copy`

`fetch_all`

`fetch_size`

`fetch_value`

`fetch_summary`

`fetch_all_values`

`fetch`

`fetch_all_indexes`

`children`

`defined`

`exists`

`has_data`

`delete`

`clear`

`clear_values`

`warning_msg`

`has_warning`

`error_msg`