Data::ModeMerge::Config - Data::ModeMerge configuration
This document describes version 0.35 of Data::ModeMerge::Config (from Perl distribution Data-ModeMerge), released on 2016-07-22.
# getting configuration if ($mm->config->allow_extra_hash_keys) { ... } # setting configuration $mm->config->max_warnings(100);
Configuration variables for Data::ModeMerge.
Context: config, options key
Default: 1
Whether to recursively merge hash. When 1, each key-value pair between 2 hashes will be recursively merged. Otherwise, the right-side hash will just replace the left-side.
Options key will not be parsed under recurse_hash=0.
Example:
mode_merge({h=>{a=>1}}, {h=>{b=>1}} ); # {h=>{a=>1, b=>1}} mode_merge({h=>{a=>1}}, {h=>{b=>1}}, {recurse_hash=>0}); # {h=>{b=>1}}
Default: 0
Whether to recursively merge array. When 1, each element is recursively merged. Otherwise, the right-side array will just replace the left-side.
mode_merge([1, 1], [4] ); # [4, 1] mode_merge([1, 1], [4], {recurse_array=>0}); # [2]
Whether to parse merge prefix in hash keys. If set to 0, merging behaviour is similar to most other nested merge modules.
mode_merge({a=>1}, {"+a"=>2} ); # {a=>3} mode_merge({a=>1}, {"+a"=>2}, {parse_prefix=>0}); # {a=>1, "+a"=>2}
Default: undef
If set, merging is only done to the specified "branch". Useful to save time/storage when merging large hash "trees" while you only want a certain branch of the trees (e.g. resolving just a config variable from several config hashes).
mode_merge( { user => { jajang => { quota => 100, admin => 1 }, paijo => { quota => 50, admin => 0 }, kuya => { quota => 150, admin => 0 }, }, groups => [qw/admin staff/], }, { user => { jajang => { quota => 1000 }, } } );
With wanted_path unset, the result would be:
{ user => { jajang => { quota => 1000, admin => 1 }, paijo => { quota => 50, admin => 0 }, kuya => { quota => 150, admin => 0 }, } groups => [qw/admin staff/], }
With wanted_path set to ["user", "jajang", "quota"] (in other words, you're saying that you'll be disregarding other branches), the result would be:
{ user => { jajang => { quota => 1000, admin => undef }, } }
Default: NORMAL
mode_merge(3, 4 ); # 4 mode_merge(3, 4, {default_mode => "ADD"}); # 7
Default: []
List of modes to ignore the prefixes of.
mode_merge({add=>1, del=>2, concat=>3}, {add=>2, "!del"=>0, .concat=>4}, {disable_modes=>[qw/CONCAT/]}); # {add=>3, concat=>3, .concat=>4}
See also: parse_prefix which if set to 0 will in effect disable all modes except the default mode.
parse_prefix
If enabled, then array creation will be allowed (from something non-array, like a hash/scalar). Setting to 0 is useful if you want to avoid the merge to "change the structure" of the left side.
mode_merge(1, [1,2] ); # success, result=[1,2] mode_merge(1, [1,2], {allow_create_array=>0}); # failed, can't create array
If enabled, then hash creation will be allowed (from something non-hash, like array/scalar). Setting to 0 is useful if you want to avoid the merge to "change the structure" of the left side.
mode_merge(1, {a=>1} ); # success, result={a=>1} mode_merge(1, {a=>1}, {allow_create_hash=>0}); # failed, can't create hash
If enabled, then replacing array on the left side with non-array (e.g. hash/scalar) on the right side is allowed. Setting to 0 is useful if you want to avoid the merge to "change the structure" of the left side.
mode_merge([1,2], {} ); # success, result={} mode_merge([1,2], {}, {allow_destroy_array=>0}); # failed, can't destroy array
If enabled, then replacing hash on the left side with non-hash (e.g. array/scalar) on the right side is allowed. Setting to 0 is useful if you want to avoid the merge to "change the structure" of the left side.
mode_merge({a=>1}, [] ); # success, result=[] mode_merge({a=>1}, [], {allow_destroy_hash=>0}); # failed, can't destroy hash
The list of hash keys that should not be parsed for prefix and merged as-is using the default mode.
If include_parse is also mentioned then only keys in include_parse and not in exclude_parse will be parsed for prefix.
include_parse
exclude_parse
mode_merge({a=>1, b=>2}, {"+a"=>3, "+b"=>4}, {exclude_parse=>["+b"]}); # {a=>4, b=>2, "+b"=>4}
Just like exclude_parse but using regex instead of list.
If specified, then only hash keys listed by this setting will be parsed for prefix. The rest of the keys will not be parsed and merged as-is using the default mode.
If exclude_parse is also mentioned then only keys in include_parse and not in exclude_parse will be parsed for prefix.
mode_merge({a=>1, b=>2, c=>3}, {"+a"=>4, "+b"=>5, "+c"=>6}, {include_parse=>["+a"]}); # {a=>1, "+a"=>4, b=>7, c=>3, "+c"=>6}
Just like include_parse but using regex instead of list.
The list of hash keys on the left side that should not be merged and instead copied directly to the result. All merging keys on the right side will be ignored.
If include_merge is also mentioned then only keys in include_merge and not in exclude_merge will be merged.
include_merge
exclude_merge
mode_merge({a=>1}, {"+a"=>20, "-a"=>30}, {exclude_merge=>["a"]}); # {a=>1}
Just like exclude_merge but using regex instead of list.
If specified, then only hash keys listed by this setting will be merged.
If exclude_merge is also mentioned then only keys in include_merge and not in exclude_merge will be merged.
mode_merge({a=>1, b=>2, c=>3}, {"+a"=>40, "+b"=>50, "+c"=>60, "!c"=>70}, {include_merge=>["a"]}); # {a=>41, b=>2, c=>3}
Just like include_merge but using regex instead of list.
Temporarily change the prefix character for each mode. Value is hashref where each hash key is mode and the value is a new prefix string.
mode_merge({a=>1, c=>2}, {'+a'=>10, '.c'=>20}); # {a=>11, c=>220} mode_merge({a=>1, c=>2}, {'+a'=>10, '.c'=>20}, {set_prefix=>{ADD=>'.', CONCAT=>'+'}}); # {a=>110, c=>22}
When merging two hashes, the prefixes are first stripped before merging. After merging is done, the prefixes by default will be re-added. This is done so that modes which are "sticky" (like KEEP) can propagate their mode). Setting readd_prefix to 0 will prevent their stickiness.
readd_prefix
mode_merge({"^a"=>1}, {a=>2}); # {"^a"=>1} mode_merge({"^a"=>1}, {a=>2}, {readd_prefix=>0}); # { "a"=>1}
Pass the key and value of each hash pair to a subroutine before merging (and before the keys are stripped for mode prefixes). Will push error if there is conflicting key in the hash.
The subroutine should return a list of new key(s) and value(s). If key is undef then it means the pair should be discarded. This way, the filter is able to add or remove pairs from the hash.
mode_merge({a=>1}, {"+amok"=>2}, {premerge_pair_filter=>sub{ uc(substr($_[0],0,2)), $_[1]*2 }}); # {"A"=>6}
Context: config
Default: '' (empty string)
If defined, then when merging two hashes, this key will be searched first on the left-side and right-side hash. The values will then be merged and override (many of) the configuration.
Options key is analogous to Apache's .htaccess mechanism, which allows setting configuration on a per-directory (per-hash) basis. There's even an allow_override config similar to Apache directive of the same name.
.htaccess
allow_override
If you want to disable processing of options key, set this to undef.
mode_merge({a=>1, {x=>3}}, {a=>2, {x=>4}}, {default_mode=>'ADD'}); # {a=>3, {x=>7}} mode_merge({a=>1, {x=>3}}, {a=>2, {x=>4, ''=>{default_mode=>'CONCAT'}}}, {default_mode=>'ADD'}); # {a=>3, {x=>34}}
On the above example, default_mode is set to ADD. But in the {x=>...} subhash, default_mode is changed to CONCAT by the options key.
default_mode
If defined, then only config names matching regex will be able to be set in options key.
If disallow_override is also set, then only config names matching allow_override and not matching disallow_override will be able to be set in options key.
disallow_override
If defined, then config names matching regex will not be able to be set in options key.
For example, if you want to restrict "structural changes" in merging while still allowing options key, you can set allow_create_hash, allow_destroy_hash, allow_create_array, and allow_destroy_array all to 0 and disallow_override to allow_create|allow_destroy to forbid overriding via options key.
allow_create_hash
allow_destroy_hash
allow_create_array
allow_destroy_array
allow_create|allow_destroy
Please visit the project's homepage at https://metacpan.org/release/Data-ModeMerge.
Source repository is at https://github.com/perlancar/perl-Data-ModeMerge.
Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=Data-ModeMerge
When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.
perlancar <perlancar@cpan.org>
This software is copyright (c) 2016 by perlancar@cpan.org.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install Data::ModeMerge, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Data::ModeMerge
CPAN shell
perl -MCPAN -e shell install Data::ModeMerge
For more information on module installation, please visit the detailed CPAN module installation guide.