--- name: "Config::Model::AnyId" section: "3pm" platform: "linux" package: "libconfig-model-perl" version: "2.155-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Config::Model::AnyId" --- # Config::Model::AnyId(3pm) Base class for hash or list element ## NAME Config::Model::AnyId - Base class for hash or list element ## VERSION version 2.155 ## SYNOPSIS ``` use Config::Model; # 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 $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 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"`. - 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"`. - \ 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 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', rules => { A => { max_nb => 1 }, B => { max_nb => 2 } } }, 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 => [ '$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 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 By default, this class provides an optional content check that checks for duplicated values (when `"duplicates"` parameter is set). Derived classes can register more global checker with the following method. ### add\_check\_content This method expects a sub ref with signature `"( $self, $error, $warn,` `$apply_fix )"`. Where `$error` and `$warn` are array ref. You can push error or warning messages there. `$apply_fix` is a boolean. When set to 1, the passed method can fix the warning or the error. Please make sure to weaken `$self` to avoid memory cycles. Example: ``` package MyId; use Mouse; extends qw/Config::Model::HashId/; use Scalar::Util qw/weaken/; sub setup { my $self = shift; weaken($self); $self-> add_check_content( sub { $self->check_usused_licenses(@_);} ) } ``` ## 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 Parameters: `"( < 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. Returns undef if the requested info is 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 returns 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 Parameters: `"( 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 is 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 \ - 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 `""` ### set Parameters: `"( path, value )"` Set a value with a directory like path. ### copy Parameters: `"( 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\_value Parameters: `"( idx => ..., mode => ..., check => ...)"` Returns the value held by the `"idx"` element of the hash or list. This method is only valid for hash or list containing leaves. See fetch\_all\_values for `"mode"` argument documentation and "fetch" in Config::Model::Value for `"check"` argument documentation. ### fetch\_summary Arguments: `"( idx => ..., mode => ..., check => ...)"` Like "fetch\_value", but returns a truncated value when the value is a string or uniline that is too long to be displayed. ### fetch\_all\_values Parameters: `"( 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 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) See "fetch" in Config::Model::Value for `"check"` argument documentation. ### 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. ### children Like fetch\_all\_indexes. This method is polymorphic for all non-leaf objects of the configuration tree. ### defined Parameters: `"( index )"` Returns true if the value held at `"index"` is defined. ### exists Parameters: `"( 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. ### has\_data Return true if the array or hash is not empty. ### delete Parameters: `"( 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 Parameters: `"( [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. ### has\_warning Returns the current number of warning. ### 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) 2005-2022 by Dominique Dumont. This is free software, licensed under: ``` The GNU Lesser General Public License, Version 2.1, February 1999 ```