* Make pagespec_match on failure return a value that is false, but in a

  scalar context, evaluates to a reason why the match failed.
* Add testpagespec plugin, which might be useful to see why a pagespec isn't
  matching something.

2 files changed, 18 insertions, 1 deletions

diff --git a/doc/plugins/testpagespec.mdwn b/doc/plugins/testpagespec.mdwn
new file mode 100644
index 000000000..28e5ba7a7
--- /dev/null
+++ b/doc/plugins/testpagespec.mdwn
@@ -0,0 +1,12 @@
+[[template id=plugin name=testpagespec author="[[Joey]]"]]
+[[tag type/useful]]
+
+This plugin allows testing a [[PageSpec]] to see if it matches a page, and
+if not, why it fails to match.
+
+Example use:
+
+	\[[testpagespec pagespec="foopage and barpage" match="foopage"]]
+
+This will print out something like "barpage does not match foopage",
+highlighting which part of the [[PageSpec]] is causing the match to fail.
diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index d9f25641d..ef9d412e5 100644
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -328,6 +328,10 @@ The most often used is "location", which specifies the location the
 PageSpec should match against. If not passed, relative PageSpecs will match
 relative to the top of the wiki.
 
+If the PageSpec fails to match, it may return a IkiWiki::FailReason object,
+which evaluates to false in a boolean context, but in a string context,
+evaulates to the reason the PageSpec failed to match.
+
 #### `bestlink($$)`
 
 Given a page and the text of a link on the page, determine which
@@ -448,4 +452,5 @@ IkiWiki::PageSpec package, that is named `match_foo`, where "foo()" is
 how it will be accessed in a [[PageSpec]]. The function will be passed
 two parameters: The name of the page being matched, and the thing to match
 against. It may also be passed additional, named parameters. It should return
-true if the page matches.
+true if the match succeeds, and either false or a IkiWiki::FailReason object
+if the match fails.