1Merge(3) User Contributed Perl Documentation Merge(3)
2
6 Hash::Merge - Merges arbitrarily deep hashes into a single hash
7
9 use Hash::Merge qw( merge );
10 my %a = (
11 'foo' => 1,
12 'bar' => [ qw( a b e ) ],
13 'querty' => { 'bob' => 'alice' },
14 );
15 my %b = (
16 'foo' => 2,
17 'bar' => [ qw(c d) ],
18 'querty' => { 'ted' => 'margeret' },
19 );
20 my %c = %{ merge( \%a, \%b ) };
22 Hash::Merge::set_behavior( 'RIGHT_PRECEDENT' );
24 # This is the same as above
26 Hash::Merge::specify_behavior(
28 {
29 'SCALAR' => {
30 'SCALAR' => sub { $_[1] },
31 'ARRAY' => sub { [ $_[0], @{$_[1]} ] },
32 'HASH' => sub { $_[1] },
33 },
34 'ARRAY => {
35 'SCALAR' => sub { $_[1] },
36 'ARRAY' => sub { [ @{$_[0]}, @{$_[1]} ] },
37 'HASH' => sub { $_[1] },
38 },
39 'HASH' => {
40 'SCALAR' => sub { $_[1] },
41 'ARRAY' => sub { [ values %{$_[0]}, @{$_[1]} ] },
42 'HASH' => sub { Hash::Merge::_merge_hashes( $_[0], $_[1] ) },
43 },
44 },
45 'My Behavior',
46 );
47 # Also there is OO interface.
49 my $merge = Hash::Merge->new( 'LEFT_PRECEDENT' );
51 my %c = %{ $merge->merge( \%a, \%b ) };
52 # All behavioral changes (e.g. $merge->set_behavior(...)), called on an object remain specific to that object
54 # The legacy "Global Setting" behavior is respected only when new called as a non-OO function.
55
57 Hash::Merge merges two arbitrarily deep hashes into a single hash.
58 That is, at any level, it will add non-conflicting key-value pairs from
59 one hash to the other, and follows a set of specific rules when there
60 are key value conflicts (as outlined below). The hash is followed
61 recursively, so that deeply nested hashes that are at the same level
62 will be merged when the parent hashes are merged. Please note that
63 self-referencing hashes, or recursive references, are not handled well
64 by this method.
65 Values in hashes are considered to be either ARRAY references, HASH
67 references, or otherwise are treated as SCALARs. By default, the data
68 passed to the merge function will be cloned using the Clone module;
69 however, if necessary, this behavior can be changed to use as many of
70 the original values as possible. (See "set_clone_behavior").
71 Because there are a number of possible ways that one may want to merge
73 values when keys are conflicting, Hash::Merge provides several preset
74 methods for your convenience, as well as a way to define you own.
75 These are (currently):
76 Left Precedence
78 This is the default behavior.
79 The values buried in the left hash will never be lost; any values
81 that can be added from the right hash will be attempted.
82 my $merge = Hash::Merge->new();
84 my $merge = Hash::Merge->new('LEFT_PRECEDENT');
85 $merge->set_set_behavior('LEFT_PRECEDENT')
86 Hash::Merge::set_set_behavior('LEFT_PRECEDENT')
87 Right Precedence
89 Same as Left Precedence, but with the right hash values never being
90 lost
91 my $merge = Hash::Merge->new('RIGHT_PRECEDENT');
93 $merge->set_set_behavior('RIGHT_PRECEDENT')
94 Hash::Merge::set_set_behavior('RIGHT_PRECEDENT')
95 Storage Precedence
97 If conflicting keys have two different storage mediums, the
98 'bigger' medium will win; arrays are preferred over scalars, hashes
99 over either. The other medium will try to be fitted in the other,
100 but if this isn't possible, the data is dropped.
101 my $merge = Hash::Merge->new('STORAGE_PRECEDENT');
103 $merge->set_set_behavior('STORAGE_PRECEDENT')
104 Hash::Merge::set_set_behavior('STORAGE_PRECEDENT')
105 Retainment Precedence
107 No data will be lost; scalars will be joined with arrays, and
108 scalars and arrays will be 'hashified' to fit them into a hash.
109 my $merge = Hash::Merge->new('RETAINMENT_PRECEDENT');
111 $merge->set_set_behavior('RETAINMENT_PRECEDENT')
112 Hash::Merge::set_set_behavior('RETAINMENT_PRECEDENT')
113 Specific descriptions of how these work are detailed below.
115 merge ( <hashref>, <hashref> )
117 Merges two hashes given the rules specified. Returns a reference
118 to the new hash.
119 _hashify( <scalar>|<arrayref> ) -- INTERNAL FUNCTION
121 Returns a reference to a hash created from the scalar or array
122 reference, where, for the scalar value, or each item in the array,
123 there is a key and it's value equal to that specific value.
124 Example, if you pass scalar '3', the hash will be { 3 => 3 }.
125 _merge_hashes( <hashref>, <hashref> ) -- INTERNAL FUNCTION
127 Actually does the key-by-key evaluation of two hashes and returns
128 the new merged hash. Note that this recursively calls "merge".
129 set_clone_behavior( <scalar> )
131 Sets how the data cloning is handled by Hash::Merge. If this is
132 true, then data will be cloned; if false, then original data will
133 be used whenever possible. By default, cloning is on (set to
134 true).
135 get_clone_behavior( )
137 Returns the current behavior for data cloning.
138 set_behavior( <scalar> )
140 Specify which built-in behavior for merging that is desired. The
141 scalar must be one of those given below.
142 get_behavior( )
144 Returns the behavior that is currently in use by Hash::Merge.
145 specify_behavior( <hashref>, [<name>] )
147 Specify a custom merge behavior for Hash::Merge. This must be a
148 hashref defined with (at least) 3 keys, SCALAR, ARRAY, and HASH;
149 each of those keys must have another hashref with (at least) the
150 same 3 keys defined. Furthermore, the values in those hashes must
151 be coderefs. These will be called with two arguments, the left and
152 right values for the merge. Your coderef should return either a
153 scalar or an array or hash reference as per your planned behavior.
154 If necessary, use the functions _hashify and _merge_hashes as
155 helper functions for these. For example, if you want to add the
156 left SCALAR to the right ARRAY, you can have your behavior
157 specification include:
158 %spec = ( ...SCALAR => { ARRAY => sub { [ $_[0], @$_[1] ] }, ... } } );
160 Note that you can import _hashify and _merge_hashes into your
162 program's namespace with the 'custom' tag.
163
165 Here is the specifics on how the current internal behaviors are called,
166 and what each does. Assume that the left value is given as $a, and the
167 right as $b (these are either scalars or appropriate references)
168 LEFT TYPE RIGHT TYPE LEFT_PRECEDENT RIGHT_PRECEDENT
170 SCALAR SCALAR $a $b
171 SCALAR ARRAY $a ( $a, @$b )
172 SCALAR HASH $a %$b
173 ARRAY SCALAR ( @$a, $b ) $b
174 ARRAY ARRAY ( @$a, @$b ) ( @$a, @$b )
175 ARRAY HASH ( @$a, values %$b ) %$b
176 HASH SCALAR %$a $b
177 HASH ARRAY %$a ( values %$a, @$b )
178 HASH HASH merge( %$a, %$b ) merge( %$a, %$b )
179 LEFT TYPE RIGHT TYPE STORAGE_PRECEDENT RETAINMENT_PRECEDENT
181 SCALAR SCALAR $a ( $a ,$b )
182 SCALAR ARRAY ( $a, @$b ) ( $a, @$b )
183 SCALAR HASH %$b merge( hashify( $a ), %$b )
184 ARRAY SCALAR ( @$a, $b ) ( @$a, $b )
185 ARRAY ARRAY ( @$a, @$b ) ( @$a, @$b )
186 ARRAY HASH %$b merge( hashify( @$a ), %$b )
187 HASH SCALAR %$a merge( %$a, hashify( $b ) )
188 HASH ARRAY %$a merge( %$a, hashify( @$b ) )
189 HASH HASH merge( %$a, %$b ) merge( %$a, %$b )
190 (*) note that merge calls _merge_hashes, hashify calls _hashify.
192
194 This will not handle self-referencing/recursion within hashes well.
195 Plans for a future version include incorporate deep recursion
196 protection.
197 As of Feb 16, 2002, ActiveState Perl's PPM of Clone.pm is only at 0.09.
199 This version does not support the cloning of scalars if passed to the
200 function. This is fixed by 0.10 (and currently, Clone.pm is at 0.13).
201 So while most other users can upgrade their Clone.pm appropriately (and
202 I could put this as a requirement into the Makefile.PL), those using
203 ActiveState would lose out on the ability to use this module.
204 (Clone.pm is not pure perl, so it's not simply a matter of moving the
205 newer file into place). Thus, for the time being, a check is done at
206 the start of loading of this module to see if a newer version of clone
207 is around. Then, all cloning calls have been wrapped in the internal
208 _my_clone function to block any scalar clones if Clone.pm is too old.
209 However, this also prevents the cloning of anything that isn't a hash
210 or array under the same conditions. Once ActiveState updates their
211 Clone, I'll remove this wrapper.
212
214 Michael K. Neylon <mneylon-pm@masemware.com>
215
217 Copyright (c) 2001,2002 Michael K. Neylon. All rights reserved.
218 This library is free software. You can redistribute it and/or modify
220 it under the same terms as Perl itself.
221perl v5.12.0 2010-02-15 Merge(3)