LaTeX::Driver - Latex driver

    use LaTeX::Driver;

    $drv = LaTeX::Driver->new( source  => \$doc_text,
                               output  => $filename,
                               format  => 'pdf',
                               %other_params );
    $ok    = $drv->run;
    $stats = $drv->stats;
    $drv->cleanup($what);

   cmd /c "cd $dir && $program $args"

#========================================================================
#
# LaTeX::Driver
#
# DESCRIPTION
#   Driver module that encapsulates the details of formatting a LaTeX document
#
# AUTHOR
#   Andrew Ford <a.ford@ford-mason.co.uk>  (current maintainer)
#
# COPYRIGHT
#   Copyright (C) 2009 Ford & Mason Ltd.   All Rights Reserved.
#   Copyright (C) 2006-2007 Andrew Ford.   All Rights Reserved.
#   Portions Copyright (C) 1996-2006 Andy Wardley.  All Rights Reserved.
#
#   This module is free software; you can redistribute it and/or
#   modify it under the same terms as Perl itself.
#
# HISTORY
#   * Added test for reruns required by longtable environments changing (AF, 2009-01-19)
#
#   * Extracted from the Template::Latex module (AF, 2007-09-10)
#
#   $Id: Driver.pm 76 2009-01-19 13:39:01Z andrew $
#========================================================================

package LaTeX::Driver;

use strict;
use warnings;

use base 'Class::Accessor';
use Cwd;                        # from PathTools
use English;                    # standard Perl class
use Exception::Class ( 'LaTeX::Driver::Exception' );
use File::Copy;                 # standard Perl class
use File::Compare;              # standard Perl class
use File::Path;                 # standard Perl class
use File::Slurp;
use File::Spec;                 # from PathTools
use IO::File;                   # from IO

our $VERSION = 0.08;

__PACKAGE__->mk_accessors( qw( basename basedir basepath options tmpdir
                               source output tmpdir format
                               formatter preprocessors postprocessors _program_path
                               maxruns extraruns stats texinputs_path
                               undefined_citations undefined_references
                               labels_changed rerun_required ) );

our $DEBUG; $DEBUG = 0 unless defined $DEBUG;
our $DEBUGPREFIX;


# LaTeX executable paths set at installation time by the Makefile.PL

eval { require LaTeX::Driver::Paths };

our @PROGRAM_NAMES = qw(latex pdflatex bibtex makeindex dvips dvipdfm ps2pdf pdf2ps);
our %program_path;

map { $program_path{$_} = $LaTeX::Driver::Paths::program_path{$_} || "/usr/bin/$_" } @PROGRAM_NAMES;


our @LOGFILE_EXTS = qw( log blg ilg );
our @TMPFILE_EXTS = qw( aux log lot toc bbl ind idx cit cbk ibk );


our $DEFAULT_TMPDIR  = 'latexdrv';
our $DEFAULT_DOCNAME = 'latexdoc';

# valid output formats and program alias

our $DEFAULT_FORMAT = 'pdf';

our %FORMATTERS  = (
    dvi        => [ 'latex' ],
    ps         => [ 'latex', 'dvips' ],
    postscript => [ 'latex', 'dvips' ],
    pdf        => [ 'pdflatex' ],
    'pdf(dvi)' => [ 'latex', 'dvipdfm' ],
    'pdf(ps)'  => [ 'latex', 'dvips', 'ps2pdf' ],
    'ps(pdf)'  => [ 'pdflatex', 'pdf2ps' ],
);




#------------------------------------------------------------------------
# new(%options)
#
# Constructor for the Latex driver
#------------------------------------------------------------------------

sub new {
    my $class = shift;
    my $options = ref $_[0] ? shift : { @_ };
    my ($volume, $basedir, $basename, $basepath, $orig_ext, $cleanup);
    my ($formatter, @postprocessors, %path);

    $DEBUG       = $options->{DEBUG} || 0;
    $DEBUGPREFIX = $options->{DEBUGPREFIX} if exists $options->{DEBUGPREFIX};

    # Sanity check first - check we're running on a supported OS

    $class->throw("not available on $OSNAME")
        if $OSNAME =~ /^(MacOS|os2|VMS)$/i;


    # Examine the options - we need at least a source to work with and
    # it should be a scalar reference or a valid filename.

    my $source = delete $options->{source};
    $class->throw("no source specified")
        unless $source;

    if (ref $source) {
        $class->throw("source is an invalid reference $source")
            if ref $source ne 'SCALAR';
    }
    else {
        $source =~ s/(\.tex)$//;
        $orig_ext = $1;
        $class->throw("source file ${source}.tex does not exist")
            unless -f $source or -f $source . ".tex";
    }


    # Determine how the document is to be processed.  Either specified
    # explicitly in the format parameter or if an output file is
    # specified it is taken from that, or the default is take.

    my $output = $options->{output};
    my $format = lc($options->{format});

    if ($output and !ref $output) {
        my ($volume, $dir, $file) = File::Spec->splitpath($output);
        $class->throw("output directory $dir does not exist")
            unless $dir and -d $dir;
        if (!$format and $file =~ /\.(\w+)$/) {
            $format = lc($1);
        }
    }


    # There is a formatter and zero or more postprocessors for each
    # format; there are also special formats 'pdf(dvi)', 'pdf(ps)' and
    # 'ps(pdf)' that specify alternate routes to generate the format.

    $format ||= $DEFAULT_FORMAT;
    $class->throw("invalid output format: '$format'")
        unless exists $FORMATTERS{$format};

    ($formatter, @postprocessors) = @{$FORMATTERS{$format}};

    # discard the parenthesized part of special formats

    $format =~ s/\(.*\)//;


    # If a temporary directory was specified or the LaTeX source was
    # given as a scalar reference then a temporary directory is
    # created and the document source written to that directory or
    # copied in if the source is a file.

    my $tmpdir = $options->{tmpdir};
    if ($tmpdir or ref $source) {
        $basedir = $class->_setup_tmpdir($tmpdir);
        $cleanup = 'rmdir' if (!defined($tmpdir) or ($tmpdir eq "1"));
        if (ref $source) {
            $basename = $DEFAULT_DOCNAME; 
            $basepath = File::Spec->catfile($basedir, $basename);
            write_file($basepath . ".tex", $source)
                or $class->throw("cannot create temporary latex file");
        }
        else {
            ($basename = $source) =~ s{.*/}{};
            $basepath = File::Spec->catfile($basedir, $basename);
            copy("$source$orig_ext", $basepath . ".tex")
                or $class->throw("cannot copy $source$orig_ext to temporary directory");
            $output  ||= $source . '.' . $format;
        }
    }

    # Otherwise the source was given as a filename, so the base name
    # and directory are taken from the source name.

    else {
        ($volume, $basedir, $basename) = File::Spec->splitpath($source);
        $basename =~ s/\.tex$//;
        if ($basedir and $volume) {
            $basedir = File::Spec->catfile($volume, $basedir);
        }
        $basedir ||= getcwd;
        $basedir =~ s{(.)/$}{$1};
        $basepath = File::Spec->catfile($basedir, $basename);
    }


    # Set up a mapping of program name to full pathname.
    # This is initialized from the paths detemined at installation
    # time, but any specified in the paths option override these
    # values.

    $options->{paths} ||= {};

    my $path = {};

    map { $path->{$_} = $program_path{$_}; } @PROGRAM_NAMES;
    map { $path->{$_} = $options->{paths}->{$_}; } keys %{ $options->{paths} };


    # Set up the texinputs path

    my $texinputs_path = $options->{TEXINPUTS} || $options->{texinputs} || [];
    $texinputs_path = [ split(/:/, $texinputs_path) ] unless ref $texinputs_path;


    # construct and return the object

    return $class->SUPER::new( { basename       => $basename,
                                 basedir        => $basedir,
                                 basepath       => $basepath,
                                 format         => $format,
                                 output         => $output,
                                 cleanup        => $cleanup || '',
                                 options        => $options,
                                 maxruns        => $options->{maxruns}   || 10,
                                 extraruns      => $options->{extraruns} ||  0,
                                 formatter      => $formatter,
                                 _program_path  => $path,
                                 texinputs_path => join(':', ('.', @$texinputs_path, '')),
                                 preprocessors  => [],
                                 postprocessors => \@postprocessors,
                                 stats          => { runs => {} } } );
    
}


