The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Data-PrefixMerge-0.02
/ Data::PrefixMerge

NAME

Data::PrefixMerge - Merge two nested data structures, with merging mode prefix on hash keys

VERSION

Version 0.02

SYNOPSIS

    # OO interface

    use Data::PrefixMerge;
    my $merger = Data::PrefixMerge->new();

    my $hash1 = { a=>1,    c=>1, d=>{  da =>[1]} };
    my $hash2 = { a=>2, "-c"=>2, d=>{"+da"=>[2]} };

    my $res = $merger->merge($hash1, $hash2);
    die $res->{error} if $res->{error};
    print $res->{result}; # { a=>2, c=>-1, d => { da=>[1,2] } }


    # procedural interface

    use Data::PrefixMerge;
    my $res = prefix_merge($hash1, $hash2);
    my $hash1 = { a=>1,    c=>1, d=>{  da =>[1]} };
    my $hash2 = { a=>2, "+c"=>2, d=>{"+da"=>[2]} };
    die $res->{error} if $res->{error};
    print $res->{result}; # { a=>2, c=>-1, d => { da=>[1,2] } }

DESCRIPTION

There are already several modules on CPAN to do recursive data structure merging. The main difference between those modules and Data::PrefixMerge is that Data::PrefixMerge supports "merge prefixes" in hash keys. Merge prefixes instruct how the merge should be done (merging mode).

Merging prefixes can also be turned off via configuration (see CONFIG section), in which Data::PrefixMerge will behave like most other merge modules.

MERGING MODES

NORMAL (no prefix)

 prefix_merge({a=>11, b=>12}, {b=>22, c=>23}); # {a=>11, b=>22, c=>23}

ADD ('+' prefix)

 prefix_merge({i=>3}, {"+i"=>4, "+j"=>1}); # {i=>7, j=>1}
 prefix_merge({a=>[1]}, {"+a"=>[2, 3]}); # {a=>[1, 2, 3]}

Additive merge on hashes will be treated like a normal merge.

CONCAT ('.' prefix)

 prefix_merge({i=>3}, {".i"=>4, ".j"=>1}); # {i=>34, j=>1}

Concative merge on arrays will be treated like additive merge.

SUBTRACT ('-' prefix)

 prefix_merge({i=>3}, {"-i"=>4}); # {i=>-1}
 prefix_merge({a=>["a","b","c"]}, {"-a"=>["b"]}); # {a=>["a","c"]}

Subtractive merge on hashes is not defined.

DELETE ('.' prefix)

 prefix_merge({x=>WHATEVER}, {"!x"=>WHATEVER}); # {}

KEEP ('*' prefix on the left side)

If you add '*' prefix on the left side, it will be protected from being replaced.

 prefix_merge({'*x'=>WHATEVER1}, {"x"=>WHATEVER2}); # {x=>WHATEVER1}

FUNCTIONS

prefix_merge($a, $b[, $config_vars])

A non-OO wrapper for merge() method. Exported by default. See merge method for default.

ATTRIBUTES

config

A hashref for config. See CONFIG section below.

METHODS

merge($a, $b)

Merge two nested data structures. Returns the result hash: { success=>0|1, error=>'...', result=>..., backup=>... }. The 'error' key is set to contain an error message if there is an error. The merge result is in the 'result' key. The 'backup' key contains replaced elements from the original hash/array.

CONFIG

You can set config like this:

 $merger->config->{CONFIGVAR} = 'VALUE';

Available config variables:

recurse_hash => 0 or 1

Whether to recursively merge hash. Default is 1.

With recurse_hash set to 1, hashes will be recursively merged:

 prefix_merge({h=>{a=>1}}, {h=>{b=>1}}); # {h=>{a=>1, b=>1}}

With recurse_hash set to 0, hashes on the left side will just be replaced with hashes on the right side:

 prefix_merge({h=>{a=>1}}, {h=>{b=>1}}); # {h=>{b=>1}}

recurse_array => 0 or 1

Whether to recursively merge hash. Default is 0.

With recurse_array set to 1, arrays will be recursively merged:

 prefix_merge([1, 1], [2]); # [2, 1]

With recurse_array set to 0, array on the left side will just be replaced with array on the right side:

 prefix_merge([1, 1], [2]); # [2]

parse_hash_key_prefix => 0 or 1

Whether to parse merge prefix for in hash keys. Default is 1. If you set this to 0, merging behaviour is similar to most other nested merge modules.

With parse_hash_key_prefix set to 1:

 prefix_merge({a=>1}, {"+a"=>2}); # {a=>3}

With parse_hash_key_prefix set to 0:

 prefix_merge({a=>1}, {"+a"=>2}); # {a=>1, "+a"=>2}

wanted_path => ARRAYREF

Default is undef. If you set this, 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:

 prefix_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 },
      tommie => undef,
      jimmy  => undef,
    }
    groups => undef,
   }

default_merge_mode => 'NORMAL' | 'ADD' | 'CONCAT' | 'SUBTRACT' | 'DELETE'

Default is 'NORMAL'.

Example:

When setting default_merge_mode to NORMAL (DEFAULT):

 prefix_merge(3, 4); # 4

When setting default_merge_mode to ADD:

 prefix_merge(3, 4); # 7

SEE ALSO

Data::Merger (from Data-Utilities) Hash::Merge Hash::Merge::Simple Data::Schema (a module that uses this module)

AUTHOR

Steven Haryanto, <steven at masterweb.net>

BUGS

Please report any bugs or feature requests to bug-data-prefixmerge at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Data-PrefixMerge. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Data::PrefixMerge

You can also look for information at:

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

Copyright 2009 Steven Haryanto, all rights reserved.

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