1Hash::Merge(3) User Contributed Perl Documentation Hash::Merge(3)
2
6 Hash::Merge - Merges arbitrarily deep hashes into a single hash
7
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 my %c = %{ merge( \%a, \%b ) };
21 Hash::Merge::set_behavior('RIGHT_PRECEDENT');
23 # This is the same as above
25 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 # Also there is OO interface.
47 my $merger = Hash::Merge->new('LEFT_PRECEDENT');
49 my %c = %{ $merger->merge( \%a, \%b ) };
50 # 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 # 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 # 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
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 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 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 Left Precedence
87 This is the default behavior.
88 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 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 Right Precedence
98 Same as Left Precedence, but with the right hash values never being
99 lost
100 my $merge = Hash::Merge->new('RIGHT_PRECEDENT');
102 $merge->set_behavior('RIGHT_PRECEDENT');
103 Hash::Merge::set_behavior('RIGHT_PRECEDENT');
104 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 my $merge = Hash::Merge->new('STORAGE_PRECEDENT');
112 $merge->set_behavior('STORAGE_PRECEDENT');
113 Hash::Merge::set_behavior('STORAGE_PRECEDENT');
114 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 my $merge = Hash::Merge->new('RETAINMENT_PRECEDENT');
120 $merge->set_behavior('RETAINMENT_PRECEDENT');
121 Hash::Merge::set_behavior('RETAINMENT_PRECEDENT');
122 Specific descriptions of how these work are detailed below.
124 merge ( <hashref>, <hashref> )
126 Merges two hashes given the rules specified. Returns a reference
127 to the new hash.
128 _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 _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 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 get_clone_behavior( )
146 Returns the current behavior for data cloning.
147 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 get_behavior( )
153 Returns the behavior that is currently in use by Hash::Merge.
154 specify_behavior( <hashref>, [<name>] ) [deprecated]
156 Alias for "add_behavior_spec".
157 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 %spec = ( ...SCALAR => { ARRAY => sub { [ $_[0], @$_[1] ] }, ... } } );
172 Note that you can import _hashify and _merge_hashes into your
174 program's namespace with the 'custom' tag.
175 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 If no such name is known referring to an behavior spec, nothing is
181 returned.
182
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 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 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 (*) note that merge calls _merge_hashes, hashify calls _hashify.
211
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 This library is free software. You can redistribute it and/or modify
223 it under the same terms as Perl itself.
224perl v5.38.0 2023-07-20 Hash::Merge(3)