#------------------------------------------------------------------------
# run()
#
# Runs the formatter and other programs to generate the ouptut.
#------------------------------------------------------------------------

sub run {
    my $self = shift;

    $DEBUG = $self->options->{DEBUG} || 0;

    # Check that the file exists

    $self->throw(sprintf("file %s.tex does not exist", $self->basepath))
        unless -f $self->basepath . '.tex';


    # Run any preprocessors (none specified yet).

    map { $self->$_ } @{$self->preprocessors};


    # Run LaTeX and friends until an error occurs, the document
    # stabilizes, or the maximum number of runs is reached.

    my $maxruns   = $self->maxruns;
    my $extraruns = $self->extraruns;
  RUN:
    foreach my $run (1 .. $maxruns) {

        if ($self->need_to_run_latex) {
            $self->run_latex;
        }
        else {
            if ($self->need_to_run_bibtex) {
                $self->run_bibtex;
            }
            elsif ($self->need_to_run_makeindex) {
                $self->run_makeindex;
            }
            else {
                last RUN unless $extraruns-- > 0;
            }
            $run--;
        }
    }


    # Run any postprocessors (e.g.: dvips, ps2pdf, etc).

    foreach my $postproc (@{$self->postprocessors}) {
        my $method = $postproc;
        if ($self->can($method)) {
            $self->$method();
        }
        else {
            $method = 'run_' . $postproc;
            if ($self->can($method)) {
                $self->$method();
            }
            else {
                $self->throw("cannot find postprocessor $postproc");
            }
        }
    }


    # Return any output

    $self->copy_to_output if $self->output;
        ;

    return 1;
}



#------------------------------------------------------------------------
# destructor
#
#------------------------------------------------------------------------

sub DESTROY {
    my $self = shift;

    debug('DESTROY called') if $DEBUG;

    $self->cleanup();
}


#------------------------------------------------------------------------
# run_latex()
#
# Run the latex processor (latex or pdflatex depending on what is configured).
#------------------------------------------------------------------------

sub run_latex {
    my $self = shift;

    my $basename = $self->basename;
    my $exitcode = $self->run_command($self->formatter =>
                                      "\\nonstopmode\\def\\TTLATEX{1}\\input{$basename}");

    # If an error occurred attempt to extract the interesting lines
    # from the log file.  Even without errors the log file may contain
    # interesting warnings indicating that LaTeX or one of its friends
    # must be rerun.

    my $errors = "";
    my $logfile = $self->basepath . ".log";

    if (my $fh = new IO::File $logfile, "r") {
        $self->reset_latex_required;
        my $matched = 0;
        while ( <$fh> ) {
            debug($_) if $DEBUG >= 9;
            # TeX errors start with a "!" at the start of the
            # line, and followed several lines later by a line
            # designator of the form "l.nnn" where nnn is the line
            # number.  We make sure we pick up every /^!/ line,
            # and the first /^l.\d/ line after each /^!/ line.
            if ( /^(!.*)/ ) {
                $errors .= $1 . "\n";
                $matched = 1;
            }
            elsif ( $matched && /^(l\.\d.*)/ ) {
                $errors .= $1 . "\n";
                $matched = 0;
            }
            elsif ( /^Output written on (.*) \((\d+) pages, (\d+) bytes\)./ ) {
                my ($ofile, $pages, $bytes) = ($1, $2, $3);
                $self->{stats}{pages} = $pages;
                $self->{stats}{bytes} = $bytes;
            }
            elsif ( /^LaTeX Warning: Reference .*? on page \d+ undefined/ ) {
                $self->undefined_references(1);
            }
            elsif ( /^LaTeX Warning: Citation .* on page \d+ undefined/ ) {
                debug('undefined citations detected') if $DEBUG;
                $self->undefined_citations(1);
            }
            elsif ( /LaTeX Warning: There were undefined references./i ) {
                debug('undefined reference detected') if $DEBUG;
                $self->undefined_references(1)
                    unless $self->undefined_citations;
            }
            elsif ( /No file $basename\.(toc|lof|lot)/i ) {
                debug("missing $1 file") if $DEBUG;
                $self->undefined_references(1);
            }
            elsif ( /^LaTeX Warning: Label\(s\) may have changed./i ) {
                debug('labels have changed') if $DEBUG;
                $self->labels_changed(1);
            }
            elsif ( /^Package longtable Warning: Table widths have changed\. Rerun LaTeX\./i) {
                debug('table widths changed') if $DEBUG;
                $self->rerun_required(1);
            }

            # A number of packages emit 'rerun' warnings (revtex4,
            # pdfmark, etc); this regexp catches most of those.

            elsif ( /Rerun to get (.*) right/i) {
                debug("$1 changed") if $DEBUG;
                $self->rerun_required(1);
            }
        }
    }
    else {
        $errors = "failed to open $logfile for input";
    }

    if ($exitcode or $errors) {
        $self->throw($self->formatter . " exited with errors:\n$errors");
    }

    $self->stats->{runs}{formatter}++;

    return;
}

sub reset_latex_required {
    my $self = shift;
    $self->rerun_required(0);
    $self->undefined_references(0);
    $self->labels_changed(0);
    return;
}

sub need_to_run_latex {
    my $self = shift;

    my $auxfile = $self->basepath . '.aux';
    return 1
        if $self->undefined_references
        || $self->labels_changed
        || $self->rerun_required
        || ! -f $auxfile;
    return;
}


#------------------------------------------------------------------------
# run_bibtex()
#
# Run bibtex to generate the bibliography
# bibtex reads references from the .aux file and writes a .bbl file
# It looks for .bib file in BIBINPUTS and TEXBIB
# It looks for .bst file in BSTINPUTS
#------------------------------------------------------------------------

sub run_bibtex {
    my $self = shift;

    my $basename = $self->basename;
    my $exitcode = $self->run_command(bibtex => $basename, 'BIBINPUTS');

    # TODO: extract meaningful error message from .blg file

    $self->throw("bibtex $basename failed ($exitcode)")
        if $exitcode;

    # Make a backup of the citations file for future comparison, reset
    # the undefined citations flag and mark the driver as needing to
    # re-run the formatter.

    my $basepath = $self->basepath;
    copy("$basepath.cit", "$basepath.cbk");

    $self->undefined_citations(0);
    $self->rerun_required(1);
    return;
}


#------------------------------------------------------------------------
# $self->need_to_run_bibtex
#
# LaTeX reports 'Citation ... undefined' if it sees a citation
# (\cite{xxx}, etc) and hasn't read a \bibcite{xxx}{yyy} from the aux
# file.  Those commands are written by parsing the bbl file, but will
# not be seen on the run after bibtex is run as the citations tend to
# come before the \bibliography.
#
# The latex driver sets undefined_citations if it sees the message,
# but we need to look at the .aux file and check whether the \citation
# lines match those seen before the last time bibtex was run.  We
# store the citation commands in a .cit file, this is copied to a cbk
# file by the bibtex method once bibtex has been run.  Doing this
# check saves an extra run of bibtex and latex.
#------------------------------------------------------------------------

sub need_to_run_bibtex {
    my $self = shift;

    if ($self->undefined_citations) {
        my $auxfile = $self->basepath . ".aux";
        my $citfile = $self->basepath . ".cit";
        my $cbkfile = $self->basepath . ".cbk";

        my $auxfh = new IO::File $auxfile, "r" or return;
        my $citfh = new IO::File $citfile, "w"
            or $self->throw("failed to open $citfile for output: $!");

        while ( <$auxfh> ) {
            print($citfh $_) if /^\\citation/;
        }
        undef $auxfh;
        undef $citfh;

        return if -e $cbkfile and (compare($citfile, $cbkfile) == 0);
        return 1;
    }
    return;
}


#------------------------------------------------------------------------
# $self->run_makeindex()
#
# Run makeindex to generate the index
#
# makeindex has a '-s style' option which specifies the style file.
# The environment variable INDEXSTYLE defines the path where the style
# file should be found.
# TODO: sanity check the indexoptions? don't want the caller
# specifying the output index file name as that might screw things up.
#------------------------------------------------------------------------

sub run_makeindex {
    my $self = shift;

    my $basename = $self->basename;
    my @args;
    if (my $stylename = $self->options->{indexstyle}) {
        push @args, "-s", $stylename;
    }
    if (my $index_options = $self->options->{indexoptions}) {
        push @args, $index_options;
    }
    my $exitcode = $self->run_command(makeindex => join(" ", (@args, $basename)));

    # TODO: extract meaningful error message from .ilg file

    $self->throw("makeindex $basename failed ($exitcode)")
        if $exitcode;


    # Make a backup of the raw index file that was just processed, so
    # that we can determine whether makeindex needs to be rerun later.

    my $basepath = $self->basepath;
    copy("$basepath.idx", "$basepath.ibk");

    $self->rerun_required(1);
    return;
}


#------------------------------------------------------------------------
# $self->need_to_run_makeindex()
#
# Determine whether makeindex needs to be run.  Checks that there is a
# raw index file and that it differs from the backup file (if that exists).
#------------------------------------------------------------------------

sub need_to_run_makeindex {
    my $self = shift;

    my $basepath = $self->basepath;
    my $raw_index_file = "$basepath.idx";
    my $backup_file    = "$basepath.ibk";

    return unless -e $raw_index_file;
    return if -e $backup_file and (compare($raw_index_file, $backup_file) == 0);
    return 1;
}


#------------------------------------------------------------------------
# $self->run_dvips()
#
# Run dvips to generate PostScript output
#------------------------------------------------------------------------

sub run_dvips {
    my $self = shift;

    my $basename = $self->basename;

    my $exitstatus = $self->run_command(dvips => "$basename -o");

    $self->throw("dvips $basename failed ($exitstatus)")
        if $exitstatus;
    return;
}


#------------------------------------------------------------------------
# $self->run_ps2pdf()
#
# Run ps2pdf to generate PDF from PostScript output
#------------------------------------------------------------------------

sub run_ps2pdf {
    my $self = shift;

    my $basename = $self->basename;

    my $exitstatus = $self->run_command(ps2pdf => sprintf("%s.ps %s.pdf", $basename, $basename));

    $self->throw("ps2pdf $basename failed ($exitstatus)")
        if $exitstatus;
    return;
}


#------------------------------------------------------------------------
# $self->run_pdf2ps()
#
# Run ps2pdf to generate PostScript from PDF output
#------------------------------------------------------------------------

sub run_pdf2ps {
    my $self = shift;

    my $basename = $self->basename;

    my $exitstatus = $self->run_command(pdf2ps => sprintf("%s.pdf %s.ps", $basename, $basename));

    $self->throw("pdf2ps $basename failed ($exitstatus)")
        if $exitstatus;
    return;
}


#------------------------------------------------------------------------
# $self->run_command($progname, $config, $dir, $args, $env)
#
# Run a command in the specified directory, setting up the environment
# and allowing for the differences between operating systems.
#------------------------------------------------------------------------

