Author image Steven Haryanto
and 1 contributors


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


version 0.12


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


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.


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},
            # {a=>1, b=>2, c=>3, d=>5}


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

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



A hashref for config. See Data::PrefixMerge::Config.


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, $maxdepth)

Recurse $data and remove keep prefix ("^") in hash keys. $maxdepth is maximum depth, default is -1 (unlimited).

Example: $merger->remove_keep_prefixes([1, "^a", {"^b"=>1}]); # [1, "^a", {b=>1}]


Alias for remove_keep_prefixes.


Data::Merger (from Data-Utilities)



Data::Schema (a module that uses this module)


Please report any bugs or feature requests to bug-data-prefixmerge at, 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.


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

    perldoc Data::PrefixMerge

You can also look for information at:


  Steven Haryanto <>


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.