NAME

Data::ModeMerge::Config - Data::ModeMerge configuration

VERSION

This document describes version 0.360 of Data::ModeMerge::Config (from Perl distribution Data-ModeMerge), released on 2021-08-15.

SYNOPSIS

# getting configuration
if ($mm->config->allow_extra_hash_keys) { ... }

# setting configuration
$mm->config->max_warnings(100);

DESCRIPTION

Configuration variables for Data::ModeMerge.

ATTRIBUTES

recurse_hash => BOOL

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

recurse_array => BOOL

Context: config, options key

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.

Example:

mode_merge([1, 1], [4]                    ); # [4, 1]
mode_merge([1, 1], [4], {recurse_array=>0}); # [2]

parse_prefix => BOOL

Context: config, options key

Default: 1

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}

wanted_path => ARRAYREF

Context: config, options key

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

Example:

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_mode => 'NORMAL' | 'ADD' | 'CONCAT' | 'SUBTRACT' | 'DELETE' | 'KEEP' | ...

Context: config, options key

Default: NORMAL

Example:

mode_merge(3, 4                         ); # 4
mode_merge(3, 4, {default_mode => "ADD"}); # 7

disable_modes => ARRAYREF

Context: config, options key

Default: []

List of modes to ignore the prefixes of.

Example:

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.

allow_create_array => BOOL

Context: config, options key

Default: 1

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.

Example:

mode_merge(1, [1,2]                         ); # success, result=[1,2]
mode_merge(1, [1,2], {allow_create_array=>0}); # failed, can't create array

allow_create_hash => BOOL

Context: config, options key

Default: 1

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.

Example:

mode_merge(1, {a=>1}                        ); # success, result={a=>1}
mode_merge(1, {a=>1}, {allow_create_hash=>0}); # failed, can't create hash

allow_destroy_array => BOOL

Context: config, options key

Default: 1

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.

Example:

mode_merge([1,2], {}                          ); # success, result={}
mode_merge([1,2], {}, {allow_destroy_array=>0}); # failed, can't destroy array

allow_destroy_hash => BOOL

Context: config, options key

Default: 1

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.

Example:

mode_merge({a=>1}, []                         ); # success, result=[]
mode_merge({a=>1}, [], {allow_destroy_hash=>0}); # failed, can't destroy hash

exclude_parse => ARRAYREF

Context: config, options key

Default: undef

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.

Example:

mode_merge({a=>1, b=>2}, {"+a"=>3, "+b"=>4}, {exclude_parse=>["+b"]}); # {a=>4, b=>2, "+b"=>4}

exclude_parse_regex => REGEX

Context: config, options key

Default: undef

Just like exclude_parse but using regex instead of list.

include_parse => ARRAYREF

Context: config, options key

Default: undef

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.

Example:

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}

include_parse_regex => REGEX

Context: config, options key

Default: undef

Just like include_parse but using regex instead of list.

exclude_merge => ARRAYREF

Context: config, options key

Default: undef

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.

Example:

mode_merge({a=>1}, {"+a"=>20, "-a"=>30}, {exclude_merge=>["a"]}); # {a=>1}

exclude_merge_regex => REGEX

Context: config, options key

Default: undef

Just like exclude_merge but using regex instead of list.

include_merge => ARRAYREF

Context: config, options key

Default: undef

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.

Example:

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}

include_merge_regex => ARRAYREF

Context: config, options key

Default: undef

Just like include_merge but using regex instead of list.

set_prefix => HASHREF

Context: config, options key

Default: undef

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}

readd_prefix => BOOL

Context: config, options key

Default: 1

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.

mode_merge({"^a"=>1}, {a=>2});                    # {"^a"=>1}
mode_merge({"^a"=>1}, {a=>2}, {readd_prefix=>0}); # { "a"=>1}

premerge_pair_filter => CODEREF

Context: config, options key

Default: undef

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}

options_key => STR

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.

If you want to disable processing of options key, set this to undef.

Example:

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.

allow_override => REGEX

Context: config

Default: undef

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 => REGEX

Context: config

Default: undef

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.

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.

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/Data-ModeMerge.

SOURCE

Source repository is at https://github.com/perlancar/perl-Data-ModeMerge.

BUGS

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.

AUTHOR

perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE

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.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

DESCRIPTION

ATTRIBUTES

recurse_hash => BOOL

recurse_array => BOOL

parse_prefix => BOOL

wanted_path => ARRAYREF

default_mode => 'NORMAL' | 'ADD' | 'CONCAT' | 'SUBTRACT' | 'DELETE' | 'KEEP' | ...

disable_modes => ARRAYREF

allow_create_array => BOOL

allow_create_hash => BOOL

allow_destroy_array => BOOL

allow_destroy_hash => BOOL

exclude_parse => ARRAYREF

exclude_parse_regex => REGEX

include_parse => ARRAYREF

include_parse_regex => REGEX

exclude_merge => ARRAYREF

exclude_merge_regex => REGEX

include_merge => ARRAYREF

include_merge_regex => ARRAYREF

set_prefix => HASHREF

readd_prefix => BOOL

premerge_pair_filter => CODEREF

options_key => STR

allow_override => REGEX

disallow_override => REGEX

HOMEPAGE

SOURCE

BUGS

AUTHOR

COPYRIGHT AND LICENSE

Module Install Instructions