rename hook: instead of modifying the passed-by-name array, return a copy

This is intended to solve Joey's concerns expressed on
http://ikiwiki.info/todo/need_global_renamepage_hook/, i.e. the need to make it
possible to use this hook from external plugins.

A plugin using this hook still can add/modify/remove elements of the
@torename array.

Signed-off-by: intrigeri <intrigeri@boum.org>

4 files changed, 28 insertions, 20 deletions

diff --git a/IkiWiki/Plugin/po.pm b/IkiWiki/Plugin/po.pm
index 6f716a91f..6c6bb2cd1 100644
--- a/IkiWiki/Plugin/po.pm
+++ b/IkiWiki/Plugin/po.pm
@@ -329,29 +329,30 @@ sub postscan (@) {
 }
 
 # Add the renamed page translations to the list of to-be-renamed pages.
-sub renamepages($$$) {
-	my ($torename, $cgi, $session) = (shift, shift, shift);
+sub renamepages(@) {
+	my %params = @_;
 
-	# copy the initial array, so that we can iterate on it AND
-	# modify it at the same time, without iterating on the items we
-	# pushed on it ourselves
-	my @torename=@{$torename};
+	my @torename = @{$params{torename}};
+	my $session = $params{session};
 
 	# Save the page(s) the user asked to rename, so that our
 	# canrename hook can tell the difference between:
 	#  - a translation being renamed as a consequence of its master page
 	#    being renamed
 	#  - a user trying to directly rename a translation
-	# This is why this hook has to be run first, before @torename is modified
-	# by other plugins.
-	$session->param(po_orig_torename => [ @torename ]);
+	# This is why this hook has to be run first, before the list of pages
+	# to rename is modified by other plugins.
+	$session->param(po_orig_torename => \@torename);
 	IkiWiki::cgi_savesession($session);
 
+	my @ret=@torename;
+	# iterate on @torename and push onto @ret, so that we don't iterate
+	# on the items we added ourselves
 	foreach my $rename (@torename) {
 		next unless istranslatable($rename->{src});
 		my %otherpages=%{otherlanguages($rename->{src})};
 		while (my ($lang, $otherpage) = each %otherpages) {
-			push @{$torename}, {
+			push @ret, {
 				src => $otherpage,
 				srcfile => $pagesources{$otherpage},
 				dest => otherlanguage($rename->{dest}, $lang),
@@ -360,6 +361,7 @@ sub renamepages($$$) {
 			};
 		}
 	}
+	return @ret;
 }
 
 sub mydelete(@) {
diff --git a/IkiWiki/Plugin/rename.pm b/IkiWiki/Plugin/rename.pm
index 90af1b4a9..f39c93332 100644
--- a/IkiWiki/Plugin/rename.pm
+++ b/IkiWiki/Plugin/rename.pm
@@ -312,7 +312,13 @@ sub sessioncgi ($$) {
 				required => 1,
 			};
 
-			IkiWiki::run_hooks(rename => sub { shift->(\@torename, $q, $session); });
+			IkiWiki::run_hooks(rename => sub {
+				@torename=shift->(
+					torename => \@torename,
+					cgi => $q,
+					session => $session
+				);
+			});
 
 			# See if any subpages need to be renamed.
 			if ($q->param("subpages") && $src ne $dest) {
diff --git a/IkiWiki/Plugin/skeleton.pm.example b/IkiWiki/Plugin/skeleton.pm.example
index 62eeaf51d..573510191 100644
--- a/IkiWiki/Plugin/skeleton.pm.example
+++ b/IkiWiki/Plugin/skeleton.pm.example
@@ -229,8 +229,8 @@ sub renamepage (@) {
 	debug("skeleton plugin running in renamepage");
 }
 
-sub rename ($$$) {
-	my ($torename, $cgi, $session) = (shift, shift, shift);
+sub rename (@) {
+	my %params=@_;
 	
 	debug("skeleton plugin running in rename");
 }
diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index 98372b33d..0c5ad4540 100644
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -414,16 +414,16 @@ new page.
 
 ### rename
 
-	hook(type => "rename", id => "foo", call => \&renamepages);
+	hook(type => "rename", id => "foo", call => \&rename);
 
 When a page or set of pages is renamed, the referenced function is
-called, and is passed:
+called, and is passed named parameters:
 
-* a reference to an array of hashes with keys: `src`, `srcfile`,
-  `dest`, `destfile`, `required`. Such a hook function can modify
-  the array.
-* a CGI object
-* a session object
+* `torename`: a reference to an array of hashes with keys: `src`, `srcfile`,
+  `dest`, `destfile`, `required`. Such a hook function can either return the
+  array content unchanged, or modify it and return the modified version.
+* `cgi`: a CGI object
+* `session`: a session object.
 
 ### getsetup