File Coverage

lib/Template/Latex.pm
Criterion Covered Total %
statement 13 15 86.6
branch n/a
condition n/a
subroutine 5 5 100.0
pod n/a
total 18 20 90.0


line stmt bran cond sub pod time code
1             #============================================================= -*-perl-*-
2             #
3             # Template::Latex
4             #
5             # DESCRIPTION
6             # Provides an interface to Latex from the Template Toolkit.
7             #
8             # AUTHOR
9             # Chris Travers <chris.travers@gmail.com> (Current Maintainer)
10             # Andrew Ford <a.ford@ford-mason.co.uk>
11             # Andy Wardley <abw@wardley.org>
12             #
13             # COPYRIGHT
14             # Copyright (C) 2014-2016 Chris Travers. All Rights Reserved.
15             # Copyright (C) 2006-2014 Andrew Ford. All Rights Reserved.
16             # Copyright (C) 1996-2006 Andy Wardley. All Rights Reserved.
17             #
18             # This module is free software; you can redistribute it and/or
19             # modify it under the same terms as Perl itself.
20             #
21             # HISTORY
22             # * Latex plugin originally written by Craig Barratt, Apr 28 2001.
23             # * Win32 additions by Richard Tietjen.
24             # * Extracted into a separate Template::Latex module by Andy Wardley,
25             # May 2006
26             # * Removed the functionality to specify program pathnames on the FILTER call
27             # Andrew Ford, 05 June 2006
28             # * Now runs BibTeX and Makeindex if required
29             # Andrew Ford, 05 June 2006
30             # * Rewritten to set up TEXINPUTS so that inclusions can be found and to run
31             # latex, bibtex and makeindex repeatedly as needed until references stabilize
32             # (NOT YET FINISHED)
33             # Andrew Ford, September 2007
34             #
35             #========================================================================
36              
37             package Template::Latex;
38              
39 2     2   3217 use strict;
  2         2  
  2         46  
40 2     2   6 use warnings;
  2         2  
  2         60  
41 2     2   14 use base 'Template';
  2         3  
  2         985  
42 2     2   30471 use Template::Exception;
  2         4  
  2         32  
43 2     2   796 use Template::Plugin::Latex;
  0            
  0            
