| 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 |