ikiwiki (3.20130711) unstable; urgency=low
[ikiwiki.git] / 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;