View of /trunk/webwork2/lib/WeBWorK/EquationCache.pm

    1 ################################################################################
    2 # WeBWorK mod_perl (c) 2000-2002 WeBWorK Project
    3 # $Id$
    4 ################################################################################
    5 
    6 package WeBWorK::PG::EquationCache;
    7 
    8 =head1 NAME
    9 
   10 WeBWorK::PG::EquationCache - create and cache images of TeX equations.
   11 
   12 =head1 SYNPOSIS
   13 
   14  my $cache = WeBWorK::PG::EquationCache->new(cacheDB => "/path/to/equationcache.db");
   15  my $imageName = $cache->lookup('\[3x^2\]');
   16 
   17 =head1 DESCRIPTION
   18 
   19 WeBWorK::PG::EquationCache maintains a list of unique identifiers for TeX
   20 strings. The unique identifier is based on an MD5 hash of the TeX string, and a
   21 sequence number. Before calcuating the MD5 hash of a TeX string, all whitespace
   22 is removed.
   23 
   24 =head2 FILE FORMAT
   25 
   26 The cache database file is a text file consisting of lines of the following
   27 form:
   28 
   29  md5_hash     sequence_number     tex_string
   30 
   31 Any amount of whitespace may separate the fields. Lines which do not conform to
   32 this format are ignored. Any string of characters beginning with `#' and
   33 extending to the end of the line is also ignored.
   34 
   35 =cut
   36 
   37 use strict;
   38 use warnings;
   39 use Digest::MD5  qw(md5_hex);
   40 use Fcntl qw(:DEFAULT :flock);
   41 
   42 =head1 METHODS
   43 
   44 =over
   45 
   46 =item new
   47 
   48 Returns a new EquationCache object. C<%options> must contain the following
   49 entries:
   50 
   51  cacheDB => path to image cache database file
   52 
   53 =cut
   54 
   55 sub new {
   56   my ($invocant, %options) = @_;
   57   my $class = ref $invocant || $invocant;
   58   my $self = {
   59     %options,
   60   };
   61 
   62   bless $self, $class;
   63 }
   64 
   65 =item lookup
   66 
   67 Looks up a TeX string in the database. A unique identifier for the cached image
   68 is returned. If necessary, the string is added to the database.
   69 
   70 =cut
   71 
   72 sub lookup {
   73   my ($self, $tex) = @_;
   74   $tex =~ s/\s+//g;
   75   my $md5 = md5_hex($tex);
   76 
   77   my $db = $self->{cacheDB};
   78   sysopen(DB, $db, O_RDWR|O_CREAT)
   79     or die "failed to create/open cacheDB $db: $!";
   80   flock(DB, LOCK_EX)
   81     or die "failed to write-lock cacheDB $db: $!";
   82 
   83   my $line = 0;
   84   my $max = 0;
   85   my $match = 0;
   86   local $/ = "\n";
   87   while (<DB>) {
   88     # find matching MD5 hashes
   89     next unless m/^$md5\s+(\d+)\s+(.*)$/;
   90     if ($tex = $2) {
   91       # the TeX string matches: use this instance number and stop looking
   92       $match = $1;
   93       last;
   94     } else {
   95       # the TeX string doesn't match: record instance number and keep looking
   96       $max = $1 if $1 > $max;
   97     }
   98   }
   99 
  100   unless ($match) {
  101     # no match: invent a new instance number and add TeX string to DB
  102     $match = $max + 1;
  103     seek(DB, 0, 2); # we should already be at EOF, but what the hell.
  104     print DB "$md5\t$match\t$tex\n";
  105   }
  106 
  107   close(DB);
  108   return "$md5$match";
  109 }
  110 
  111 1;