Add entries_cache_meta to general.
[matthijs/upstream/blosxom-plugins.git] / general / entries_cache_meta
1 # vim: ft=perl
2 # Blosxom Plugin: entries_cache_meta
3 # Author(s): Jason Thaxter <sseye@ahab.com>
4 # Version: 0.6
5
6 package entries_cache_meta;
7
8 # --- Configurable variables -----
9
10 #
11 # Caching variables
12 #
13
14 # How many minutes delay before entries are re-indexed?
15 # (In minutes)
16 # default: 15
17 # zero means never auto-reindex
18 $cache_period;
19
20 # reindex password via query string to force re-indexing
21 # default: none (re-index by time only)
22 $reindex_passwd;
23
24 # if true, this will warn when the cachefile can't be locked
25 # default: off
26 $write_lock_warn;
27
28 #
29 # Meta-related variables
30 #
31
32 # What prefix should I expect prepended to each meta tag?
33 # default: meta-
34 $meta_prefix;
35
36 # If set, this meta variable will enable you to set modification times
37 # e.g.:
38 #   meta-last_modified: 2003/01/12 10:33:33
39 # see pod docs re: time format
40 # default: mtime
41 $meta_mtime;
42
43 # enabled
44 # default: 1
45 # set to zero to disable this plugin
46 # good for use w/ config plugin
47 $enabled;
48
49 # --------------------------------
50
51 # defaults
52 $cache_period = 15 if not defined $cache_period;
53 $meta_prefix ||= 'meta-';
54 $meta_mtime = 'mtime' unless defined $meta_mtime;
55 $enabled    = 1       unless defined $enabled;
56
57 # standard perl modules
58 use Fcntl qw(:DEFAULT :flock);
59 use File::stat;
60 use File::Find;
61 use Data::Dumper;
62
63 # standard for blosxom
64 use CGI qw/:standard/;
65
66 # we'll use Date::Parse if we have it
67 $have_date_parse;
68 eval { require Date::Parse; };
69 if ($@) {
70     use Time::Local;
71 }
72 else {
73     $have_date_parse = 1;
74 }
75
76 %cache;    # the cache
77 %indexes = ();    # nothing - we don't do static
78 $reindex;         # reindex or not
79 *CACHE;           # for the cache file
80 $reindexed;       # flag for "save cache"
81
82 # the filename where the cache is stored
83 $cachefile = "$blosxom::plugin_state_dir/entries_cache_meta";
84 # and a temporary one while generating the cache
85 $cache_tmp = "$cachefile.TMP";
86
87 sub start {
88
89     return 0 if ( not $enabled or param('-all') );
90
91     # Read cache and reindex if failed or otherwise directed
92     (
93         (
94             not( $reindex_passwd and param('reindex') eq $reindex_passwd )
95               and not( $cache_period
96                 and -f "$cachefile"
97                 and stat($cachefile)->mtime lt( time() - $cache_period * 60 ) )
98         )
99           and ( open( MYCACHE, $cachefile )
100             and $index = join '', <MYCACHE>
101             and $index =~ /\$VAR1 = /
102             and eval($index)
103             and !$@
104             and %cache = %$VAR1
105             and close MYCACHE )
106
107       )
108       or $reindex = &lokkit( \*CACHE );
109
110     return 1;
111 }
112
113 sub entries {
114
115     # If we haven't flagged a need to re-index,
116     # copy from the cache
117     return sub {
118         my %files;
119         foreach ( keys %cache ) {
120
121             # copy into cache if the file exists
122             $files{$_} = $cache{$_}{mtime} if -f $_;
123         }
124         return ( \%files, \%indexes );
125       }
126       unless $reindex;
127
128     # otherwise, do a full reindex
129     return sub {
130
131         # Check to see if previously indexed files exist, and then rescan
132         # the datadir for any new files, while preserving the old times
133
134         for my $file ( keys %cache ) {
135             -f $file or do { $reindexed++; delete $cache{$file} };
136         }
137
138         find(
139             sub {
140
141                 # easier to read.
142                 $ffname = $File::Find::name;
143
144                 # return if we're out of our depth
145                 my $curr_depth = $File::Find::dir =~ tr[/][];
146                 if ( $blosxom::depth and $curr_depth > $blosxom::depth ) {
147                     $cache{$ffname}
148                       and delete $cache{$ffname};
149                     return;
150                 }
151
152                 # only bother for real entries
153                 return
154                   unless ( $ffname =~
155 m!^$blosxom::datadir/(?:(.*)/)?(.+)\.$blosxom::file_extension$!
156                     and $2 ne 'index'
157                     and $2 !~ /^\./
158                     and ( -r "$ffname" )
159                     and ++$reindexed );
160
161                 # process meta tags
162                 if ( -T "$ffname" and open( FF, "<$ffname" ) ) {
163                     $meta_title = <FF>;
164                     chomp($meta_title);
165                     $cache{$ffname}{title} = $meta_title;
166                     while (<FF>) {
167
168                         # get values
169                         my ( $key, $value ) = m/^$meta_prefix(\w+)\s*:\s*(.+)$/;
170                         last if not $key;
171
172                         # set values
173                         if ( $key ne "$meta_mtime" ) {
174                             $cache{$ffname}{$key} = $value;
175                         }
176
177                         # set modification time
178                         # with a double negative (hey)
179                         else {
180                             if ($have_date_parse) {
181                                 $time = Date::Parse::str2time($value);
182                             }
183                             elsif (
184                                 my ( $yr, $mo, $day, $hr, $min, $sec, $tz ) = (
185                                     $value =~
186 m! (\d{4}) [/\:\-] (\d{2}) [/\:\-] (\d{2}) \s+
187                                       (\d{2}) : (\d{2}) : (\d{2})
188                                       \s*((UTC|GMT)*)!x
189                                 )
190                               )
191                             {
192                                 if ($tz) {
193                                     $time =
194                                       timegm( $sec, $min, $hr, $day, --$mo,
195                                         $yr );
196                                 }
197                                 else {
198                                     $time =
199                                       timelocal( $sec, $min, $hr, $day, --$mo,
200                                         $yr );
201                                 }
202                             }
203                             else {
204                                 warn "unparseable time in $ffname: $value";
205                             }
206                             $cache{$ffname}{mtime} = $time;
207                         }
208                     }
209                     close FF;
210                 }
211                 else {
212                     warn "couldn't open entry ($ffname): $!";
213                 }
214
215                 # If we have no meta mtime and no cached time,
216                 # stat the file and store it.
217                 if ( $cache{$ffname}{mtime} ) {
218                     $files{$ffname} = $cache{$ffname}{mtime};
219                 }
220                 else {    # make sure blosxom behaves normally
221                     $files{$ffname} = stat($ffname)->mtime;
222                     $cache{$ffname}{mtime} = $files{$ffname};
223                 }
224
225                 # show or not to show future entries
226                 if ( not $blosxom::show_future_entries
227                     and $files{$ffname} > time() )
228                 {
229                     delete $files{$ffname} and return;
230                 }
231
232             },
233             $blosxom::datadir
234         );
235
236         return ( \%files, \%indexes );    # indexes is bogus: we don't do static
237       }
238 }
239
240 # put the stuff into $meta:: namespace for story rendering
241 # and trim meta tags out of our story
242 sub story {
243     my ( $pkg, $path, $filename, $story_ref, $title_ref, $body_ref ) = @_;
244
245     # first, load up our cached meta values
246     foreach my $key ( keys %{ $cache{$filename} } ) {
247         ${"meta::$key"} = $cache{$filename}{$key};
248     }
249
250     # next, remove any meta tags from the body
251     my ( $body, $in_body );
252     foreach ( split /\n/, $$body_ref ) {
253         if ($in_body) {
254             $body .= "$_\n";
255         }
256         elsif (/^$meta_prefix(\w+)\s*:\s*(.+)$/) {
257             ;
258         }
259         else {
260             $in_body = 1;
261             $body .= "$_\n";
262         }
263     }
264
265     $$body_ref = $body;
266
267     return 1;
268 }
269
270 # save cache - as late as possible
271 # this gives other plugins a chance to alter values
272 # or, forbid us from caching them!
273 sub end {
274     &stuffit( \*CACHE, Dumper \%cache ) if ($reindexed);
275     1;
276 }
277
278 #####################################################################
279 # Internal subs
280 #
281
282 # Reserve file for writing
283 sub lokkit {
284     local *FH = shift;
285
286     # open it
287     my $umask = umask 002;    # group-write is useful
288     sysopen( FH, "$cache_tmp", O_RDWR | O_CREAT )
289       or ( warn "can't open file $cache_tmp: $!" and return );
290     umask $umask;             # restore so it doesn't affect other plugins
291
292     # lock file
293     flock( FH, LOCK_EX | LOCK_NB )
294       or (  close FH
295         and ( not $write_lock_warn or warn "can't lock file: $!" )
296         and return );
297
298     return 1;
299 }
300
301 # Write and release file
302 sub stuffit {
303     local *FH       = shift;
304     local $contents = shift;
305
306     my $err;
307     print FH $contents or $err = "can't write cache $cache_tmp: $!";
308     flock( FH, LOCK_UN ) or $err = "can't unlock cache $cache_tmp: $!";
309     close FH or $err = "can't close cache $cache_tmp: $!";
310
311     if ( not $err ) {
312         rename "$cache_tmp", $cachefile
313           or warn "Error installing cache $cache_tmp: $!";
314     }
315     else {
316         warn $err;
317         unlink "$cache_tmp";
318     }
319 }
320
321 1;
322
323 __END__
324
325 =head1 NAME - entries_cache_meta
326
327 Blosxom Plug-in: entries_cache_meta
328
329 =head1 DESCRIPTION
330
331 The entries_cache_meta plugin is Yet Another Caching Plugin, with some
332 additional features, notably meta-tagging.
333
334 By combining the meta-tag functionality with the entries cache, it becomes
335 possible to write or use plugins that access meta-values outside the C<story>
336 hook. For example, you could use this plugin to write another one showing the
337 most recent entry for each author defined in meta tags.
338
339 Additionally, it makes use of file locking to avoid from re-indexing if another
340 request already has re-indexing in progress. Simultaneous re-indexing could
341 corrupt the cache file, or bog down the server with redundant, expensive tasks;
342 the larger and busier the site, the more likely these problems. For added
343 security, you must supply a password if you want to force re-indexing via query
344 string; this prevents any Blosxom-savvy user from forcing a re-index on your
345 site.
346
347 =head1 USAGE
348
349 A properly permissioned $plugin_state_dir is required. Configuration is
350 optional, but there are a few useful configuration variables.
351
352 =over 4
353
354 =item $cache_period
355
356 How often, in minutes, to reindex automatically. If set to zero, re-indexing will never
357 be automatic.
358
359 =item $reindex_passwd
360
361 What query string password forces reindex.  You can force a scan by appending a
362 query string, e.g.  C<?reindex=mypassword> to the end of the url.  This will
363 also cause meta tags to be updated. However, for security's sake, you must
364 set the password in the configuration to use this.
365
366 =item $write_lock_warn
367
368 Send a warning to the error log when it can't get a write-lock on the cache
369 file. This is mostly useful for verifying that write-locking actually does
370 something.
371
372 =item $meta_prefix
373
374 What prefix marks meta variable names. Defaults to C<meta->. An empty string
375 should be permitted, but currently it isn't.
376
377 =item $meta_mtime
378
379 The name of the meta-property for file modification times. If this property is
380 present in a given entry, it will override the modification time of the file as
381 the entry's time. The default value is "mtime".
382
383 The format of the time is obviously important: it can be either
384
385         meta-mtime: YYYY/MM/DD HH:MM:SS [UTC|GMT]
386
387 or, if Date::Parse is present, any format parseable by that module. Either way,
388 unparseable dates are simply ignored as if the property was not present. This
389 feature may be disabled by setting it to an empty string.
390
391 =back
392
393 =head1 VERSION
394
395 Version 0.6
396
397 =head1 AUTHOR
398
399 Jason Thaxter <sseye@ahab.com>
400
401 This plugin is now maintained by the Blosxom Sourceforge Team,
402 <blosxom-devel@lists.sourceforge.net>.
403
404 =head1 SEE ALSO
405
406 Blosxom Home/Docs/Licensing: http://blosxom.sourceforge.net
407
408 Blosxom Plugin Docs: http://blosxom.sourceforge.net/documentation/users/plugins.html
409
410 =head1 BUGS
411
412 It doesn't currently work in static mode, in part because the premise of static
413 mode is to be a performance benefit all on its own. Also because I don't use
414 static mode and I'm lazy.
415
416 Please send bug reports and feedback to the Blosxom development mailing list 
417 <blosxom-devel@lists.sourceforge.net>.
418
419 =head1 LICENSE
420
421 entries_cache_meta plugin
422 Copyright 2004, Jason Thaxter
423
424 Permission is hereby granted, free of charge, to any person obtaining a
425 copy of this software and associated documentation files (the "Software"),
426 to deal in the Software without restriction, including without limitation
427 the rights to use, copy, modify, merge, publish, distribute, sublicense,
428 and/or sell copies of the Software, and to permit persons to whom the
429 Software is furnished to do so, subject to the following conditions:
430
431 The above copyright notice and this permission notice shall be included
432 in all copies or substantial portions of the Software.
433
434 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
435 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
436 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
437 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
438 OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
439 ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
440 OTHER DEALINGS IN THE SOFTWARE.