Steven Haryanto > Data-ModeMerge > Data::ModeMerge::Config

Download:
Data-ModeMerge-0.30.tar.gz

Dependencies

Annotate this POD

Website

CPAN RT

Open  0
View/Report Bugs
Module Version: 0.30   Source  

NAME ^

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

VERSION ^

version 0.30

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 => {
      steven => { quota => 100, admin => 1 },
      tommie => { quota =>  50, admin => 0 },
      jimmy  => { quota => 150, admin => 0 },
    },
    groups => [qw/admin staff/],
   },
   {
    user => {
      steven => { quota => 1000 },
    }
   }
 );

With wanted_path unset, the result would be:

   {
    user => {
      steven => { quota => 1000, admin => 1 },
      tommie => { quota =>   50, admin => 0 },
      jimmy  => { quota =>  150, admin => 0 },
    }
    groups => [qw/admin staff/],
   }

With wanted_path set to ["user", "steven", "quota"] (in other words, you're saying that you'll be disregarding other branches), the result would be:

   {
    user => {
      steven => { 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.

AUTHOR ^

Steven Haryanto <stevenharyanto@gmail.com>

COPYRIGHT AND LICENSE ^

This software is copyright (c) 2013 by Steven Haryanto.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

syntax highlighting: