add influence info to match_*

Also update docs, test suite.

IkiWiki.pm

@@ -2039,7 +2039,7 @@ use overload (
 sub new {
 	my $class = shift;
 	my $value = shift;
-	return bless [$value, {@_}], $class;
+	return bless [$value, {map { $_ => 1 } @_}], $class;
 }
 
 sub influences {
@@ -2099,23 +2099,23 @@ sub match_link ($$;@) {
 	my $from=exists $params{location} ? $params{location} : '';
 
 	my $links = $IkiWiki::links{$page};
-	return IkiWiki::FailReason->new("$page has no links") unless $links && @{$links};
+	return IkiWiki::FailReason->new("$page has no links", $link) unless $links && @{$links};
 	my $bestlink = IkiWiki::bestlink($from, $link);
 	foreach my $p (@{$links}) {
 		if (length $bestlink) {
-			return IkiWiki::SuccessReason->new("$page links to $link")
+			return IkiWiki::SuccessReason->new("$page links to $link", $page)
 				if $bestlink eq IkiWiki::bestlink($page, $p);
 		}
 		else {
-			return IkiWiki::SuccessReason->new("$page links to page $p matching $link")
+			return IkiWiki::SuccessReason->new("$page links to page $p matching $link", $page)
 				if match_glob($p, $link, %params);
 			my ($p_rel)=$p=~/^\/?(.*)/;
 			$link=~s/^\///;
-			return IkiWiki::SuccessReason->new("$page links to page $p_rel matching $link")
+			return IkiWiki::SuccessReason->new("$page links to page $p_rel matching $link", $page)
 				if match_glob($p_rel, $link, %params);
 		}
 	}
-	return IkiWiki::FailReason->new("$page does not link to $link");
+	return IkiWiki::FailReason->new("$page does not link to $link", $page);
 }
 
 sub match_backlink ($$;@) {
@@ -2131,14 +2131,14 @@ sub match_created_before ($$;@) {
 
 	if (exists $IkiWiki::pagectime{$testpage}) {
 		if ($IkiWiki::pagectime{$page} < $IkiWiki::pagectime{$testpage}) {
-			return IkiWiki::SuccessReason->new("$page created before $testpage");
+			return IkiWiki::SuccessReason->new("$page created before $testpage", $testpage);
 		}
 		else {
-			return IkiWiki::FailReason->new("$page not created before $testpage");
+			return IkiWiki::FailReason->new("$page not created before $testpage", $testpage);
 		}
 	}
 	else {
-		return IkiWiki::ErrorReason->new("$testpage does not exist");
+		return IkiWiki::ErrorReason->new("$testpage does not exist", $testpage);
 	}
 }
 
@@ -2151,14 +2151,14 @@ sub match_created_after ($$;@) {
 
 	if (exists $IkiWiki::pagectime{$testpage}) {
 		if ($IkiWiki::pagectime{$page} > $IkiWiki::pagectime{$testpage}) {
-			return IkiWiki::SuccessReason->new("$page created after $testpage");
+			return IkiWiki::SuccessReason->new("$page created after $testpage", $testpage);
 		}
 		else {
-			return IkiWiki::FailReason->new("$page not created after $testpage");
+			return IkiWiki::FailReason->new("$page not created after $testpage", $testpage);
 		}
 	}
 	else {
-		return IkiWiki::ErrorReason->new("$testpage does not exist");
+		return IkiWiki::ErrorReason->new("$testpage does not exist", $testpage);
 	}
 }
 

IkiWiki/Plugin/meta.pm

@@ -291,21 +291,21 @@ sub match {
 
 	if (defined $val) {
 		if ($val=~/^$re$/i) {
-			return IkiWiki::SuccessReason->new("$re matches $field of $page");
+			return IkiWiki::SuccessReason->new("$re matches $field of $page", $page);
 		}
 		else {
-			return IkiWiki::FailReason->new("$re does not match $field of $page");
+			return IkiWiki::FailReason->new("$re does not match $field of $page", $page);
 		}
 	}
 	else {
-		return IkiWiki::FailReason->new("$page does not have a $field");
+		return IkiWiki::FailReason->new("$page does not have a $field", $page);
 	}
 }
 
 package IkiWiki::PageSpec;
 
 sub match_title ($$;@) {
-	IkiWiki::Plugin::meta::match("title", @_);	
+	IkiWiki::Plugin::meta::match("title", @_);
 }
 
 sub match_author ($$;@) {

debian/changelog

@@ -32,6 +32,8 @@ ikiwiki (3.14159266) UNRELEASED; urgency=low
   * Transitive dependencies are now correctly supported.
   * Rebuild wikis on upgrade to this version to get improved dependency
     info.
+  * Plugins providing PageSpec `match_*` functions should pass additional
+    influence information when creating result objects.
 
  -- Joey Hess <joeyh@debian.org>  Sun, 27 Sep 2009 17:40:03 -0400
 

doc/plugins/write.mdwn

@@ -982,6 +982,13 @@ an IkiWiki::FailReason object if the match fails. If the match cannot be
 attempted at all, for any page, it can instead return an
 IkiWiki::ErrorReason object explaining why.
 
+When constructing these objects, you should also include a list of any
+pages whose contents or other metadata influenced the result of the match.
+For example, "backlink(foo)" is influenced by the contents of page foo;
+"link(foo)" and "title(bar)" are influenced by the contents of any
+page they match; "created_before(foo)" is influenced by the metadata of
+foo; while "glob(*)" is not influenced by the contents of any page.
+
 ### Setup plugins
 
 The ikiwiki setup file is loaded using a pluggable mechanism. If you look

t/pagespec_match.t

@@ -1,7 +1,7 @@
 #!/usr/bin/perl
 use warnings;
 use strict;
-use Test::More tests => 56;
+use Test::More tests => 61;
 
 BEGIN { use_ok("IkiWiki"); }
 
@@ -89,6 +89,17 @@ my $ret=pagespec_match("foo", "(invalid");
 ok(! $ret, "syntax error");
 ok($ret =~ /syntax error/, "error message");
 
-my $ret=pagespec_match("foo", "bar or foo");
+$ret=pagespec_match("foo", "bar or foo");
 ok($ret, "simple match");
 is($ret, "foo matches foo", "stringified return");
+
+$ret=pagespec_match("foo", "link(bar)");
+is(join(",", $ret->influences), 'foo', "link is influenced by the page with the link");
+$ret=pagespec_match("bar", "backlink(foo)");
+is(join(",", $ret->influences), 'foo', "backlink is influenced by the page with the link");
+$ret=pagespec_match("bar", "backlink(foo)");
+is(join(",", $ret->influences), 'foo', "backlink is influenced by the page with the link");
+$ret=pagespec_match("bar", "created_before(foo)");
+is(join(",", $ret->influences), 'foo', "created_before is influenced by the comparison page");
+$ret=pagespec_match("bar", "created_after(foo)");
+is(join(",", $ret->influences), 'foo', "created_after is influenced by the comparison page");