.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Hash::Merge 3pm"
.TH Hash::Merge 3pm "2020-08-04" "perl v5.30.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Hash::Merge \- Merges arbitrarily deep hashes into a single hash
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 10
\&    my %a = (
\&        \*(Aqfoo\*(Aq    => 1,
\&        \*(Aqbar\*(Aq    => [qw( a b e )],
\&        \*(Aqquerty\*(Aq => { \*(Aqbob\*(Aq => \*(Aqalice\*(Aq },
\&    );
\&    my %b = (
\&        \*(Aqfoo\*(Aq    => 2,
\&        \*(Aqbar\*(Aq    => [qw(c d)],
\&        \*(Aqquerty\*(Aq => { \*(Aqted\*(Aq => \*(Aqmargeret\*(Aq },
\&    );
\&    
\&    my %c = %{ merge( \e%a, \e%b ) };
\&    
\&    Hash::Merge::set_behavior(\*(AqRIGHT_PRECEDENT\*(Aq);
\&    
\&    # This is the same as above
\&    
\&    Hash::Merge::add_behavior_spec(
\&        {   \*(AqSCALAR\*(Aq => {
\&                \*(AqSCALAR\*(Aq => sub { $_[1] },
\&                \*(AqARRAY\*(Aq  => sub { [ $_[0], @{ $_[1] } ] },
\&                \*(AqHASH\*(Aq   => sub { $_[1] },
\&            },
\&            \*(AqARRAY\*(Aq => {
\&                \*(AqSCALAR\*(Aq => sub { $_[1] },
\&                \*(AqARRAY\*(Aq  => sub { [ @{ $_[0] }, @{ $_[1] } ] },
\&                \*(AqHASH\*(Aq   => sub { $_[1] },
\&            },
\&            \*(AqHASH\*(Aq => {
\&                \*(AqSCALAR\*(Aq => sub { $_[1] },
\&                \*(AqARRAY\*(Aq  => sub { [ values %{ $_[0] }, @{ $_[1] } ] },
\&                \*(AqHASH\*(Aq   => sub { Hash::Merge::_merge_hashes( $_[0], $_[1] ) },
\&            },
\&        },
\&        \*(AqMy Behavior\*(Aq,
\&    );
\&    
\&    # Also there is OO interface.
\&    
\&    my $merger = Hash::Merge\->new(\*(AqLEFT_PRECEDENT\*(Aq);
\&    my %c = %{ $merger\->merge( \e%a, \e%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.
\&
\&    # re\-use globally specified behavior
\&    my $merger = Hash::Merge\->new();
\&    $merger\->add_behavior_spec(Hash::Merge::get_behavior_spec("My Behavior"), "My Behavior");
\&    my %c = %{ $merger\->merge( \e%a, \e%b ) };
\&
\&    # re\-use externally specified behavior
\&    use Hash::Merge::Extra ();
\&    my $merger = Hash::Merge\->new();
\&    $merger\->add_behavior_spec(Hash::Merge::Extra::L_REPLACE, "L_REPLACE");
\&    my %c = %{ $merger\->merge( \e%a, \e%b ) };
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Hash::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.  \fBPlease note that self-referencing
hashes, or recursive references, are not handled well by this method.\fR
.PP
Values in hashes are considered to be either \s-1ARRAY\s0 references, 
\&\s-1HASH\s0 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 \f(CW\*(C`set_clone_behavior\*(C'\fR).
.PP
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):
.IP "Left Precedence" 4
.IX Item "Left Precedence"
This is the default behavior.
.Sp
The values buried in the left hash will never
be lost; any values that can be added from the right hash will be
attempted.
.Sp
.Vb 4
\&    my $merge = Hash::Merge\->new();
\&    my $merge = Hash::Merge\->new(\*(AqLEFT_PRECEDENT\*(Aq);
\&    $merge\->set_behavior(\*(AqLEFT_PRECEDENT\*(Aq);
\&    Hash::Merge::set_behavior(\*(AqLEFT_PRECEDENT\*(Aq);
.Ve
.IP "Right Precedence" 4
.IX Item "Right Precedence"
Same as Left Precedence, but with the right
hash values never being lost
.Sp
.Vb 3
\&    my $merge = Hash::Merge\->new(\*(AqRIGHT_PRECEDENT\*(Aq);
\&    $merge\->set_behavior(\*(AqRIGHT_PRECEDENT\*(Aq);
\&    Hash::Merge::set_behavior(\*(AqRIGHT_PRECEDENT\*(Aq);
.Ve
.IP "Storage Precedence" 4
.IX Item "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.
.Sp
.Vb 3
\&    my $merge = Hash::Merge\->new(\*(AqSTORAGE_PRECEDENT\*(Aq);
\&    $merge\->set_behavior(\*(AqSTORAGE_PRECEDENT\*(Aq);
\&    Hash::Merge::set_behavior(\*(AqSTORAGE_PRECEDENT\*(Aq);
.Ve
.IP "Retainment Precedence" 4
.IX Item "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.
.Sp
.Vb 3
\&    my $merge = Hash::Merge\->new(\*(AqRETAINMENT_PRECEDENT\*(Aq);
\&    $merge\->set_behavior(\*(AqRETAINMENT_PRECEDENT\*(Aq);
\&    Hash::Merge::set_behavior(\*(AqRETAINMENT_PRECEDENT\*(Aq);
.Ve
.PP
Specific descriptions of how these work are detailed below.
.IP "merge ( <hashref>, <hashref> )" 4
.IX Item "merge ( <hashref>, <hashref> )"
Merges two hashes given the rules specified.  Returns a reference to 
the new hash.
.IP "_hashify( <scalar>|<arrayref> ) \*(-- \s-1INTERNAL FUNCTION\s0" 4
.IX Item "_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 }.
.IP "_merge_hashes( <hashref>, <hashref> ) \*(-- \s-1INTERNAL FUNCTION\s0" 4
.IX Item "_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 \f(CW\*(C`merge\*(C'\fR.
.IP "set_clone_behavior( <scalar> )" 4
.IX Item "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).
.IP "get_clone_behavior( )" 4
.IX Item "get_clone_behavior( )"
Returns the current behavior for data cloning.
.IP "set_behavior( <scalar> )" 4
.IX Item "set_behavior( <scalar> )"
Specify which built-in behavior for merging that is desired.  The scalar
must be one of those given below.
.IP "get_behavior( )" 4
.IX Item "get_behavior( )"
Returns the behavior that is currently in use by Hash::Merge.
.IP "specify_behavior( <hashref>, [<name>] ) [deprecated]" 4
.IX Item "specify_behavior( <hashref>, [<name>] ) [deprecated]"
Alias for \f(CW\*(C`add_behavior_spec\*(C'\fR.
.IP "add_behavior_spec( <hashref>, [<name>] )" 4
.IX Item "add_behavior_spec( <hashref>, [<name>] )"
Add a custom merge behavior spec for Hash::Merge.  This must be a hashref
defined with (at least) 3 keys, \s-1SCALAR, ARRAY,\s0 and \s-1HASH\s0; 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 \s-1SCALAR\s0 to the right \s-1ARRAY,\s0 you can have your
behavior specification include:
.Sp
.Vb 1
\&    %spec = ( ...SCALAR => { ARRAY => sub { [ $_[0], @$_[1] ] }, ... } } );
.Ve
.Sp
Note that you can import _hashify and _merge_hashes into your program's
namespace with the 'custom' tag.
.IP "get_behavior_spec( [<name>] )" 4
.IX Item "get_behavior_spec( [<name>] )"
Return a previously defined merge behavior spec. If name ism't specified,
the same default as add_behavior_spec is applied.
.Sp
If no such name is known referring to an behavior spec, nothing is returned.
.SH "BUILT-IN BEHAVIORS"
.IX Header "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 \f(CW$a\fR, and
the right as \f(CW$b\fR (these are either scalars or appropriate references)
.PP
.Vb 10
\&    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 )
.Ve
.PP
(*) note that merge calls _merge_hashes, hashify calls _hashify.
.SH "AUTHOR"
.IX Header "AUTHOR"
Michael K. Neylon <mneylon\-pm@masemware.com>,
Daniel Muey <dmuey@cpan.org>,
Jens Rehsack <rehsack@cpan.org>,
Stefan Hermes <hermes@cpan.org>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2001,2002 Michael K. Neylon. All rights reserved.
Copyright (c) 2013\-2020 Jens Rehsack. All rights reserved.
Copyright (c) 2017\-2020 Stefan Hermes. All rights reserved.
.PP
This library is free software.  You can redistribute it and/or modify it 
under the same terms as Perl itself.