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.09
++
/ Data::PrefixMerge

NAME

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

VERSION

version 0.09

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)

Recurse $data and remove keep prefix ("^") in hash keys.

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

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.