1Hash::Merge(3)        User Contributed Perl Documentation       Hash::Merge(3)
2
3
4

NAME

6       Hash::Merge - Merges arbitrarily deep hashes into a single hash
7

SYNOPSIS

9           my %a = (
10               'foo'    => 1,
11               'bar'    => [qw( a b e )],
12               'querty' => { 'bob' => 'alice' },
13           );
14           my %b = (
15               'foo'    => 2,
16               'bar'    => [qw(c d)],
17               'querty' => { 'ted' => 'margeret' },
18           );
19
20           my %c = %{ merge( \%a, \%b ) };
21
22           Hash::Merge::set_behavior('RIGHT_PRECEDENT');
23
24           # This is the same as above
25
26           Hash::Merge::add_behavior_spec(
27               {   'SCALAR' => {
28                       'SCALAR' => sub { $_[1] },
29                       'ARRAY'  => sub { [ $_[0], @{ $_[1] } ] },
30                       'HASH'   => sub { $_[1] },
31                   },
32                   'ARRAY' => {
33                       'SCALAR' => sub { $_[1] },
34                       'ARRAY'  => sub { [ @{ $_[0] }, @{ $_[1] } ] },
35                       'HASH'   => sub { $_[1] },
36                   },
37                   'HASH' => {
38                       'SCALAR' => sub { $_[1] },
39                       'ARRAY'  => sub { [ values %{ $_[0] }, @{ $_[1] } ] },
40                       'HASH'   => sub { Hash::Merge::_merge_hashes( $_[0], $_[1] ) },
41                   },
42               },
43               'My Behavior',
44           );
45
46           # Also there is OO interface.
47
48           my $merger = Hash::Merge->new('LEFT_PRECEDENT');
49           my %c = %{ $merger->merge( \%a, \%b ) };
50
51           # All behavioral changes (e.g. $merge->set_behavior(...)), called on an object remain specific to that object
52           # The legacy "Global Setting" behavior is respected only when new called as a non-OO function.
53
54           # re-use globally specified behavior
55           my $merger = Hash::Merge->new();
56           $merger->add_behavior_spec(Hash::Merge::get_behavior_spec("My Behavior"), "My Behavior");
57           my %c = %{ $merger->merge( \%a, \%b ) };
58
59           # re-use externally specified behavior
60           use Hash::Merge::Extra ();
61           my $merger = Hash::Merge->new();
62           $merger->add_behavior_spec(Hash::Merge::Extra::L_REPLACE, "L_REPLACE");
63           my %c = %{ $merger->merge( \%a, \%b ) };
64

DESCRIPTION

66       Hash::Merge merges two arbitrarily deep hashes into a single hash.
67       That is, at any level, it will add non-conflicting key-value pairs from
68       one hash to the other, and follows a set of specific rules when there
69       are key value conflicts (as outlined below).  The hash is followed
70       recursively, so that deeply nested hashes that are at the same level
71       will be merged when the parent hashes are merged.  Please note that
72       self-referencing hashes, or recursive references, are not handled well
73       by this method.
74
75       Values in hashes are considered to be either ARRAY references, HASH
76       references, or otherwise are treated as SCALARs.  By default, the data
77       passed to the merge function will be cloned using the Clone module;
78       however, if necessary, this behavior can be changed to use as many of
79       the original values as possible.  (See "set_clone_behavior").
80
81       Because there are a number of possible ways that one may want to merge
82       values when keys are conflicting, Hash::Merge provides several preset
83       methods for your convenience, as well as a way to define you own.
84       These are (currently):
85
86       Left Precedence
87           This is the default behavior.
88
89           The values buried in the left hash will never be lost; any values
90           that can be added from the right hash will be attempted.
91
92               my $merge = Hash::Merge->new();
93               my $merge = Hash::Merge->new('LEFT_PRECEDENT');
94               $merge->set_behavior('LEFT_PRECEDENT');
95               Hash::Merge::set_behavior('LEFT_PRECEDENT');
96
97       Right Precedence
98           Same as Left Precedence, but with the right hash values never being
99           lost
100
101               my $merge = Hash::Merge->new('RIGHT_PRECEDENT');
102               $merge->set_behavior('RIGHT_PRECEDENT');
103               Hash::Merge::set_behavior('RIGHT_PRECEDENT');
104
105       Storage Precedence
106           If conflicting keys have two different storage mediums, the
107           'bigger' medium will win; arrays are preferred over scalars, hashes
108           over either.  The other medium will try to be fitted in the other,
109           but if this isn't possible, the data is dropped.
110
111               my $merge = Hash::Merge->new('STORAGE_PRECEDENT');
112               $merge->set_behavior('STORAGE_PRECEDENT');
113               Hash::Merge::set_behavior('STORAGE_PRECEDENT');
114
115       Retainment Precedence
116           No data will be lost; scalars will be joined with arrays, and
117           scalars and arrays will be 'hashified' to fit them into a hash.
118
119               my $merge = Hash::Merge->new('RETAINMENT_PRECEDENT');
120               $merge->set_behavior('RETAINMENT_PRECEDENT');
121               Hash::Merge::set_behavior('RETAINMENT_PRECEDENT');
122
123       Specific descriptions of how these work are detailed below.
124
125       merge ( <hashref>, <hashref> )
126           Merges two hashes given the rules specified.  Returns a reference
127           to the new hash.
128
129       _hashify( <scalar>|<arrayref> ) -- INTERNAL FUNCTION
130           Returns a reference to a hash created from the scalar or array
131           reference, where, for the scalar value, or each item in the array,
132           there is a key and it's value equal to that specific value.
133           Example, if you pass scalar '3', the hash will be { 3 => 3 }.
134
135       _merge_hashes( <hashref>, <hashref> ) -- INTERNAL FUNCTION
136           Actually does the key-by-key evaluation of two hashes and returns
137           the new merged hash.  Note that this recursively calls "merge".
138
139       set_clone_behavior( <scalar> )
140           Sets how the data cloning is handled by Hash::Merge.  If this is
141           true, then data will be cloned; if false, then original data will
142           be used whenever possible.  By default, cloning is on (set to
143           true).
144
145       get_clone_behavior( )
146           Returns the current behavior for data cloning.
147
148       set_behavior( <scalar> )
149           Specify which built-in behavior for merging that is desired.  The
150           scalar must be one of those given below.
151
152       get_behavior( )
153           Returns the behavior that is currently in use by Hash::Merge.
154
155       specify_behavior( <hashref>, [<name>] ) [deprecated]
156           Alias for "add_behavior_spec".
157
158       add_behavior_spec( <hashref>, [<name>] )
159           Add a custom merge behavior spec for Hash::Merge.  This must be a
160           hashref defined with (at least) 3 keys, SCALAR, ARRAY, and HASH;
161           each of those keys must have another hashref with (at least) the
162           same 3 keys defined.  Furthermore, the values in those hashes must
163           be coderefs.  These will be called with two arguments, the left and
164           right values for the merge.  Your coderef should return either a
165           scalar or an array or hash reference as per your planned behavior.
166           If necessary, use the functions _hashify and _merge_hashes as
167           helper functions for these.  For example, if you want to add the
168           left SCALAR to the right ARRAY, you can have your behavior
169           specification include:
170
171               %spec = ( ...SCALAR => { ARRAY => sub { [ $_[0], @$_[1] ] }, ... } } );
172
173           Note that you can import _hashify and _merge_hashes into your
174           program's namespace with the 'custom' tag.
175
176       get_behavior_spec( [<name>] )
177           Return a previously defined merge behavior spec. If name ism't
178           specified, the same default as add_behavior_spec is applied.
179
180           If no such name is known referring to an behavior spec, nothing is
181           returned.
182

