rename use_pagespec to pagespec_match_list
authorJoey Hess <joey@gnu.kitenet.net>
Fri, 9 Oct 2009 03:51:06 +0000 (23:51 -0400)
committerJoey Hess <joey@gnu.kitenet.net>
Fri, 9 Oct 2009 03:51:06 +0000 (23:51 -0400)
To avoid breaking plugins, also support the old pagespec_match_list
calling convention, with a deprecation warning.

12 files changed:
IkiWiki.pm
IkiWiki/Plugin/calendar.pm
IkiWiki/Plugin/inline.pm
IkiWiki/Plugin/map.pm
IkiWiki/Plugin/orphans.pm
IkiWiki/Plugin/pagecount.pm
IkiWiki/Plugin/pagestats.pm
IkiWiki/Plugin/postsparkline.pm
debian/changelog
doc/plugins/write.mdwn
t/pagespec_match_list.t [new file with mode: 0755]
t/use_pagespec.t [deleted file]

index daa71059b093c5bdc95327459acf508c8ff72bc4..fd7e2352474400c04eb7bdc4b4dd79746d570da6 100644 (file)
@@ -17,7 +17,7 @@ use vars qw{%config %links %oldlinks %pagemtime %pagectime %pagecase
            %forcerebuild %loaded_plugins};
 
 use Exporter q{import};
