NAME Data::PrefixMerge - Merge two nested data structures, with merging mode prefix on hash keys VERSION version 0.11 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 more details. 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. remove_keep_prefixes($data, $maxlevel) Recurse $data and remove keep prefix ("^") in hash keys. $maxlevel is maximum depth, default is -1 (unlimited). Example: $merger->remove_keep_prefixes([1, "^a", {"^b"=>1}]); # [1, "^a", {b=>1}] remove_keep_prefix Alias for remove_keep_prefixes. SEE ALSO Data::Merger (from Data-Utilities) Hash::Merge Hash::Merge::Simple Data::Schema (a module that uses this module) BUGS Please report any bugs or feature requests to "bug-data-prefixmerge at rt.cpan.org", or through the web interface at . 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: * RT: CPAN's request tracker * AnnoCPAN: Annotated CPAN documentation * CPAN Ratings * Search CPAN AUTHOR Steven Haryanto COPYRIGHT AND LICENSE This software is copyright (c) 2009 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.