Debian Codegraph @

bin/perlanet

raw
1 #!/usr/bin/env perl
2
3 use 5.10.0;
4 use strict;
5 use warnings;
6
7 use Perlanet::Simple;
8 use Getopt::Std;
9 use File::Basename;
10
11 our $VERSION = $Perlanet::VERSION;
12
13 my %opts;
14 getopts('hv', \%opts);
15
16 version() if $opts{v} || $opts{h};
17 help() if $opts{h};
18 exit if $opts{v} || $opts{h};
19
20 my $cfg = shift || './perlanetrc';
21 my $p = Perlanet::Simple->new_with_config(configfile => $cfg);
22
23 $p->run;
24
25 sub version {
26 my ($me) = fileparse $0;
27
28 print "\n$me, version $VERSION\n\n";
29 }
30
31 sub help {
32 my ($me) = fileparse $0;
33
34 print <<EOTEXT;
35 Usage: $me [-h] [-v] [config_file]
36
37 -h Display this help message
38 -v Display version information
39
40 config_file
41 Name of configuration file (defaults to perlanetrc)
42
43 EOTEXT
44 }
45
46 =head1 NAME
47
48 perlanet - command line interface to Perlanet.pm
49
50 =head1 SYNOPSIS
51
52 $ perlanet
53
54 Or
55
56 $ perlanet config_file
57
58 =head1 DESCRIPTION
59
60 C<perlanet> is a command line program for aggregating web feeds (both Atom
61 and RSS) and publishing a new web page and a new web feed containing the
62 results of that aggregation.
63
64 =head1 COMMAND LINE ARGUMENTS
65
66 C<perlanet> takes one optional command line argument, which is the name of
67 a configuration file to use. If no filename is given then the program looks
68 for a file called C<perlanetrc> in the current directory.
69
70 =head1 CONFIGURATION FILE
71
72 C<perlanet> requires a configuration file which contains details of which
73 feeds to aggregate and what to do with the results of the aggregation. By
74 default, C<perlanet> looks for a file called C<perlanetrc> in the current
75 directory, but this name can be overridden by passing the name of a different
76 file when calling the program.
77
78 The configuration file is in YAML format. YAML is a simple text-based file
79 format. See L<http://yaml.org/> for further details.
80
81 =head2 Configuration Options
82
83 The configuration file can contain the following options.
84
85 =over 4
86
87 =item title
88
89 The title of the resulting page and web feed. This option is mandatory.
90
91 =item description
92
93 The description of the resulting page and web feed. This option is mandatory.
94
95 =item url
96
97 A URL which will be associated with the resulting page and web feed. This will
98 usually be the address where the web page will be published. This option is
99 mandatory.
100
101 =item author
102
103 The name and email address of the author of the aggregated content. This
104 item has two sub-items - one each for the name and email address. This option
105 is mandatory.
106
107 =item agent
108
109 This optional entry defines the agent string that perlanet will use when
110 requesting data from web sites. It's the name of the program that site owners
111 will see in their web site access logs. Although it is optional, it is strongly
112 recommended that you give a value for this configuration option and that the
113 value you use includes contact details so that web site owners can get in
114 touch with you if they have any concerns about your use of their site.
115
116 =item entries
117
118 The maximum number of entries to include in the aggregated content. This option
119 is mandatory.
120
121 =item entries_per_feed
122
123 The C<entries> value above defines the total number of entries in the
124 aggregated output feed. The <entries_per_feed> value defines the number of
125 entries to take from each of your source feeds. For example, if this is
126 set to 1 then there will only be one entry from each feed in your output.
127 If this value is 0 (or missing) then all values from all source feeds are
128 used.
129
130 =item entry_sort_order
131
132 Entries have two dates, issued (which is the date that the item was first
133 published) and modified (which is the date that the item was last updated).
134 This configuration option controls which of these two dates are used to sort
135 the entries in a feed. It can be one of the two values C<issued> or
136 C<modified>. If this option is omitted, then C<modified> is used.
137
138 =item cutoff_duration
139
140 Sometimes you might want your generated feed to only contain entries from,
141 say, the last month. You can do that with the C<cutoff_duration> configuration
142 option. This takes the form of sub-parameters which are in the same format
143 as you would use when calling the constructor for
144 L<DateTime::Duration> (which isn't surprising as that's what happens to
145 them). For example the to exclude entries that are more than a month old,
146 you would use:
147
148 cutoff_duration:
149 months: 1
150
151 =item opml
152
153 The system can optionally create an OPML file containing details of the
154 feeds which are being aggregated. This optional option controls whether or not
155 this file is created. If it exists, it should be the name of the OPML file
156 to be created. If an OPML file is being created, then the C<feeds> options
157 (described below) will all require a C<web> sub-option.
158
159 =item page
160
161 This mandatory option contains the details of the web page to be created.
162 There are two sub-options - C<file> gives the name of the file to be created
163 and C<template> gives the name of a Template Toolkit template which will be
164 processed in order to create this file. See the section L<Output Template>
165 for more details on this template, and the web site L<http://tt2.org/> for
166 more information about the Template Toolkit.
167
168 =item feed
169
170 This mandatory option contains the details of the web feed to be created.
171 There are two sub-options - C<file> gives the name of the file to be created
172 and C<format> gives the format of the output (currently 'Atom' or 'RSS').
173
174 =item cache_dir
175
176 This if you give a directory name in this option then perlanet will use the
177 cache facility of URI::Fetch. This means that web feeds will only be downloaded
178 when they change.
179
180 =item feeds
181
182 This mandatory option gives details of the web feeds to be aggregated. Each
183 item on the list has one mandatory sub-option and two optional sub-options.
184 The mandatory sub-option is C<url> which gives the URL of the feed. The
185 optional sub-option C<title> gives a title to the feed which can be used
186 to identify the entries that originate from this feed. The optional C<web>
187 sub-option gives a web site URL associated with the feed (often the address
188 of the web site that the feed comes from). This can be used to create a list
189 of the aggregated sites. The C<web> sub-option becomes mandatory if you are
190 creating an OPML file. You can also add a C<max_entries> option which will
191 override the global C<entries_per_feed> setting. If this setting exists
192 and is set to zero, then the output feed will contain all of the entries
193 from this input feed.
194
195 =back
196
197 =head2 Example Configuration File
198
199 title: planet test
200 description: A Test Planet
201 url: http://planet.example.com/
202 author:
203 name: Dave Cross
204 email: [email protected]
205 entries: 20
206 opml: opml.xml
207 page:
208 file: index.html
209 template: index.tt
210 feed:
211 file: atom.xml
212 format: Atom
213 cache_dir: /tmp/feeds
214 feeds:
215 - url: http://blog.dave.org.uk/atom.xml
216 title: Dave's Blog
217 web: http://blog.dave.org.uk/
218 - url: http://use.perl.org/~davorg/journal/rss
219 title: Dave's use.perl Journal
220 web: http://use.perl.org/~davorg/journal/
221 - url: http://www.oreillynet.com/pub/feed/31?au=2607
222 title: Dave on O'Reillynet
223 web: http://www.oreillynet.com/pub/au/2607
224
225 =head2 Output Template
226
227 The web page is created from a Template Toolkit template. This template is
228 passed two variables.
229
230 =over 4
231
232 =item feed
233
234 This is the XML::Feed object which has been used to create the aggregated
235 feed. See the L<XML::Feed> documentation for details of the data that is
236 held in this object.
237
238 =item cfg
239
240 This is the contents of the configuration file, converted to a (nested)
241 Perl hash.
242
243 =back
244
245 =head2 Example Output Template
246
247 This is a simple template which uses the C<feed> variable to display details
248 of the aggregated feeds.
249
250 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
251 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
252 <html xmlns="http://www.w3.org/1999/xhtml">
253 <html>
254 <head>
255 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
256 <title>[% feed.title %]</title>
257 </head>
258 <body>
259 <h1>[% feed.title | html %]</h1>
260 <p>[% feed.description | html %]</p>
261 [% FOREACH entry IN feed.entries %]
262 <h2><a href="[% entry.link | url | html %]">[% entry.title | html %]</h2></a>
263 [% entry.content.body %]
264 [% IF entry.author OR entry.issued %]
265 <p>Published[% IF entry.author %] by [% entry.author | html; END %]
266 [% IF entry.issued %] on [% entry.issued | html; END %]</p>
267 [% END %]
268 [% END %]
269 <hr />
270 <address>[% feed.author | html %] / [% feed.modified | html %]</address>
271 </body>
272 </html>
273
274 In the future, the Perlanet wiki at L<http://wiki.github.com/davorg/perlanet>
275 will contain a cookbook of useful ideas to include in the output template.
276
277 =head1 SUPPORT
278
279 To report bugs in Perlanet, please use the CPAN request tracker. You can
280 either use the web page at
281 L<http://rt.cpan.org/Public/Bug/Report.html?Queue=Perlanet> or send an email
282 to [email protected].
283
284 =head1 SEE ALSO
285
286 =over 4
287
288 =item *
289
290 L<perlanet>
291
292 =item *
293
294 L<Plagger>
295
296 =back
297
298 =head1 AUTHOR
299
300 Dave Cross, <[email protected]>
301
302 =head1 COPYRIGHT AND LICENSE
303
304 Copyright (C) 2008 by Magnum Solutions Ltd.
305
306 This program library is free software; you can redistribute it and/or modify
307 it under the same terms as Perl itself, either Perl version 5.10.0 or,
308 at your option, any later version of Perl 5 you may have available.
309
310 =cut