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

VERSION
    version 0.07

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.

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
    <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:

    *   RT: CPAN's request tracker

        <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Data-PrefixMerge>

    *   AnnoCPAN: Annotated CPAN documentation

        <http://annocpan.org/dist/Data-PrefixMerge>

    *   CPAN Ratings

        <http://cpanratings.perl.org/d/Data-PrefixMerge>

    *   Search CPAN

        <http://search.cpan.org/dist/Data-PrefixMerge/>

AUTHOR
      Steven Haryanto <stevenharyanto@gmail.com>

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.