IkiWiki/Plugin/trail.pm

   1 #!/usr/bin/perl
   2 # Copyright © 2008-2011 Joey Hess
   3 # Copyright © 2009-2012 Simon McVittie <http://smcv.pseudorandom.co.uk/>
   4 # Licensed under the GNU GPL, version 2, or any later version published by the
   5 # Free Software Foundation
   6 package IkiWiki::Plugin::trail;
   7
   8 use warnings;
   9 use strict;
  10 use IkiWiki 3.00;
  11
  12 sub import {
  13         hook(type => "getsetup", id => "trail", call => \&getsetup);
  14         hook(type => "needsbuild", id => "trail", call => \&needsbuild);
  15         hook(type => "preprocess", id => "trailoptions", call => \&preprocess_trailoptions, scan => 1);
  16         hook(type => "preprocess", id => "trailitem", call => \&preprocess_trailitem, scan => 1);
  17         hook(type => "preprocess", id => "trailitems", call => \&preprocess_trailitems, scan => 1);
  18         hook(type => "preprocess", id => "traillink", call => \&preprocess_traillink, scan => 1);
  19         hook(type => "pagetemplate", id => "trail", call => \&pagetemplate);
  20         hook(type => "build_affected", id => "trail", call => \&build_affected);
  21 }
  22
  23 # Page state
  24 #
  25 # If a page $T is a trail, then it can have
  26 #
  27 # * $pagestate{$T}{trail}{contents}
  28 #   Reference to an array of lists each containing either:
  29 #     - [pagenames => "page1", "page2"]
  30 #       Those literal pages
  31 #     - [link => "link"]
  32 #       A link specification, pointing to the same page that [[link]]
  33 #       would select
  34 #     - [pagespec => "posts/*", "age", 0]
  35 #       A match by pagespec; the third array element is the sort order
  36 #       and the fourth is whether to reverse sorting
  37 #
  38 # * $pagestate{$T}{trail}{sort}
  39 #   A sorting order; if absent or undef, the trail is in the order given
  40 #   by the links that form it
  41 #
  42 # * $pagestate{$T}{trail}{circular}
  43 #   True if this trail is circular (i.e. going "next" from the last item is
  44 #   allowed, and takes you back to the first)
  45 #
  46 # * $pagestate{$T}{trail}{reverse}
  47 #   True if C<sort> is to be reversed.
  48 #
  49 # If a page $M is a member of a trail $T, then it has
  50 #
  51 # * $pagestate{$M}{trail}{item}{$T}[0]
  52 #   The page before this one in C<$T> at the last rebuild, or undef.
  53 #
  54 # * $pagestate{$M}{trail}{item}{$T}[1]
  55 #   The page after this one in C<$T> at the last refresh, or undef.
  56
  57 sub getsetup () {
  58         return
  59                 plugin => {
  60                         safe => 1,
  61                         rebuild => undef,
  62                 },
  63 }
  64
  65 # Cache of pages' old titles, so we can tell whether they changed
  66 my %old_trail_titles;
  67
  68 sub needsbuild (@) {
  69         my $needsbuild=shift;
  70
  71         foreach my $page (keys %pagestate) {
  72                 if (exists $pagestate{$page}{trail}) {
  73                         if (exists $pagesources{$page} &&
  74                             grep { $_ eq $pagesources{$page} } @$needsbuild) {
  75                                 # Remember its title, so we can know whether
  76                                 # it changed.
  77                                 $old_trail_titles{$page} = title_of($page);
  78
  79                                 # Remove state, it will be re-added
  80                                 # if the preprocessor directive is still
  81                                 # there during the rebuild. {item} is the
  82                                 # only thing that's added for items, not
  83                                 # trails, and it's harmless to delete that -
  84                                 # the item is being rebuilt anyway.
  85                                 delete $pagestate{$page}{trail};
  86                         }
  87                 }
  88         }
  89
  90         return $needsbuild;
  91 }
  92
  93 my $scanned = 0;
  94
  95 sub preprocess_trailoptions (@) {
  96         my %params = @_;
  97
  98         if (exists $params{circular}) {
  99                 $pagestate{$params{page}}{trail}{circular} =
 100                         IkiWiki::yesno($params{circular});
 101         }
 102
 103         if (exists $params{sort}) {
 104                 $pagestate{$params{page}}{trail}{sort} = $params{sort};
 105         }
 106
 107         if (exists $params{reverse}) {
 108                 $pagestate{$params{page}}{trail}{reverse} = $params{reverse};
 109         }
 110
 111         return "";
 112 }
 113
 114 sub preprocess_trailitem (@) {
 115         my $link = shift;
 116         shift;
 117
 118         # avoid collecting everything in the preprocess stage if we already
 119         # did in the scan stage
 120         if (defined wantarray) {
 121                 return "" if $scanned;
 122         }
 123         else {
 124                 $scanned = 1;
 125         }
 126
 127         my %params = @_;
 128         my $trail = $params{page};
 129
 130         $link = linkpage($link);
 131
 132         add_link($params{page}, $link, 'trail');
 133         push @{$pagestate{$params{page}}{trail}{contents}}, [link => $link];
 134
 135         return "";
 136 }
 137
 138 sub preprocess_trailitems (@) {
 139         my %params = @_;
 140
 141         # avoid collecting everything in the preprocess stage if we already
 142         # did in the scan stage
 143         if (defined wantarray) {
 144                 return "" if $scanned;
 145         }
 146         else {
 147                 $scanned = 1;
 148         }
 149
 150         # trail members from a pagespec ought to be in some sort of order,
 151         # and path is a nice obvious default
 152         $params{sort} = 'path' unless exists $params{sort};
 153         $params{reverse} = 'no' unless exists $params{reverse};
 154
 155         if (exists $params{pages}) {
 156                 push @{$pagestate{$params{page}}{trail}{contents}},
 157                         ["pagespec" => $params{pages}, $params{sort},
 158                                 IkiWiki::yesno($params{reverse})];
 159         }
 160
 161         if (exists $params{pagenames}) {
 162                 push @{$pagestate{$params{page}}{trail}{contents}},
 163                         [pagenames => (split ' ', $params{pagenames})];
 164         }
 165
 166         return "";
 167 }
 168
 169 sub preprocess_traillink (@) {
 170         my $link = shift;
 171         shift;
 172
 173         my %params = @_;
 174         my $trail = $params{page};
 175
 176         $link =~ qr{
 177                         (?:
 178                                 ([^\|]+)        # 1: link text
 179                                 \|              # followed by |
 180                         )?                      # optional
 181
 182                         (.+)                    # 2: page to link to
 183                 }x;
 184
 185         my $linktext = $1;
 186         $link = linkpage($2);
 187
 188         add_link($params{page}, $link, 'trail');
 189
 190         # avoid collecting everything in the preprocess stage if we already
 191         # did in the scan stage
 192         my $already;
 193         if (defined wantarray) {
 194                 $already = $scanned;
 195         }
 196         else {
 197                 $scanned = 1;
 198         }
 199
 200         push @{$pagestate{$params{page}}{trail}{contents}}, [link => $link] unless $already;
 201
 202         if (defined $linktext) {
 203                 $linktext = pagetitle($linktext);
 204         }
 205
 206         if (exists $params{text}) {
 207                 $linktext = $params{text};
 208         }
 209
 210         if (defined $linktext) {
 211                 return htmllink($trail, $params{destpage},
 212                         $link, linktext => $linktext);
 213         }
 214
 215         return htmllink($trail, $params{destpage}, $link);
 216 }
 217
 218 # trail => [member1, member2]
 219 my %trail_to_members;
 220 # member => { trail => [prev, next] }
 221 # e.g. if %trail_to_members = (
 222 #       trail1 => ["member1", "member2"],
 223 #       trail2 => ["member0", "member1"],
 224 # )
 225 #
 226 # then $member_to_trails{member1} = {
 227 #       trail1 => [undef, "member2"],
 228 #       trail2 => ["member0", undef],
 229 # }
 230 my %member_to_trails;
 231
 232 # member => 1
 233 my %rebuild_trail_members;
 234
 235 sub trails_differ {
 236         my ($old, $new) = @_;
 237
 238         foreach my $trail (keys %$old) {
 239                 if (! exists $new->{$trail}) {
 240                         return 1;
 241                 }
 242
 243                 if (exists $old_trail_titles{$trail} &&
 244                         title_of($trail) ne $old_trail_titles{$trail}) {
 245                         return 1;
 246                 }
 247
 248                 my ($old_p, $old_n) = @{$old->{$trail}};
 249                 my ($new_p, $new_n) = @{$new->{$trail}};
 250                 $old_p = "" unless defined $old_p;
 251                 $old_n = "" unless defined $old_n;
 252                 $new_p = "" unless defined $new_p;
 253                 $new_n = "" unless defined $new_n;
 254                 if ($old_p ne $new_p) {
 255                         return 1;
 256                 }
 257
 258                 if (exists $old_trail_titles{$old_p} &&
 259                         title_of($old_p) ne $old_trail_titles{$old_p}) {
 260                         return 1;
 261                 }
 262
 263                 if ($old_n ne $new_n) {
 264                         return 1;
 265                 }
 266
 267                 if (exists $old_trail_titles{$old_n} &&
 268                         title_of($old_n) ne $old_trail_titles{$old_n}) {
 269                         return 1;
 270                 }
 271         }
 272
 273         foreach my $trail (keys %$new) {
 274                 if (! exists $old->{$trail}) {
 275                         return 1;
 276                 }
 277         }
 278
 279         return 0;
 280 }
 281
 282 my $done_prerender = 0;
 283
 284 sub prerender {
 285         return if $done_prerender;
 286
 287         %trail_to_members = ();
 288         %member_to_trails = ();
 289
 290         foreach my $trail (keys %pagestate) {
 291                 next unless exists $pagestate{$trail}{trail}{contents};
 292
 293                 my $members = [];
 294                 my @contents = @{$pagestate{$trail}{trail}{contents}};
 295
 296                 foreach my $c (@contents) {
 297                         if ($c->[0] eq 'pagespec') {
 298                                 push @$members, pagespec_match_list($trail,
 299                                         $c->[1], sort => $c->[2],
 300                                         reverse => $c->[3]);
 301                         }
 302                         elsif ($c->[0] eq 'pagenames') {
 303                                 my @pagenames = @$c;
 304                                 shift @pagenames;
 305                                 foreach my $page (@pagenames) {
 306                                         if (exists $pagesources{$page}) {
 307                                                 push @$members, $page;
 308                                         }
 309                                         else {
 310                                                 # rebuild trail if it turns up
 311                                                 add_depends($trail, $page, deptype("presence"));
 312                                         }
 313                                 }
 314                         }
 315                         elsif ($c->[0] eq 'link') {
 316                                 my $best = bestlink($trail, $c->[1]);
 317                                 push @$members, $best if length $best;
 318                         }
 319                 }
 320
 321                 if (defined $pagestate{$trail}{trail}{sort}) {
 322                         # re-sort
 323                         @$members = pagespec_match_list($trail, 'internal(*)',
 324                                 list => $members,
 325                                 sort => $pagestate{$trail}{trail}{sort});
 326                 }
 327
 328                 if (IkiWiki::yesno $pagestate{$trail}{trail}{reverse}) {
 329                         @$members = reverse @$members;
 330                 }
 331
 332                 # uniquify
 333                 my %seen;
 334                 my @tmp;
 335                 foreach my $member (@$members) {
 336                         push @tmp, $member unless $seen{$member};
 337                         $seen{$member} = 1;
 338                 }
 339                 $members = [@tmp];
 340
 341                 for (my $i = 0; $i <= $#$members; $i++) {
 342                         my $member = $members->[$i];
 343                         my $prev;
 344                         $prev = $members->[$i - 1] if $i > 0;
 345                         my $next = $members->[$i + 1];
 346
 347                         $member_to_trails{$member}{$trail} = [$prev, $next];
 348                 }
 349
 350                 if ((scalar @$members) > 1 && $pagestate{$trail}{trail}{circular}) {
 351                         $member_to_trails{$members->[0]}{$trail}[0] = $members->[$#$members];
 352                         $member_to_trails{$members->[$#$members]}{$trail}[1] = $members->[0];
 353                 }
 354
 355                 $trail_to_members{$trail} = $members;
 356         }
 357
 358         foreach my $member (keys %pagestate) {
 359                 if (exists $pagestate{$member}{trail}{item} &&
 360                         ! exists $member_to_trails{$member}) {
 361                         $rebuild_trail_members{$member} = 1;
 362                         delete $pagestate{$member}{trail}{item};
 363                 }
 364         }
 365
 366         foreach my $member (keys %member_to_trails) {
 367                 if (! exists $pagestate{$member}{trail}{item}) {
 368                         $rebuild_trail_members{$member} = 1;
 369                 }
 370                 else {
 371                         if (trails_differ($pagestate{$member}{trail}{item},
 372                                         $member_to_trails{$member})) {
 373                                 $rebuild_trail_members{$member} = 1;
 374                         }
 375                 }
 376
 377                 $pagestate{$member}{trail}{item} = $member_to_trails{$member};
 378         }
 379
 380         $done_prerender = 1;
 381 }
 382
 383 sub build_affected {
 384         my %affected;
 385
 386         # In principle we might not have done this yet, although in practice
 387         # at least the trail itself has probably changed, and its template
 388         # almost certainly contains TRAILS or TRAILLOOP, triggering our
 389         # prerender as a side-effect.
 390         prerender();
 391
 392         foreach my $member (keys %rebuild_trail_members) {
 393                 $affected{$member} = sprintf(gettext("building %s, its previous or next page has changed"), $member);
 394         }
 395
 396         return %affected;
 397 }
 398
 399 sub title_of ($) {
 400         my $page = shift;
 401         if (defined ($pagestate{$page}{meta}{title})) {
 402                 return $pagestate{$page}{meta}{title};
 403         }
 404         return pagetitle(IkiWiki::basename($page));
 405 }
 406
 407 my $recursive = 0;
 408
 409 sub pagetemplate (@) {
 410         my %params = @_;
 411         my $page = $params{page};
 412         my $template = $params{template};
 413
 414         return unless length $page;
 415
 416         if ($template->query(name => 'trails') && ! $recursive) {
 417                 prerender();
 418
 419                 $recursive = 1;
 420                 my $inner = template("trails.tmpl", blind_cache => 1);
 421                 IkiWiki::run_hooks(pagetemplate => sub {
 422                                 shift->(%params, template => $inner)
 423                         });
 424                 $template->param(trails => $inner->output);
 425                 $recursive = 0;
 426         }
 427
 428         if ($template->query(name => 'trailloop')) {
 429                 prerender();
 430
 431                 my @trails;
 432
 433                 # sort backlinks by page name to have a consistent order
 434                 foreach my $trail (sort keys %{$member_to_trails{$page}}) {
 435
 436                         my $members = $trail_to_members{$trail};
 437                         my ($prev, $next) = @{$member_to_trails{$page}{$trail}};
 438                         my ($prevurl, $nexturl, $prevtitle, $nexttitle);
 439
 440                         if (defined $prev) {
 441                                 $prevurl = urlto($prev, $page);
 442                                 $prevtitle = title_of($prev);
 443                         }
 444
 445                         if (defined $next) {
 446                                 $nexturl = urlto($next, $page);
 447                                 $nexttitle = title_of($next);
 448                         }
 449
 450                         push @trails, {
 451                                 prevpage => $prev,
 452                                 prevtitle => $prevtitle,
 453                                 prevurl => $prevurl,
 454                                 nextpage => $next,
 455                                 nexttitle => $nexttitle,
 456                                 nexturl => $nexturl,
 457                                 trailpage => $trail,
 458                                 trailtitle => title_of($trail),
 459                                 trailurl => urlto($trail, $page),
 460                         };
 461                 }
 462
 463                 $template->param(trailloop => \@trails);
 464         }
 465 }
 466
 467 1;