44             use LaTeX::Driver;
45              
46             our $VERSION = '3.11';
47             our $DEBUG = 0 unless defined $DEBUG;
48             our $ERROR = '';
49             our $FILTER = 'latex'; # default filter name
50             our $FORMAT = ''; # output format (auto-detect if unset)
51             our @PROGRAMS = qw( latex pdflatex bibtex makeindex dvips ps2pdf );
52              
53              
54             sub new {
55             my $class = shift;
56             my $config = @_ && ref $_[0] eq 'HASH' ? shift : { @_ };
57             my $self = $class->SUPER::new($config) || return;
58             my %options;
59            
60             # # set default format from config option
61             $options{format} = $config->{LATEX_FORMAT}
62             if $config->{LATEX_FORMAT};
63              
64              
65             my @unsupported = ( 'LATEX', 'PDFLATEX', 'DVIPS', 'PS2PDF',
66             'BIBTEX', 'MAKEINDEX' );
67            
68             warn "Template::Latex no longer supports various *_PATH options to new()"
69             if scalar(grep { defined $config->{"${_}_PATH"} } @unsupported) > 0;
70            
71              
72             # install the latex filter
73             Template::Plugin::Latex->new($self->context, \%options);
74              
75             return $self;
76             }
77              
78              
79             #------------------------------------------------------------------------
80             # latex_format()
81             # latex_path()
82             # pdflatex_path()
83             # dvips_path()
84             #
85             # Methods to get/set the $FORMAT, $LATEX, $PDFLATEX and $DVIPS package
86             # variables that specify the default output format and the paths to
87             # the latex, pdflatex and dvips programs.
88             #------------------------------------------------------------------------
89              
90             sub latex_format {
91             my $class = shift;
92             return @_ ? ($FORMAT = shift) : $FORMAT;
93             }
94              
95             sub latex_path {
96             my $class = shift;
97             return LaTeX::Driver->program_path('latex', @_);
98             }
99              
100             sub pdflatex_path {
101             my $class = shift;
102             return LaTeX::Driver->program_path('pdflatex', @_);
103             }
104              
105             sub dvips_path {
106             my $class = shift;
107             return LaTeX::Driver->program_path('dvips', @_);
108             }
109              
110             sub ps2pdf_path {
111             my $class = shift;
112             return LaTeX::Driver->program_path('ps2pdf', @_);
113             }
114              
115             sub bibtex_path {
116             my $class = shift;
117             return LaTeX::Driver->program_path('bibtex', @_);
118             }
119              
120             sub makeindex_path {
121             my $class = shift;
122             return LaTeX::Driver->program_path('makeindex', @_);
123             }
124              
125             sub xelatex_path {
126             my $class = shift;
127             return LaTeX::Driver->program_path('xelatex', @_);
128             }
129              
130             #------------------------------------------------------------------------
131             # latex_paths()
132             #
133             # Method to get/set the above all in one go.
134             #------------------------------------------------------------------------
135              
136             sub latex_paths {
137             my $class = shift;
138             if (@_) {
139             my $args = ref $_[0] eq 'HASH' ? shift : { @_ };
140              
141             LaTeX::Driver->program_path($_, $args->{$_})
142             for qw( latex pdflatex bibtex makeindex dvips ps2pdf );
143             }
144             else {
145             return {
146             map { ( $_ => LaTeX::Driver->program_path($_) ) } @PROGRAMS
147             };
148             }
149             }
150              
151             1;
152              
153             __END__
154              
155              
156             =head1 NAME
157              
158             Template::Latex - Latex support for the Template Toolkit
159              
160             =head1 SYNOPSIS
161              
162             use Template::Latex;
163            
164             my $tt = Template::Latex->new({
165             INCLUDE_PATH => '/path/to/templates',
166             OUTPUT_PATH => '/path/to/pdf/output',
167             LATEX_FORMAT => 'pdf',
168             });
169             my $vars = {
170             title => 'Hello World',
171             }
172             $tt->process('example.tt2', $vars, 'example.pdf', binmode => 1)
173             || die $tt->error();
174              
175             =head1 DESCRIPTION
176              
177             The Template::Latex module is a wrapper of convenience around the
178             Template module, providing additional support for generating PDF,
179             PostScript and DVI documents from LaTeX templates.
180              
181             You use the Template::Latex module exactly as you would the Template
182             module.
183              
184             my $tt = Template::Latex->new(\%config);
185             $tt->process($input, \%vars, $output)
186             || die $t->error();
187              
188             It supports the C<LATEX_FORMAT> option to specify the default
189             output format. This can be set to C<pdf>, C<ps> or C<dvi>.
190              
191             my $tt = Template::Latex->new({
192             LATEX_FORMAT => 'pdf',
193             });
194              
195             Previous versions of the module supported the C<LATEX_PATH>,
196             C<PDFLATEX_PATH>, C<DVIPS_PATH>, C<PS2PDF_PATH>, C<BIBTEX_PATH>
197             and C<MAKEINDEX_PATH> options. These are now deprecated
198             and their use will result in a deprecation warning, as their use
199             would result in modifying global state, disallowing different values
200             for different simultaneous instances.
201              
202             To change the paths of the various programs being called by the
203             LaTeX::Driver module which this module wraps, the user is referred
204             to the API of that module. This module provides a number of (wrapper)
205             class methods around the LaTeX::Driver routine (latex_path() and
206             friends).
207              
208             The C<latex> filter is automatically defined when you use the
209             Template::Latex module. There's no need to load the Latex plugin in
210             this case, although you can if you want (e.g. to set some
211             configuration defaults). If you're using the regular Template module
212             then you should first load the Latex plugin to define the C<latex>
213             filter.
214              
215             [% USE Latex %]
216             [% FILTER latex('example.pdf') %]
217             ...LaTeX doc...
218             [% END %]
219              
220             =head1 PUBLIC METHODS
221              
222             The Template::Latex module is a subclass of the Template module and
223             inherits all its methods. Please consult the documentation for the
224             L<Template> module for further information on using it for template
225             processing. Wherever you see C<Template> substitute it for
226             C<Template::Latex>.
227              
228             In addition to those inherted from the Template module, the following
229             methods are also defined.
230              
231             =head2 latex_paths()
232              
233             Method to get or set the paths to the F<latex>, F<pdflatex> and
234             F<dvips> programs. These values are stored in the Template::Latex
235             C<$LATEX>, C<$PDFLATEX> and C<$DVIPS> package variables, respectively.
236             It can be called as either a class or object method.
237              
238             Template::Latex->latex_paths({
239             latex => '/usr/bin/latex',
240             pdflatex => '/usr/bin/pdflatex',
241             dvips => '/usr/bin/dvips',
242             });
243              
244             my $paths = Template::Latex->latex_paths();
245             print $paths->{ latex }; # /usr/bin/latex
246              
247             =head2 latex_path()
248              
249             Method to get or set the C<$Template::Latex::LATEX> package
250             variable which defines the location of the F<latex> program on your
251             system. It can be called as a class or object method.
252              
253             Template::Latex->latex_path('/usr/bin/latex');
254             print Template::Latex->latex_path(); # '/usr/bin/latex'
255              
256             =head2 pdflatex_path()
257              
258             Method to get or set the C<$Template::Latex::PDFLATEX> package
259             variable which defines the location of the F<pdflatex> program on your
260             system. It can be called as a class or object method.
261              
262             Template::Latex->pdflatex_path('/usr/bin/pdflatex');
263             print Template::Latex->pdflatex_path(); # '/usr/bin/pdflatex'
264              
265             =head2 dvips_path()
266              
267             Method to get or set the C<$Template::Latex::DVIPS> package
268             variable which defines the location of the F<dvips> program on your
269             system. It can be called as a class or object method.
270              
271             Template::Latex->dvips_path('/usr/bin/dvips');
272             print Template::Latex->dvips_path(); # '/usr/bin/dvips'
273              
274             =head2 bibtex_path()
275              
276             Method to get or set the C<$Template::Latex::BIBTEX> package
277             variable which defines the location of the F<bibtex> program on your
278             system. It can be called as a class or object method.
279              
280             Template::Latex->bibtex_path('/usr/bin/bibtex');
281             print Template::Latex->bibtex_path(); # '/usr/bin/bibtex'
282              
283             =head2 makeindex_path()
284              
285             Method to get or set the C<$Template::Latex::MAKEINDEX> package
286             variable which defines the location of the F<makeindex> program on your
287             system. It can be called as a class or object method.
288              
289             Template::Latex->makeindex_path('/usr/bin/makeindex');
290             print Template::Latex->makeindex_path(); # '/usr/bin/makeindex'
291              
292             =head1 INTERNALS
293              
294             This section is aimed at a technical audience. It documents the
295             internal methods and subroutines as a reference for the module's
296             developers, maintainers and anyone interesting in understanding how it
297             works. You don't need to know anything about them to use the module
298             and can safely skip this section.
299              
300             =head2 define_filter($context,\%config)
301              
302             This class method installs the C<latex> filter in the context passed
303             as the first argument. The second argument is a hash reference
304             containing any default filter parameters (e.g. those specified when
305             the Template::Plugin::Latex plugin is loaded via a C<USE> directive).
306              
307             Template::Latex->define_filter($context, { format => 'pdf' });
308              
309             The filter is installed as a I<dynamic filter factory>. This is just
310             a fancy way of saying that the filter generates a new filter
311             subroutine each time it is used to account for different invocation
312             parameters. The filter subroutine it creates is effectively a wrapper
313             (a "closure" in technical terms) around the C<filter()> subroutine
314             (see below) which does the real work. The closure keeps track of any
315             configuration parameters specified when the filter is first defined
316             and/or when the filter is invoked. It passes the merged configuration
317             as the second argument to the C<filter()> subroutine (see below).
318              
319             See the L<Template::Filters> module for further information on how
320             filters work.
321              
322             =head2 filter($text,\%config)
323              
324             This is the main LaTeX filter subroutine which is called by the
325             Template Toolkit to generate a LaTeX document from the text passed as
326             the first argument. The second argument is a reference to a hash
327             array of configuration parameters. These are usually provided by the
328             filter subroutine that is generated by the filter factory.
329              
330             Template::Latex::filter($latex, {
331             latex => '/usr/bin/latex',
332             pdflatex => '/usr/bin/pdflatex',
333             dvips => '/usr/bin/dvips',
334             output => 'example.pdf',
335             });
336              
337             =head2 throw($message)
338              
339             Subroutine which throws a L<Template::Exception> error using C<die>.
340             The exception type is set to C<latex>.
341              
342             Template::Latex::throw("I'm sorry Dave, I can't do that");
343              
344             =head2 debug($message)
345              
346             Debugging subroutine which print all argument to STDERR. Set the
347             C<$DEBUG> package variable to enable debugging messages.
348              
349             $Template::Latex::DEBUG = 1;
350              
351             =head1 AUTHOR
352              
353             Andrew Ford E<lt>a.ford@ford-mason.co.ukE<gt> (current maintainer)
354              
355             Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/>
356              
357             The original Latex plugin on which this is based was written by Craig
358             Barratt with additions for Win32 by Richard Tietjen.
359              
360             =head1 COPYRIGHT
361              
362             Copyright (C) 1996-2006 Andy Wardley. All Rights Reserved.
363             Copyright (C) 2006-2014 Andrew Ford. All Rights Reserved.
364             Copyright (C) 2014-2016 Chris Travers. All Rights Reserved.
365              
366             This module is free software; you can redistribute it and/or
367             modify it under the same terms as Perl itself.
368              
369             =head1 SEE ALSO
370              
371             L<Template::Plugin::Latex>
372              
373             =cut
374              
375             # Local Variables:
376             # mode: perl
377             # perl-indent-level: 4
378             # indent-tabs-mode: nil
379             # End:
380             #
381             # vim: expandtab shiftwidth=4: