Merge(3) User Contributed Perl Documentation Merge(3)NAMEHash::Merge - Merges arbitrarily deep hashes into a single hash
SYNOPSIS
use Hash::Merge qw( merge );
my %a = (
'foo' => 1,
'bar' => [ qw( a b e ) ],
'querty' => { 'bob' => 'alice' },
);
my %b = (
'foo' => 2,
'bar' => [ qw(c d) ],
'querty' => { 'ted' => 'margeret' },
);
my %c = %{ merge( \%a, \%b ) };
Hash::Merge::set_behavior( 'RIGHT_PRECEDENT' );
# This is the same as above
Hash::Merge::specify_behavior(
{
'SCALAR' => {
'SCALAR' => sub { $_[1] },
'ARRAY' => sub { [ $_[0], @{$_[1]} ] },
'HASH' => sub { $_[1] },
},
'ARRAY => {
'SCALAR' => sub { $_[1] },
'ARRAY' => sub { [ @{$_[0]}, @{$_[1]} ] },
'HASH' => sub { $_[1] },
},
'HASH' => {
'SCALAR' => sub { $_[1] },
'ARRAY' => sub { [ values %{$_[0]}, @{$_[1]} ] },
'HASH' => sub { Hash::Merge::_merge_hashes( $_[0], $_[1] ) },
},
},
'My Behavior',
);
# Also there is OO interface.
my $merge = Hash::Merge->new( 'LEFT_PRECEDENT' );
my %c = %{ $merge->merge( \%a, \%b ) };
# All behavioral changes (e.g. $merge->set_behavior(...)), called on an object remain specific to that object
# The legacy "Global Setting" behavior is respected only when new called as a non-OO function.
DESCRIPTIONHash::Merge merges two arbitrarily deep hashes into a single hash.
That is, at any level, it will add non-conflicting key-value pairs from
one hash to the other, and follows a set of specific rules when there
are key value conflicts (as outlined below). The hash is followed
recursively, so that deeply nested hashes that are at the same level
will be merged when the parent hashes are merged. Please note that
self-referencing hashes, or recursive references, are not handled well
by this method.
Values in hashes are considered to be either ARRAY references, HASH
references, or otherwise are treated as SCALARs. By default, the data
passed to the merge function will be cloned using the Clone module;
however, if necessary, this behavior can be changed to use as many of
the original values as possible. (See "set_clone_behavior").
Because there are a number of possible ways that one may want to merge
values when keys are conflicting, Hash::Merge provides several preset
methods for your convenience, as well as a way to define you own.
These are (currently):
Left Precedence
This is the default behavior.
The values buried in the left hash will never be lost; any values
that can be added from the right hash will be attempted.
my $merge = Hash::Merge->new();
my $merge = Hash::Merge->new('LEFT_PRECEDENT');
$merge->set_set_behavior('LEFT_PRECEDENT')
Hash::Merge::set_set_behavior('LEFT_PRECEDENT')
Right Precedence
Same as Left Precedence, but with the right hash values never being
lost
my $merge = Hash::Merge->new('RIGHT_PRECEDENT');
$merge->set_set_behavior('RIGHT_PRECEDENT')
Hash::Merge::set_set_behavior('RIGHT_PRECEDENT')
Storage Precedence
If conflicting keys have two different storage mediums, the
'bigger' medium will win; arrays are preferred over scalars, hashes
over either. The other medium will try to be fitted in the other,
but if this isn't possible, the data is dropped.
my $merge = Hash::Merge->new('STORAGE_PRECEDENT');
$merge->set_set_behavior('STORAGE_PRECEDENT')
Hash::Merge::set_set_behavior('STORAGE_PRECEDENT')
Retainment Precedence
No data will be lost; scalars will be joined with arrays, and
scalars and arrays will be 'hashified' to fit them into a hash.
my $merge = Hash::Merge->new('RETAINMENT_PRECEDENT');
$merge->set_set_behavior('RETAINMENT_PRECEDENT')
Hash::Merge::set_set_behavior('RETAINMENT_PRECEDENT')
Specific descriptions of how these work are detailed below.
merge ( <hashref>, <hashref> )
Merges two hashes given the rules specified. Returns a reference
to the new hash.
_hashify( <scalar>|<arrayref> ) -- INTERNAL FUNCTION
Returns a reference to a hash created from the scalar or array
reference, where, for the scalar value, or each item in the array,
there is a key and it's value equal to that specific value.
Example, if you pass scalar '3', the hash will be { 3 => 3 }.
_merge_hashes( <hashref>, <hashref> ) -- INTERNAL FUNCTION
Actually does the key-by-key evaluation of two hashes and returns
the new merged hash. Note that this recursively calls "merge".
set_clone_behavior( <scalar> )
Sets how the data cloning is handled by Hash::Merge. If this is
true, then data will be cloned; if false, then original data will
be used whenever possible. By default, cloning is on (set to
true).
get_clone_behavior( )
Returns the current behavior for data cloning.
set_behavior( <scalar> )
Specify which built-in behavior for merging that is desired. The
scalar must be one of those given below.
get_behavior( )
Returns the behavior that is currently in use by Hash::Merge.
specify_behavior( <hashref>, [<name>] )
Specify a custom merge behavior for Hash::Merge. This must be a
hashref defined with (at least) 3 keys, SCALAR, ARRAY, and HASH;
each of those keys must have another hashref with (at least) the
same 3 keys defined. Furthermore, the values in those hashes must
be coderefs. These will be called with two arguments, the left and
right values for the merge. Your coderef should return either a
scalar or an array or hash reference as per your planned behavior.
If necessary, use the functions _hashify and _merge_hashes as
helper functions for these. For example, if you want to add the
left SCALAR to the right ARRAY, you can have your behavior
specification include:
%spec = ( ...SCALAR => { ARRAY => sub { [ $_[0], @$_[1] ] }, ... } } );
Note that you can import _hashify and _merge_hashes into your
program's namespace with the 'custom' tag.
BUILT-IN BEHAVIORS
Here is the specifics on how the current internal behaviors are called,
and what each does. Assume that the left value is given as $a, and the
right as $b (these are either scalars or appropriate references)
LEFT TYPE RIGHT TYPE LEFT_PRECEDENT RIGHT_PRECEDENT
SCALAR SCALAR $a $b
SCALAR ARRAY $a ( $a, @$b )
SCALAR HASH $a %$b
ARRAY SCALAR ( @$a, $b ) $b
ARRAY ARRAY ( @$a, @$b ) ( @$a, @$b )
ARRAY HASH ( @$a, values %$b ) %$b
HASH SCALAR %$a $b
HASH ARRAY %$a ( values %$a, @$b )
HASH HASH merge( %$a, %$b ) merge( %$a, %$b )
LEFT TYPE RIGHT TYPE STORAGE_PRECEDENT RETAINMENT_PRECEDENT
SCALAR SCALAR $a ( $a ,$b )
SCALAR ARRAY ( $a, @$b ) ( $a, @$b )
SCALAR HASH %$b merge( hashify( $a ), %$b )
ARRAY SCALAR ( @$a, $b ) ( @$a, $b )
ARRAY ARRAY ( @$a, @$b ) ( @$a, @$b )
ARRAY HASH %$b merge( hashify( @$a ), %$b )
HASH SCALAR %$a merge( %$a, hashify( $b ) )
HASH ARRAY %$a merge( %$a, hashify( @$b ) )
HASH HASH merge( %$a, %$b ) merge( %$a, %$b )
(*) note that merge calls _merge_hashes, hashify calls _hashify.
CAVEATS
This will not handle self-referencing/recursion within hashes well.
Plans for a future version include incorporate deep recursion
protection.
As of Feb 16, 2002, ActiveState Perl's PPM of Clone.pm is only at 0.09.
This version does not support the cloning of scalars if passed to the
function. This is fixed by 0.10 (and currently, Clone.pm is at 0.13).
So while most other users can upgrade their Clone.pm appropriately (and
I could put this as a requirement into the Makefile.PL), those using
ActiveState would lose out on the ability to use this module.
(Clone.pm is not pure perl, so it's not simply a matter of moving the
newer file into place). Thus, for the time being, a check is done at
the start of loading of this module to see if a newer version of clone
is around. Then, all cloning calls have been wrapped in the internal
_my_clone function to block any scalar clones if Clone.pm is too old.
However, this also prevents the cloning of anything that isn't a hash
or array under the same conditions. Once ActiveState updates their
Clone, I'll remove this wrapper.
AUTHOR
Michael K. Neylon <mneylon-pm@masemware.com>
COPYRIGHT
Copyright (c) 2001,2002 Michael K. Neylon. All rights reserved.
This library is free software. You can redistribute it and/or modify
it under the same terms as Perl itself.
perl v5.16.2 2010-02-15 Merge(3)
