lib/Plerd.pm

filter: Statementstmt 66.3% 260 / 392 Branchbran 42.6% 29 / 68 Conditioncond 25.0% 7 / 28 MC/DCmcdc 5.5% 1 / 18 Subroutinesub 73.6% 56 / 76 Podpod 22.2% 4 / 18 totaltotal 59.5% 357 / 600 CC 55 SCAR 17.2
CC
55
Cov
61%
_ordered_basenames
42.0
neighbor_basename
20.0
_build_recent_posts
8.0
CRAP 5.6
« lib/Plerd/Tag.pm ↑ Summary lib/Plerd/Init.pm »
1 package Plerd;
2  
3 13 our $VERSION = '2.000';
4  
5 13 ▶use Moose;
Subroutine BEGIN: called CC=1 SCAR=0.0
6 13 ▶use MooseX::Types::URI qw(Uri);
Subroutine BEGIN: called CC=1 SCAR=0.0
7 13 ▶use Template;
Subroutine BEGIN: called CC=1 SCAR=0.0
8 13 ▶use Path::Class::Dir;
Subroutine BEGIN: called CC=1 SCAR=0.0
9 13 ▶use DateTime;
Subroutine BEGIN: called CC=1 SCAR=0.0
10 13 ▶use DateTime::Format::W3CDTF;
Subroutine BEGIN: called CC=1 SCAR=0.0
11 13 ▶use URI;
Subroutine BEGIN: called CC=1 SCAR=0.0
12 13 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
13 13 ▶use Try::Tiny;
Subroutine BEGIN: called CC=1 SCAR=0.0
14 13 ▶use JSON;
Subroutine BEGIN: called CC=1 SCAR=0.0
15 13 ▶use Digest::MD5;
Subroutine BEGIN: called CC=1 SCAR=0.0
16 13 ▶use File::Temp ();
Subroutine BEGIN: called CC=1 SCAR=0.0
17  
18 13 ▶use Plerd::Post;
Subroutine BEGIN: called CC=1 SCAR=0.0
19 13 ▶use Plerd::Tag;
Subroutine BEGIN: called CC=1 SCAR=0.0
20  
21 13 has 'path' => (
22 is => 'ro',
23 isa => 'Str',
24 );
25  
26 13 has 'source_path' => (
27 is => 'ro',
28 isa => 'Str',
29 );
30  
31 13 has 'template_path' => (
32 is => 'ro',
33 isa => 'Str',
34 );
35  
36 13 has 'publication_path' => (
37 is => 'ro',
38 isa => 'Str',
39 );
40  
41 13 has 'database_path' => (
42 is => 'ro',
43 isa => 'Str',
44 );
45  
46 13 has 'tags_publication_path' => (
47 is => 'ro',
48 isa => 'Str',
49 lazy_build => 1,
50 );
51  
52 13 has 'base_uri' => (
53 is => 'ro',
54 required => 1,
55 isa => Uri,
56 coerce => 1,
57 );
58  
59 13 has 'tags_index_uri' => (
60 is => 'ro',
61 isa => Uri,
62 lazy_build => 1,
63 );
64  
65  
66 13 has 'title' => (
67 is => 'ro',
68 required => 1,
69 isa => 'Str',
70 );
71  
72 13 has 'author_name' => (
73 is => 'ro',
74 required => 1,
75 isa => 'Str',
76 );
77  
78 13 has 'author_email' => (
79 is => 'ro',
80 required => 1,
81 isa => 'Str',
82 );
83  
84 13 has 'twitter_id' => (
85 is => 'ro',
86 isa => 'Maybe[Str]',
87 default => undef,
88 );
89  
90 13 has 'facebook_id' => (
91 is => 'ro',
92 isa => 'Maybe[Str]',
93 default => undef,
94 );
95  
96 13 has 'image' => (
97 is => 'ro',
98 isa => Uri,
99 coerce => 1,
100 );
101  
102 13 has 'image_alt' => (
103 is => 'ro',
104 isa => 'Maybe[Str]',
105 default => undef,
106 );
107  
108 13 has 'recent_posts_maxsize' => (
109 is => 'ro',
110 isa => 'Int',
111 default => 10,
112 );
113  
114 13 has 'directory' => (
115 is => 'ro',
116 isa => 'Path::Class::Dir',
117 lazy_build => 1,
118 );
119  
120 13 has 'source_directory' => (
121 is => 'ro',
122 isa => 'Path::Class::Dir',
123 lazy_build => 1,
124 );
125  
126 13 has 'template_directory' => (
127 is => 'ro',
128 isa => 'Path::Class::Dir',
129 lazy_build => 1,
130 );
131  
132 13 has 'database_directory' => (
133 is => 'ro',
134 isa => 'Path::Class::Dir',
135 lazy_build => 1,
136 );
137  
138 13 has 'publication_directory' => (
139 is => 'ro',
140 isa => 'Path::Class::Dir',
141 lazy_build => 1,
142 );
143  
144 13 has 'tags_publication_directory' => (
145 is => 'ro',
146 isa => 'Path::Class::Dir',
147 lazy_build => 1,
148 );
149  
150 13 has 'template' => (
151 is => 'ro',
152 isa => 'Template',
153 lazy_build => 1,
154 );
155  
156 13 has 'post_template_file' => (
157 is => 'ro',
158 isa => 'Path::Class::File',
159 lazy_build => 1,
160 );
161  
162 13 has 'archive_template_file' => (
163 is => 'ro',
164 isa => 'Path::Class::File',
165 lazy_build => 1,
166 );
167  
168 13 has 'rss_template_file' => (
169 is => 'ro',
170 isa => 'Path::Class::File',
171 lazy_build => 1,
172 );
173  
174 13 has 'tags_template_file' => (
175 is => 'ro',
176 isa => 'Path::Class::File',
177 lazy_build => 1,
178 );
179  
180 13 has 'jsonfeed_template_file' => (
181 is => 'ro',
182 isa => 'Path::Class::File',
183 lazy_build => 1,
184 );
185  
186 13 has 'recent_file' => (
187 is => 'ro',
188 isa => 'Path::Class::File',
189 lazy_build => 1,
190 );
191  
192 13 has 'archive_file' => (
193 is => 'ro',
194 isa => 'Path::Class::File',
195 lazy_build => 1,
196 );
197  
198 13 has 'rss_file' => (
199 is => 'ro',
200 isa => 'Path::Class::File',
201 lazy_build => 1,
202 );
203  
204 13 has 'jsonfeed_file' => (
205 is => 'ro',
206 isa => 'Path::Class::File',
207 lazy_build => 1,
208 );
209  
210 13 has 'recent_posts' => (
211 is => 'ro',
212 isa => 'ArrayRef[Plerd::Post]',
213 lazy_build => 1,
214 clearer => 'clear_recent_posts',
215 );
216  
217 has 'datetime_formatter' => (
218 is => 'ro',
219 isa => 'DateTime::Format::W3CDTF',
220 10 ▶ default => sub { DateTime::Format::W3CDTF->new },
Subroutine __ANON__: called CC=1 SCAR=0.0
221 13 );
222  
223 13 has 'posts' => (
224 is => 'ro',
225 isa => 'ArrayRef[Plerd::Post]',
226 lazy_build => 1,
227 clearer => 'clear_posts',
228 );
229  
230 13 has 'index_of_post_with_guid' => (
231 is => 'ro',
232 isa => 'HashRef',
233 lazy_build => 1,
234 clearer => 'clear_post_index_hash',
235 );
236  
237 13 has 'index_of_post_with_url' => (
238 is => 'ro',
239 isa => 'HashRef',
240 lazy_build => 1,
241 clearer => 'clear_post_url_index_hash',
242 );
243  
244 13 has 'has_tags' => (
245 is => 'ro',
246 isa => 'Bool',
247 lazy_build => 1,
248 );
249  
250 has 'tags_map' => (
251 is => 'rw',
252 isa => 'HashRef',
253 10 ▶ default => sub { {} },
Subroutine __ANON__: called CC=1 SCAR=0.0
254 13 );
255  
256 has 'tag_case_conflicts' => (
257 is => 'rw',
258 isa => 'HashRef',
259 10 ▶ default => sub { {} },
Subroutine __ANON__: called CC=1 SCAR=0.0
260 13 );
261  
262 10 ▶sub BUILD {
Subroutine BUILD: called CC=3 SCAR=16.0
Pod undocumented
263 10 my $self = shift;
264  
265 10 ▶ unless ( $self->path ) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($self->path) 0 10 10
266 0 for my $subdir_type ( qw( source template publication database ) ) {
267 0 ▶ try {
Subroutine __ANON__: not called CC=1 SCAR=6.9
268 0 my $method = "${subdir_type}_directory";
269 0 my $dir = $self->$method;
270 }
271 0 ▶ catch {
Subroutine __ANON__: not called CC=1 SCAR=6.9
272 0 die "Can't create a new Plerd object, due to insufficient "
273 . "configuration: $_";
274 0 };
275 }
276 }
277  
278 10 return $self;
279 }
280  
281 9 ▶sub publish_all {
Subroutine publish_all: called CC=2 SCAR=7.1
Pod documented
282 9 my $self = shift;
283  
284 9 for my $post ( @{ $self->posts } ) {
285 3 $post->publish;
286 }
287  
288 2 $self->publish_tag_indexes;
289 2 $self->report_tag_case_conflicts;
290  
291 2 $self->publish_archive_page;
292  
293 2 $self->publish_recent_page;
294 2 $self->publish_rss;
295 0 $self->publish_jsonfeed;
296  
297 0 $self->_clear_caches;
298 }
299  
300 # Republish just enough to reflect a change to a single source file.
301 1 ▶sub publish_file {
Subroutine publish_file: called CC=4 SCAR=20.1
Pod documented
302 1 my $self = shift;
303 1 my ( $source_file ) = @_;
304  
305 # We hash the file's metadata block (everything above the first blank
306 # line) and compare it against the hash stored, by basename, in the
307 # db/posts.json index. A missing or changed hash means the change may
308 # affect the blog's sidebar, archive, and tag pages -- so we republish
309 # everything. An unchanged hash means only the post's body changed.
310 #
311 # For a body-only edit we always republish the post's own page. We touch
312 # the recent page and feeds only if this post is actually in the recent
313 # set; an edit to an older, out-of-feed post leaves every other file
314 # alone. Either way we consult the index for ordering and recency, so we
315 # never re-render the whole blog to publish one post.
316 1 my $basename = $source_file->basename;
317 1 my $index = $self->_read_post_index;
318 1 my $stored = $index->{ $basename };
319 1 my $current_hash = $self->_hash_of_metadata_block( $source_file );
320  
321 1 ▶ if ( !defined $stored || $stored->{ hash } ne $current_hash ) {
Branch: 1 branch
BranchTrueFalseTotal
if (not defined $stored or $stored->{'hash'} ne $current_hash) { } 1 0 1
Condition33%1/3
not defined $stored or $stored->{"hash"} ne $current_hash
l!l&&r!l&&!r
100
MC/DC0%0/2
not defined $stored or $stored->{"hash"} ne $current_hash
not defined $stored $stored->{"hash"} ne $current_hash
Truth table33%1/3
not(A) or B
A= not defined $storedB= $stored->{"hash"} ne $current_hash
ABresult
1X1
011
000
322 1 $self->publish_all;
323  
324 # publish_all may have rewritten source files (adding time, guid,
325 # etc.), so recompute the whole index from the files as they are now.
326 0 $self->_write_post_index( $self->_post_index_from_source );
327 }
328 else {
329 0 my $post = Plerd::Post->new(
330 plerd => $self,
331 source_file => $source_file,
332 );
333 0 $post->publish;
334  
335 0 my %is_recent = map { $_ => 1 } $self->_recent_basenames( $index );
336 0 ▶ if ( $is_recent{ $basename } ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($is_recent{$basename}) 0 0 0
337 0 $self->publish_recent_page;
338 0 $self->publish_rss;
339 0 $self->publish_jsonfeed;
340 }
341  
342 0 $self->_clear_caches;
343 }
344 }
345  
346 0 ▶sub _clear_caches {
Subroutine _clear_caches: not called CC=1 SCAR=6.9
347 0 my $self = shift;
348  
349 0 $self->clear_recent_posts;
350 0 $self->clear_posts;
351 0 $self->clear_post_index_hash;
352 0 $self->clear_post_url_index_hash;
353  
354 0 $self->tags_map( {} );
355 0 $self->tag_case_conflicts( {} );
356 }
357  
358 # The JSON index of the blog's posts, keyed by source-file basename. Each
359 # value is a record: { hash => <metadata-block MD5>, time => <W3C date> }.
360 # The hash answers "did this post's metadata change?"; the time is all the
361 # meta-work (ordering, recency, neighbor-finding) needs, since everything else
362 # derives from publication date. Together they let an incremental publish
363 # reason about the whole blog without re-rendering a single other post.
364 1 ▶sub _post_index_file {
Subroutine _post_index_file: called CC=1 SCAR=0.0
365 1 my $self = shift;
366  
367 1 return Path::Class::File->new(
368 $self->database_directory,
369 'posts.json',
370 );
371 }
372  
373 1 ▶sub _read_post_index {
Subroutine _read_post_index: called CC=2 SCAR=7.6
374 1 my $self = shift;
375  
376 1 my $file = $self->_post_index_file;
377 1 ▶ return {} unless -e $file;
Branch: 1 branch
BranchTrueFalseTotal
unless -e $file 1 0 1
378  
379 0 return JSON->new->decode(
380 scalar $file->slurp( iomode => '<:encoding(utf8)' )
381 );
382 }
383  
384 0 ▶sub _write_post_index {
Subroutine _write_post_index: not called CC=1 SCAR=6.9
385 0 my $self = shift;
386 0 my ( $index ) = @_;
387  
388 0 $self->_post_index_file->spew(
389 iomode => '>:encoding(utf8)',
390 JSON->new->canonical->pretty->encode( $index ),
391 );
392 }
393  
394 # Build an index record (hash + time) for one source file by reading only its
395 # leading metadata block -- the lines above the first blank line -- so no
396 # Markdown is rendered. Read as raw bytes so the MD5 is stable and wide
397 # characters don't trip up Digest::MD5.
398 1 ▶sub _index_record_for_file {
Subroutine _index_record_for_file: called CC=3 SCAR=11.0
399 1 my $self = shift;
400 1 my ( $source_file ) = @_;
401  
402 1 my $fh = $source_file->open('<:raw');
403 1 my $block = '';
404 1 ▶ while ( my $line = <$fh> ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined(my $line = readline $fh)) 2 0 2
405 2 ▶ last unless $line =~ /\S/;
Branch: 1 branch
BranchTrueFalseTotal
unless $line =~ /\S/ 1 1 2
406 1 $block .= $line;
407 }
408 1 close $fh;
409  
410 1 my ( $time ) = $block =~ /^time\s*:\s*(.+?)\s*$/mi;
411  
412 return {
413 1 hash => Digest::MD5::md5_hex( $block ),
414 time => $time,
415 };
416 }
417  
418 # Just the metadata-block hash for a single file, for change detection.
419 1 ▶sub _hash_of_metadata_block {
Subroutine _hash_of_metadata_block: called CC=1 SCAR=0.0
420 1 my $self = shift;
421 1 my ( $source_file ) = @_;
422  
423 1 return $self->_index_record_for_file( $source_file )->{ hash };
424 }
425  
426 0 ▶sub _post_index_from_source {
Subroutine _post_index_from_source: not called CC=2 SCAR=17.9
427 0 my $self = shift;
428  
429 0 my %index;
430 0 for my $file ( grep { /\.markdown$|\.md$/ }
431 $self->source_directory->children )
432 {
433 0 $index{ $file->basename } = $self->_index_record_for_file( $file );
434 }
435  
436 0 return \%index;
437 }
438  
439 # Source-file basenames ordered newest-first by publication date (ties broken
440 # by basename), derived from the post index. Undated records (which shouldn't
441 # occur after a full publish) sort to the very end.
442 0 ▶sub _ordered_basenames {
Subroutine _ordered_basenames: not called CC=6 SCAR=37.4
443 0 my $self = shift;
444 0 my ( $index ) = @_;
445 0 ▶ $index ||= $self->_read_post_index;
Condition0%0/3
$index ||= $self->_read_post_index
l!l&&r!l&&!r
000
MC/DC0%0/2
$index ||= $self->_read_post_index
$index $self->_read_post_index
Truth table0%0/3
A ||= B
A= $indexB= $self->_read_post_index
ABresult
1X1
011
000
446  
447 0 my $formatter = $self->datetime_formatter;
448 0 my $epoch_zero = DateTime->from_epoch( epoch => 0 );
449 0 my %date_of;
450 0 for my $basename ( keys %$index ) {
451 0 my $time = $index->{ $basename }->{ time };
452 0 ▶ my $dt = $time && eval { $formatter->parse_datetime( $time ) };
Condition0%0/3
$time && eval { do { $formatter->parse_datetime($time) } }
!ll&&!rl&&r
000
MC/DC0%0/2
$time && eval { do { $formatter->parse_datetime($time) } }
$time eval { do { $formatter->parse_datetime($time) } }
Truth table0%0/3
A && B
A= $timeB= eval { do { $formatter->parse_datetime($time) } }
ABresult
0X0
100
111
453 0 ▶ $date_of{ $basename } = $dt || $epoch_zero;
Condition0%0/3
$dt || $epoch_zero
l!l&&r!l&&!r
000
MC/DC0%0/2
$dt || $epoch_zero
$dt $epoch_zero
Truth table0%0/3
A || B
A= $dtB= $epoch_zero
ABresult
1X1
011
000
454 }
455  
456 return sort {
457 0 ▶ ( $date_of{ $b } <=> $date_of{ $a } ) || ( $a cmp $b )
Condition0%0/3
$date_of{$b} <=> $date_of{$a} || $a cmp $b
l!l&&r!l&&!r
000
MC/DC0%0/2
$date_of{$b} <=> $date_of{$a} || $a cmp $b
$date_of{$b} <=> $date_of{$a} $a cmp $b
Truth table0%0/3
A || B
A= $date_of{$b} <=> $date_of{$a}B= $a cmp $b
ABresult
1X1
011
000
458 } keys %$index;
459 }
460  
461 # The basenames that currently make up the recent set (the front page + feeds).
462 0 ▶sub _recent_basenames {
Subroutine _recent_basenames: not called CC=2 SCAR=17.9
463 0 my $self = shift;
464 0 my ( $index ) = @_;
465  
466 0 my @ordered = $self->_ordered_basenames( $index );
467 0 my $max = $self->recent_posts_maxsize;
468 0 ▶ $max = @ordered if @ordered < $max;
Branch: 1 branch
BranchTrueFalseTotal
if @ordered < $max 0 0 0
469  
470 0 return @ordered[ 0 .. $max - 1 ];
471 }
472  
473 # Given a post's basename, return the basename of its neighbor in publication
474 # order: $offset of -1 is the next-newer post, +1 the next-older. Returns undef
475 # at the ends (or if the post isn't in the index). Used so an incrementally
476 # published post page can resolve its prev/next links without building the
477 # whole blog.
478 0 ▶sub neighbor_basename {
Subroutine neighbor_basename: not called CC=4 SCAR=30.0
Pod undocumented
479 0 my $self = shift;
480 0 my ( $basename, $offset ) = @_;
481  
482 0 my @ordered = $self->_ordered_basenames;
483 0 my %position = map { $ordered[$_] => $_ } 0 .. $#ordered;
484  
485 0 my $i = $position{ $basename };
486 0 ▶ return unless defined $i;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $i 0 0 0
487  
488 0 my $j = $i + $offset;
489 0 ▶ return if $j < 0 || $j > $#ordered;
Branch: 1 branch
BranchTrueFalseTotal
if $j < 0 or $j > $#ordered 0 0 0
Condition0%0/3
$j < 0 or $j > $#ordered
l!l&&r!l&&!r
000
MC/DC0%0/2
$j < 0 or $j > $#ordered
$j < 0 $j > $#ordered
Truth table0%0/3
A or B
A= $j < 0B= $j > $#ordered
ABresult
1X1
011
000
490  
491 0 return $ordered[ $j ];
492 }
493  
494 # Create a page that lists all available tags with
495 # links to those pages that list the articles that
496 # have those tags
497 2 ▶sub publish_tag_indexes {
Subroutine publish_tag_indexes: called CC=5 SCAR=18.4
Pod undocumented
498 2 my $self = shift;
499  
500 # tags.tt is the one non-critical template: if it's missing, publish the
501 # rest of the blog anyway rather than dying. Warn only if the blog actually
502 # uses tags and therefore loses content by skipping their pages.
503 2 ▶ unless ( -e $self->tags_template_file ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (-e $self->tags_template_file) 0 2 2
504 0 ▶ if ( $self->has_tags ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->has_tags) 0 0 0
505 0 carp "This blog uses tags, but its template directory has no "
506 . "tags.tt file. Skipping publication of tag pages.\n";
507 }
508 0 return;
509 }
510  
511 2 my $tag_map = $self->tags_map;
512  
513 # Commentary: Ideally we'd just pass a sorted array of tag objects
514 # to the template. But alas said template was designed before tags were
515 # objects, and I didn't want to make Plerd users have to go mess around
516 # in their templates in between minor Plerd versions. And thus, we
517 # pull out some tag data into a hash and pass that in, instead.
518  
519 # Create all the individual tag pages
520 2 for my $tag (values %$tag_map) {
521  
522 2 $self->_publish_template_to_file(
523 $self->tags_template_file,
524 {
525 self_uri => $tag->uri,
526 is_tags_page => 1,
527 tags => { $tag->name => $tag->posts },
528 plerd => $self,
529 },
530 $self->tags_publication_file($tag->name),
531 );
532 }
533  
534 # Create the tag index
535 2 my %simplified_tag_map;
536 2 for my $tag (values %$tag_map) {
537 2 $simplified_tag_map{ $tag->name } = $tag->posts;
538 }
539 $self->_publish_template_to_file(
540 2 $self->tags_template_file,
541 {
542 self_uri => $self->tags_index_uri,
543 is_tags_index_page => 1,
544 is_tags_page => 1,
545 tags => \%simplified_tag_map,
546 plerd => $self,
547 },
548 $self->tags_publication_file,
549 );
550  
551 }
552  
553 2 ▶sub publish_recent_page {
Subroutine publish_recent_page: called CC=5 SCAR=18.1
Pod undocumented
554 2 my $self = shift;
555  
556 2 $self->_publish_template_to_file(
557 $self->post_template_file,
558 {
559 plerd => $self,
560 posts => $self->recent_posts,
561 title => $self->title,
562 },
563 $self->recent_file,
564 );
565  
566 2 my $index_file =
567 Path::Class::File->new( $self->publication_directory, 'index.html' );
568 # Swap index.html into place atomically: build the symlink under a temp
569 # name, then rename() it over any existing index.html. (symlink() silently
570 # fails if its destination already exists, and removing index.html first
571 # would briefly 404 it on republication.)
572 2 my $temp_link = Path::Class::File->new(
573 $self->publication_directory, "index.html.$$.tmp"
574 );
575 2 ▶ $temp_link->remove if -e $temp_link || -l $temp_link;
Branch: 1 branch
BranchTrueFalseTotal
if -e $temp_link or -l $temp_link 0 2 2
Condition33%1/3
-e $temp_link or -l $temp_link
l!l&&r!l&&!r
002
MC/DC0%0/2
-e $temp_link or -l $temp_link
-e $temp_link -l $temp_link
Truth table33%1/3
A or B
A= -e $temp_linkB= -l $temp_link
ABresult
1X1
011
000
576 2 ▶ if ( symlink $self->recent_file->basename, $temp_link ) {
Branch: 1 branch
BranchTrueFalseTotal
if (symlink $self->recent_file->basename, $temp_link) { } 2 0 2
577 2 ▶ rename "$temp_link", "$index_file"
Branch: 1 branch
BranchTrueFalseTotal
rename "$temp_link", "$index_file" or warn "Couldn't move the index.html symlink into place: $!\n" 2 0 2
578 or warn "Couldn't move the index.html symlink into place: $!\n";
579 }
580 else {
581 0 warn "Couldn't create the index.html symlink pointing at "
582 . $self->recent_file . ": $!\n";
583 }
584 }
585  
586 2 ▶sub publish_rss {
Subroutine publish_rss: called CC=1 SCAR=0.0
Pod undocumented
587 2 my $self = shift;
588  
589 2 $self->_publish_feed( 'rss' );
590 }
591  
592 0 ▶sub publish_jsonfeed {
Subroutine publish_jsonfeed: not called CC=1 SCAR=6.9
Pod undocumented
593 0 my $self = shift;
594  
595 0 $self->_publish_feed( 'jsonfeed' );
596 }
597  
598 0 ▶sub post_with_url {
Subroutine post_with_url: not called CC=2 SCAR=17.9
Pod documented
599 0 my $self = shift;
600 0 my ( $url ) = @_;
601  
602 0 my $index = $self->index_of_post_with_url->{ $url };
603 0 ▶ if ( defined $index ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $index) { } 0 0 0
604 0 return $self->posts->[ $self->index_of_post_with_url->{ $url } ];
605 }
606 else {
607 0 return;
608 }
609 }
610  
611 2 ▶sub _publish_feed {
Subroutine _publish_feed: called CC=2 SCAR=7.1
612 2 my $self = shift;
613 2 my ( $feed_type ) = @_;
614  
615 2 my $template_file_method = "${feed_type}_template_file";
616 2 my $file_method = "${feed_type}_file";
617  
618 2 ▶ return unless -e $self->$template_file_method;
Branch: 1 branch
BranchTrueFalseTotal
unless -e $self->$template_file_method 0 2 2
619  
620 2 my $formatter = $self->datetime_formatter;
621 2 my $timestamp =
622 $formatter->format_datetime( DateTime->now( time_zone => 'local' ) )
623 ;
624  
625 0 $self->_publish_template_to_file(
626 $self->$template_file_method,
627 {
628 plerd => $self,
629 posts => $self->recent_posts,
630 timestamp => $timestamp,
631 },
632 $self->$file_method,
633 );
634 }
635  
636 2 ▶sub publish_archive_page {
Subroutine publish_archive_page: called CC=1 SCAR=0.0
Pod undocumented
637 2 my $self = shift;
638  
639 2 $self->_publish_template_to_file(
640 $self->archive_template_file,
641 {
642 plerd => $self,
643 posts => $self->posts,
644 },
645 $self->archive_file,
646 );
647  
648 }
649  
650  
651 10 ▶sub _build_directory {
Subroutine _build_directory: called CC=2 SCAR=7.6
652 10 my $self = shift;
653  
654 10 ▶ if ( defined $self->path ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $self->path) { } 10 0 10
655 10 return Path::Class::Dir->new( $self->path );
656 }
657 else {
658 0 return undef;
659 }
660 }
661  
662 17 ▶sub _build_subdirectory {
Subroutine _build_subdirectory: called CC=3 SCAR=11.2
663 17 my $self = shift;
664 17 my ( $path_method, $subdir_name ) = @_;
665  
666 17 ▶ if ( defined $self->$path_method ) {
Branch: 2 branches
BranchTrueFalseTotal
if (defined $self->$path_method) { } 2 15 17
elsif (defined $self->path) { } 15 0 15
667 2 return Path::Class::Dir->new( $self->$path_method );
668 }
669 elsif ( defined $self->path ) {
670 15 return Path::Class::Dir->new(
671 $self->directory,
672 $subdir_name,
673 );
674 }
675 else {
676 0 die "Can't build $subdir_name directory! Neither a '$path_method' nor "
677 . "a 'path' attribute is defined.\n";
678 }
679 }
680  
681 10 ▶sub _build_source_directory {
Subroutine _build_source_directory: called CC=1 SCAR=0.0
682 10 my $self = shift;
683  
684 10 return $self->_build_subdirectory( 'source_path', 'source' );
685 }
686  
687 1 ▶sub _build_database_directory {
Subroutine _build_database_directory: called CC=1 SCAR=0.0
688 1 my $self = shift;
689  
690 1 return $self->_build_subdirectory( 'database_path', 'db' );
691 }
692  
693 2 ▶sub _build_publication_directory {
Subroutine _build_publication_directory: called CC=1 SCAR=0.0
694 2 my $self = shift;
695  
696 2 return $self->_build_subdirectory( 'publication_path', 'docroot' );
697 }
698  
699 2 ▶sub _build_template_directory {
Subroutine _build_template_directory: called CC=1 SCAR=0.0
700 2 my $self = shift;
701  
702 2 return $self->_build_subdirectory( 'template_path', 'templates' );
703 }
704  
705 2 ▶sub _build_template {
Subroutine _build_template: called CC=1 SCAR=3.1
706 2 my $self = shift;
707  
708 return Template->new( {
709 INCLUDE_PATH => $self->template_directory,
710 FILTERS => {
711 0 ▶ json => sub {
Subroutine __ANON__: not called CC=1 SCAR=6.9
712 0 my $text = shift;
713 # Encode as a JSON string, which correctly escapes
714 # backslashes, quotes, newlines, tabs, and other control
715 # characters. Then strip the enclosing quotes, since the
716 # template supplies its own.
717 0 my $encoded = JSON->new->allow_nonref->encode( $text );
718 0 $encoded =~ s/^"//;
719 0 $encoded =~ s/"$//;
720 0 return $encoded;
721 },
722 },
723 2 ENCODING => 'utf8',
724 } );
725 }
726  
727 2 ▶sub _build_post_template_file {
Subroutine _build_post_template_file: called CC=1 SCAR=0.0
728 2 my $self = shift;
729  
730 2 return Path::Class::File->new(
731 $self->template_directory,
732 'post.tt',
733 );
734 }
735  
736 2 ▶sub _build_rss_template_file {
Subroutine _build_rss_template_file: called CC=1 SCAR=0.0
737 2 my $self = shift;
738  
739 2 return Path::Class::File->new(
740 $self->template_directory,
741 'atom.tt',
742 );
743 }
744  
745 0 ▶sub _build_jsonfeed_template_file {
Subroutine _build_jsonfeed_template_file: not called CC=1 SCAR=6.9
746 0 my $self = shift;
747  
748 0 return Path::Class::File->new(
749 $self->template_directory,
750 'jsonfeed.tt',
751 );
752 }
753  
754 2 ▶sub _build_archive_template_file {
Subroutine _build_archive_template_file: called CC=1 SCAR=0.0
755 2 my $self = shift;
756  
757 2 return Path::Class::File->new(
758 $self->template_directory,
759 'archive.tt',
760 );
761 }
762  
763 2 ▶sub _build_recent_file {
Subroutine _build_recent_file: called CC=1 SCAR=0.0
764 2 my $self = shift;
765  
766 2 return Path::Class::File->new(
767 $self->publication_directory,
768 'recent.html',
769 );
770 }
771  
772 2 ▶sub _build_archive_file {
Subroutine _build_archive_file: called CC=1 SCAR=0.0
773 2 my $self = shift;
774  
775 2 return Path::Class::File->new(
776 $self->publication_directory,
777 'archive.html',
778 );
779 }
780  
781 0 ▶sub _build_rss_file {
Subroutine _build_rss_file: not called CC=1 SCAR=6.9
782 0 my $self = shift;
783  
784 0 return Path::Class::File->new(
785 $self->publication_directory,
786 'atom.xml',
787 );
788 }
789  
790 0 ▶sub _build_jsonfeed_file {
Subroutine _build_jsonfeed_file: not called CC=1 SCAR=6.9
791 0 my $self = shift;
792  
793 0 return Path::Class::File->new(
794 $self->publication_directory,
795 'feed.json',
796 );
797 }
798  
799 2 ▶sub _build_recent_posts {
Subroutine _build_recent_posts: called CC=6 SCAR=20.9
800 2 my $self = shift;
801  
802 # Incremental path: when the full post list hasn't been built (a body-only
803 # republish), construct only the recent posts named by the index, rather
804 # than rendering the whole blog just to find the newest few.
805 2 ▶ unless ( $self->has_posts ) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($self->has_posts) 0 2 2
806 return [
807 map {
808 0 Plerd::Post->new(
809 plerd => $self,
810 source_file => $self->source_directory->file( $_ ),
811 )
812 } $self->_recent_basenames
813 ];
814 }
815  
816 2 my @recent_posts = ();
817  
818 2 for my $post ( @{ $self->posts } ) {
819  
820 3 my $did_update = 0;
821  
822 3 ▶ if ( @recent_posts < $self->recent_posts_maxsize ) {
Branch: 2 branches
BranchTrueFalseTotal
if (@recent_posts < $self->recent_posts_maxsize) { } 3 0 3
elsif ($post->date > $recent_posts[-1]->date) { } 0 0 0
823 3 push @recent_posts, $post;
824 3 $did_update = 1;
825 }
826 elsif ( $post->date > $recent_posts[ -1 ]->date ) {
827 0 pop @recent_posts;
828 0 push @recent_posts, $post;
829 0 $did_update = 1;
830 }
831  
832 3 ▶ if ( $did_update ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($did_update) 3 0 3
833 3 @recent_posts = sort { $b->date <=> $a->date } @recent_posts;
834 }
835 }
836  
837 2 return \@recent_posts;
838 }
839  
840 10 ▶sub _build_posts {
Subroutine _build_posts: called CC=2 SCAR=7.0
841 10 my $self = shift;
842  
843 # Newest publication date first, ties broken by source basename, using the
844 # same comparator as _ordered_basenames so a full publish and an incremental
845 # publish agree on order. The inner sort guarantees order regardless of
846 # readdir order, and the grep keeps both .md and .markdown sources.
847 my @posts =
848 sort {
849 4 ▶ $b->date <=> $a->date
Condition66%2/3
$b->date <=> $a->date || $a->source_file->basename cmp $b->source_file->basename
l!l&&r!l&&!r
310
MC/DC0%0/2
$b->date <=> $a->date || $a->source_file->basename cmp $b->source_file->basename
$b->date <=> $a->date $a->source_file->basename cmp $b->source_file->basename
Truth table66%2/3
A || B
A= $b->date <=> $a->dateB= $a->source_file->basename cmp $b->source_file->basename
ABresult
1X1
011
000
850 || $a->source_file->basename cmp $b->source_file->basename
851 }
852 13 map { Plerd::Post->new( plerd => $self, source_file => $_ ) }
853 9 sort { $a->basename cmp $b->basename }
854 10 grep { /\.markdown$|\.md$/ }
855 $self->source_directory->children
856 ;
857  
858 3 return \@posts;
859 }
860  
861 2 ▶sub _build_index_of_post_with_guid {
Subroutine _build_index_of_post_with_guid: called CC=2 SCAR=6.9
862 2 my $self = shift;
863  
864 2 my %index_of_post;
865  
866 2 my $current_index = 0;
867  
868 2 for my $post ( @{ $self->posts } ) {
869 3 $index_of_post{ $post->guid } = $current_index++;
870 }
871  
872 2 return \%index_of_post;
873 }
874  
875 0 ▶sub _build_index_of_post_with_url {
Subroutine _build_index_of_post_with_url: not called CC=2 SCAR=17.9
876 0 my $self = shift;
877  
878 0 my %index_of_post;
879  
880 0 my $current_index = 0;
881  
882 0 for my $post ( @{ $self->posts } ) {
883 0 $index_of_post{ $post->uri } = $current_index++;
884 }
885  
886 0 return \%index_of_post;
887 }
888  
889 # Publish atomically: render into a temp file in the target's own directory,
890 # then rename() it into place. A rename(2) on the same filesystem is atomic, so
891 # a web server reading the published file always sees either the complete old
892 # file or the complete new one -- never a truncated or zero-length one. A render
893 # that dies partway through leaves the existing published file untouched.
894 11 ▶sub _atomically_write {
Subroutine _atomically_write: called CC=3 SCAR=12.0
895 11 my $self = shift;
896 11 my ( $target_file, $writer ) = @_;
897  
898 11 my ( $fh, $temp_path ) = File::Temp::tempfile(
899 'plerd-XXXXXX',
900 DIR => $target_file->parent->stringify,
901 UNLINK => 0,
902 );
903 11 binmode $fh, ':encoding(utf8)';
904  
905 11 my $ok = eval { $writer->( $fh ); 1 };
906 11 my $error = $@;
907 11 close $fh;
908  
909 11 ▶ unless ( $ok ) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($ok) 0 11 11
910 0 unlink $temp_path;
911 0 die $error;
912 }
913  
914 # File::Temp creates the file mode 0600; restore the perms a normally
915 # created file would get, so the web server can read it.
916 11 chmod 0666 & ~umask, $temp_path;
917  
918 11 ▶ unless ( rename $temp_path, $target_file->stringify ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (rename $temp_path, $target_file->stringify) 0 11 11
919 0 my $rename_error = $!;
920 0 unlink $temp_path;
921 0 die "Couldn't move $temp_path into place as $target_file: "
922 . "$rename_error\n";
923 }
924 }
925  
926 # Render a Template Toolkit template to a file, atomically (see
927 # _atomically_write). Dies via _throw_template_exception on a processing error,
928 # leaving any existing published file intact.
929 11 ▶sub _publish_template_to_file {
Subroutine _publish_template_to_file: called CC=1 SCAR=0.1
930 11 my $self = shift;
931 11 my ( $template_file, $vars, $target_file ) = @_;
932  
933 11 ▶ $self->_atomically_write( $target_file, sub {
Subroutine __ANON__: called CC=3 SCAR=11.7
934 11 my $out_fh = shift;
935 11 ▶ my $in_fh = $template_file->open('<:encoding(utf8)')
Branch: 1 branch
BranchTrueFalseTotal
my $in_fh = $template_file->open("<:encoding(utf8)") or die "Can't open template file $template_file for reading: $!\n" 11 0 11
936 or die "Can't open template file $template_file for reading: $!\n";
937 11 ▶ $self->template->process( $in_fh, $vars, $out_fh )
Branch: 1 branch
BranchTrueFalseTotal
$self->template->process($in_fh, $vars, $out_fh) or $self->_throw_template_exception($template_file) 11 0 11
938 or $self->_throw_template_exception( $template_file );
939 11 } );
940 }
941  
942 0 ▶sub _throw_template_exception {
Subroutine _throw_template_exception: not called CC=1 SCAR=6.9
943 0 my $self = shift;
944 0 my ( $template_file ) = @_;
945  
946 0 my $error = $self->template->error;
947  
948 0 die "Publication interrupted due to an error encountered while processing "
949 . "template file $template_file: $error\n";
950 }
951  
952 0 ▶sub generates_post_guids {
Subroutine generates_post_guids: not called CC=1 SCAR=6.9
Pod undocumented
953 0 carp "generates_post_guids() is deprecated. (Also, it doesn't do anything "
954 . "anyway.)";
955 }
956  
957 # Returns the blog's base_uri, guaranteed to end with a slash, so that
958 # URI->new_abs() builds correct URLs even when base_uri points at a
959 # subdirectory (e.g. http://example.com/blog).
960 7 ▶sub base_uri_with_slash {
Subroutine base_uri_with_slash: called CC=2 SCAR=7.2
Pod undocumented
961 7 my $self = shift;
962  
963 7 my $base_uri = $self->base_uri->clone;
964 7 my $path = $base_uri->path;
965 7 ▶ unless ( $path =~ m{/$} ) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($path =~ m[/$]) 0 7 7
966 0 $base_uri->path( "$path/" );
967 }
968 7 return $base_uri;
969 }
970  
971 # Tag-related builders & methods
972 2 ▶sub _build_tags_index_uri {
Subroutine _build_tags_index_uri: called CC=1 SCAR=0.0
973 2 my $self = shift;
974 2 return URI->new_abs(
975 'tags/',
976 $self->base_uri_with_slash,
977 );
978 }
979  
980 2 ▶sub _build_tags_publication_path { 'tags' }
Subroutine _build_tags_publication_path: called CC=1 SCAR=0.0
981  
982 2 ▶sub _build_tags_publication_directory {
Subroutine _build_tags_publication_directory: called CC=1 SCAR=0.0
983 2 my $self = shift;
984  
985 2 return $self->_build_subdirectory( 'tags_publication_path', 'docroot' );
986 }
987  
988 2 ▶sub _build_tags_template_file {
Subroutine _build_tags_template_file: called CC=1 SCAR=0.0
989 2 my $self = shift;
990  
991 2 return Path::Class::File->new(
992 $self->template_directory,
993 'tags.tt',
994 );
995 }
996  
997 0 ▶sub _build_has_tags {
Subroutine _build_has_tags: not called CC=2 SCAR=17.9
998 0 my $self = shift;
999  
1000 0 my $tags_map = $self->tags_map;
1001  
1002 0 ▶ if (scalar keys %$tags_map) {
Branch: 1 branch
BranchTrueFalseTotal
if (scalar keys %$tags_map) { } 0 0 0
1003 0 return 1;
1004 }
1005 else {
1006 0 return 0;
1007 }
1008  
1009 }
1010  
1011 # Return either the tags/index.html file
1012 # or a tags/TAGNAME.html file if given a tag
1013 4 ▶sub tags_publication_file {
Subroutine tags_publication_file: called CC=4 SCAR=13.9
Pod undocumented
1014 4 my ($self, $tag) = @_;
1015 4 ▶ $tag //= 'index';
Condition100%2/2
$tag //= "index"
l!l
22
MC/DC100%1/1
$tag //= "index"
$tag
Truth table100%2/2
A
A= $tag
Aresult
11
00
1016  
1017 4 my $file = Path::Class::File->new($self->publication_directory,
1018 $self->tags_publication_directory,
1019 "$tag.html");
1020  
1021 4 my $dir = $file->parent->stringify;
1022 4 ▶ if ( !-d $dir) {
Branch: 1 branch
BranchTrueFalseTotal
unless (-d $dir) 2 2 4
1023 2 ▶ mkdir $dir || die ("Cannot make directory: '$dir'. Create it manually, please.");
Condition50%1/2
$dir || die("Cannot make directory: '${dir}'. Create it manually, please.")
l!l
20
MC/DC0%0/1
$dir || die("Cannot make directory: '${dir}'. Create it manually, please.")
$dir
Truth table50%1/2
A
A= $dir
Aresult
11
00
1024 }
1025  
1026 4 return $file;
1027 }
1028  
1029 8 ▶sub tag_named {
Subroutine tag_named: called CC=2 SCAR=6.9
Pod undocumented
1030 8 my ( $self, $tag_name ) = @_;
1031  
1032 8 my $key = lc $tag_name;
1033  
1034 8 my $tag = $self->tags_map->{ $key };
1035  
1036 8 ▶ if ( $tag ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($tag) { } 6 2 8
1037 6 $tag->ponder_new_name( $tag_name );
1038 }
1039 else {
1040 2 $tag = Plerd::Tag->new(
1041 name => $tag_name,
1042 plerd => $self,
1043 );
1044 2 $self->tags_map->{ $key } = $tag;
1045 }
1046  
1047 8 return $tag;
1048 }
1049  
1050 0 ▶sub publish {
Subroutine publish: not called CC=1 SCAR=6.9
Pod undocumented
1051 0 my $self = shift;
1052  
1053 0 return $self->publish_all;
1054 }
1055  
1056 6 ▶sub tag_uri {
Subroutine tag_uri: called CC=2 SCAR=7.4
Pod documented
1057 6 my ( $self, $tag_name ) = @_;
1058  
1059 6 my $tag = $self->tag_named( $tag_name );
1060  
1061 6 ▶ if ( $tag ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($tag) { } 6 0 6
1062 6 return $tag->uri;
1063 }
1064 else {
1065 0 return $self->tags_index_uri;
1066 }
1067 }
1068  
1069 0 ▶sub add_tag_case_conflict {
Subroutine add_tag_case_conflict: not called CC=2 SCAR=17.9
Pod undocumented
1070 0 my ( $self, $conflicting_tag, $existing_tag ) = @_;
1071  
1072 0 ▶ return unless $conflicting_tag ne $existing_tag;
Branch: 1 branch
BranchTrueFalseTotal
unless $conflicting_tag ne $existing_tag 0 0 0
1073  
1074 0 $self->tag_case_conflicts->{lc $existing_tag}->{$conflicting_tag} = 1;
1075 0 $self->tag_case_conflicts->{lc $existing_tag}->{$existing_tag} = 1;
1076 }
1077  
1078 2 ▶sub report_tag_case_conflicts {
Subroutine report_tag_case_conflicts: called CC=3 SCAR=16.8
Pod undocumented
1079 2 my $self = shift;
1080  
1081 2 ▶ unless ( keys %{$self->tag_case_conflicts} ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (keys %{$self->tag_case_conflicts;}) 2 0 2
1082 2 return;
1083 }
1084  
1085 0 my $warning = "This blog's tags include the following case-conflicts:\n";
1086  
1087 0 foreach ( keys %{$self->tag_case_conflicts} ) {
1088 0 my $conflicts = join ', ', sort keys %{$self->tag_case_conflicts->{$_}};
1089 0 $warning .= "$conflicts\n";
1090 }
1091  
1092 0 $warning .= "This can lead to unexpected behavior, broken links, and other\n"
1093 . "sadnesses and regrets. Please normalize these tags!\n";
1094  
1095 0 warn $warning;
1096 }
1097  
1098 13 1;
1099  
1100 =encoding utf8
1101  
1102 =head1 NAME
1103  
1104 Plerd - Ultralight blogging with Markdown and Dropbox
1105  
1106 =head1 DESCRIPTION
1107  
1108 Plerd is a very lightweight system for writing and maintaining a blog based on
1109 Markdown files stored in a Dropbox-synced directory.
1110  
1111 For instructions on installing and using Plerd, please see the README file that
1112 should have accompanied this distribution. It is also available online
1113 at L<https://github.com/jmacdotorg/plerd#plerd>.
1114  
1115 The remainder of this document describes method calls and other
1116 information specific to the Plerd object class. (If you are using Plerd
1117 to run a blog, you don't necessarily have to know any of this!)
1118  
1119 =head1 CLASS METHODS
1120  
1121 =over
1122  
1123 =item new( \%config )
1124  
1125 Object constructor. The single config hashref I<must> include the following keys,
1126 each of which maps to the object attribute of the same name
1127 (see L<"OBJECT ATTRIBUTES">).
1128  
1129 =over
1130  
1131 =item *
1132  
1133 path
1134  
1135 =item *
1136  
1137 title
1138  
1139 =item *
1140  
1141 base_uri
1142  
1143 =item *
1144  
1145 author_name
1146  
1147 =item *
1148  
1149 author_email
1150  
1151 =back
1152  
1153 And, optional keys:
1154  
1155 =over
1156  
1157 =item *
1158  
1159 image
1160  
1161 =item *
1162  
1163 image_alt
1164  
1165 =item *
1166  
1167 twitter_id
1168  
1169 =item *
1170  
1171 recent_posts_maxsize I<Default value: 10>
1172  
1173 =back
1174  
1175 =back
1176  
1177 =head1 OBJECT ATTRIBUTES
1178  
1179 =head2 Read-only attributes, set during construction
1180  
1181 =over
1182  
1183 =item base_uri
1184  
1185 L<URI> object representing the base URI for this blog, which the system will prepend
1186 to any absolute links it builds.
1187  
1188 =item image
1189  
1190 (Optional) L<URI> object representing this blog's default image, for use in
1191 social media metadata and such.
1192  
1193 =item image_alt
1194  
1195 (Optional) A text description of this blog's default image, for use in
1196 social media metadata and such.
1197  
1198 =item path
1199  
1200 The path to a filesystem directory within which Plerd will look for
1201 "source", "docroot", "templates", and "db" directories as needed, using those names exactly.
1202  
1203 B<Caution:> If this is not defined I<and> any one of the previous three attributes
1204 is also undefined, then Plerd will die if you try to publish the blog.
1205  
1206 =item publication_path
1207  
1208 The path to the filesystem directory containing this blog's output directory.
1209  
1210 =item source_path
1211  
1212 The path to the filesystem directory containing this blog's source directory.
1213  
1214 =item template_path
1215  
1216 The path to the filesystem directory containing this blog's templates directory.
1217  
1218 =item database_path
1219  
1220 The path to the filesystem directory containing this blog's database directory.
1221  
1222 =item tags_publication_path
1223  
1224 The path to the filesystem directory containing this blog's out
1225 directory for tag index files.
1226  
1227 =item title
1228  
1229 String representing this blog's title.
1230  
1231 =item twitter_id
1232  
1233 (Optional) This Twitter username associated with this blog. Does not include
1234 the leading '@' character.
1235  
1236 =item recent_posts_maxsize
1237  
1238 Integer representing the maximum size of the recent_posts array, which in turn
1239 defines how many posts (at most) appear on the blog's front page and syndication
1240 document.
1241  
1242 =back
1243  
1244 =head2 Read-only attributes
1245  
1246 =over
1247  
1248 =item posts
1249  
1250 An arrayref of L<Plerd::Post> objects, representing all the blog's posts, in
1251 newest-to-oldest order. (Recency is determined by the dates manually
1252 set on the posts by the posts' author, not on their source files' modification
1253 time or whatever.)
1254  
1255 =item recent_posts
1256  
1257 An arrayref of L<Plerd::Post> objects, representing the most recent posts made to
1258 the blog, in newest-to-oldest order. (Recency is determined by the dates manually
1259 set on the posts by the posts' author, not on their source files' modification
1260 time or whatever.)
1261  
1262 The size of the array is no larger than the current value of the Plerd
1263 object's C<recent_posts_maxsize> attribute (and thus will be equal to that number
1264 for any blog whose total number of posts is greater than that number).
1265  
1266 =item directory
1267  
1268 A L<Path::Class::Dir> object representation of the path provided via this object's
1269 C<path> attribute. If said attribute is undefined, then this will return undef.
1270  
1271 =item source_directory
1272  
1273 A L<Path::Class::Dir> object representation of the Dropbox-synced directory that holds
1274 the blog's Markdown-based source files.
1275  
1276 =item template_directory
1277  
1278 A L<Path::Class::Dir> object representation of the Dropbox-synced directory that holds
1279 the blog's Template Toolkit-based template files. (See also L<Template>.)
1280  
1281 =item publication_directory
1282  
1283 A L<Path::Class::Dir> object representation of the Dropbox-synced directory that holds
1284 the blog's docroot -- in other words, the place Plerd will write HTML and XML files to.
1285  
1286 =item database_directory
1287  
1288 A L<Path::Class::Dir> object representation of the directory that holds
1289 the blogs's private, not-necessarily-human-readable data files.
1290  
1291 =item tags_publication_directory
1292  
1293 A L<Path::Class::Dir> object representation of the directory within the docroot that holds
1294 tag index HTML files.
1295  
1296 =item tag_index_uri
1297  
1298 This is a L<URI> object that points to the tag index. It is
1299 particularly helpful when creating navigation.
1300  
1301 =back
1302  
1303 =head1 OBJECT METHODS
1304  
1305 =over
1306  
1307 =item publish_all
1308  
1309 Publishes every Markdown file in the blog's source directory.
1310 Also recreates the recent, archive, and syndication files.
1311  
1312 =item publish_file( $source_file )
1313  
1314 Republishes the blog in response to a change to a single source file,
1315 given as a L<Path::Class::File> object.
1316  
1317 Plerd hashes the file's leading metadata block (everything above the
1318 first blank line) and compares it against the hash stored, keyed by the
1319 file's basename, in the C<db/posts.json> index. If the hash is missing or
1320 has changed -- meaning the change might affect shared pages such as the
1321 sidebar, archive, or tag indexes -- this calls L<"publish_all"> and
1322 rebuilds the index. If the hash is unchanged -- meaning only the post's
1323 body changed -- this republishes just that one post's page. It also
1324 refreshes the recent-posts page and the syndication feeds, but only when
1325 the edited post is currently in the recent set; a body edit to an older,
1326 out-of-feed post rewrites that post's page and nothing else. Ordering,
1327 recency, and prev/next neighbors are all read from the index, so a single
1328 post is republished without re-rendering the rest of the blog.
1329  
1330 =item post_with_url( $absolute_url )
1331  
1332 Returns the Plerd::Post object that has the given absolute URL. Returns undef
1333 if there is no such post.
1334  
1335 =item tag_uri( $tag )
1336  
1337 If $tag is defined, returns a L<URI> object with the address of the web
1338 page for the given tag.
1339  
1340 Otherwise, returns a L<URI> object referring to the tag index page.
1341  
1342 =item has_tags
1343  
1344 If the blog's posts declare any tags at all, then this returns true. Otherwise,
1345 returns false.
1346  
1347 =back
1348  
1349 =head1 AUTHOR
1350  
1351 Jason McIntosh <jmac@jmac.org>
1352  
1353 =head1 CONTRIBUTORS
1354  
1355 =over
1356  
1357 =item *
1358  
1359 Petter Hassberg
1360  
1361 =item *
1362  
1363 Joe Johnston
1364  
1365 =item *
1366  
1367 Christian Sánchez
1368  
1369 =item *
1370  
1371 David Turner
1372  
1373 =item *
1374  
1375 Rebecca Turner
1376  
1377 =back
« lib/Plerd/Tag.pm ↑ Summary lib/Plerd/Init.pm »