blib/lib/App/WRT.pm

filter: Statementstmt 96.6% 57 / 59 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 20 / 20 Podpod n/a totaltotal 97.4% 77 / 79 CC 1 SCAR 0.1
CC
1
Cov
97%
BEGIN
1.3
BEGIN
1.0
BEGIN
1.0
CRAP 1.0
« bin/wrt-render-all ↑ Summary
1 package App::WRT;
2  
3 # From semver.org:
4 #
5 # Given a version number MAJOR.MINOR.PATCH, increment the:
6 #
7 # MAJOR version when you make incompatible API changes,
8 # MINOR version when you add functionality in a backwards-compatible
9 # manner, and
10 # PATCH version when you make backwards-compatible bug fixes.
11 #
12 # Additional labels for pre-release and build metadata are available as
13 # extensions to the MAJOR.MINOR.PATCH format.
14 #
15 # Honestly I have always found it just about impossible to follow semver
16 # without overthinking a bunch of hair-splitting decisions and categories,
17 # but whatever. I'll try to follow it, roughly.
18  
19 9 ▶use version; our $VERSION = version->declare("v8.0.0");
Subroutine BEGIN: called CC=1 SCAR=0.0
20  
21 9 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
22 9 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
23 9 ▶no warnings 'uninitialized';
Subroutine BEGIN: called CC=1 SCAR=0.0
24 9 ▶use 5.14.0;
Subroutine BEGIN: called CC=1 SCAR=0.0
25 9 ▶use utf8;
Subroutine BEGIN: called CC=1 SCAR=0.0
26  
27 9 ▶use open qw(:std :utf8);
Subroutine BEGIN: called CC=1 SCAR=0.0
28  
29 9 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
30 9 ▶use Cwd qw(getcwd abs_path);
Subroutine BEGIN: called CC=1 SCAR=0.0
31 9 ▶use Encode qw(decode encode);
Subroutine BEGIN: called CC=1 SCAR=0.0
32 9 ▶use File::Spec;
Subroutine BEGIN: called CC=1 SCAR=0.0
33 9 ▶use HTML::Entities;
Subroutine BEGIN: called CC=1 SCAR=0.0
34 9 ▶use JSON;
Subroutine BEGIN: called CC=1 SCAR=0.0
35 9 ▶use JSON::Feed;
Subroutine BEGIN: called CC=1 SCAR=0.0
36 9 ▶use Mojo::DOM;
Subroutine BEGIN: called CC=1 SCAR=0.0
37 9 ▶use XML::Atom::SimpleFeed;
Subroutine BEGIN: called CC=1 SCAR=0.0
38  
39 9 ▶use App::WRT::Date qw(iso_date rfc_3339_date get_mtime month_name);
Subroutine BEGIN: called CC=1 SCAR=0.0
40 9 ▶use App::WRT::EntryStore;
Subroutine BEGIN: called CC=1 SCAR=0.0
41 9 ▶use App::WRT::FileIO;
Subroutine BEGIN: called CC=1 SCAR=0.0
42 0 ▶use App::WRT::Filters;
Subroutine BEGIN: called CC=1 SCAR=2.6
43 use App::WRT::HTML qw(:all);
44 use App::WRT::Image qw(image_size);
45 use App::WRT::Markup qw(line_parse image_markup eval_perl);
46 use App::WRT::Util qw(dir_list file_get_contents);
47  
48 =pod
49  
50 =head1 NAME
51  
52 App::WRT - WRiting Tool, a static site/blog generator and related utilities
53  
54 =head1 SYNOPSIS
55  
56 Using the commandline tools:
57  
58 $ mkdir project
59 $ cd project
60 $ wrt init # set up some defaults
61 $ wrt config # dump configuration values
62 $ wrt ls # list entries
63 $ wrt display new # print HTML for new entries to stdout
64 $ wrt render-all # publish HTML to project/public/
65  
66 Using App::WRT in library form:
67  
68 #!/usr/bin/env perl
69  
70 use App::WRT;
71 my $w = App::WRT->new(
72 entry_dir => 'archives',
73 url_root => '/',
74 # etc.
75 );
76 print $w->display(@ARGV);
77  
78 =head1 INSTALLING
79  
80 It's possible this would run on a Perl as old as 5.14.0. In practice, I know
81 that it works under 5.26.2. It should be fine on any reasonably modern Linux
82 distribution, and might work on BSD of your choosing. Maybe even MacOS. It's
83 possible that it would run under the Windows Subsystem for Linux, but it would
84 definitely fail under vanilla Windows; it currently makes too many assumptions
85 about things like directory path separators and filesystem semantics.
86  
87 (Although I would like the code to be more robust across platforms, this is not
88 a problem I feel much urgency about solving at the moment, since I'm pretty
89 sure I am the only user of this software. Please let me know if I'm mistaken.)
90  
91 To install the latest development version from the main repo:
92  
93 $ git clone https://code.p1k3.com/gitea/brennen/wrt.git
94 $ cd wrt
95 $ perl Build.PL
96 $ ./Build installdeps
97 $ ./Build test
98 $ ./Build install
99  
100 To install the latest version released on CPAN:
101  
102 $ cpanm App::WRT
103  
104 Or:
105  
106 $ cpan -i App::WRT
107  
108 You will likely need to use C<sudo> or C<su> to get a systemwide install.
109  
110 =head1 DESCRIPTION
111  
112 This started life somewhere around 2001 as C<display.pl>, a CGI script to
113 concatenate fragments of handwritten HTML by date. It has since accumulated
114 several of the usual weblog features (lightweight markup, feed generation,
115 embedded Perl, poetry tools, image galleries, and ill-advised dependencies),
116 but the basic idea hasn't changed that much.
117  
118 The C<wrt> utility now generates static HTML files, instead of expecting to
119 run as a CGI script. This is a better idea, for the most part.
120  
121 By default, entries are stored in a simple directory tree under C<entry_dir>.
122  
123 Like:
124  
125 archives/2001/1/1
126 archives/2001/1/2/index
127 archives/2001/1/2/sub_entry
128  
129 Which will publish files like so:
130  
131 public/index.html
132 public/all/index.html
133 public/2001/index.html
134 public/2001/1/index.html
135 public/2001/1/1/index.html
136 public/2001/1/2/index.html
137 public/2001/1/2/sub_entry/index.html
138  
139 Contents will be generated for each year and for the entire collection of dated
140 entries. Month indices will consist of all entries for that month. A
141 top-level index file will consist of the most recent month's entries.
142  
143 An entry may be either a plain UTF-8 text file, or a directory containing
144 several such files. If it's a directory, a file named "index" will be treated
145 as the text of the entry, and all other lower-case filenames without extensions
146 will be treated as sub-entries or documents within that entry, and displayed
147 accordingly. Links to certain other filetypes will be displayed as well.
148  
149 Directories may be nested to an arbitrary depth, although it's probably not a
150 good idea to go very deep with the current display logic.
151  
152 A PNG or JPEG file with a name like
153  
154 2001/1/1.icon.png
155 2001/1/1/index.icon.png
156 2001/1/1/whatever.icon.png
157 2001/1/1/whatever/index.icon.png
158  
159 will be treated as an icon for the corresponding entry file.
160  
161 =head2 MARKUP
162  
163 Entries may consist of hand-written HTML (to be passed along without further
164 mangling), a supported form of lightweight markup, or some combination thereof.
165  
166 Header tags (<h1>, <h2>, etc.) will be used to display titles in feeds,
167 navigation, and other places.
168  
169 Other special markup is indicated by a variety of HTML-like container tags.
170  
171 B<Embedded Perl> - evaluated and replaced by whatever value you return
172 (evaluated in a scalar context):
173  
174 <perl>my $dog = "Ralph."; return $dog;</perl>
175  
176 This code is evaluated before any other processing is done, so you can return
177 any other markup understood by the script and have it handled appropriately.
178  
179 B<Interpolated variables> - actually keys to the hash underlying the App::WRT
180 object, for the moment:
181  
182 <perl>$self->{title} = "About Ralph, My Dog"; return '';</perl>
183  
184 <p>The title is <em>${title}</em>.</p>
185  
186 This is likely to change at some point, so don't build anything too elaborate
187 on it.
188  
189 Embedded code and variables are intended only for use in the F<template> file,
190 where it's handy to drop in titles or conditionalize aspects of a layout. You
191 want to be careful with this sort of thing - it's useful in small doses, but
192 it's also a maintainability nightmare waiting to happen.
193  
194 B<Includes> - replaced by the contents of the enclosed file path, from the
195 root of the current wrt project:
196  
197 <include>path/to/file</include>
198  
199 This is a bit constraining, since it doesn't currently allow for files outside
200 of the current project, but is useful for including HTML generated by some
201 external script in a page.
202  
203 B<Several forms of lightweight markup>:
204  
205 <markdown>John Gruber's Markdown, by way of
206 Text::Markdown::Discount</markdown>
207  
208 <textile>Dean Allen's Textile, via Brad Choate's
209 Text::Textile.</textile>
210  
211 <freeverse>An easy way to
212 get properly broken lines
213 plus -- em dashes --
214 for poetry and such.</freeverse>
215  
216 B<And a couple of shortcuts>:
217  
218 <image>filename.ext
219 alt text, if any</image>
220  
221 <list>
222 one list item
223  
224 another list item
225 </list>
226  
227 As it stands, freeverse, image, and list are not particularly robust. In
228 practice, image and list have not proven all that useful, and may be deprecated
229 in a future release.
230  
231 =head2 TEMPLATES
232  
233 A single template, specified by the C<template_dir> and C<template> config
234 values, is used to render all pages. See F<example/templates/basic> for an
235 example, or run C<wrt init> in an empty directory and look at
236 F<templates/default>.
237  
238 Here's a short example:
239  
240 <!DOCTYPE html>
241 <html>
242 <head>
243 <meta charset="UTF-8">
244 <title>${title_prefix} - ${title}</title>
245 </head>
246  
247 <body>
248 ${content}
249 </body>
250  
251 </html>
252  
253 Within templates, C<${foo}> will be replaced with the corresponding
254 configuration value. C<${content}> will always be set to the content of the
255 current entry.
256  
257 =head2 CONFIGURATION
258  
259 Configuration is read from a F<wrt.json> in the directory where the C<wrt>
260 utility is invoked, or can (usually) be specified with the C<--config> option.
261  
262 See F<example/wrt.json> for a sample configuration.
263  
264 Under the hood, configuration is done by combining a hash called C<%default>
265 with values pulled out of the JSON file. Most defaults can be overwritten
266 from the config file, but changing some would require writing Perl, since
267 they contain things like subroutine references.
268  
269 =cut
270  
271 =over
272  
273 =item %default
274  
275 Here's a verbatim copy of C<%default>, with some commentary about values.
276  
277 my %default = (
278 root_dir => '.', # dir for wrt repository
279 entry_dir => 'archives', # dir for entry files
280 filter_dir => 'filters', # dir to contain filter scripts
281 publish_dir => 'public', # dir to publish site to
282 url_root => "/", # root URL for building links
283 image_url_root => '', # same for images
284 template_dir => 'templates', # dir for template files
285 template => 'default', # template to use
286 title => '', # current title (used in template)
287 title_prefix => '', # a string to slap in front of titles
288 stylesheet_url => undef, # path to a CSS file (used in template)
289 favicon_url => undef, # path to a favicon (used in template)
290 feed_alias => 'feed', # what entry path should correspond to feed?
291 feed_length => 30, # how many entries should there be in the feed?
292 author => undef, # author name (used in template, feed)
293 description => undef, # site description (used in template)
294 content => undef, # place to stash content for templates
295 default_entry => 'new', # what to display if no entry specified
296 cache_includes => 0, # should included files be cached in memory?
297  
298 # A license string for site content:
299 license => 'public domain',
300  
301 # A string value to replace all pages with (useful for occasional
302 # situations where every page of a site should serve some other
303 # content in-place, like Net Neutrality protest blackouts):
304 overlay => undef,
305  
306 # We'll show links for these, but not display them inline:
307 binfile_expr => qr/[.](tgz|zip|tar[.]gz|gz|txt|pdf)$/,
308 );
309  
310 =cut
311  
312 my %default = (
313 root_dir => '.', # dir for wrt repository
314 root_dir_abs => undef, # for stashing absolute path to wrt repo
315 entry_dir => 'archives', # dir for entry files
316 filter_dir => 'filters', # dir to contain filter scripts
317 publish_dir => 'public', # dir to publish site to
318 url_root => "/", # root URL for building links
319 image_url_root => '', # same for images
320 template_dir => 'templates', # dir for template files
321 template => 'default', # template to use
322 title => '', # current title (used in template)
323 title_prefix => '', # a string to slap in front of titles
324 stylesheet_url => undef, # path to a CSS file (used in template)
325 favicon_url => undef, # path to a favicon (used in template)
326 feed_alias => 'feed', # what entry path should correspond to feed?
327 feed_length => 30, # how many entries should there be in feed?
328 author => undef, # author name (used in template, feed)
329 description => undef, # site description (used in template)
330 content => undef, # place to stash content for templates
331 default_entry => 'new', # what to display if no entry specified
332 cache_includes => 0, # should included files be cached in memory?
333  
334 # A license string for site content:
335 license => 'public domain',
336  
337 # A string value to replace all pages with (useful for occasional
338 # situations where every page of a site should serve some other
339 # content in-place, like Net Neutrality protest blackouts):
340 overlay => undef,
341  
342 # We'll show links for these, but not display them inline:
343 binfile_expr => qr/[.](tgz|zip|tar[.]gz|gz|txt|pdf)$/,
344 );
345  
346 =item $default{entry_descriptions}
347  
348 A hashref which contains a map of entry titles to entry descriptions.
349  
350 =cut
351  
352 # TODO: this has gotten more than a little silly.
353 $default{entry_descriptions} = {
354 new => 'newest entries',
355 all => 'all entries',
356 };
357  
358 =item $default{title_cache}
359  
360 A hashref which contains a cache of entry titles, populated by the renderer.
361  
362 =cut
363  
364 $default{title_cache} = { };
365  
366 =back
367  
368 =head2 METHODS AND INTERNALS
369  
370 For no bigger than this thing is, the internals are convoluted. (This is
371 because it's spaghetti code originally written in a now-archaic language by a
372 teenager who didn't know how to program.)
373  
374 =over
375  
376 =item new_from_file($config_file)
377  
378 Takes a filename to pull JSON config data out of, and returns a new App::WRT
379 instance with the parameters set in that file.
380  
381 =cut
382  
383 sub new_from_file {
384 my ($config_file) = @_;
385  
386 my $JSON = JSON->new->utf8->pretty;
387  
388 # Grab configuration from wrt.json or other file:
389 my $config_hashref = $JSON->decode(file_get_contents($config_file));
390  
391 # Check for deprecated or removed configuration, and warn accordingly.
392 # TODO: These are really user-facing errors, so Carp is probably the wrong
393 # tool for the job here.
394 if ( defined $config_hashref->{entry_map} ) {
395 carp(
396 "Caution: wrt v7.0.0 and later no longer support entry_map.\n"
397 . "Please check $config_file and remove this value."
398 );
399 }
400 if ( defined $config_hashref->{embedded_perl} ) {
401 carp(
402 "Caution: wrt v7.0.0 and later no longer support toggling embedded_perl.\n"
403 . "Please check $config_file and remove this value.\n"
404 . "Note that embedded Perl may be deprecated in a future release."
405 );
406 }
407  
408 # decode() returns a hashref; this needs to be dereferenced:
409 return App::WRT->new(%{ $config_hashref });
410 }
411  
412 =item new(%params)
413  
414 Get a new WRT object with the specified parameters set.
415  
416 =cut
417  
418 sub new {
419 my $class = shift;
420 my %params = @_;
421  
422 # Stash absolute path to root directory.
423 #
424 # TODO: This is bad. It's here because imgsize() winds up calling getcwd() a
425 # ton of times if you don't give it absolute paths, which is actually super
426 # inefficient. See icon_markup() and image_markup() for usage.
427 # image_markup() in particular is awful and should be rewritten anyway.
428 $params{root_dir_abs} = abs_path($params{root_dir});
429  
430 my %copy_of_default = %default;
431 my $self = \%copy_of_default;
432 bless $self, $class;
433  
434 # Configure from passed-in values, overwriting defaults:
435 for my $p (keys %params) {
436 $self->{$p} = $params{$p};
437 }
438  
439 # Check and set up template path for later use:
440 $self->{template_path} = File::Spec->catfile(
441 $self->{template_dir},
442 $self->{template}
443 );
444 unless (-f $self->{template_path}) {
445 croak($self->{template_path} . ' does not exist or is not a plain file');
446 }
447 $self->{template_source} = file_get_contents($self->{template_path});
448  
449 $self->{entries} = App::WRT::EntryStore->new( $self->{entry_dir} );
450 $self->{filters} = App::WRT::Filters->new( $self->{filter_dir} );
451  
452 $self->populate_entry_caches();
453 $self->populate_metadata_cache();
454  
455 return $self;
456 }
457  
458 =item populate_entry_caches()
459  
460 Render each renderable path, cache the HTML, and parse to extract titles.
461  
462 =cut
463  
464 sub populate_entry_caches {
465 my $self = shift;
466  
467 my %html_cache;
468 my %title_cache;
469  
470 foreach my $entry ($self->{entries}->all_renderable()) {
471 $html_cache{$entry} = $self->handle($entry);
472 next unless length $html_cache{$entry};
473  
474 my @headers;
475  
476 eval {
477 local $SIG{__WARN__} = sub { die; };
478 my $dom = Mojo::DOM->new($html_cache{$entry});
479 @headers = $dom->find('h1, h2, h3, h4, h5, h6')->map('text')->each;
480 };
481 if ($@) {
482 carp("Parsing issues for $entry: $@");
483 }
484 if (@headers) {
485 $title_cache{$entry} = join ' - ', @headers;
486 }
487 }
488  
489 $self->{html_cache} = \%html_cache;
490 $self->{title_cache} = \%title_cache;
491 }
492  
493 =item populate_metadata_cache()
494  
495 If there's any metadata, such as tagged relationships, for a given entry,
496 populate an HTML blob for that stuff.
497  
498 XXX: Here is where we put the list of pages for a given tag, but also maybe
499 other things about a page or its properties. There should be a template /
500 partial involved.
501  
502 =cut
503  
504 sub populate_metadata_cache {
505 my $self = shift;
506  
507 my %metadata_html_cache;
508 foreach my $entry ($self->{entries}->all()) {
509 my $result = '';
510  
511 my $tag_for_this_entry = 'tag.' . join('.', split('/', $entry));
512 my (@tagged_entries) = $self->{entries}->by_prop($tag_for_this_entry);
513 my (@alpha_entries, @dated_entries);
514 for (@tagged_entries) {
515 if (m{^\d}) {
516 push @dated_entries, $_;
517 } else {
518 push @alpha_entries, $_;
519 }
520 }
521  
522 if (@tagged_entries) {
523 $result .= "<h1>entries tagged " . encode_entities($entry)
524 . "</h1>\n\n<table class=tags>";
525  
526 # Things starting with letters first, then things starting with digits:
527 foreach my $tagged_entry (@alpha_entries, reverse @dated_entries) {
528 $result .= table_row(
529 table_cell(
530 a($tagged_entry, { href => $self->{url_root} . "$tagged_entry" })
531 ),
532 table_cell(
533 encode_entities($self->get_title($tagged_entry))
534 )
535 );
536 $result .= "\n";
537 }
538 $result .= "</table>";
539 }
540  
541 $metadata_html_cache{$entry} = $result;
542 }
543  
544 $self->{metadata_html_cache} = \%metadata_html_cache;
545 }
546  
547 =item display($entry1, $entry2, ...)
548  
549 Return a string containing the given entries, which are in the form of
550 date/entry strings. If no parameters are given, default to C<default_entry>.
551  
552 display() expands aliases ("new" and "all", for example) as necessary, collects
553 entry content and metadata from the pre-rendered HTML caches, and wraps
554 everything up in the template.
555  
556 If C<overlay> is set, will return the value of overlay regardless of options.
557 (This is useful for hackily replacing every page in a site with a single blob
558 of HTML, for example if you're participating in some sort of blackout or
559 something.)
560  
561 =cut
562  
563 sub display {
564 my $self = shift;
565 my (@entries) = @_;
566  
567 return $self->{overlay} if defined $self->{overlay};
568  
569 # If no entries are defined, either...
570 if ($self->{entries}->is_extant('index')) {
571 # Fall back to the existing index file:
572 $entries[0] = 'index';
573 } else {
574 # Or use the default:
575 $entries[0] //= $self->{default_entry};
576 }
577  
578 # Title and navigation for template:
579 $self->{page_navigation} = '';
580 $self->{title} = join ' ', map { encode_entities($_) } @entries;
581  
582 if (scalar @entries == 1) {
583 # We've got a single path - it could be an alias that'll expand, or it
584 # could be an individual entry. See what can be done with navigation
585 # and title:
586 $self->{page_navigation} = $self->page_navigation($entries[0]);
587 $self->{title} = encode_entities($self->get_title($entries[0]));
588 }
589  
590 # Expand on any aliases:
591 @entries = map { $self->expand_alias($_) } @entries;
592  
593 # To be accessed as ${content} in the template below:
594 $self->{content} = join '', map {
595 $self->{html_cache}{$_}
596 . '<div class=entry-metadata>'
597 . $self->{metadata_html_cache}{$_}
598 . '</div>'
599 } @entries;
600  
601 # TODO: There may be an optimization to be had below in only running
602 # line_parse() against the template when the source is stashed. This would
603 # also lead to confusing weirdness if the template contained any special
604 # markup besides an <include> or relied on any side effects of embedded Perl
605 # code. For now, I'm leaving it alone.
606  
607 # Evaluate the template much like an entry:
608 # Eventually, the eval_perl() call should probably be hoisted up here and
609 # only used for templates.
610 return $self->line_parse($self->{template_source}, $self->{template_path});
611 }
612  
613 =item handle($entry)
614  
615 Return the text of an individual entry:
616  
617 nnnn/[nn/nn/]doc_name - a document within a day.
618 nnnn/nn/nn - a specific day.
619 nnnn/nn - a month.
620 nnnn - a year.
621 doc_name - a document in the root directory.
622  
623 =cut
624  
625 sub handle {
626 my ($self, $entry) = @_;
627  
628 for ($entry) {
629 return entry(@_) if $_ eq 'index';
630 return entry_stamped(@_, 'index') if m'^ [\d/]+ [[:lower:]_ /]+ $'x;
631 return entry_stamped(@_, 'all') if m'^ \d+ / \d{1,2} / \d{1,2} $'x;
632 return month(@_) if m'^ \d+ / \d{1,2} $'x;
633 return year(@_) if m'^ \d+ $'x;
634 return entry_stamped(@_, 'index') if m'^ [[:lower:]_] 'x;
635 }
636 }
637  
638 =item expand_alias($option)
639  
640 Expands/converts 'all', 'new', and 'fulltext' to appropriate values.
641  
642 Removes trailing slashes.
643  
644 =cut
645  
646 sub expand_alias {
647 my ($self, $alias) = @_;
648  
649 # Take care of trailing slashes:
650 chop $alias if $alias =~ m{/$};
651  
652 return reverse $self->{entries}->all_years() if $alias eq 'all';
653 return $self->{entries}->recent_days(5) if $alias eq 'new';
654 return $self->{entries}->all_days() if $alias eq 'fulltext';
655  
656 # No expansion, just give back our original value:
657 return $alias;
658 }
659  
660 =item link_bar(@extra_links)
661  
662 Returns a little context-sensitive navigation bar.
663  
664 =cut
665  
666 sub link_bar {
667 my $self = shift;
668 my (@extra_links) = @_;
669  
670 my $output;
671  
672 my (%description) = %{ $self->{entry_descriptions} };
673  
674 my @linklist = ( qw(new all), @extra_links );
675  
676 foreach my $link (@linklist) {
677 my $link_title;
678 if (exists $description{$link}) {
679 $link_title = $description{$link};
680 } else {
681 $link_title = 'entries for ' . $link;
682 }
683  
684 my $href = $self->{url_root} . $link . '/';
685 if ($link eq 'new') {
686 $href = $self->{url_root};
687 }
688 my $link_html = a({href => $href, title => $link_title}, $link) . "\n";
689  
690 if ($self->{title} eq $link) {
691 $link_html = qq{<strong>$link_html</strong>};
692 }
693  
694 $output .= $link_html;
695 }
696  
697 return $output;
698 }
699  
700 =item page_navigation($entry)
701  
702 Returns context-sensitive page navigation (next / previous links).
703  
704 =cut
705  
706 sub page_navigation {
707 my ($self) = shift;
708 my ($entry) = @_;
709 # Handle prev/next links.
710  
711 if ($entry eq 'new') {
712 return qq{<a href="/all" title="all">&larr; all archives</a>};
713 }
714  
715 my $output = '';
716  
717 my $prev = $self->{entries}->previous($entry);
718 my $next = $self->{entries}->next($entry);
719  
720 if ($prev) {
721 $output .= '<p>previous: <a title="previous" href="'
722 . encode_entities($self->{url_root} . $prev)
723 . '">'
724 . encode_entities($self->get_title($prev))
725 . '</a></p> ';
726 }
727  
728 if ($next) {
729 $output .= '<p>next: <a title="next" href="'
730 . encode_entities($self->{url_root} . $next)
731 . '">'
732 . encode_entities($self->get_title($next))
733 . '</a></p>';
734 }
735  
736 return $output;
737 }
738  
739 =item year($year)
740  
741 List out the updates for a year.
742  
743 =cut
744  
745 sub year {
746 my $self = shift;
747 my ($year) = @_;
748  
749 # Year is a text file:
750 return entry_markup($self->entry($year))
751 if $self->{entries}->is_file($year);
752  
753 # If it's not a directory, we can't do anything further. Bail out:
754 return p('No such year.')
755 unless $self->{entries}->is_dir($year);
756  
757 my $result;
758  
759 # Handle year directories with index files:
760 $result .= $self->entry($year)
761 if $self->{entries}->has_index($year);
762  
763 my $header_text = $self->icon_markup($year, $year);
764 $header_text ||= q{};
765  
766 $result .= heading("${header_text}${year}", 3);
767  
768 my @months = reverse $self->{entries}->months_for($year);
769  
770 my $year_text;
771 my $count = 0; # explicitly defined for later printing.
772  
773 foreach my $month (@months) {
774 my $month_text = '';
775 my @days = $self->{entries}->days_for($month);
776 $count += @days;
777  
778 foreach my $day (@days) {
779 my ($day_file, $day_url) = $self->root_locations($day);
780 $month_text .= a(
781 { href => "${day_url}/" },
782 $self->{entries}->basename($day)
783 ) . "\n";
784 }
785  
786 $month_text = small("( $month_text )");
787  
788 my ($month_file, $month_url) = $self->root_locations($month);
789 my $link = a(
790 { href => "${month_url}/" },
791 month_name($self->{entries}->basename($month))
792 );
793  
794 $year_text .= table_row(
795 table_cell({class => 'datelink'}, $link),
796 table_cell({class => 'datelink'}, $month_text)
797 ) . "\n\n";
798 }
799  
800 if ($count > 1) {
801 $year_text .= table_row(
802 table_cell(scalar(@months) . ' months'),
803 table_cell("$count entries")
804 );
805 }
806 elsif ($count == 0) { $year_text .= table_row(table_cell('No entries')); }
807 elsif ($count == 1) { $year_text .= table_row(table_cell("$count entry")); }
808  
809 $result .= "\n\n" . table($year_text) . "\n";
810  
811 return entry_markup($result);
812 }
813  
814 =item month($month)
815  
816 Prints the entries in a given month (nnnn/nn).
817  
818 =cut
819  
820 sub month {
821 my ($self, $month) = @_;
822  
823 my ($month_file, $month_url) = $self->root_locations($month);
824  
825 # If $month is a directory, render those of its children with day-like names:
826 if ($self->{entries}->is_dir($month)) {
827 my $result;
828 $result = $self->entry($month)
829 if $self->{entries}->has_index($month);
830  
831 my @days = reverse $self->{entries}->days_for($month);
832  
833 foreach my $day (@days) {
834 $result .= $self->entry_stamped($day);
835 }
836  
837 return $result;
838 } elsif ($self->{entries}->is_file($month)) {
839 # If $month is a file, it should just be rendered as a regular entry, more
840 # or less:
841 return $self->entry($month);
842 }
843 }
844  
845 =item entry_stamped($entry, $level)
846  
847 Wraps entry() + a datestamp in entry_markup().
848  
849 =cut
850  
851 sub entry_stamped {
852 my $self = shift;
853 my ($entry, $level) = @_;
854  
855 return entry_markup(
856 $self->entry($entry, $level)
857 . $self->datestamp($entry)
858 );
859 }
860  
861 =item entry_tag_list($entry)
862  
863 Get tag links for the entry.
864  
865 =cut
866  
867 sub entry_tag_list {
868 my $self = shift;
869 my ($entry) = @_;
870  
871 my @tags = sort grep {
872 m/^tag [.] .*/x
873 } $self->{entries}->props_for($entry);
874  
875 if (@tags) {
876 return '<b>tags:</b> ' . join ', ', map {
877 s/^tag[.](.*)$/$1/;
878 s{[.]}{/}g;
879 a(encode_entities($_), { href => $self->{url_root} . $_ })
880 } @tags;
881 }
882  
883 return '';
884 }
885  
886 =item entry($entry)
887  
888 Returns the contents of a given entry. May recurse, slightly.
889  
890 =cut
891  
892 sub entry {
893 my ($self, $entry, $level) = @_;
894 $level ||= 'index';
895  
896 my $result;
897  
898 # Display an icon, if we have one:
899 if ( my $icon_markup = $self->icon_markup($entry) ) {
900 $result = heading($icon_markup, 2) . "\n\n";
901 }
902  
903 # Note this may be an empty string
904 $result .= $self->get_entry_body($entry);
905  
906 # For text files we can bail out early:
907 if ($self->{entries}->is_file($entry)) {
908 return $result;
909 }
910  
911 # Past this point, we're assuming a directory.
912  
913 # Head of entry is followed by any sub-entries:
914 my @sub_entries = $self->{entries}->get_sub_entries($entry);
915  
916 if (@sub_entries >= 1) {
917 if ($level eq 'index' || $self->{entries}->has_prop($entry, 'wrt-noexpand')) {
918 # If we're only supposed to show the index, or the wrt-noexpand property
919 # is present, then don't expand sub-entries. A hack.
920  
921 # Icons or text links:
922 $result .= $self->list_contents($entry, @sub_entries);
923 }
924 elsif ($level eq 'all') {
925 # Everything displayable in the directory:
926 foreach my $se (@sub_entries) {
927 next if ($se =~ $self->{binfile_expr});
928  
929 # Recurse violently:
930 $result .= p({class => 'centerpiece'}, '+')
931 . $self->entry("$entry/$se");
932 }
933  
934 # Handle links to any remaining files that match binfile_expr:
935 $result .= $self->list_contents(
936 $entry,
937 grep { $self->{binfile_expr} } @sub_entries
938 );
939 }
940 }
941  
942 return $result;
943 }
944  
945 =item get_entry_body($entry)
946  
947 Returns the markup for an entry's body - which will be either the contents of
948 the entry if it's a text file, or an index file contained therein if it's a
949 directory.
950  
951 Also handles any filters.
952  
953 =cut
954  
955 sub get_entry_body {
956 my ($self, $entry) = @_;
957  
958 # Location of entry on local filesystem, and its URL:
959 my ($entry_loc, $entry_url) = $self->root_locations($entry);
960  
961 my $path_to_body;
962  
963 # For entries which are text files:
964 if ($self->{entries}->is_file($entry)) {
965 $path_to_body = $entry_loc;
966 }
967  
968 # For entries which are directories containing an index:
969 if ($self->{entries}->has_index($entry)) {
970 $path_to_body = "$entry_loc/index";
971 }
972  
973 # Process filters
974 my @filter_list;
975 if ($self->{entries}->has_prop($entry, 'filters')) {
976 my $filter_prop = $self->{entries}->prop_value($entry, 'filters');
977 @filter_list = split("\n", $filter_prop);
978 }
979  
980 if (defined $path_to_body) {
981 my $html = $self->line_parse(
982 file_get_contents($path_to_body),
983 $path_to_body
984 );
985 if (scalar @filter_list) {
986 return $self->{filters}->dispatch($entry, $html, @filter_list);
987 }
988 return $html;
989 }
990  
991 return '';
992 }
993  
994 =item list_contents($entry, @entries)
995  
996 Returns links (maybe with icons) for a set of sub-entries within an entry.
997  
998 =cut
999  
1000 sub list_contents {
1001 my $self = shift;
1002 my ($entry) = shift;
1003 my (@entries) = @_;
1004  
1005 my $contents;
1006 foreach my $se (@entries) {
1007 my $linktext = $self->icon_markup("$entry/$se", $se);
1008 $linktext ||= $se;
1009  
1010 $contents .= q{ }
1011 . a({ href => $self->{url_root} . "$entry/$se",
1012 title => $se },
1013 $linktext);
1014 }
1015  
1016 return p( em('more:') . " $contents" ) . "\n";
1017 }
1018  
1019 =item get_title($entry)
1020  
1021 Returns a title for the entry - potentially a cached one extracted earlier from
1022 the entry's HTML; otherwise just reuse the entry path itself.
1023  
1024 =cut
1025  
1026 sub get_title {
1027 my ($self, $entry) = @_;
1028  
1029 # Base title - just the entry path:
1030 my $title = $entry;
1031  
1032 # Do we have anything in the cache?
1033 if (defined $self->{title_cache}{$entry}) {
1034 $title = $self->{title_cache}{$entry};
1035 }
1036 return $title;
1037 }
1038  
1039 =item icon_markup($entry, $alt)
1040  
1041 Check if an icon exists for a given entry if so, return markup to include it.
1042 Icons are PNG or JPEG image files following a specific naming convention:
1043  
1044 index.icon.[png|jp(e)g] for directories
1045 [filename].icon.[png|jp(e)g] for flat text files
1046  
1047 Calls image_size, uses filename to determine type.
1048  
1049 =cut
1050  
1051 { my %cache;
1052 sub icon_markup {
1053 my ($self, $entry, $alt) = @_;
1054  
1055 return $cache{$entry . $alt}
1056 if defined $cache{$entry . $alt};
1057  
1058 my $icon_basepath;
1059 if ($self->{entries}->is_file($entry)) {
1060 $icon_basepath = "$entry.icon";
1061 }
1062 elsif ($self->{entries}->is_dir($entry)) {
1063 $icon_basepath = "$entry/index.icon";
1064 } else {
1065 # XXX there are bugs lurking here for virtual entries probably
1066 return;
1067 }
1068  
1069 # First suffix found will be used:
1070 my $suffix;
1071 for (qw(png jpg gif jpeg)) {
1072 if ($self->{entries}->is_extant( "$icon_basepath.$_")) {
1073 $suffix = $_;
1074 last;
1075 }
1076 }
1077  
1078 # Fail unless there's a file with one of the above suffixes:
1079 return 0 unless $suffix;
1080  
1081 my ($icon_loc, $icon_url) = $self->root_locations($icon_basepath);
1082  
1083 # Slurp width & height from the image file:
1084 my ($width, $height) = image_size(
1085 $self->{root_dir_abs} . '/' . "$icon_loc.$suffix"
1086 );
1087  
1088 return $cache{$entry . $alt} =
1089 qq{<img src="$icon_url.$suffix"\n width="$width" }
1090 . qq{height="$height"\n alt="$alt" />};
1091 }
1092 }
1093  
1094 =item datestamp($entry)
1095  
1096 Returns a nice html datestamp / breadcrumbs for a given entry.
1097  
1098 =cut
1099  
1100 sub datestamp {
1101 my $self = shift;
1102 my ($entry) = @_;
1103  
1104 my @fragment_stack;
1105 my @fragment_stamps = (
1106 a({ href => $self->{url_root} }, $self->{title_prefix}),
1107 );
1108  
1109 # Chop up by directory separator:
1110 my @pieces = split '/', $entry;
1111  
1112 foreach my $fragment (@pieces) {
1113 push @fragment_stack, $fragment;
1114 push @fragment_stamps,
1115 a({ href => $self->{url_root} . (join '/', @fragment_stack) . '/',
1116 title => $fragment }, $fragment);
1117 }
1118  
1119 my $stamp = p({class => 'datestamp'}, join(" /\n", @fragment_stamps));
1120 my $tag_list = $self->entry_tag_list($entry);
1121 if ($tag_list) {
1122 $stamp = "\n" . p({class => 'tags'}, $tag_list) . $stamp;
1123 }
1124  
1125 return "\n$stamp\n";
1126 }
1127  
1128 =item root_locations($file)
1129  
1130 Given an entry, return the appropriate concatenations with entry_dir and
1131 url_root.
1132  
1133 =cut
1134  
1135 sub root_locations {
1136 return (
1137 $_[0]->{entry_dir} . '/' . $_[1], # location on filesystem
1138 $_[0]->{url_root} . $_[1] # URL
1139 );
1140 }
1141  
1142 =item feed_print_recent($count)
1143  
1144 Print $count recent entries, falling back to the configured $feed_length.
1145  
1146 =cut
1147  
1148 sub feed_print_recent {
1149 my ($self, $count) = @_;
1150  
1151 $count //= $self->{feed_length};
1152  
1153 return $self->feed_print(
1154 $self->{entries}->recent_days($count)
1155 );
1156 }
1157  
1158 =item feed_print_json_recent($count)
1159  
1160 Print $count recent entries in JSON, falling back to the configured
1161 $feed_length.
1162  
1163 =cut
1164  
1165 sub feed_print_json_recent {
1166 my ($self, $count) = @_;
1167  
1168 $count //= $self->{feed_length};
1169  
1170 return $self->feed_print_json(
1171 $self->{entries}->recent_days($count)
1172 );
1173 }
1174  
1175 =item feed_print(@entries)
1176  
1177 Return an Atom feed for the given list of entries.
1178  
1179 Requires XML::Atom::SimpleFeed.
1180  
1181 XML::Atom::SimpleFeed will give bogus results with input that's just a string
1182 of octets (I think) if it contains characters outside of US-ASCII. In order to
1183 spit out clean UTF-8 output, we need to use Encode::decode() to flag entry
1184 content as UTF-8 / represent it internally as a string of characters. There's
1185 a whole lot I don't really understand about how this is handled in Perl, and it
1186 may be a locus of bugs elsewhere in wrt, but for now I'm just dealing with it
1187 here.
1188  
1189 Some references on that:
1190  
1191 =over
1192  
1193 =item * L<https://github.com/ap/XML-Atom-SimpleFeed/issues/2>
1194  
1195 =item * L<https://rt.cpan.org/Public/Bug/Display.html?id=19722>
1196  
1197 =item * L<https://cpanratings.perl.org/dist/XML-Atom-SimpleFeed>
1198  
1199 =item * L<perlunitut>
1200  
1201 =back
1202  
1203 =cut
1204  
1205 sub feed_print {
1206 my $self = shift;
1207 my (@entries) = @_;
1208  
1209 my $feed_url = $self->{url_root} . $self->{feed_alias};
1210  
1211 my ($first_entry_file, $first_entry_url) = $self->root_locations($entries[0]);
1212  
1213 my $feed = XML::Atom::SimpleFeed->new(
1214 -encoding => 'UTF-8',
1215 title => $self->{title_prefix} . "::" . $self->{feed_alias},
1216 subtitle => $self->{description},
1217 link => $self->{url_root},
1218 link => { rel => 'self', href => $feed_url, },
1219 icon => $self->{favicon_url},
1220 author => $self->{author},
1221 id => $self->{url_root},
1222 generator => 'App::WRT.pm / XML::Atom::SimpleFeed',
1223 updated => iso_date(get_mtime($first_entry_file)),
1224 );
1225  
1226 foreach my $entry (@entries) {
1227 my $content = $self->{html_cache}{$entry};
1228 if ( $self->{metadata_html_cache}{$entry} ) {
1229 $content .= '<div class=entry-metadata>'
1230 . $self->{metadata_html_cache}{$entry}
1231 . '</div>';
1232 }
1233  
1234 my ($entry_file, $entry_url) = $self->root_locations($entry);
1235  
1236 $feed->add_entry(
1237 title => $self->get_title($entry),
1238 link => $entry_url,
1239 id => $entry_url,
1240 content => $content,
1241 updated => iso_date(get_mtime($entry_file)),
1242 );
1243 }
1244  
1245 # Note: This output should be served with
1246 # Content-type: application/atom+xml
1247 #
1248 # I'm not, to be frank, entirely clear on why the decode() call here is
1249 # necessary:
1250 return decode('UTF-8', $feed->as_string);
1251 }
1252  
1253 =item feed_print_json
1254  
1255 Like feed_print(), but for JSON Feed.
1256  
1257 L<https://jsonfeed.org/>
1258  
1259 =cut
1260  
1261 sub feed_print_json {
1262 my ($self, @entries) = @_;
1263 my ($first_entry_file, $first_entry_url) = $self->root_locations($entries[0]);
1264  
1265 my $json_feed_url = $self->{url_root} . $self->{feed_alias} . '.json';
1266  
1267 my $user_comment = "This feed allows you to read the posts from this site in"
1268 . " any feed reader that supports the JSON Feed format. To "
1269 . "add this feed to your reader, copy the following URL — "
1270 . "$json_feed_url — and add it your reader.";
1271  
1272 my $feed = JSON::Feed->new(
1273 user_comment => $user_comment,
1274 title => $self->{title_prefix} . "::" . $self->{feed_alias},
1275 home_page_url => $self->{url_root},
1276 feed_url => $json_feed_url,
1277 description => $self->{description},
1278 author => +{ name => $self->{author}, },
1279 );
1280  
1281 if (defined $self->{favicon_url}) {
1282 $feed->set('favicon', $self->{favicon_url});
1283 }
1284  
1285 foreach my $entry (@entries) {
1286 my $content = $self->{html_cache}{$entry};
1287 if ($self->{metadata_html_cache}{$entry}) {
1288 $content .= '<div class=entry-metadata>'
1289 . $self->{metadata_html_cache}{$entry}
1290 . '</div>';
1291 }
1292  
1293 my ($entry_file, $entry_url) = $self->root_locations($entry);
1294  
1295 $feed->add_item(
1296 id => $entry_url,
1297 title => $self->get_title($entry),
1298 content_html => $content,
1299 date_modified => rfc_3339_date(get_mtime($entry_file)),
1300 date_published => rfc_3339_date(get_mtime($entry_file)),
1301 );
1302 }
1303  
1304 # Output
1305 return $feed->to_string;
1306 }
1307  
1308 =back
1309  
1310 =head1 SEE ALSO
1311  
1312 walawiki.org, Blosxom, rassmalog, Text::Textile, XML::Atom::SimpleFeed,
1313 Image::Size, and about a gazillion static site generators.
1314  
1315 =head1 AUTHOR
1316  
1317 Copyright 2001-2022 Brennen Bearnes
1318  
1319 =head1 LICENSE
1320  
1321 wrt is free software; you can redistribute it and/or modify
1322 it under the terms of the GNU General Public License as published by
1323 the Free Software Foundation, version 2 or 3 of the License.
1324  
1325 This program is distributed in the hope that it will be useful,
1326 but WITHOUT ANY WARRANTY; without even the implied warranty of
1327 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
1328 GNU General Public License for more details.
1329  
1330 You should have received a copy of the GNU General Public License
1331 along with this program. If not, see <http://www.gnu.org/licenses/>.
1332  
1333 =cut
1334  
1335 1;
« bin/wrt-render-all ↑ Summary