File Coverage

blib/lib/App/WRT.pm
Criterion Covered Total %
statement 340 348 97.7
branch 89 108 82.4
condition 11 19 57.8
subroutine 47 48 97.9
pod 24 24 100.0
total 511 547 93.4


line stmt bran cond sub pod time code
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     9   544058 use version; our $VERSION = version->declare("v7.1.0");
  9         17366  
  9         51  
20              
21 9     9   765 use strict;
  9         18  
  9         168  
22 9     9   44 use warnings;
  9         17  
  9         255  
23 9     9   41 no warnings 'uninitialized';
  9         21  
  9         274  
24 9     9   92 use 5.14.0;
  9         55  
25 9     9   3198 use utf8;
  9         78  
  9         46  
26              
27 9     9   3135 use open qw(:std :utf8);
  9         7312  
  9         56  
28              
29 9     9   1341 use Carp;
  9         18  
  9         612  
30 9     9   55 use Cwd qw(getcwd abs_path);
  9         15  
  9         472  
31 9     9   2870 use Encode qw(decode encode);
  9         51380  
  9         614  
32 9     9   56 use File::Spec;
  9         17  
  9         269  
33 9     9   4603 use HTML::Entities;
  9         52620  
  9         709  
34 9     9   5350 use JSON;
  9         87486  
  9         52  
35 9     9   5384 use JSON::Feed;
  9         1702748  
  9         336  
36 9     9   4993 use Mojo::DOM;
  9         1661653  
  9         410  
37 9     9   5049 use XML::Atom::SimpleFeed;
  9         28280  
  9         432  
38              
39 9     9   4189 use App::WRT::Date qw(iso_date rfc_3339_date get_mtime month_name);
  9         23  
  9         598  
40 9     9   3791 use App::WRT::EntryStore;
  9         23  
  9         305  
41 9     9   3228 use App::WRT::FileIO;
  9         39  
  9         384  
42 9     9   3400 use App::WRT::HTML qw(:all);
  9         23  
  9         1791  
43 9     9   3362 use App::WRT::Image qw(image_size);
  9         24  
  9         568  
44 9     9   3563 use App::WRT::Markup qw(line_parse image_markup eval_perl);
  9         28  
  9         816  
45 9     9   72 use App::WRT::Util qw(dir_list file_get_contents);
  9         18  
  9         48692  
46              
47             =pod
48              
49             =head1 NAME
50              
51             App::WRT - WRiting Tool, a static site/blog generator and related utilities
52              
53             =head1 SYNOPSIS
54              
55             Using the commandline tools:
56              
57             $ mkdir project
58             $ cd project
59             $ wrt init # set up some defaults
60             $ wrt config # dump configuration values
61             $ wrt ls # list entries
62             $ wrt display new # print HTML for new entries to stdout
63             $ wrt render-all # publish HTML to project/public/
64              
65             Using App::WRT in library form:
66              
67             #!/usr/bin/env perl
68              
69             use App::WRT;
70             my $w = App::WRT->new(
71             entry_dir => 'archives',
72             url_root => '/',
73             # etc.
74             );
75             print $w->display(@ARGV);
76              
77             =head1 INSTALLING
78              
79             It's possible this would run on a Perl as old as 5.14.0. In practice, I know
80             that it works under 5.26.2. It should be fine on any reasonably modern Linux
81             distribution, and might work on BSD of your choosing. Maybe even MacOS. It's
82             possible that it would run under the Windows Subsystem for Linux, but it would
83             definitely fail under vanilla Windows; it currently makes too many assumptions
84             about things like directory path separators and filesystem semantics.
85              
86             (Although I would like the code to be more robust across platforms, this is not
87             a problem I feel much urgency about solving at the moment, since I'm pretty
88             sure I am the only user of this software. Please let me know if I'm mistaken.)
89              
90             To install the latest development version from the main repo:
91              
92             $ git clone https://code.p1k3.com/gitea/brennen/wrt.git
93             $ cd wrt
94             $ perl Build.PL
95             $ ./Build installdeps
96             $ ./Build test
97             $ ./Build install
98              
99             To install the latest version released on CPAN:
100              
101             $ cpanm App::WRT
102              
103             Or:
104              
105             $ cpan -i App::WRT
106              
107             You will likely need to use C or C to get a systemwide install.
108              
109             =head1 DESCRIPTION
110              
111             This started life somewhere around 2001 as C, a CGI script to
112             concatenate fragments of handwritten HTML by date. It has since accumulated
113             several of the usual weblog features (lightweight markup, feed generation,
114             embedded Perl, poetry tools, image galleries, and ill-advised dependencies),
115             but the basic idea hasn't changed that much.
116              
117             The C utility now generates static HTML files, instead of expecting to
118             run as a CGI script. This is a better idea, for the most part.
119              
120             By default, entries are stored in a simple directory tree under C.
121              
122             Like:
123              
124             archives/2001/1/1
125             archives/2001/1/2/index
126             archives/2001/1/2/sub_entry
127              
128             Which will publish files like so:
129              
130             public/index.html
131             public/all/index.html
132             public/2001/index.html
133             public/2001/1/index.html
134             public/2001/1/1/index.html
135             public/2001/1/2/index.html
136             public/2001/1/2/sub_entry/index.html
137              
138             Contents will be generated for each year and for the entire collection of dated
139             entries. Month indices will consist of all entries for that month. A
140             top-level index file will consist of the most recent month's entries.
141              
142             An entry may be either a plain UTF-8 text file, or a directory containing
143             several such files. If it's a directory, a file named "index" will be treated
144             as the text of the entry, and all other lower-case filenames without extensions
145             will be treated as sub-entries or documents within that entry, and displayed
146             accordingly. Links to certain other filetypes will be displayed as well.
147              
148             Directories may be nested to an arbitrary depth, although it's probably not a
149             good idea to go very deep with the current display logic.
150              
151             A PNG or JPEG file with a name like
152              
153             2001/1/1.icon.png
154             2001/1/1/index.icon.png
155             2001/1/1/whatever.icon.png
156             2001/1/1/whatever/index.icon.png
157              
158             will be treated as an icon for the corresponding entry file.
159              
160             =head2 MARKUP
161              
162             Entries may consist of hand-written HTML (to be passed along without further
163             mangling), a supported form of lightweight markup, or some combination thereof.
164              
165             Header tags (

,

, etc.) will be used to display titles in feeds,

166             navigation, and other places.
167              
168             Other special markup is indicated by a variety of HTML-like container tags.
169              
170             B - evaluated and replaced by whatever value you return
171             (evaluated in a scalar context):
172              
173             my $dog = "Ralph."; return $dog;
174              
175             This code is evaluated before any other processing is done, so you can return
176             any other markup understood by the script and have it handled appropriately.
177              
178             B - actually keys to the hash underlying the App::WRT
179             object, for the moment:
180              
181             $self->{title} = "About Ralph, My Dog"; return '';
182              
183            

The title is ${title}.

184              
185             This is likely to change at some point, so don't build anything too elaborate
186             on it.
187              
188             Embedded code and variables are intended only for use in the F