-our @EXPORT = qw(hook debug error template htmlpage deptype use_pagespec
+our @EXPORT = qw(hook debug error template htmlpage deptype
                  add_depends pagespec_match pagespec_match_list bestlink
                 htmllink readfile writefile pagetype srcfile pagename
                 displaytime will_render gettext urlto targetpage
@@ -1798,91 +1798,6 @@ sub add_depends ($$;$) {
        return 1;
 }
 
-sub use_pagespec ($$;@) {
-       my $page=shift;
-       my $pagespec=shift;
-       my %params=@_;
-
-       my $sub=pagespec_translate($pagespec);
-       error "syntax error in pagespec \"$pagespec\""
-               if $@ || ! defined $sub;
-
-       my @candidates;
-       if (exists $params{limit}) {
-               @candidates=grep { $params{limit}->($_) } keys %pagesources;
-       }
-       else {
-               @candidates=keys %pagesources;
-       }
-
-       if (defined $params{sort}) {
-               my $f;
-               if ($params{sort} eq 'title') {
-                       $f=sub { pagetitle(basename($a)) cmp pagetitle(basename($b)) };
-               }
-               elsif ($params{sort} eq 'title_natural') {
-                       eval q{use Sort::Naturally};
-                       if ($@) {
-                               error(gettext("Sort::Naturally needed for title_natural sort"));
-                       }
-                       $f=sub { Sort::Naturally::ncmp(pagetitle(basename($a)), pagetitle(basename($b))) };
-                }
-               elsif ($params{sort} eq 'mtime') {
-                       $f=sub { $pagemtime{$b} <=> $pagemtime{$a} };
-               }
-               elsif ($params{sort} eq 'age') {
-                       $f=sub { $pagectime{$b} <=> $pagectime{$a} };
-               }
-               else {
-                       error sprintf(gettext("unknown sort type %s"), $params{sort});
-               }
-               @candidates = sort { &$f } @candidates;
-       }
-
-       @candidates=reverse(@candidates) if $params{reverse};
-       
-       my @matches;
-       my $firstfail;
-       my $count=0;
-       foreach my $p (@candidates) {
-               my $r=$sub->($p, location => $page);
-               if ($r) {
-                       push @matches, [$p, $r];
-                       last if defined $params{num} && ++$count == $params{num};
-               }
-               elsif (! defined $firstfail) {
-                       $firstfail=$r;
-               }
-       }
-       
-       $depends{$page}{$pagespec} |= ($params{deptype} || $DEPEND_CONTENT);
-
-       my @ret;
-       if (@matches) {
-               # Add all influences from successful matches.
-               foreach my $m (@matches) {
-                       push @ret, $m->[0];
-                       my %i=$m->[1]->influences;
-                       foreach my $i (keys %i) {
-                               $depends_simple{$page}{lc $i} |= $i{$i};
-                       }
-               }
-       }
-       elsif (defined $firstfail) {
-               # Add influences from one failure. (Which one should not
-               # matter; all should have the same influences.)
-               my %i=$firstfail->influences;
-               foreach my $i (keys %i) {
-                       $depends_simple{$page}{lc $i} |= $i{$i};
-               }
-
-               error(sprintf(gettext("cannot match pages: %s"), $firstfail))
-                       if $firstfail->isa("IkiWiki::ErrorReason");
-       }
-
-       return @ret;
-}
-
 sub deptype (@) {
        my $deptype=0;
        foreach my $type (@_) {
@@ -2055,27 +1970,95 @@ sub pagespec_match ($$;@) {
 }
 
 sub pagespec_match_list ($$;@) {
-       my $pages=shift;
-       my $spec=shift;
-       my @params=@_;
+       my $page=shift;
+       my $pagespec=shift;
+       my %params=@_;
 
-       my $sub=pagespec_translate($spec);
-       error "syntax error in pagespec \"$spec\""
+       # Backwards compatability with old calling convention.
+       if (ref $page) {
+               print STDERR "warning: a plugin (".caller().") is using pagespec_match_list in an obsolete way, and needs to be updated\n";
+               $params{list}=$page;
+               $page=$params{location}; # ugh!
+       }
+
+       my $sub=pagespec_translate($pagespec);
+       error "syntax error in pagespec \"$pagespec\""
                if $@ || ! defined $sub;
+
+       my @candidates;
+       if (exists $params{limit}) {
+               @candidates=grep { $params{limit}->($_) } keys %pagesources;
+       }
+       else {
+               @candidates=keys %pagesources;
+       }
+
+       if (defined $params{sort}) {
+               my $f;
+               if ($params{sort} eq 'title') {
+                       $f=sub { pagetitle(basename($a)) cmp pagetitle(basename($b)) };
+               }
+               elsif ($params{sort} eq 'title_natural') {
+                       eval q{use Sort::Naturally};
+                       if ($@) {
+                               error(gettext("Sort::Naturally needed for title_natural sort"));
+                       }
+                       $f=sub { Sort::Naturally::ncmp(pagetitle(basename($a)), pagetitle(basename($b))) };
+                }
+               elsif ($params{sort} eq 'mtime') {
+                       $f=sub { $pagemtime{$b} <=> $pagemtime{$a} };
+               }
+               elsif ($params{sort} eq 'age') {
+                       $f=sub { $pagectime{$b} <=> $pagectime{$a} };
+               }
+               else {
+                       error sprintf(gettext("unknown sort type %s"), $params{sort});
+               }
+               @candidates = sort { &$f } @candidates;
+       }
+
+       @candidates=reverse(@candidates) if $params{reverse};
        
-       my @ret;
-       my $r;
-       foreach my $page (@$pages) {
-               $r=$sub->($page, @params);
-               push @ret, $page if $r;
+       my @matches;
+       my $firstfail;
+       my $count=0;
+       foreach my $p (@candidates) {
+               my $r=$sub->($p, location => $page);
+               if ($r) {
+                       push @matches, [$p, $r];
+                       last if defined $params{num} && ++$count == $params{num};
+               }
+               elsif (! defined $firstfail) {
+                       $firstfail=$r;
+               }
        }
+       
+       $depends{$page}{$pagespec} |= ($params{deptype} || $DEPEND_CONTENT);
 
-       if (! @ret && defined $r && $r->isa("IkiWiki::ErrorReason")) {
-               error(sprintf(gettext("cannot match pages: %s"), $r));
+       my @ret;
+       if (@matches) {
+               # Add all influences from successful matches.
+               foreach my $m (@matches) {
+                       push @ret, $m->[0];
+                       my %i=$m->[1]->influences;
+                       foreach my $i (keys %i) {
+                               $depends_simple{$page}{lc $i} |= $i{$i};
+                       }
+               }
        }
-       else {
-               return @ret;
+       elsif (defined $firstfail) {
+               # Add influences from one failure. (Which one should not
+               # matter; all should have the same influences.)
+               my %i=$firstfail->influences;
+               foreach my $i (keys %i) {
+                       $depends_simple{$page}{lc $i} |= $i{$i};
+               }
+
+               error(sprintf(gettext("cannot match pages: %s"), $firstfail))
+                       if $firstfail->isa("IkiWiki::ErrorReason");
        }
+
+       return @ret;
 }
 
 sub pagespec_valid ($) {
index a89175cfbf8a5b51b4765e55ca4e63e90c557ab6..c50d038df4f80314bf4a3f3070aa65fa474e264d 100644 (file)
@@ -74,7 +74,7 @@ sub format_month (@) {
        my $nyear    = $params{nyear};
 
        my %linkcache;
-       foreach my $p (use_pagespec($params{page}, $params{pagespec},
+       foreach my $p (pagespec_match_list($params{page}, $params{pagespec},
                                # add presence dependencies to update
                                # month calendar when pages are added/removed
                                deptype => deptype("presence"))) {
index c02137aed267d4895bf75303c50fab2e1705632f..815a3783841b7b1017d82d51d754041f1be13f34 100644 (file)
@@ -216,7 +216,7 @@ sub preprocess_inline (@) {
                        $num+=$params{skip};
                }
 
-               @list = use_pagespec($params{page}, $params{pages},
+               @list = pagespec_match_list($params{page}, $params{pages},
                        deptype => deptype($quick ? "presence" : "content"),
                        limit => sub { $_[0] ne $params{page} },
                        sort => exists $params{sort} ? $params{sort} : "age",
@@ -245,9 +245,11 @@ sub preprocess_inline (@) {
        }
 
        if ($feeds && exists $params{feedpages}) {
-               @feedlist = use_pagespec($params{page}, "($params{pages}) and ($params{feedpages})",
+               @feedlist = pagespec_match_list(
+                       $params{page}, "($params{pages}) and ($params{feedpages})",
                        deptype => deptype($quick ? "presence" : "content"),
-                       list => \@feedlist);
+                       list => \@feedlist,
+               );
        }
 
        my ($feedbase, $feednum);
index 634b0e4d6794a2d52179f561d26f8ea4bb8ac0cc..788b9682706c9e3a303b0920267e8ea20061305e 100644 (file)
@@ -36,7 +36,8 @@ sub preprocess (@) {
 
        # Get all the items to map.
        my %mapitems;
-       foreach my $page (use_pagespec($params{page}, $params{pages}, deptype => $deptype)) {
+       foreach my $page (pagespec_match_list($params{page}, $params{pages},
+                                       deptype => $deptype)) {
                if (exists $params{show} && 
                    exists $pagestate{$page} &&
                    exists $pagestate{$page}{meta}{$params{show}}) {
index 6072395002ec2da8e0be02303e82b17fc9623d4e..b1ebd1b9d8489cd5d0a5971b7c9943ea2d4dfef7 100644 (file)
@@ -28,7 +28,7 @@ sub preprocess (@) {
        # considering as orphans.
        add_depends($params{page}, "*", deptype("links"));
        
-       my @orphans=use_pagespec($params{page}, $params{pages},
+       my @orphans=pagespec_match_list($params{page}, $params{pages},
                # update when orphans are added/removed
                deptype => deptype("presence"),
                limit => sub {
index 40474b2a1c4b1e05bfac394075339a2d37f7c82a..8d36f057eb0820a62c9704988d66fde75ccf6c4b 100644 (file)
@@ -32,7 +32,7 @@ sub preprocess (@) {
                return scalar keys %pagesources;
        }
 
-       return scalar use_pagespec($params{page}, $pages,
+       return scalar pagespec_match_list($params{page}, $pages,
                deptype => deptype("presence"));
 }
 
index e64f7d9c38869ae1baf5734101f8afe705f90e9f..47638210aeddeff49866ac1e5a6459828556ddd2 100644 (file)
@@ -37,16 +37,17 @@ sub preprocess (@) {
        
        my %counts;
        my $max = 0;
-       foreach my $page (use_pagespec($params{page}, $params{pages},
-                         # update when a displayed page is added or removed
-                         deptype => deptype("presence"))) {
+       foreach my $page (pagespec_match_list($params{page}, $params{pages},
+                                 # update when a displayed page is added/removed
+                                 deptype => deptype("presence"))) {
                use IkiWiki::Render;
 
                my @backlinks = IkiWiki::backlink_pages($page);
 
                if (exists $params{among}) {
                        # only consider backlinks from the amoung pages
-                       @backlinks = use_pagespec($params{page}, $params{among},
+                       @backlinks = pagespec_match_list(
+                               $params{page}, $params{among},
                                # update whenever links on those pages change
                                deptype => deptype("links"),
                                list => \@backlinks
index f51e309c89800c8fddf38b0728a0b39e094cee57..1d4532366e4f2d12eac17f65e5cdf56bb6e7308b 100644 (file)
@@ -54,7 +54,7 @@ sub preprocess (@) {
        }
 
        my @list=sort { $params{timehash}->{$b} <=> $params{timehash}->{$a} } 
-               use_pagespec($params{page}, $params{pages},
+               pagespec_match_list($params{page}, $params{pages},
                        deptype => $deptype,
                        limit => sub { $_[0] ne $params{page} },
                );
index 3a6fdf77d22495ca5d60e8479022195c7a298e3a..49809e6cf0f915e3aa0b2f3c069c0d9c40ed57c3 100644 (file)
@@ -33,9 +33,9 @@ ikiwiki (3.14159266) UNRELEASED; urgency=low
     info.
   * Plugins providing PageSpec `match_*` functions should pass additional
     influence information when creating result objects.
-  * Added `use_pagespec` function, that plugins can use to find a list
-    of matching pages and add dependencies and influences, all at once,
-    and efficiently.
+  * API change: `pagespec_match_list` has completly changed its interface.
+    The old interface will be removed soon, and a warning will be printed
+    if any plugins try to use it.
   * Optimize away most expensive file prune calls, when refreshing,
     by only checking new files.
 
index 62bebbeedf28bfe5124c6ff67b0b399cc4094ede..f6ea76c3607fca1104ae9d999799d8e693c598ca 100644 (file)
@@ -625,16 +625,16 @@ dependency type from one or more of these keywords:
 
 If multiple types are specified, they are combined.
 
-#### `use_pagespec($$;@)`
+#### `pagespec_match_list($$;@)`
 
 Passed a page name, and [[ikiwiki/PageSpec]], returns a list of pages
 in the wiki that match the [[ikiwiki/PageSpec]]. 
 
 The page will automatically be made to depend on the specified
 [[ikiwiki/PageSpec]], so `add_depends` does not need to be called. This
-is significantly more efficient than calling `add_depends`
-followed by `pagespec_match_list`. You should use this anytime a plugin
-needs to match a set of pages and generate something based on that list.
+is significantly more efficient than calling `add_depends` and
+`pagespec_match` in a loop. You should use this anytime a plugin
+needs to match a set of pages and do something based on that list.
 
 Additional named parameters can be specified:
 
@@ -650,6 +650,9 @@ Additional named parameters can be specified:
 * `list` makes it only match amoung the specified list of pages.
   Default is to match amoung all pages in the wiki.
 
+Unlike pagespec_match, this may throw an error if there is an error in
+the pagespec.
+
 #### `add_depends($$;$)`
 
 Makes the specified page depend on the specified [[ikiwiki/PageSpec]].
@@ -672,19 +675,6 @@ 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.
 
-#### `pagespec_match_list($$;@)`
-
-Passed a reference to a list of page names, and [[ikiwiki/PageSpec]],
-returns the set of pages that match the [[ikiwiki/PageSpec]].
-
-Additional named parameters can be passed, to further limit the match.
-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.
-
-Unlike pagespec_match, this may throw an error if there is an error in
-the pagespec.
-
 #### `bestlink($$)`
 
 Given a page and the text of a link on the page, determine which
diff --git a/t/pagespec_match_list.t b/t/pagespec_match_list.t
new file mode 100755 (executable)
index 0000000..85a30b5
--- /dev/null
@@ -0,0 +1,31 @@
+#!/usr/bin/perl
+use warnings;
+use strict;
+use Test::More tests => 10;
+
+BEGIN { use_ok("IkiWiki"); }
+
+%pagesources=(
+       foo => "foo.mdwn",
+       bar => "bar.mdwn",
+       "post/1" => "post/1.mdwn",
+       "post/2" => "post/2.mdwn",
+       "post/3" => "post/3.mdwn",
+);
+
+is_deeply([pagespec_match_list("foo", "bar")], ["bar"]);
+is_deeply([sort(pagespec_match_list("foo", "post/*"))], ["post/1", "post/2", "post/3"]);
+is_deeply([pagespec_match_list("foo", "post/*", sort => "title", reverse => 1)],
+       ["post/3", "post/2", "post/1"]);
+is_deeply([pagespec_match_list("foo", "post/*", sort => "title", num => 2)],
+       ["post/1", "post/2"]);
+is_deeply([pagespec_match_list("foo", "post/*", sort => "title", num => 50)],
+       ["post/1", "post/2", "post/3"]);
+is_deeply([pagespec_match_list("foo", "post/*", sort => "title",
+                         limit => sub { $_[0] !~ /3/}) ],
+       ["post/1", "post/2"]);
+my $r=eval { pagespec_match_list("foo", "beep") };
+ok(eval { pagespec_match_list("foo", "beep") } == 0);
+ok(! $@, "does not fail with error when unable to match anything");
+eval { pagespec_match_list("foo", "this is not a legal pagespec!") };
+ok($@, "fails with error when pagespec bad");
diff --git a/t/use_pagespec.t b/t/use_pagespec.t
deleted file mode 100755 (executable)
index 92d7977..0000000
+++ /dev/null
@@ -1,31 +0,0 @@
-#!/usr/bin/perl
-use warnings;
-use strict;
-use Test::More tests => 10;
-
-BEGIN { use_ok("IkiWiki"); }
-
-%pagesources=(
-       foo => "foo.mdwn",
-       bar => "bar.mdwn",
-       "post/1" => "post/1.mdwn",
-       "post/2" => "post/2.mdwn",
-       "post/3" => "post/3.mdwn",
-);
-
-is_deeply([use_pagespec("foo", "bar")], ["bar"]);
-is_deeply([sort(use_pagespec("foo", "post/*"))], ["post/1", "post/2", "post/3"]);
-is_deeply([use_pagespec("foo", "post/*", sort => "title", reverse => 1)],
-       ["post/3", "post/2", "post/1"]);
-is_deeply([use_pagespec("foo", "post/*", sort => "title", num => 2)],
-       ["post/1", "post/2"]);
-is_deeply([use_pagespec("foo", "post/*", sort => "title", num => 50)],
-       ["post/1", "post/2", "post/3"]);
-is_deeply([use_pagespec("foo", "post/*", sort => "title",
-                         limit => sub { $_[0] !~ /3/}) ],
-       ["post/1", "post/2"]);
-my $r=eval { use_pagespec("foo", "beep") };
-ok(eval { use_pagespec("foo", "beep") } == 0);
-ok(! $@, "does not fail with error when unable to match anything");
-eval { use_pagespec("foo", "this is not a legal pagespec!") };
-ok($@, "fails with error when pagespec bad");