/ 
Data-PrefixMerge-0.06
/ Data::PrefixMerge

NAME

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

VERSION

Version 0.06

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 Data::PrefixMerge::Config), in which Data::PrefixMerge will behave like most other merge modules.

MERGING MODES

NORMAL (optional '*' prefix on left/right side)

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

ADD ('+' prefix on the right side)

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 on the right side)

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

Concative merge on arrays will be treated like additive merge.

SUBTRACT ('-' prefix on the right side)

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 on the right side)

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

KEEP ('^' prefix on the left/right side)

If you add '^' prefix on the left side, it will be protected from being replaced/deleted/etc.

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

For hashes, KEEP mode means that all keys on the left side will not be replaced/modified/deleted, *but* you can still add more keys from the right side hash.

prefix_merge({a=>1, b=>2, c=>3},
             {a=>4, '^c'=>1, d=>5},
             'KEEP');
           # {a=>1, b=>2, c=>3, d=>5}

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 Data::PrefixMerge::Config.

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.

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.