From 5e7b2dea84a35163b599b88efc02cd7ef3e0ad46 Mon Sep 17 00:00:00 2001 From: Joey Hess Date: Thu, 8 Oct 2009 23:51:06 -0400 Subject: [PATCH] rename use_pagespec to pagespec_match_list To avoid breaking plugins, also support the old pagespec_match_list calling convention, with a deprecation warning. --- IkiWiki.pm | 183 +++++++++++++++----------------- IkiWiki/Plugin/calendar.pm | 2 +- IkiWiki/Plugin/inline.pm | 8 +- IkiWiki/Plugin/map.pm | 3 +- IkiWiki/Plugin/orphans.pm | 2 +- IkiWiki/Plugin/pagecount.pm | 2 +- IkiWiki/Plugin/pagestats.pm | 9 +- IkiWiki/Plugin/postsparkline.pm | 2 +- debian/changelog | 6 +- doc/plugins/write.mdwn | 24 ++--- t/pagespec_match_list.t | 31 ++++++ t/use_pagespec.t | 31 ------ 12 files changed, 140 insertions(+), 163 deletions(-) create mode 100755 t/pagespec_match_list.t delete mode 100755 t/use_pagespec.t diff --git a/IkiWiki.pm b/IkiWiki.pm index daa71059b..fd7e23524 100644 --- a/IkiWiki.pm +++ b/IkiWiki.pm @@ -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 ($) { diff --git a/IkiWiki/Plugin/calendar.pm b/IkiWiki/Plugin/calendar.pm index a89175cfb..c50d038df 100644 --- a/IkiWiki/Plugin/calendar.pm +++ b/IkiWiki/Plugin/calendar.pm @@ -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"))) { diff --git a/IkiWiki/Plugin/inline.pm b/IkiWiki/Plugin/inline.pm index c02137aed..815a37838 100644 --- a/IkiWiki/Plugin/inline.pm +++ b/IkiWiki/Plugin/inline.pm @@ -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); diff --git a/IkiWiki/Plugin/map.pm b/IkiWiki/Plugin/map.pm index 634b0e4d6..788b96827 100644 --- a/IkiWiki/Plugin/map.pm +++ b/IkiWiki/Plugin/map.pm @@ -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}}) { diff --git a/IkiWiki/Plugin/orphans.pm b/IkiWiki/Plugin/orphans.pm index 607239500..b1ebd1b9d 100644 --- a/IkiWiki/Plugin/orphans.pm +++ b/IkiWiki/Plugin/orphans.pm @@ -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 { diff --git a/IkiWiki/Plugin/pagecount.pm b/IkiWiki/Plugin/pagecount.pm index 40474b2a1..8d36f057e 100644 --- a/IkiWiki/Plugin/pagecount.pm +++ b/IkiWiki/Plugin/pagecount.pm @@ -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")); } diff --git a/IkiWiki/Plugin/pagestats.pm b/IkiWiki/Plugin/pagestats.pm index e64f7d9c3..47638210a 100644 --- a/IkiWiki/Plugin/pagestats.pm +++ b/IkiWiki/Plugin/pagestats.pm @@ -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 diff --git a/IkiWiki/Plugin/postsparkline.pm b/IkiWiki/Plugin/postsparkline.pm index f51e309c8..1d4532366 100644 --- a/IkiWiki/Plugin/postsparkline.pm +++ b/IkiWiki/Plugin/postsparkline.pm @@ -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} }, ); diff --git a/debian/changelog b/debian/changelog index 3a6fdf77d..49809e6cf 100644 --- a/debian/changelog +++ b/debian/changelog @@ -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. diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn index 62bebbeed..f6ea76c36 100644 --- a/doc/plugins/write.mdwn +++ b/doc/plugins/write.mdwn @@ -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 index 000000000..85a30b542 --- /dev/null +++ b/t/pagespec_match_list.t @@ -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 index 92d7977cf..000000000 --- a/t/use_pagespec.t +++ /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"); -- 2.44.0