t/9000-bug-41738-merge-with-side-effects.t t/release/boilerplate.t t/release/pod-coverage.t t/release/pod.t @@ -1,3 +1,8 @@ +0.04 Saturday February 21 23:22:34 PST 2009: + - Addressed bug 41738: https://rt.cpan.org/Ticket/Display.html?id=41738 (thanks Uri) + - Updated boilerplate and Makefile.PL + - Conversion of repository to git (github) + 0.03 Sunday May 04 02:39:59 PDT 2008: - Tweak acknowledgements - Reference Hash::Merge in SEE ALSO Changes @@ -1,14 +1,17 @@ -.PHONY: all test time clean distclean dist distcheck upload distupload +.PHONY: all test clean distclean dist all: test dist: - rm -rf inc META.yaml + rm -rf inc META.y*ml perl Makefile.PL $(MAKE) -f Makefile dist -distclean test tardist: Makefile - make -f $< $@ +install distclean tardist: Makefile + $(MAKE) -f $< $@ + +test: Makefile + TEST_RELEASE=1 $(MAKE) -f $< $@ Makefile: Makefile.PL perl $< @@ -17,4 +20,4 @@ clean: distclean reset: clean perl Makefile.PL - make -f Makefile test + $(MAKE) test GNUmakefile @@ -17,7 +17,7 @@ inc/Module/Install/Metadata.pm inc/Module/Install/Win32.pm inc/Module/Install/WriteAll.pm t/01-basic.t -t/author/boilerplate.t -t/author/pod-coverage.t -t/author/pod.t - +t/9000-bug-41738-merge-with-side-effects.t +t/release/boilerplate.t +t/release/pod-coverage.t +t/release/pod.t MANIFEST @@ -3,8 +3,40 @@ use inc::Module::Install; name 'Hash-Merge-Simple'; all_from 'lib/Hash/Merge/Simple.pm'; -build_requires 'Test::More'; -build_requires 'Test::Deep'; +resources repository => 'http://github.com/robertkrimen/hash-merge-simple/tree/master'; + +{ + require ExtUtils::MakeMaker; + use strict; + no strict 'refs'; + + my $libscan = \&{"ExtUtils::MM_Any::libscan"}; + *{"ExtUtils::MM_Any::libscan"} = sub { + return '' unless $libscan->(@_); + return '' if $_[1] =~ /\.sw[p-z]$/; + return $_[1]; + }; +} + +{ + map { my ($pk, $vr) = split m/\s/; build_requires $pk => $vr || 0 } grep { ! /^\s*#/ } split m/\n/, <<_END_; +Test::Most +Test::Deep +_END_ + + map { my ($pk, $vr) = split m/\s/; requires $pk => $vr || 0 } grep { ! /^\s*#/ } split m/\n/, <<_END_; +_END_ + + map { my ($pk, $vr) = split m/\s/; recommends $pk => $vr || 0 } grep { ! /^\s*#/ } split m/\n/, <<_END_; +Clone +Storable +_END_ +} + +if (-e 'inc/.author') { + my $all_from = join '/', 'lib', split m/-/, name . '.pm'; + `perldoc -tF $all_from > README` if ! -e 'README' || (stat $all_from)[9] > (stat 'README')[9]; +} auto_install; Makefile.PL @@ -1,40 +1,138 @@ -Hash-Merge-Simple +NAME + Hash::Merge::Simple - Recursively merge two or more hashes, simply -INSTALLATION +VERSION + Version 0.04 -To install this module, run the following commands: +SYNOPSIS + use Hash::Merge::Simple qw/merge/; - perl Makefile.PL - make - make test - make install + my $a = { a => 1 }; + my $b = { a => 100, b => 2}; -SUPPORT AND DOCUMENTATION + # Merge with righthand hash taking precedence + my $c = merge $a, $b; + # $c is { a => 100, b => 2 } ... Note: a => 100 has overridden => 1 -After installing, you can find documentation for this module with the -perldoc command. + # Also, merge will take care to recursively merge any subordinate hashes found + my $a = { a => 1, c => 3, d => { i => 2 }, r => {} }; + my $b = { b => 2, a => 100, d => { l => 4 } }; + my $c = merge $a, $b; + # $c is { a => 100, b => 2, c => 3, d => { i => 2, l => 4 }, r => {} } - perldoc Hash::Merge::Simple + # You can also merge more than two hashes at the same time + # The precedence increases from left to right (the rightmost has the most precedence) + my $everything = merge $this, $that, $mine, $yours, $kitchen_sink, ...; -You can also look for information at: +DESCRIPTION + Hash::Merge::Simple will recursively merge two or more hashes and return + the result as a new hash reference. The merge function will descend and + merge hashes that exist under the same node in both the left and right + hash, but doesn't attempt to combine arrays, objects, scalars, or + anything else. The rightmost hash also takes precedence, replacing + whatever was in the left hash if a conflict occurs. - RT, CPAN's request tracker - http://rt.cpan.org/NoAuth/Bugs.html?Dist=Hash-Merge-Simple + This code was pretty much taken straight from Catalyst::Utils, and + modified to handle more than 2 hashes at the same time. - AnnoCPAN, Annotated CPAN documentation - http://annocpan.org/dist/Hash-Merge-Simple +EXPORTS + merge + See below. - CPAN Ratings - http://cpanratings.perl.org/d/Hash-Merge-Simple +METHODS + Hash::Merge::Simple->merge( <hash1>, <hash2>, <hash3>, ..., <hashN> ) + Hash::Merge::Simple::merge( <hash1>, <hash2>, <hash3>, ..., <hashN> ) + Merge <hash1> through <hashN>, with the nth-most (rightmost) hash taking + precedence. - Search CPAN - http://search.cpan.org/dist/Hash-Merge-Simple + Returns a new hash reference representing the merge. + NOTE: The code does not currently check for cycles, so infinite loops + are possible: -COPYRIGHT AND LICENCE + my $a = {}; + $a->{b} = $a; + merge $a, $a; -Copyright (C) 2008 Robert Krimen + NOTE: If you want to avoid giving/receiving side effects with the merged + result, use "clone_merge" or "dclone_merge" An example of this problem + (thanks Uri): -This program is free software; you can redistribute it and/or modify it -under the same terms as Perl itself. + my $left = { a => { b => 2 } } ; + my $right = { c => 4 } ; + + my $result = merge( $left, $right ) ; + + $left->{a}{b} = 3 ; + $left->{a}{d} = 5 ; + + # $result->{a}{b} == 3 ! + # $result->{a}{d} == 5 ! + + Hash::Merge::Simple->clone_merge( <hash1>, <hash2>, <hash3>, ..., <hashN> ) + Hash::Merge::Simple::clone_merge( <hash1>, <hash2>, <hash3>, ..., <hashN> ) + Perform a merge, clone the merge, and return the result + + This is useful in cases where you need to ensure that the result can be + tweaked without fear of giving/receiving any side effects + + This method will use Clone to do the cloning + + Hash::Merge::Simple->dclone_merge( <hash1>, <hash2>, <hash3>, ..., <hashN> ) + Hash::Merge::Simple::dclone_merge( <hash1>, <hash2>, <hash3>, ..., <hashN> ) + Perform a merge, clone the merge, and return the result + + This is useful in cases where you need to ensure that the result can be + tweaked without fear of giving/receiving any side effects + + This method will use Storable (dclone) to do the cloning + +AUTHOR + Robert Krimen, "<rkrimen at cpan.org>" + +SEE ALSO + Hash::Merge, Catalyst::Utils + +BUGS + Please report any bugs or feature requests to "bug-hash-merge-simple at + rt.cpan.org", or through the web interface at + <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Hash-Merge-Simple>. I + will be notified, and then you'll automatically be notified of progress + on your bug as I make changes. + +SUPPORT + You can find documentation for this module with the perldoc command. + + perldoc Hash::Merge::Simple + + You can also look for information at: + + * RT: CPAN's request tracker + + <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Hash-Merge-Simple> + + * AnnoCPAN: Annotated CPAN documentation + + <http://annocpan.org/dist/Hash-Merge-Simple> + + * CPAN Ratings + + <http://cpanratings.perl.org/d/Hash-Merge-Simple> + + * Search CPAN + + <http://search.cpan.org/dist/Hash-Merge-Simple> + +ACKNOWLEDGEMENTS + This code was pretty much taken directly from Catalyst::Utils: + + Sebastian Riedel "sri@cpan.org" + + Yuval Kogman "nothingmuch@woobling.org" + +COPYRIGHT & LICENSE + Copyright 2008 Robert Krimen, all rights reserved. + + This program is free software; you can redistribute it and/or modify it + under the same terms as Perl itself. README @@ -9,14 +9,14 @@ Hash::Merge::Simple - Recursively merge two or more hashes, simply =head1 VERSION -Version 0.03 +Version 0.04 =cut -our $VERSION = '0.03'; +our $VERSION = '0.04'; use vars qw/@ISA @EXPORT_OK/; @ISA = qw/Exporter/; -@EXPORT_OK = qw/merge/; +@EXPORT_OK = qw/merge clone_merge dclone_merge/; =head1 SYNOPSIS @@ -69,12 +69,26 @@ NOTE: The code does not currently check for cycles, so infinite loops are possib $a->{b} = $a; merge $a, $a; +NOTE: If you want to avoid giving/receiving side effects with the merged result, use C<clone_merge> or C<dclone_merge> +An example of this problem (thanks Uri): + + my $left = { a => { b => 2 } } ; + my $right = { c => 4 } ; + + my $result = merge( $left, $right ) ; + + $left->{a}{b} = 3 ; + $left->{a}{d} = 5 ; + + # $result->{a}{b} == 3 ! + # $result->{a}{d} == 5 ! + =cut # This was stoled from Catalyst::Utils... thanks guys! sub merge (@); sub merge (@) { - shift if ! ref $_[0]; # Take care of the case we're called like Hash::Merge::Simple->merge(...) + shift unless ref $_[0]; # Take care of the case we're called like Hash::Merge::Simple->merge(...) my ($left, @right) = @_; return $left unless @right; @@ -86,8 +100,8 @@ sub merge (@) { my %merge = %$left; for my $key (keys %$right) { - my $hr = (ref $right->{$key} || '') eq 'HASH'; - my $hl = ((exists $left->{$key} && ref $left->{$key}) || '') eq 'HASH'; + + my ($hr, $hl) = map { ref $_->{$key} eq 'HASH' } $right, $left; if ($hr and $hl){ $merge{$key} = merge($left->{$key}, $right->{$key}); @@ -100,6 +114,44 @@ sub merge (@) { return \%merge; } +=head2 Hash::Merge::Simple->clone_merge( <hash1>, <hash2>, <hash3>, ..., <hashN> ) + +=head2 Hash::Merge::Simple::clone_merge( <hash1>, <hash2>, <hash3>, ..., <hashN> ) + +Perform a merge, clone the merge, and return the result + +This is useful in cases where you need to ensure that the result can be tweaked without fear +of giving/receiving any side effects + +This method will use L<Clone> to do the cloning + +=cut + +sub clone_merge { + require Clone; + my $result = merge @_; + return Clone::clone( $result ); +} + +=head2 Hash::Merge::Simple->dclone_merge( <hash1>, <hash2>, <hash3>, ..., <hashN> ) + +=head2 Hash::Merge::Simple::dclone_merge( <hash1>, <hash2>, <hash3>, ..., <hashN> ) + +Perform a merge, clone the merge, and return the result + +This is useful in cases where you need to ensure that the result can be tweaked without fear +of giving/receiving any side effects + +This method will use L<Storable> (dclone) to do the cloning + +=cut + +sub dclone_merge { + require Storable; + my $result = merge @_; + return Storable::dclone( $result ); +} + =head1 AUTHOR Robert Krimen, C<< <rkrimen at cpan.org> >> lib/Hash/Merge/Simple.pm t/author/boilerplate.t t/author/pod-coverage.t t/author/pod.t d9083a444a2679b287ca8564f4cba66d0bdf707e robertkrimen robertkrimen@gmail.com http://github.com/robertkrimen/hash-merge-simple/commit/f3602de4a7219c3b11f4913bdbddf504baff1780 f3602de4a7219c3b11f4913bdbddf504baff1780 2009-02-21T23:25:07-08:00 2009-02-21T23:25:07-08:00 Addressed bug 41738: https://rt.cpan.org/Ticket/Display.html?id=41738 (thanks Uri) Updated boilerplate and Makefile.PL Conversion of repository to git (github) 423867124884cd35eec2fd15fe030fe1d7c9e024 robertkrimen robertkrimen@gmail.com