-
Notifications
You must be signed in to change notification settings - Fork 3
/
atomfeed-beta6
539 lines (395 loc) · 21 KB
/
atomfeed-beta6
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
# Blosxom Plugin: atomfeed -*-cperl-*-
# Author(s): Original plugin: Rael Dornfest <[email protected]>
# XML::Parser: Sam Ruby
# UTC and <modified> fixes for 0.3: Frank Hecker
# Enclosures support: Dave Slusher and Keith Irwin
# Upgrade to Atom 1.0 spec: Sam Pearson
# Version: atomfeed-beta-6
# Docs: Included below: type "perldoc atomfeed", or scroll down
# Blosxom Home/Docs/Licensing: http://www.raelity.org/apps/blosxom/
# Blosxom Plugin Docs: http://www.raelity.org/apps/blosxom/plugin.shtml
package atomfeed;
# ----- Mandatory configurable variables -----
# For a basic atom feed, you only need set $default_author and $feed_yr.
# If you do not, the plugin will exit quietly.
# All other configuration is optional, and can be safely ignored.
# Who would you like your feed to credit as the default author of each entry?
# Leave blank and the atomfeed plugin will attempt to use the whoami and
# fauxami plugins
$default_author = '';
# What year was your weblog started? This will be used
# to form part of your weblog's unique ID.
$feed_yr = '';
# ----- Optional configurable variables -----
# What is the default author's URL?
# Blank defaults to $blosxom::url
$author_uri = '';
# What is the default author's email address?
# Leave blank to exclude.
$author_email = '';
# Copyright statement:
# leave blank to exclude.
$copyright = '';
# What domain should Blosxom use in ID tags?
# Leave blank if you don't understand or for Blosxom to use the domain in $url.
$id_domain = '';
# Feed url
# Set the URL of the atom feed here. Defaults to $blosxom::url/index.atom
$feed_url = '';
# Icon
# Put the URL for a site icon here (for example, your site's favicon). Leave blank to exclude.
$icon_url = '';
# Logo
# Set to the URL for your site logo. Leave blank to exclude.
$logo_url = '';
# What template placeholder in your flavour template should I replace with feed-level <updated>?
# If you are using the built-in templates, leave this alone.
my $template_placeholder = "{{{updated}}}";
# Enclosures support
# ------------------
# You can add enclosures to your atom feed by linking to them in your post
# and giving the anchor tag a rel attribute of "enclosure".
# Set $use_full_enclosures to 1 if you wish to add length and content-type
# to your enclosures. This function relies upon your webserver having
# LWP modules installed.
$use_full_enclosures = '0';
# Name of a file to cache info about your enclosures:
$DataFile = "$blosxom::plugin_state_dir/enclosures.dat";
# Stylesheet support
# ------------------
# If you have a stylesheet to associate with your atom feed, place it's URL here.
$css_url = "";
# You can specify the type of stylesheet here:
$css_type = "text/css";
# ----- END OF CONFIGURABLE VARIABLES -----
# --- Plug-in package variables -----
$author = '';
$T = 'T';
$colon = ':';
$zerozero = '00';
# Sort out stylesheet:
$css_url and $css_url = "\n<?xml-stylesheet href=\"$css_url\" type=\"$css_type\"?>";
# Try to glean the domain from $url
$id_domain or ($id_domain) = $blosxom::url =~ m#http://(?:www\.)?([^\/]+)#;
# Feed url checking:
$feed_url or $feed_url = "$blosxom::url/index.atom";
$utc_date = '';
$feed_utc_date = '';
use vars qw/$feed_utc_date/;
$category;
$links;
$summary;
$copyright and $copyright = "<rights>$copyright</rights>";
$author_uri or $author_uri = "$blosxom::url";
$author_uri = "<uri>$author_uri</uri>";
$author_email and $author_email = "\n <email>$author_email</email>";
$icon_url and $icon_url = "<icon>$icon_url</icon>";
$logo_url and $logo_url = "<logo>$logo_url</logo>";
# ----- plugin subroutines -----
sub start {
# Check for our two mandatory variables:
unless ( $default_author and $feed_yr ) {
warn 'Blosxom plugin: atomfeed > Please set $default_author and $feed_yr. Exiting.\n';
return 0;
}
# Check for the existence of already-loaded flavour templates or theme,
# loading templates if there's nothing:
# Note that it looks like this condition should *never* be met, so why
# did Rael put this code here? Can't we just do _load_templates();
$blosxom::template{'atom'}{'head'} or _load_templates();
# changed to require from use to make plugin work for those
# without XML::Parser. Consequence: entries will never be labelled
# type='xhtml', only 'text' or 'html'. Thanks, S2!
eval { require XML::Parser; $parser = new XML::Parser; };
%escape = ('<'=>'<', '>'=>'>', '&'=>'&', '"'=>'"');
$escape_re = join '|' => keys %escape;
# If required, initialise the enclosures data cache:
$use_full_enclosures and _load_cache();
1;
}
sub head {
# Check and prepare a <title> and <subtitle>:
($blog_title_type, $blog_title) = _parse_markup($blosxom::blog_title);
($blog_description_type, $blog_description) = _parse_markup($blosxom::blog_description);
1;
}
sub story {
my($pkg, $path, $filename, $story_ref, $title_ref, $body_ref) = @_;
use File::stat;
# set up <category>:
if ( $path ) {
$category = "<category term=\"$path\"/>";
}
# <published>: derive from %blosxom::files
my @published_utc = gmtime($blosxom::files{"$blosxom::datadir$path/$filename.$blosxom::file_extension"});
$published_utc_date = sprintf("%4d-%02d-%02dT%02d:%02d:00Z",
$published_utc[5]+1900,
$published_utc[4]+1,
$published_utc[3],
$published_utc[2],
$published_utc[1]);
# <updated>: derive by stat()ing the file for its mtime:
my @updated_utc = gmtime(stat("$blosxom::datadir$path/$filename.$blosxom::file_extension")->mtime);
$updated_utc_date = sprintf("%4d-%02d-%02dT%02d:%02d:00Z",
$updated_utc[5]+1900,
$updated_utc[4]+1,
$updated_utc[3],
$updated_utc[2],
$updated_utc[1]);
# Date/time of most recently-modified story becomes date/time of the feed.
$feed_utc_date = $updated_utc_date if $updated_utc_date > $feed_utc_date;
# use %blosxom::files for the year component of feed-level <atom:id>
# in case the creation time is cached somewhere.
$utc_yr = $published_utc[5]+1900;
# Set authorship if available, falling back to $atomfeed::author
$author = $whoami::fullname || $fauxami::name || $default_author || '';
# Setup $summary. Adapted from Rael's foreshortened plugin.
$summary = $$body_ref;
$summary =~ s/<.+?>//gs;
$summary =~ s/[\.\!\?].+$/.../s;
$summary =~ s/[\r\n]/ /g;
$summary = "<summary type=\"text\">$summary</summary>";
# take look through $$body_ref for any enclosures or via/related links:
my @anchors = ( $$body_ref =~ /(<a [^>]+>)/gis );
$links = "\n";
foreach my $anchor ( @anchors ) {
if ( $anchor =~ /rel\s*=\s*"?\s*(via|enclosure|related)"?/is ) {
my( $type, $href );
$type = $1;
if ( $anchor =~ /href\s*=\s*"([^"]+)"/is ) {
$href = $1;
}
elsif ( $anchor =~ /href\s*=\s*([^\s]+)/is ) {
$href = $1;
}
if ( $href ){
$href =~ s/\s//g;
if ( $use_full_enclosures && ( $type eq "enclosure" ) ) {
my( $mime, $length );
# Check for presence of enclosure in $info:
unless ( $info->{$href} ) { _get_info($href); }
if ( $info->{$href} ) {
# Check again for data on enclosure in $info, just in case of problems getting it.
$mime = $info->{$href}->{type};
$length = $info->{$href}->{length};
$links .= " <link rel=\"$type\" href=\"$href\" type=\"$mime\" length=\"$length\"/>\n";
}
else {
# Fall back on a basic link:
$links .= " <link rel=\"$type\" href=\"$href\"/>\n";
}
}
else {
# Basic link:
$links .= " <link rel=\"$type\" href=\"$href\"/>\n";
}
}
}
}
# Parse post title:
($title_type, $title) = _parse_markup($$title_ref);
# Parse the post body:
($body_type, $body) = _parse_markup($$body_ref);
1;
}
sub foot {
my($pkg, $currentdir, $foot_ref) = @_;
# Replace the placeholder with the feed-level <updated> element:
$feed_utc_date = "<updated>$feed_utc_date</updated>";
$blosxom::output =~ s/$template_placeholder/$feed_utc_date/m;
return 1;
}
# ----- private subroutines -----
sub _parse_markup {
# Pass in some test to parse, and I'll return a type and the text suitably configured.
my $text = shift;
my $type;
# First, check to see if $text appears to contain markup.
# This regex should match any tag-like string: opening, closing or orphan tags.
if ( $text =~ m!</?[a-zA-Z0-9]+ ?/?>! ) {
# OK, looks like markup in there.
# Now, check to see if it looks well-formed:
if ( eval{$parser->parse("<div>$text</div>")}) {
# Yes? XHTML it is, then. I hope.
$type = 'xhtml';
$text = "<div xmlns=\"http://www.w3.org/1999/xhtml\">$text</div>";
}
else {
# No? Good old tag soup.
$type = 'html';
$text =~ s/($escape_re)/$escape{$1}/g;
}
}
else {
# We'll assume it's plaintext then.
$type = 'text';
}
# Out go the results:
return $type, $text;
}
sub _load_cache {
# Loads the data stored in $DataFile:
$info = {};
#open data file
local *FH;
if( -e "$DataFile") {
open FH, "$DataFile" or return $info;
}
flock(FH, 2);
while (<FH>) {
chomp ($_);
my ($url, $size, $type) = split (/ /, $_);
$info->{$url}->{length} = $size;
$info->{$url}->{type} = $type;
}
close (FH);
return $info;
}
sub _save_cache {
# Saves enclosure data structure in $info out to $DataFile
local *FH;
open FH, ">$DataFile" or return 0;
flock(FH, 2);
foreach $url (keys (%{$info})) {
print FH $url." ".$info->{$url}->{length} ." ". $info->{$url}->{type}."\n";
}
close FH;
return 1;
}
sub _get_info {
# Uses LWP to get content-type and content-length data
# for a given URL, adds this to the $info data structure
# and then calls _save_cache to preserve $info
return 0 unless eval "require LWP::UserAgent";
my $url = shift;
my $ua = LWP::UserAgent->new;
$ua->agent('BlosxomAtomFeed/0.5');
my $req = HTTP::Request->new(HEAD => "$url");
my $res = $ua->request($req);
my( $ct, $cl );
if ( $res->is_success ){
$ct = $res->header('content-type');
$cl = $res->header('content-length');
$info->{$url}->{type} = $ct;
$info->{$url}->{length} = $cl;
_save_cache();
return 1;
}
return 0;
}
sub _load_templates {
$blosxom::template{'atom'}{'content_type'} = 'application/atom+xml';
$blosxom::template{'atom'}{'date'} = "\n";
$blosxom::template{'atom'}{'head'} =<<'HEAD';
<?xml version="1.0" encoding="utf-8"?>$atomfeed::css_url
<feed xmlns="http://www.w3.org/2005/Atom">
<title type="$atomfeed::blog_title_type">$atomfeed::blog_title</title>
<subtitle type="$atomfeed::blog_description_type">$atomfeed::blog_description</subtitle>
<link rel="self" type="application/atom+xml" href="$atomfeed::feed_url"/>
<link rel="alternate" type="text/html" hreflang="$blosxom::blog_language" href="$blosxom::url" />
<id>tag$atomfeed::colon$atomfeed::id_domain,$atomfeed::feed_yr$atomfeed::colon/$blosxom::path_info</id>
<generator uri="http://www.blosxom.com/" version="$blosxom::version">Blosxom</generator>
$atomfeed::copyright
$atomfeed::icon_url
$atomfeed::logo_url
{{{updated}}}
HEAD
$blosxom::template{'atom'}{'story'} =<<'STORY';
<entry>
<id>tag$atomfeed::colon$atomfeed::id_domain,$atomfeed::utc_yr$atomfeed::colon$path/$fn</id>
<link rel="alternate" type="text/html" href="$blosxom::url$blosxom::path/$blosxom::fn.$blosxom::default_flavour" />$atomfeed::links
<title type="$atomfeed::title_type">$atomfeed::title</title>
<published>$atomfeed::published_utc_date</published>
<updated>$atomfeed::updated_utc_date</updated>
$atomfeed::category
<author>
<name>$atomfeed::author</name>
$atomfeed::author_uri$atomfeed::author_email
</author>
<content type="$atomfeed::body_type" xml:base="$blosxom::url" xml:lang="$blosxom::blog_language">
$atomfeed::body
</content>
</entry>
STORY
$blosxom::template{'atom'}{'foot'} =<<'FOOT';
</feed>
FOOT
1;
}
1;
__END__
=head1 NAME
Blosxom Plug-in: atomfeed
=head1 SYNOPSIS
Provides an Atom 1.0 feed of your weblog.
The plugin has all you need right on-board, including the appropriate flavour template components and a couple-three configuration directives.
It supports the majorty of the Atom 1.0 spec exluding the <source> element, which seems intended for use in feeds that contain items aggregated from other feeds, and currently the <contributor> element, which could be included using the meta plugin.
Point you browser/Atom feed reader at http://yoururl/index.atom.
=head1 VERSION
beta-6
=head1 AUTHORS
Rael Dornfest <[email protected]>, http://www.raelity.org/
- wrote the original plugin based on the 0.3 spec
Sam Ruby <[email protected]>, http://www.intertwingly.net/
- contributed the XML::Parser magic
Frank Hecker <[email protected]>, http://www.hecker.org/
- contributed patches for Atom 0.3 compliance, UTC date/time fix
Sam Pearson <[email protected]>, http://sgp.me.uk/
- Upgraded the plugin to handle Atom 1.0
Additional code was incorporated in the Atom 1.0 revision from the enclosures plugin originally written by:
Dave Slusher, http://www.evilgeniuschronicles.org/wordpress/ and Keith Irwin, http://www.asyserver.com/~kirwin/.
=head1 QUICKSTART INSTALLATION
To get an Atom feed up and running in a jiffy, you need only set the following variables and drop the plugin into your plugins directory:
B<$default_author> is where you specify who to credit as the default author of each entry. This can be overidden with the value provided by the whoami or fauxami plugins.
B<$feed_yr> is where you specify the year your site began. This is important as atomfeed needs to create a unique, unchanging ID for your weblog and it need this information to do so.
Everything else is optional.
=head1 FURTHER CONFIGURATION
There are a lot of variables available in the plugin you can use to further customise your Atom feed. These are all listed under B<VARIABLES>, below, with some notes as to their intended usage. Some have defaults already specified, others will silently be excluded until you set them.
Some elements of the feed - such as the <category> - are automatically generated: see B<OTHER ELEMENTS>, below, for more information.
If you wish to include enclosures or other types of <link> element in your feed, see the section B<ENCLOSURES AND LINK ELEMENTS>, below.
Although you can use this plugin without anything other than blosxom itself and a standard perl installation, it will perform better with some optional extras availabe. See B<OTHER RECOMMENDATIONS> for more information. This section also contains notes you will need to read if you intend to use this plugin alongside plugins that act on blosxom's variable interpolation, such as interpolate_fancy.
=head1 VARIABLES
B<$author_uri> This provides a URI for your default author. If you leave this blank, it defaults to $blosxom::url.
B<$author_email> Set this if you wish to include an email address for the author of each entry. Leave it blank to exclude this element of the feed.
B<$copyright> Set this variable to a statement of copyright for your site. Leave blank to exclude.
B<$id_domain> Atom associates unique ID tags with the feed itself and individual entries. By default it'll attempt to glean your domain from the specified or calculated value of $blosxom::url. But you can override this by setting $id_domain.
B<$feed_url> Atom feeds contain pointers to themselves, so you can set this variable to the location of your atom feed. If you leave in blank, it will use $blosxom::url/index.atom, which in most cases will be correct.
B<$icon_url> Set this variable to the URL of an icon to associate with your site. This should be a small image with a 1:1 aspect ratio - favicons are ideal. Leave blank to exclude.
B<$logo_url> Set this variable to the URL of a logo to associate with your site. This can be larger than the icon, and should have an aspect ratio of 2:1. Leave blank to exclude.
B<$template_placeholder> Set this varibale to the string used in your head.atom flavour template to idetify where you would like the feed-level updated element to appear. If you are using the built in templates, there is no need to change the default value.
B<$use_full_enclosures> If you are including enclosures in your Atom feed, set this variable to 1 if you would like to include length and type attributes. This requires that you have the LWP modules installed on your webserver to work. See B<ENCLOSURES AND LINK ELEMENTS>, below, for more information.
B<$DataFile> Set this variable to the name of a file where length and type data on your enclosures is stored.
B<$css_url> Set this variable to the location of a stylesheet you would like to have applied to your Atom feed. Leave blank to exclude altogether.
B<$css_type> Set this variable to the correct MIME type for the stylesheet you are including in your feed. Defaults to 'text/css'.
=head1 OTHER ELEMENTS
The plugin attempts to derive a <category> element based on the path of each post. As a consequence, posts in the root area of the weblog will have no <category>.
The plugin does provide a <summary> element, although this is not included in the default templates. It is derived by stripping html from the entry and truncating it to the first sentence, similar to the foreshortened plugin.
<published> is based on the timestamp for each entry contained with the %blosxom::files hash. <updated> is based on a direct stat on each entry for its mtime. All timestamps are in UTC.
=head1 ENCLOSURES AND LINK ELEMENTS
Atom provides an elegant method for expressing relationships between different resources using the rel attribute of its <link> element. This includes the method Atom uses to support enclosures, used to deliver additional content - often audio or video data - to the receipient of the feed.
To take advantage of this, the plugin supports rel attribute values of via, related and enclosure. To have these included in your feed, simply link the the resource in the body of your weblog post and make sure that the link has an appropriate rel attribute of enclosure, via or related, depending upon the kind of relationship you are expressing.
Ideally, enclosures should also contain information on their length (the size of the file) and MIME type. The atomfeed plugin will try to determine this information if you set the B<$use_full_enclosures> variable to '1'. To make sure this works correctly, you should link to the anclosure using an absolute URL rather than a relative one - "http://example.com/podcasts/july-05.mp3" instead of "/podcasts/july-05.mp3" - even if the enclosure is hosted under the same domain.
If you are unsure as to whether your server has this module installed, you should be able to experiment by setting the variable anyway, as the plugin should continue to function even if it is not present.
=head1 OTHER RECOMMENDATIONS
This plugin will work at its best if your server has B<XML::Parser> and B<LWP> modules installed, although it will function adequately without them.
In order for the <published> and <updated> timestamps to make sense, you should be running a plugin like entries_cache that retains the original timestamps of your entries and places them into the %blosxom::files hash. If you are not, you should remove the <published> element from the story template.
The atomfeed plugin assumes you're not running any fancy interpolation plugin (e.g. interpolate_fancy) which changes the way variables are specified in a template (e.g. <$foo /> rather than $foo). If you are running interpolate_fancy or the like--I am--use the config plugin and a config.atom file in your blosxom $datadir consisting of:
$blosxom::plugins{"interpolate_fancy"} = 0;
Where "interpolate_fancy" is the name of the interpolation plugin you're turning off _just for the atom feed_.
=head1 SEE ALSO
Blosxom Home/Docs/Licensing:
http://www.raelity.org/apps/blosxom/
Blosxom Plugin Docs:
http://www.raelity.org/apps/blosxom/plugin.shtml
Notes on 1.0 beta versions:
http://sgp.me.uk/sam/2005/07/20/atom-1-beta
Atom 1.0 Specification:
http://atompub.org/2005/07/11/draft-ietf-atompub-format-10.html
=head1 BUGS
Address bug reports and comments to the Blosxom mailing list: http://www.yahoogroups.com/group/blosxom
=head1 LICENSE
Blosxom and this Blosxom Plug-in
Copyright 2003, Rael Dornfest
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.