sub run_command {
    my ($self, $progname, $args, $envvars) = @_;

    # get the full path to the executable for this output format
    my $program = $self->program_path($progname)
        || $self->throw("$progname cannot be found, please specify its location");

    my $dir  = $self->basedir;
    my $null = File::Spec->devnull();
    my $cmd;

    $args ||= '';


    # Set up localized environment variables in preparation for running the command
    # Note that the localized hash slice assignment of %ENV ensures that
    # the localization is done at the same block level as the system().
    # Even doing something like  local($ENV{$_}) = $val for @{$envvars} 
    # puts the localization in a deeper level block so the previous value
    # is restored before the system() call is made.

    $envvars ||= "TEXINPUTS";
    $envvars = [ $envvars ] unless ref $envvars;
    local(@ENV{@{$envvars}}) = map { $self->texinputs_path } @{$envvars};

    # Format the command appropriately for our O/S
    if ($OSNAME eq 'MSWin32') {
        $cmd = "cmd /c \"cd $dir && $program $args\"";
    }
    else {
        $args = "'$args'" if $args =~ / \\ /mx;
        $cmd  = "cd $dir; $program $args 1>$null 2>$null 0<$null";
    }

    $self->stats->{runs}{$progname}++;
    debug("running '$program $args'") if $DEBUG;

    my $exitstatus = system($cmd);
    return $exitstatus;
}


#------------------------------------------------------------------------
# $self->copy_to_output
#
#------------------------------------------------------------------------

sub copy_to_output {
    my $self = shift;
    my $output = $self->output or return;

    # construct file name of the generated document
    my $file = $self->basepath . '.' . $self->format;

    if (ref $output) {
        $$output = read_file($file);
    }
    else {
        # see if we can rename the generate file to the desired output 
        # file - this may fail, e.g. across filesystem boundaries (and
        # it's quite common for /tmp to be a separate filesystem

        if (rename($file, $output)) {
            debug("renamed $file to $output") if $DEBUG;
        }
        elsif (copy($file, $output)) {
            debug("copied $file to $output") if $DEBUG;
        }
        else {
            $self->throw("failed to copy $file to $output");
        }
    }
    return;
}



#------------------------------------------------------------------------
# _setup_tmpdir($dirname)
#
# create a temporary directory 
#------------------------------------------------------------------------

sub _setup_tmpdir {
    my ($class, $dirname) = @_;

    my $tmp  = File::Spec->tmpdir();

    if ($dirname and ($dirname ne 1)) {
        $dirname = File::Spec->catdir($tmp, $dirname);
        eval { mkpath($dirname, 0, 0700) } unless -d $dirname;
    }
    else {
        my $n = 0;
        do { 
            $dirname = File::Spec->catdir($tmp, "$DEFAULT_TMPDIR$$" . '_' . $n++);
        } while (-e $dirname);
        eval { mkpath($dirname, 0, 0700) };
    }
    $class->throw("cannot create temporary directory: $@") 
        if $@;

    debug(sprintf("setting up temporary directory '%s'\n", $dirname)) if $DEBUG;

    return $dirname;
}


#------------------------------------------------------------------------
# $self->cleanup
#
# cleans up the temporary files
# TODO: work out exactly what this should do
#------------------------------------------------------------------------

sub cleanup {
    my ($self, $what) = @_;
    my $cleanup = $self->{cleanup};
    debug('cleanup called') if $DEBUG;
    if ($cleanup eq 'rmdir') {
        if (!defined($what) or ($what ne 'none')) {
            debug('cleanup removing directory tree ' . $self->basedir) if $DEBUG;
            rmtree($self->basedir);
        }
    }
    return;
}


#------------------------------------------------------------------------
# $self->program_path($progname, $optional_value)
#
# 
#------------------------------------------------------------------------

sub program_path {
    my $class_or_self = shift;
    my $href     = ref $class_or_self ? $class_or_self->{_program_path} : \%program_path;
    my $progname = shift;

    return @_ ? ($href->{$progname} = shift) : $href->{$progname};
}



#------------------------------------------------------------------------
# throw($error)
#
# Throw an error message
#------------------------------------------------------------------------

sub throw {
    my $self = shift;
    LaTeX::Driver::Exception->throw( error => join('', @_) );
}

sub debug {
    print STDERR $DEBUGPREFIX || "[latex] ", @_;
    print STDERR "\n" unless $_[-1] =~ / \n $ /mx;
    return;
}


1;

__END__

# Local Variables:
# mode: perl
# perl-indent-level: 4
# indent-tabs-mode: nil
# End:
#
# vim: expandtab shiftwidth=4: