gavinc/entries_timestamp

   1 # Blosxom Plugin: entries_timestamp
   2 # Author(s): Gavin Carr <gavin@openfusion.com.au>
   3 # Version: 0.002000
   4 # Documentation: See the bottom of this file or type: perldoc entries_timestamp
   5
   6 package entries_timestamp;
   7
   8 use strict;
   9 use File::stat;
  10 use File::Find;
  11 use Data::Dumper;
  12 use Time::Local;
  13 use CGI ();
  14
  15 # Uncomment next line to enable debug output (don't uncomment debug() lines)
  16 #use Blosxom::Debug debug_level => 2;
  17
  18 # --- Configurable variables -----
  19
  20 my %config = ();
  21
  22 # Where should I store the entries_timestamp index file?
  23 # IMO timestamps are metadata rather than state, but you may well not care.
  24 $config{meta_dir} = "$blosxom::datadir/../meta";
  25 #$config{meta_dir} = $blosxom::plugin_state_dir;
  26
  27 # What name should my entries_timestamp index file be called?
  28 # If you want to migrate from entries_index, you can just use the original
  29 # entries_index .entries_index.index file, or or just copy/rename it.
  30 $config{entries_index} = 'entries_timestamp.index';
  31 #$config{entries_index} = '.entries_index.index';
  32
  33 # Reindexing password. If entries_timestamp finds a '?reindex=$reindex_password'
  34 # parameter it will check and resync machine timestamps to the human versions
  35 $config{reindex_password} = 'abracad';    # CHANGEME!
  36
  37 # --------------------------------
  38 # __END_CONFIG__
  39
  40 my $q = CGI->new;
  41
  42 use vars qw($TS_MACHINE $TS_HUMAN $SYMLINKS $VAR1 $VAR2 $VAR3);
  43
  44 sub start { 1 }
  45
  46 sub entries {
  47   return sub {
  48     my(%indexes, %files_ts, %files_ts_str, %files_symlinks);
  49
  50     # Read $config{entries_index}
  51     if ( open ENTRIES, "$config{meta_dir}/$config{entries_index}" ) {
  52       my $index = join '', <ENTRIES>;
  53       close ENTRIES;
  54       if ( $index =~ m/\$(TS_\w+|VAR1) = \{/ ) {
  55         eval $index;
  56         if ( $@ ) {
  57           warn "(entries_timestamp) eval of $config{entries_index} failed: $@";
  58           return;
  59         }
  60         else {
  61           if ($TS_MACHINE && keys %$TS_MACHINE) {
  62             %files_ts = %$TS_MACHINE;
  63           } elsif ($VAR1 && keys %$VAR1) {
  64             %files_ts = %$VAR1;
  65           }
  66           if ($TS_HUMAN && keys %$TS_HUMAN) {
  67             %files_ts_str = %$TS_HUMAN;
  68           } elsif ($VAR2 && keys %$VAR2) {
  69             %files_ts_str = %$VAR2;
  70           }
  71           if ($SYMLINKS && keys %$SYMLINKS) {
  72             %files_symlinks = %$SYMLINKS;
  73           } elsif ($VAR3 && keys %$VAR3) {
  74             %files_symlinks = %$VAR3;
  75           }
  76         }
  77       }
  78     }
  79     %files_ts_str = () unless defined %files_ts_str;
  80     %files_symlinks = () unless defined %files_symlinks;
  81
  82     my $index_mods = 0;
  83
  84     # Check for deleted files
  85     for my $file (keys %files_ts) {
  86       if ( ! -f $file || ( -l $file && ! -f readlink($file)) ) {
  87         $index_mods++;
  88         delete $files_ts{$file};
  89         delete $files_ts_str{$file};
  90         delete $files_symlinks{$file};
  91         # debug(2, "deleting removed file '$file' from indexes");
  92       }
  93     }
  94
  95     # Check for new files
  96     find(
  97       sub {
  98         my $d;
  99         my $curr_depth = $File::Find::dir =~ tr[/][];
 100         if ( $blosxom::depth and $curr_depth > $blosxom::depth ) {
 101           delete $files_ts{$File::Find::name};
 102           delete $files_ts_str{$File::Find::name};
 103           delete $files_symlinks{$File::Find::name};
 104           return;
 105         }
 106
 107         # Return unless a match
 108         return unless $File::Find::name =~
 109           m! ^$blosxom::datadir/(?:(.*)/)?(.+)\.$blosxom::file_extension$ !x;
 110         my $path = $1;
 111         my $filename = $2;
 112         # Return if an index, a dotfile, or unreadable
 113         if ( $filename eq 'index' or $filename =~ /^\./ or ! -r $File::Find::name ) {
 114           # debug(1, "(entries_timetamp) '$path/$filename.$blosxom::file_extension' is an index, a dotfile, or is unreadable - skipping\n");
 115           return;
 116         }
 117
 118         # Get modification time
 119         my $mtime = stat($File::Find::name)->mtime or return;
 120
 121         # Ignore if future unless $show_future_entries is set
 122         return unless $blosxom::show_future_entries or $mtime <= time;
 123
 124         my @nice_date = blosxom::nice_date( $mtime );
 125
 126         # If a new symlink, add to %files_symlinks
 127         if ( -l $File::Find::name ) {
 128           if ( ! exists $files_symlinks{ $File::Find::name } ) {
 129             $files_symlinks{$File::Find::name} = 1;
 130             $index_mods++;
 131             # Backwards compatibility deletes
 132             delete $files_ts{$File::Find::name};
 133             delete $files_ts_str{$File::Find::name};
 134             # debug(2, "new file_symlinks entry $File::Find::name, index_mods now $index_mods");
 135           }
 136         }
 137
 138         # If a new file, add to %files_ts and %files_ts_str
 139         else {
 140           if ( ! exists $files_ts{$File::Find::name} ) {
 141             $files_ts{$File::Find::name} = $mtime;
 142             $index_mods++;
 143             # debug(2, "new file entry $File::Find::name, index_mods now $index_mods");
 144           }
 145           if ( ! exists $files_ts_str{$File::Find::name} ) {
 146             my $date = join('-', @nice_date[5,2,3]);
 147             my $time = sprintf '%s:%02d', $nice_date[4], (localtime($mtime))[0];
 148             $files_ts_str{$File::Find::name} = join(' ', $date, $time, $nice_date[6]);
 149             $index_mods++;
 150             # debug(2, "new file_ts_str entry $File::Find::name, index_mods now $index_mods");
 151           }
 152
 153           # If asked to reindex, check and sync machine timestamps to the human ones
 154           if ( my $reindex = $q->param('reindex') ) {
 155             if ( $reindex eq $config{reindex_password} ) {
 156               if ( my $reindex_ts = parse_ts( $files_ts_str{$File::Find::name} )) {
 157                 if ($reindex_ts != $files_ts{$File::Find::name}) {
 158                   # debug(1, "reindex: updating timestamp on '$File::Find::name'\n");
 159                   # debug(2, "reindex_ts $reindex_ts, files_ts $files_ts{$File::Find::name}");
 160                   $files_ts{$File::Find::name} = $reindex_ts;
 161                   $index_mods++;
 162                 }
 163               }
 164               else {
 165                 warn "(entries_timestamp) Warning: bad timestamp '$files_ts_str{$File::Find::name}' on file '$File::Find::name' - failed to parse (not %Y-%m-%d %T %z?)\n";
 166               }
 167             }
 168             else {
 169               warn "(entries_timestamp) Warning: reindex requested with incorrect password\n";
 170             }
 171           }
 172         }
 173
 174         # Static rendering
 175         if ($blosxom::static_entries) {
 176           my $static_file = "$blosxom::static_dir/$path/index.$blosxom::static_flavours[0]";
 177           if ( $q->param('-all')
 178                or ! -f $static_file
 179                or stat($static_file)->mtime < $mtime ) {
 180             # debug(3, "static_file: $static_file");
 181             $indexes{$path} = 1;
 182             $d = join('/', @nice_date[5,2,3]);
 183             $indexes{$d} = $d;
 184             $path = $path ? "$path/" : '';
 185             $indexes{ "$path$filename.$blosxom::file_extension" } = 1;
 186           }
 187         }
 188       }, $blosxom::datadir
 189     );
 190
 191     # If updates, save back to index
 192     if ( $index_mods ) {
 193       # debug(1, "index_mods $index_mods, saving \%files to $config{meta_dir}/$config{entries_index}");
 194       if ( open ENTRIES, "> $config{meta_dir}/$config{entries_index}" ) {
 195         print ENTRIES Data::Dumper->Dump([ \%files_ts_str, \%files_ts, \%files_symlinks ],
 196           [ qw(TS_HUMAN TS_MACHINE SYMLINKS) ] );
 197         close ENTRIES;
 198       }
 199       else {
 200         warn "(entries_timestamp) couldn't open $config{meta_dir}/$config{entries_index} for writing: $!\n";
 201       }
 202     }
 203
 204     # Generate blosxom %files from %files_ts and %files_symlinks
 205     my %files = %files_ts;
 206     for (keys %files_symlinks) {
 207       # Add to %files with mtime of referenced file
 208       my $target = readlink $_;
 209       # Note that we only support symlinks pointing to other posts
 210       $files{ $_ } = $files{ $target } if exists $files{ $target };
 211     }
 212
 213     return (\%files, \%indexes);
 214   };
 215 }
 216
 217 # Helper function to parse human-friendly %Y-%m-%d %T %z timestamps
 218 sub parse_ts {
 219   my ($ts_str) = @_;
 220
 221   if ($ts_str =~ m/^(\d{4})-(\d{2})-(\d{2})           # %Y-%m-%d
 222                     \s+ (\d{2}):(\d{2})(?::(\d{2}))?  # %H-%M-%S
 223                     (?:\s+ [+-]?(\d{2})(\d{2})?)?     # %z
 224                   /x) {
 225     my ($yy, $mm, $dd, $hh, $mi, $ss, $zh, $zm) = ($1, $2, $3, $4, $5, $6, $7, $8);
 226     $mm--;
 227     # FIXME: just use localtime for now
 228     if (my $mtime = timelocal($ss, $mi, $hh, $dd, $mm, $yy)) {
 229       return $mtime;
 230     }
 231   }
 232
 233   return 0;
 234 }
 235
 236 1;
 237
 238 __END__
 239
 240 =head1 NAME
 241
 242 entries_timestamp: blosxom plugin to capture and preserve the original
 243 creation timestamp on blosxom posts
 244
 245 =head1 SYNOPSIS
 246
 247 entries_timestamp is a blosxom plugin for capturing and preserving the
 248 original creation timestamp on blosxom posts. It is based on Rael
 249 Dornfest's original L<entries_index> plugin, and works in the same way:
 250 it maintains an index file (configurable, but 'entries_timestamp.index',
 251 by default) maintaining creation timestamps for all blosxom posts, and
 252 replaces the default $blosxom::entries subrouting with one returning a
 253 file hash using that index.
 254
 255 It differs from Rael's L<entries_index> as follows:
 256
 257 =over 4
 258
 259 =item User-friendly timestamps
 260
 261 The index file contains two timestamps for every file - the
 262 machine-friendly system L<time/2> version, for use by blosxom, and a
 263 human-friendly stringified timestamp, to allow timestamps to be reviewed
 264 and or modified easily.
 265
 266 entries_timestamp ordinarily just assumes those timestamps are in sync,
 267 and ignores the string version. If you update the string version and want
 268 that to override the system time, you should pass a
 269 ?reindex=<reindex_password> argument to blosxom to force the system
 270 timestamps to be checked and updated.
 271
 272 =item Separate symlink handling
 273
 274 entries_timestamp uses separate indexes for posts that are files and
 275 posts that are symlinks, and doesn't bother to cache timestamps for
 276 the latter at all, deriving them instead from the post they point to.
 277 (Note that this means entries_timestamp currently doesn't support
 278 symlinks to non-post files at all - they're just ignored).
 279
 280 =item Configurable index file name and location
 281
 282 I consider post timestamps to be metadata rather than state, so I
 283 tend to use a separate C<meta> directory alongside by posts for this,
 284 rather than the traditional $plugin_state_dir. You may note care. ;-)
 285
 286 =item A complete rewrite
 287
 288 Completely rewritten code, since the original used evil evil and-chains
 289 and was pretty difficult to understand (imho).
 290
 291 =back
 292
 293 =head1 SEE ALSO
 294
 295 L<entries_index>, L<entries_cache>, L<entries_cache_meta>
 296
 297 Blosxom Home/Docs/Licensing: http://blosxom.sourceforge.net/
 298
 299 =head1 ACKNOWLEDGEMENTS
 300
 301 This plugin is largely based on Rael Dornfest's original
 302 L<entries_index> plugin.
 303
 304 =head1 BUGS AND LIMITATIONS
 305
 306 entries_timestamp currently only supports symlinks to local post files,
 307 not symlinks to arbitrary files outside your $datadir.
 308
 309 entries_timestamp doesn't currently do any kind caching, so it's not
 310 directly equivalent to L<entries_cache> or L<entries_cache_meta>.
 311
 312 Please report bugs either directly to the author or to the blosxom
 313 development mailing list: <blosxom-devel@lists.sourceforge.net>.
 314
 315 =head1 AUTHOR
 316
 317 Gavin Carr <gavin@openfusion.com.au>, http://www.openfusion.net/
 318
 319 =head1 LICENSE
 320
 321 Copyright 2007, Gavin Carr.
 322
 323 This plugin is licensed under the same terms as blosxom itself i.e.
 324
 325 Permission is hereby granted, free of charge, to any person obtaining a
 326 copy of this software and associated documentation files (the "Software"),
 327 to deal in the Software without restriction, including without limitation
 328 the rights to use, copy, modify, merge, publish, distribute, sublicense,
 329 and/or sell copies of the Software, and to permit persons to whom the
 330 Software is furnished to do so, subject to the following conditions:
 331
 332 The above copyright notice and this permission notice shall be included
 333 in all copies or substantial portions of the Software.
 334
 335 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 336 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 337 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
 338 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
 339 OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
 340 ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 341 OTHER DEALINGS IN THE SOFTWARE.
 342
 343 =cut
 344
 345 # vim:ft=perl