BUILT-IN BEHAVIORS

184       Here is the specifics on how the current internal behaviors are called,
185       and what each does.  Assume that the left value is given as $a, and the
186       right as $b (these are either scalars or appropriate references)
187
188           LEFT TYPE    RIGHT TYPE    LEFT_PRECEDENT       RIGHT_PRECEDENT
189            SCALAR       SCALAR        $a                   $b
190            SCALAR       ARRAY         $a                   ( $a, @$b )
191            SCALAR       HASH          $a                   %$b
192            ARRAY        SCALAR        ( @$a, $b )          $b
193            ARRAY        ARRAY         ( @$a, @$b )         ( @$a, @$b )
194            ARRAY        HASH          ( @$a, values %$b )  %$b
195            HASH         SCALAR        %$a                  $b
196            HASH         ARRAY         %$a                  ( values %$a, @$b )
197            HASH         HASH          merge( %$a, %$b )    merge( %$a, %$b )
198
199           LEFT TYPE    RIGHT TYPE    STORAGE_PRECEDENT    RETAINMENT_PRECEDENT
200            SCALAR       SCALAR        $a                   ( $a ,$b )
201            SCALAR       ARRAY         ( $a, @$b )          ( $a, @$b )
202            SCALAR       HASH          %$b                  merge( hashify( $a ), %$b )
203            ARRAY        SCALAR        ( @$a, $b )          ( @$a, $b )
204            ARRAY        ARRAY         ( @$a, @$b )         ( @$a, @$b )
205            ARRAY        HASH          %$b                  merge( hashify( @$a ), %$b )
206            HASH         SCALAR        %$a                  merge( %$a, hashify( $b ) )
207            HASH         ARRAY         %$a                  merge( %$a, hashify( @$b ) )
208            HASH         HASH          merge( %$a, %$b )    merge( %$a, %$b )
209
210       (*) note that merge calls _merge_hashes, hashify calls _hashify.
211

AUTHOR

213       Michael K. Neylon <mneylon-pm@masemware.com>, Daniel Muey
214       <dmuey@cpan.org>, Jens Rehsack <rehsack@cpan.org>, Stefan Hermes
215       <hermes@cpan.org>
216
218       Copyright (c) 2001,2002 Michael K. Neylon. All rights reserved.
219       Copyright (c) 2013-2020 Jens Rehsack. All rights reserved.  Copyright
220       (c) 2017-2020 Stefan Hermes. All rights reserved.
221
222       This library is free software.  You can redistribute it and/or modify
223       it under the same terms as Perl itself.
224
225
226
227perl v5.36.0                      2022-07-22                    Hash::Merge(3)
Impressum