Updated the blosxom homepage and mailing list URL
[matthijs/upstream/blosxom-plugins.git] / general / allconsuming
1 # Blosxom Plugin: allconsuming                                    -*- cperl -*-
2 # Author: Todd Larason (jtl@molehill.org)
3 # Version: 0+4i
4 # Blosxom Home/Docs/Licensing: http://blosxom.sourceforge.net/
5 # Netflix plugin Home/Docs/Licensing:
6 # http://molelog.molehill.org/blox/Computers/Internet/Web/Blosxom/AllConsuming/
7 package allconsuming;
8
9 # http://allconsuming.net/news/000012.html
10
11 # -------------- Configuration Variables --------------
12 # AllConsuming username
13 $username = undef
14   unless defined $username;
15
16 # Amazon Associate ID; feel free to leave this =)
17 $associate_id = 'mtmolel-20'
18   unless defined $associate_id;
19
20 # undef == "list all"
21 #     0 == "don't list at all"
22 #    >0 == list first N (or all, if < N)
23 #    <0 == list random N (or all in random order, if < N)
24 %num = (
25         purchased => 5,          # most recent 5
26         reading   => undef,      # all
27         rereading => undef,      # all
28         favorite  => -5,         # random 5
29         completed => 5,          # most recent 5
30         nofinish  => 0           # none
31        ) unless scalar keys %num > 0;
32
33 # one of: SOAP::Lite, LWP, wget (or a pathname to wget), curl (or a pathname)
34 # SOAP::Lite should be fastest and most likely to stay working long-term,
35 # but is the hardest to get installed
36 $networking = 'LWP'
37   unless defined $networking;
38
39 # Whether to try to use caching; default is yes, and caching is very
40 # strongly recommended
41 $use_caching = 1
42   unless defined $use_caching;
43
44 # how long to go between re-fetching the data, in seconds
45 # default value is 1 week
46 $max_cache_data_age = 60 * 60 * 24 * 7
47   unless defined $max_cache_data_age;
48
49 # how long to go between re-formatting the lists, in seconds
50 # default is 5 minutes
51 $max_cache_layout_age = 60 * 5
52   unless defined $max_cache_layout_age;
53
54 $debug_level = 1
55   unless defined $debug_level;
56 # -----------------------------------------------------
57 \f
58 $purchased = '';
59 $reading   = '';
60 $rereading = '';
61 $favorite  = '';
62 $completed = '';
63 $nofinish  = '';
64 \f
65 use CGI qw/param/;
66 use strict;
67 use vars qw/$username $associate_id $max_cache_data_age $max_cache_layout_age
68   %num $networking $use_caching $debug_level
69   $purchased $reading $rereading $favorite $completed $nofinish/;
70 \f
71 my $cache;
72 my $package = "allconsuming";
73 my $cachefile = "$blosxom::plugin_state_dir/.$package.cache";
74 my $save_cache = 0;
75 \f
76 # General utility functions
77
78 sub debug {
79     my ($level, @msg) = @_;
80
81     if ($debug_level >= $level) {
82         print STDERR "$package debug $level: @msg\n";
83     }
84 }
85
86 sub load_template {
87     my ($bit) = @_;
88     return $blosxom::template->('', "$package.$bit", $blosxom::flavour);
89 }
90
91 sub report {
92     my ($bit, $listname, $title, $author, $asin, $image, $allconsuming_url, $amazon_url) = @_;
93     my $f   = load_template("$listname.$bit") || load_template($bit);
94     $title  = encode_entities($title);
95     $author = encode_entities($author);
96     $f =~ s/((\$[\w:]+)|(\$\{[\w:]+\}))/$1 . "||''"/gee;
97     return $f;
98 }
99
100 sub encode_entities {
101     my ($text) = @_;
102     eval "require HTML::Entities";
103     if ($@) {
104         my %map = ('<' => 'lt', '&' => 'amp', '>' => 'gt');
105         my $keys = join '',keys %map;
106         $text =~ s:([$keys]):&$map{$1};:g;
107         return $text;
108     }
109     return HTML::Entities::encode_entities($text);
110 }
111 \f
112 # General networking
113
114 sub GET {
115     my ($url) = @_;
116
117     if ($networking =~ m:curl:) {
118         return `$networking -m 30 -s "$url"`;
119     } elsif ($networking =~ m:wget:) {
120         return `$networking --quiet -O - "$url"`;
121     } elsif ($networking eq 'LWP') {
122         foreach (qw/LWP::UserAgent HTTP::Request::Common/) {
123             eval "require $_";
124             if ($@) {
125                 debug(0, "Can't load $_, can't use LWP networking: $@");
126                 return undef;
127             }
128         }
129         my $ua  = LWP::UserAgent->new;
130         my $res = $ua->request(HTTP::Request::Common::GET $url);
131         if (!$res->is_success) {
132             my $error = $res->status_line;
133             debug(0, "HTTP GET error: $error");
134             return undef;
135         }
136         return $res->content;
137     } else {
138         debug(0, "ERROR: invalid \$networking $networking");
139     }
140 }
141 \f
142 # AllConsuming-specific networking
143
144 sub allconsuming_handle {
145     if ($networking eq 'SOAP::Lite') {
146         eval "require SOAP::Lite;";
147         if ($@) {
148             debug(0, "SOAP::Lite couldn't be loaded");
149             return undef;
150         }
151         my @now = localtime;
152         my $soap = SOAP::Lite
153           -> uri('http://www.allconsuming.net/AllConsumingAPI')
154             -> proxy('http://www.allconsuming.net/soap.cgi');
155         my $obj = $soap
156               -> call(new => $now[2], $now[3], $now[4] + 1, $now[5] + 1900)
157                 -> result;
158         return {soap => $soap,
159                 obj  => $obj,
160                 map  => {purchased => 'GetPurchasedBooksList',
161                          reading   => 'GetCurrentlyReadingList',
162                          rereading => 'GetRereadingBooksList',
163                          favorite  => 'GetFavoriteBooksList',
164                          completed => 'GetCompletedBooksList',
165                          nofinish  => 'GetNeverFinishedBooksList'}
166                };
167     } else {
168         return {
169                 map => {purchased => 'purchased_books',
170                         reading   => 'currently_reading',
171                         rereading => 'rereading_books',
172                         favorite  => 'favorite_books',
173                         completed => 'completed_books',
174                         nofinish  => 'never_finished_books'}
175                };
176     }
177 }
178
179 sub allconsuming_lookup {
180     my ($handle, $username, $list) = @_;
181
182     return undef unless defined $handle;
183
184     if ($networking eq 'SOAP::Lite') {
185         return undef unless defined $handle->{map}{$list};
186         return $handle->{soap}
187           -> call($handle->{map}{$list} => $handle->{obj}, $username)
188             -> result;
189     } else {
190         my $data = GET('http://allconsuming.net/soap-client.cgi?' .
191                        "$handle->{map}{$list}=1&username=$username");
192         $data =~ s:\A\<pre>\$VAR1 =(.*)</pre>\Z:\1:ms;
193         return eval $data;
194     }
195 }
196
197 sub get_data {
198     if (defined $cache->{data} and
199         $^T - $cache->{data_timestamp} < $max_cache_data_age) {
200         return;
201     }
202     debug(1, "cache miss data");
203     $cache->{data_timestamp} = $^T;
204     my $obj = allconsuming_handle();
205
206     foreach (keys %num) {
207         next if defined($num{$_}) && $num{$_} == 0;
208         $cache->{data}{$_} = allconsuming_lookup($obj, $username, $_);
209     }
210     $save_cache = 1;
211 }
212 \f
213 # Cache handling
214
215 sub prime_cache {
216     return if (!$use_caching);
217     eval "require Storable";
218     if ($@) {
219         debug(1, "cache disabled, Storable not available");
220         $use_caching = 0;
221         return 0;
222     }
223     if (!Storable->can('lock_retrieve')) {
224         debug(1, "cache disabled, Storable::lock_retrieve not available");
225         $use_caching = 0;
226         return 0;
227     }
228     $cache = (-r $cachefile ? Storable::lock_retrieve($cachefile) : {});
229     if (defined(param('allconsuming'))) {
230         if (param('allconsuming') eq 'refresh_data') {
231             $cache = {};
232         } elsif (param('allconsuming') eq 'refresh_layout') {
233             $cache->{layout} = {};
234         }
235     }
236 }
237
238 sub save_cache {
239     return if (!$use_caching || !$save_cache);
240     debug(1, "Saving cache");
241     -d $blosxom::plugin_state_dir
242         or mkdir $blosxom::plugin_state_dir 
243         or (debug(0, "State dir $blosxom::plugin_state_dir nonexistant and noncreatable: $!") and return);
244     Storable::lock_store($cache, $cachefile);
245 }
246 \f
247 sub build_list {
248     my ($listname, $num, $list) = @_;
249     my $count = 0;
250     my $results;
251
252     return '' if (defined $num and $num == 0);
253     $list = [$list] if (ref $list eq 'HASH');
254     if (defined $list and defined $num and $num < 0) {
255         # algorithm from Algorithm::Numerical::Shuffle by Abigail
256         for (my $i = @$list; -- $i;) {
257             my $r = int rand ($i + 1);
258             ($list -> [$i], $list -> [$r]) = ($list -> [$r], $list -> [$i]);
259         }
260         $num = -$num;
261     }
262     $results = report('head', $listname);
263     foreach (@$list) {
264         $results .= report('item', $listname,
265                            @{$_}{qw/title author asin image allconsuming_url
266                                    amazon_url/});
267         $count++;
268         last if (defined $num and $count == $num);
269     }
270     $results .= report('foot', $listname);
271
272     return $results;
273 }
274 \f
275 # Blosxom plugin interface
276
277 sub head {
278     prime_cache();
279     get_data();
280     save_cache();
281
282     foreach (keys %num) {
283         next if defined($num{$_}) && $num{$_} == 0;
284         no strict;
285         $$_ = $cache->{layout}{$_}{$blosxom::flavour};
286         next if (defined $$_ &&
287                  ($^T - $cache->{layout_timestamp}{$_}{$blosxom::flavour}
288                   < $max_cache_layout_age));
289         debug(1, "cache miss layout $_ $blosxom::flavour");
290         $$_ = build_list($_, $num{$_}, $cache->{data}{$_}{asins});
291         $cache->{layout}{$_}{$blosxom::flavour} = $$_;
292         $cache->{layout_timestamp}{$_}{$blosxom::flavour} = $^T;
293         $save_cache = 1;
294         use strict;
295     }
296     save_cache();
297     
298     1;
299 }
300
301 sub start {
302     return 0 unless defined $username;
303     while (<DATA>) {
304         last if /^(__END__)?$/;
305         chomp;
306         my ($flavour, $comp, $txt) = split ' ',$_,3;
307         $txt =~ s:\\n:\n:g;
308         $blosxom::template{$flavour}{"$package.$comp"} = $txt;
309     }
310     return 1;
311 }
312
313 1;
314 __DATA__
315 error head <table class="allconsuming $listname">\n
316 error item <tr><td><a href="http://www.amazon.com/exec/obidos/ASIN/$asin/$associate_id/ref=nosim"><img border="0" src="$image" alt="$title Book cover"></a></td><td><a href="http://www.amazon.com/exec/obidos/ASIN/$asin/$associate_id/ref=nosim"><i>$title</i></a>, $author</td></tr>\n
317 error foot </table>
318 __END__
319
320 =head1 NAME
321
322 Blosxom Plug-in: allconsuming
323
324 =head1 SYNOPSIS
325
326 Purpose: Lets you easily share your AllConsuming information
327
328   * $allconsuming::purchased -- list of books you've purchased
329   * $allconsuming::reading -- list of books you're reading
330   * $allconsuming::rereading -- list of books you're re-reading
331   * $allconsuming::favorite -- list of your favorite books
332   * $allconsuming::completed -- list of books you've completed
333   * $allconsuming::nofinish -- list of books you never finished
334
335 =head1 VERSION
336
337 0+3i
338
339 2nd test release
340
341 =head1 AUTHOR
342
343 Todd Larason  <jtl@molehill.org>, http://molelog.molehill.org/
344
345 This plugin is now maintained by the Blosxom Sourceforge Team,
346 <blosxom-devel@lists.sourceforge.net>.
347
348 =head1 BUGS
349
350 None known; please send bug reports and feedback to the Blosxom
351 development mailing list <blosxom-devel@lists.sourceforge.net>.
352
353 =head1 Customization
354
355 =head2 Configuration variables
356
357 C<$username> is your AllConsuming username.  Until it's defined, this plugin does nothing. 
358
359 C<$associate_id> is an Amazon Associate ID.  By default, it's mine;
360  change it to yours if you have one.
361
362 C<%num> sets how many items to include in each list.  Each of C<purchased>,
363 C<reading>, C<rereading>, C<favorite>, C<completed> and C<nofinish> can be
364 set separately.  Setting C<$num{foo}> to undef means to include the whole
365 list; setting it to 0 means to not build the list at all (or retrieve the
366 data from AllConsuming); setting it to a positive number N means to list the
367 first N items (or the whole list, if there aren't that many items) in order;
368 setting it to a negative number -N means to list a randomly selected set of
369 N items (or the whole list, in a random order, if there are fewer than N
370 items).
371
372 C<$networking> controls which networking implemenentation to use.  If set to
373 'SOAP::Lite', then the SOAP::Lite module will be used to communicate with
374 AllConsuming's official SOAP interface; this method is preferable for both
375 speed and reliability, but requires by far the most work to get working if
376 you don't already have the modules installed.  If set to 'LWP', then the
377 LWP family of modules will be used to communicate with a demonstration CGI
378 script.  If set to 'wget' or 'curl' (or a pathname that includes one of
379 those), then the respective external utility is used to communicate with
380 the demonstration CGI script.
381
382 C<$use_caching> is a boolean controlling whether to use caching at all.
383 Caching is very strongly recommended -- AllConsuming is rather slow.
384
385 C<$max_cache_data_age> sets how long to cache the downloaded AllConsuming
386 information for.  Fetching the data is pretty slow, so this defaults to a high
387 value -- 1 week.
388
389 C<$max_cache_layout_age> sets how long to cache the formatted data.
390 Formatting the data is relatively fast, so this defaults to a small value -- 5
391 minutes.  If you aren't modifying templates and aren't using randomized lists,
392 this can be set to the same as $max_cache_data_age without ill effects.
393
394 C<$debug_level> can be set to a value between 0 and 5; 0 will output
395 no debug information, while 5 will be very verbose.  The default is 1,
396 and should be changed after you've verified the plugin is working
397 correctly.
398
399 =head2 Classes for CSS control
400
401 There's are some classes used, available for CSS customization.
402
403   * C<allconsuming> -- all lists are in the netflix class
404   * C<purchased>, etc -- each list is also in a class named for the list
405
406 =head2 Flavour-style files
407
408 If you want a format change that can't be made by CSS, you can
409 override the HTML generated by creating files similar to Blosxom's
410 flavour files.  They should be named allconsuming.I<bit>.I<flavour>; for
411 available I<bit>s and their default meanings, see the C<__DATA__>
412 section in the plugin.
413
414 =head1 Caching
415
416 Because fetching the queue information is relatively slow, caching is very
417 strongly recommended.  Caching requires a version of the Storable module
418 that supports the 'lock_save' and 'lock_retrieve' functions.
419
420 Since the data reload is so slow, you may wish to raise the $max_cache_data_age
421 even higher, and use explicit cache reloading.  The cache can be reloaded
422 either by deleting the cache file $plugin_state_dir/.allconsuming.cache, or
423 by passing an C<allconsuming=refresh_data> parameter to the blosxom script;
424 the latter is preferable, as you can insure that you take the time hit, not
425 a random visitor.
426
427 =head1 LICENSE
428
429 this Blosxom Plug-in
430 Copyright 2003, Todd Larason
431
432 (This license is the same as Blosxom's)
433
434 Permission is hereby granted, free of charge, to any person obtaining a
435 copy of this software and associated documentation files (the "Software"),
436 to deal in the Software without restriction, including without limitation
437 the rights to use, copy, modify, merge, publish, distribute, sublicense,
438 and/or sell copies of the Software, and to permit persons to whom the
439 Software is furnished to do so, subject to the following conditions:
440
441 The above copyright notice and this permission notice shall be included
442 in all copies or substantial portions of the Software.
443
444 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
445 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
446 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
447 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
448 OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
449 ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
450 OTHER DEALINGS IN THE SOFTWARE.
451
452 =cut