]> git.vanrenterghem.biz Git - git.ikiwiki.info.git/commitdiff
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};
            %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
                  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;
 }
 
        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 (@_) {
 sub deptype (@) {
        my $deptype=0;
        foreach my $type (@_) {
@@ -2055,27 +1970,95 @@ sub pagespec_match ($$;@) {
 }
 
 sub pagespec_match_list ($$;@) {
 }
 
 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;
                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 ($) {
 }
 
 sub pagespec_valid ($) {
index a89175cfbf8a5b51b4765e55ca4e63e90c557ab6..c50d038df4f80314bf4a3f3070aa65fa474e264d 100644 (file)
@@ -74,7 +74,7 @@ sub format_month (@) {
        my $nyear    = $params{nyear};
 
        my %linkcache;
        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"))) {
                                # 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};
                }
 
                        $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",
                        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}) {
        }
 
        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"),
                        deptype => deptype($quick ? "presence" : "content"),
-                       list => \@feedlist);
+                       list => \@feedlist,
+               );
        }
 
        my ($feedbase, $feednum);
        }
 
        my ($feedbase, $feednum);
index 634b0e4d6794a2d52179f561d26f8ea4bb8ac0cc..788b9682706c9e3a303b0920267e8ea20061305e 100644 (file)
@@ -36,7 +36,8 @@ sub preprocess (@) {
 
        # Get all the items to map.
        my %mapitems;
 
        # 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}}) {
                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"));
        
        # 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 {
                # 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 keys %pagesources;
        }
 
-       return scalar use_pagespec($params{page}, $pages,
+       return scalar pagespec_match_list($params{page}, $pages,
                deptype => deptype("presence"));
 }
 
                deptype => deptype("presence"));
 }
 
index e64f7d9c38869ae1baf5734101f8afe705f90e9f..47638210aeddeff49866ac1e5a6459828556ddd2 100644 (file)
@@ -37,16 +37,17 @@ sub preprocess (@) {
        
        my %counts;
        my $max = 0;
        
        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
                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
                                # 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} } 
        }
 
        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} },
                );
                        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.
     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.
 
   * 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.
 
 
 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
 
 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:
 
 
 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.
 
 * `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]].
 #### `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 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
 #### `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");