Debian Codegraph @

texmf-dist/source/latex/perltex/perltex.dtx

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (C) 2003-2024 Scott Pakin <[email protected]>
4 % --------------------------------------------------------
5 %
6 % This file may be distributed and/or modified under the conditions of
7 % the LaTeX Project Public License, either version 1.3c of this license
8 % or (at your option) any later version. The latest version of this
9 % license is in:
10 %
11 % http://www.latex-project.org/lppl.txt
12 %
13 % and version 1.3c or later is part of all distributions of LaTeX
14 % version 2006/05/20 or later.
15 %
16 % \fi
17 %
18 % \iffalse
19 %<*driver>
20 \ProvidesFile{perltex.dtx}
21 %</driver>
22 %<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
23 %<package>\ProvidesPackage{perltex}
24 %<*package>
25 [2024/12/03 v2.3 LaTeX macros for use with PerlTeX]
26 %</package>
27 %
28 %<*driver>
29 \documentclass{ltxdoc}
30 \makeatletter
31 \def\plmac@tag{FakingBeingRunFromPerlTeX}
32 \def\plmac@tofile{\jobname.topl}
33 \def\plmac@fromfile{\jobname.frpl}
34 \def\plmac@toflag{\jobname.tfpl}
35 \def\plmac@fromflag{\jobname.ffpl}
36 \def\plmac@doneflag{\jobname.dfpl}
37 \def\plmac@pipe{\jobname.pipe}
38 \makeatother
39 \usepackage{perltex}
40 \usepackage{varioref}
41 \usepackage{flafter}
42 \usepackage{textcomp}
43 \usepackage{graphicx}
44 \usepackage{hyperref}
45 \hypersetup{%
46 hyperindex=false,
47 bookmarksopen,
48 pdftitle={PerlTeX: Defining LaTeX macros in terms of Perl code},
49 pdfauthor={Scott Pakin, [email protected]},
50 pdfsubject={Using Perl to define LaTeX macros},
51 pdfkeywords={programming, LaTeX, macros, Perl}
52 }
53 \EnableCrossrefs
54 \CodelineIndex
55 \RecordChanges
56 \setcounter{IndexColumns}{2}
57 \begin{document}
58 \DocInput{perltex.dtx}
59 \end{document}
60 %</driver>
61 % \fi
62 %
63 % \CheckSum{622}
64 %
65 % \CharacterTable
66 % {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
67 % Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
68 % Digits \0\1\2\3\4\5\6\7\8\9
69 % Exclamation \! Double quote \" Hash (number) \#
70 % Dollar \$ Percent \% Ampersand \&
71 % Acute accent \' Left paren \( Right paren \)
72 % Asterisk \* Plus \+ Comma \,
73 % Minus \- Point \. Solidus \/
74 % Colon \: Semicolon \; Less than \<
75 % Equals \= Greater than \> Question mark \?
76 % Commercial at \@ Left bracket \[ Backslash \\
77 % Right bracket \] Circumflex \^ Underscore \_
78 % Grave accent \` Left brace \{ Vertical bar \|
79 % Right brace \} Tilde \~}
80 %
81 %
82 % \changes{v1.0}{2003/07/13}{Initial version}
83 % \changes{v1.2}{2004/10/07}{Renamed \texttt{perlmacros.sty} to
84 % \texttt{perltex.sty} for consistency.}
85 %
86 % \GetFileInfo{perltex.sty}
87 %
88 % \DoNotIndex{\$, \', \(, \), \., \\, \{, \}, \^, \", \@}
89 % \DoNotIndex{\@empty, \@ifnextchar, \@ifundefined, \@makeother, \@ne}
90 % \DoNotIndex{\@permittedops}
91 % \DoNotIndex{\A, \active, \advance}
92 % \DoNotIndex{\b, \begin, \begingroup, \bgroup, \btrapped}
93 % \DoNotIndex{\catcode, \csname}
94 % \DoNotIndex{\d, \def, \documentclass}
95 % \DoNotIndex{\E, \edef, \egroup, \else, \end, \endcsname, \endgroup}
96 % \DoNotIndex{\expandafter}
97 % \DoNotIndex{\fi}
98 % \DoNotIndex{\gdef, \global}
99 % \DoNotIndex{\ifeof, \ifnum, \ifx, \immediate}
100 % \DoNotIndex{\let, \loop}
101 % \DoNotIndex{\makeatletter, \makeatother, \MessageBreak}
102 % \DoNotIndex{\n, \newcommand, \newcount, \newenvironment, \newif}
103 % \DoNotIndex{\newread, \newtoks, \newwrite}
104 % \DoNotIndex{\noexpand, \number}
105 % \DoNotIndex{\obeyspaces}
106 % \DoNotIndex{\ProcessOptions, \protect}
107 % \DoNotIndex{\Q}
108 % \DoNotIndex{\r, \relax, \repeat}
109 % \DoNotIndex{\s, \space, \string}
110 % \DoNotIndex{\TeX, \the}
111 % \DoNotIndex{\W}
112 %
113 % \newcommand{\indexpkg}[1]{^^A ^^A Index a package name
114 % \index{#1=\textsf{#1} (package)}^^A
115 % \index{packages>#1=\textsf{#1}}^^A
116 % }
117 % \newcommand{\pkgname}[1]{^^A ^^A Name of an arbitrary package
118 % \textsf{#1}^^A
119 % \indexpkg{#1}^^A
120 % }
121 % \newcommand{\PerlTeX}{Perl\TeX{}} ^^A Name of the complete system
122 % \newcommand{\perltex}{\texttt{perltex.pl}} ^^A Name of the Perl script
123 % \newcommand{\perlmac}{^^A ^^A Name of the LaTeX package
124 % \texttt{perltex.sty}^^A
125 % \indexpkg{perltex}^^A
126 % }
127 % \newcommand{\noperlmac}{\texttt{noperltex.sty}} ^^A Name of the alternate LaTeX package
128 % \newcommand{\XeTeX}{^^A ^^A Name of the typesetting system
129 % X\lower0.5ex\hbox{\kern-0.15em\reflectbox{E}}\kern-0.1667em\TeX^^A
130 % }
131 % \newcommand{\signal}[1]{^^A ^^A Signal handler
132 % \lowercase{\textsc{sig#1}}^^A
133 % \index{SIG#1=\lowercase{\textsc{sig#1}}}^^A
134 % }
135 %
136 % ^^A Typeset package options.
137 % \newcommand{\DescribeOption}[1]{^^A
138 % \marginpar{\raggedleft\PrintDescribeEnv{#1}}}
139 % \newcommand{\pkgoption}[1]{^^A
140 % \texttt{#1}^^A
141 % \index{#1=\texttt{#1} (package option)}^^A
142 % \index{package options>#1=\texttt{#1}}^^A
143 % }
144 %
145 %
146 % ^^A Define an environment just like macro but for Perl subroutines
147 % \makeatletter
148 % \newenvironment{perlsub}{^^A
149 % \begingroup
150 % \catcode`\_=11
151 % \def\PrintMacroName##1{\strut\MacroFont\string##1\ }^^A
152 % \def\SpecialIndex@##1##2{^^A
153 % \@bsphack
154 % \special@index{\string##1\actualchar
155 % \string\verb\quotechar*\verbatimchar##1\verbatimchar##2}^^A
156 % \@esphack
157 % }^^A
158 % \begin{macro}^^A
159 % }{^^A
160 % \end{macro}^^A
161 % \endgroup
162 % }
163 % \makeatother
164 %
165 % ^^A Define an environment just like macro but for Perl scalars or lists.
166 % \makeatletter
167 % \newenvironment{perlvar}{^^A
168 % \begingroup
169 % \catcode`\_=11
170 % \def\PrintMacroName##1{\strut\MacroFont\string##1\ }^^A
171 % \def\SpecialIndex@##1##2{^^A
172 % \@bsphack
173 % \special@index{\expandafter\@gobble\string##1\actualchar
174 % \string\verb\quotechar*\verbatimchar\string##1\verbatimchar##2}^^A
175 % \@esphack
176 % }^^A
177 % \begin{macro}^^A
178 % }{^^A
179 % \end{macro}^^A
180 % \endgroup
181 % }
182 % \makeatother
183 %
184 % \title{\PerlTeX: \\ Defining \LaTeX{} macros in terms of Perl code^^A
185 % \thanks{This document corresponds to \PerlTeX~\fileversion, dated
186 % \filedate.}}
187 % \author{Scott Pakin \\ \texttt{[email protected]}}
188 %
189 % \maketitle
190 % \sloppy
191 %
192 % \begin{abstract}
193 % \PerlTeX{} is a combination Perl script (\perltex) and \LaTeXe{}
194 % style file (\perlmac) that, together, give the user the ability to
195 % define \LaTeX{} macros in terms of Perl code. Once defined, a Perl
196 % macro becomes indistinguishable from any other \LaTeX{} macro.
197 % \PerlTeX{} thereby combines \LaTeX's typesetting power with Perl's
198 % programmability.
199 % \end{abstract}
200 %
201 % \section{Introduction}
202 %
203 % \TeX{} is a professional-quality typesetting system. However, its
204 % programming language is rather hard to use for anything but the most
205 % simple forms of text substitution. Even \LaTeX, the most popular
206 % macro package for \TeX, does little to simplify \TeX{} programming.
207 %
208 % Perl is a general-purpose programming language whose forte is in text
209 % manipulation. However, it has no support whatsoever for typesetting.
210 %
211 % \PerlTeX's goal is to bridge these two worlds. It enables the
212 % construction of documents that are primarily \LaTeX-based but contain
213 % a modicum of Perl. \PerlTeX{} seamlessly integrates Perl code into a
214 % \LaTeX{} document, enabling the user to define macros whose bodies
215 % consist of Perl code instead of \TeX{} and \LaTeX{} code.
216 %
217 % As an example, suppose you need to define a macro that reverses a set
218 % of words. Although it sounds like it should be simple, few \LaTeX{}
219 % authors are sufficiently versed in the \TeX{} language to be able to
220 % express such a macro. However, a word-reversal function is easy to
221 % express in Perl: one need only |split| a string into a list of words,
222 % |reverse| the list, and |join| it back together. The following is how
223 % a |\reversewords| macro could be defined using \PerlTeX:
224 %
225 % \begin{verbatim}
226 % \perlnewcommand{\reversewords}[1]{join " ", reverse split " ", $_[0]}
227 % \end{verbatim}
228 %
229 % \noindent
230 % Then, executing ``\texttt{\string\reversewords\string{Try doing this
231 % without Perl!\string}}'' in a document would produce the text ``Perl!
232 % without this doing Try''. Simple, isn't it?
233 %
234 % As another example, think about how you'd write a macro in \LaTeX{} to
235 % extract a substring of a given string when provided with a starting
236 % position and a length. Perl has an built-in |substr| function and
237 % \PerlTeX{} makes it easy to export this to \LaTeX:
238 %
239 % \begin{verbatim}
240 % \perlnewcommand{\substr}[3]{substr $_[0], $_[1], $_[2]}
241 % \end{verbatim}
242 %
243 % |\substr| can then be used just like any other \LaTeX{} macro---and as
244 % simply as Perl's |substr| function:
245 %
246 % \bigskip
247 %
248 % \noindent| |^^A
249 % \begin{tabular}{@{}l@{}}
250 % |\newcommand{\str}{superlative}| \\
251 % |A sample substring of ``\str'' is ``\substr{\str}{2}{4}''.| \\[1ex]
252 % \multicolumn{1}{@{}c@{}}{\Huge$\Downarrow$} \\[2ex]
253 % \multicolumn{1}{@{}c@{}}{A sample substring of ``superlative'' is ``perl''.}
254 % \end{tabular}
255 %
256 % \bigskip
257 %
258 % To present a somewhat more complex example, observe how much
259 % easier it is to generate a repetitive matrix using Perl code than
260 % ordinary \LaTeX{} commands:
261 %
262 % \begin{verbatim}
263 % \perlnewcommand{\hilbertmatrix}[1]{
264 % my $result = '
265 % \[
266 % \renewcommand{\arraystretch}{1.3}
267 % ';
268 % $result .= '\begin{array}{' . 'c' x $_[0] . "}\n";
269 % foreach $j (0 .. $_[0]-1) {
270 % my @row;
271 % foreach $i (0 .. $_[0]-1) {
272 % push @row, ($i+$j) ? (sprintf '\frac{1}{%d}', $i+$j+1) : '1';
273 % }
274 % $result .= join (' & ', @row) . " \\\\\n";
275 % }
276 % $result .= '\end{array}
277 % \]';
278 % return $result;
279 % }
280 %
281 % \hilbertmatrix{20}
282 % \end{verbatim}
283 %
284 % \begin{center}
285 % {\Huge$\Downarrow$}
286 % \end{center}
287 %
288 % \[
289 % \renewcommand{\arraystretch}{1.3}
290 % \begin{array}{ccccccccccccccc}
291 % 1 & \frac{1}{2} & \frac{1}{3} & \frac{1}{4} & \frac{1}{5} & \frac{1}{6} & \frac{1}{7} & \frac{1}{8} & \frac{1}{9} & \frac{1}{10} & \frac{1}{11} & \frac{1}{12} & \frac{1}{13} & \frac{1}{14} & \frac{1}{15} \\
292 % \frac{1}{2} & \frac{1}{3} & \frac{1}{4} & \frac{1}{5} & \frac{1}{6} & \frac{1}{7} & \frac{1}{8} & \frac{1}{9} & \frac{1}{10} & \frac{1}{11} & \frac{1}{12} & \frac{1}{13} & \frac{1}{14} & \frac{1}{15} & \frac{1}{16} \\
293 % \frac{1}{3} & \frac{1}{4} & \frac{1}{5} & \frac{1}{6} & \frac{1}{7} & \frac{1}{8} & \frac{1}{9} & \frac{1}{10} & \frac{1}{11} & \frac{1}{12} & \frac{1}{13} & \frac{1}{14} & \frac{1}{15} & \frac{1}{16} & \frac{1}{17} \\
294 % \frac{1}{4} & \frac{1}{5} & \frac{1}{6} & \frac{1}{7} & \frac{1}{8} & \frac{1}{9} & \frac{1}{10} & \frac{1}{11} & \frac{1}{12} & \frac{1}{13} & \frac{1}{14} & \frac{1}{15} & \frac{1}{16} & \frac{1}{17} & \frac{1}{18} \\
295 % \frac{1}{5} & \frac{1}{6} & \frac{1}{7} & \frac{1}{8} & \frac{1}{9} & \frac{1}{10} & \frac{1}{11} & \frac{1}{12} & \frac{1}{13} & \frac{1}{14} & \frac{1}{15} & \frac{1}{16} & \frac{1}{17} & \frac{1}{18} & \frac{1}{19} \\
296 % \frac{1}{6} & \frac{1}{7} & \frac{1}{8} & \frac{1}{9} & \frac{1}{10} & \frac{1}{11} & \frac{1}{12} & \frac{1}{13} & \frac{1}{14} & \frac{1}{15} & \frac{1}{16} & \frac{1}{17} & \frac{1}{18} & \frac{1}{19} & \frac{1}{20} \\
297 % \frac{1}{7} & \frac{1}{8} & \frac{1}{9} & \frac{1}{10} & \frac{1}{11} & \frac{1}{12} & \frac{1}{13} & \frac{1}{14} & \frac{1}{15} & \frac{1}{16} & \frac{1}{17} & \frac{1}{18} & \frac{1}{19} & \frac{1}{20} & \frac{1}{21} \\
298 % \frac{1}{8} & \frac{1}{9} & \frac{1}{10} & \frac{1}{11} & \frac{1}{12} & \frac{1}{13} & \frac{1}{14} & \frac{1}{15} & \frac{1}{16} & \frac{1}{17} & \frac{1}{18} & \frac{1}{19} & \frac{1}{20} & \frac{1}{21} & \frac{1}{22} \\
299 % \frac{1}{9} & \frac{1}{10} & \frac{1}{11} & \frac{1}{12} & \frac{1}{13} & \frac{1}{14} & \frac{1}{15} & \frac{1}{16} & \frac{1}{17} & \frac{1}{18} & \frac{1}{19} & \frac{1}{20} & \frac{1}{21} & \frac{1}{22} & \frac{1}{23} \\
300 % \frac{1}{10} & \frac{1}{11} & \frac{1}{12} & \frac{1}{13} & \frac{1}{14} & \frac{1}{15} & \frac{1}{16} & \frac{1}{17} & \frac{1}{18} & \frac{1}{19} & \frac{1}{20} & \frac{1}{21} & \frac{1}{22} & \frac{1}{23} & \frac{1}{24} \\
301 % \frac{1}{11} & \frac{1}{12} & \frac{1}{13} & \frac{1}{14} & \frac{1}{15} & \frac{1}{16} & \frac{1}{17} & \frac{1}{18} & \frac{1}{19} & \frac{1}{20} & \frac{1}{21} & \frac{1}{22} & \frac{1}{23} & \frac{1}{24} & \frac{1}{25} \\
302 % \frac{1}{12} & \frac{1}{13} & \frac{1}{14} & \frac{1}{15} & \frac{1}{16} & \frac{1}{17} & \frac{1}{18} & \frac{1}{19} & \frac{1}{20} & \frac{1}{21} & \frac{1}{22} & \frac{1}{23} & \frac{1}{24} & \frac{1}{25} & \frac{1}{26} \\
303 % \frac{1}{13} & \frac{1}{14} & \frac{1}{15} & \frac{1}{16} & \frac{1}{17} & \frac{1}{18} & \frac{1}{19} & \frac{1}{20} & \frac{1}{21} & \frac{1}{22} & \frac{1}{23} & \frac{1}{24} & \frac{1}{25} & \frac{1}{26} & \frac{1}{27} \\
304 % \frac{1}{14} & \frac{1}{15} & \frac{1}{16} & \frac{1}{17} & \frac{1}{18} & \frac{1}{19} & \frac{1}{20} & \frac{1}{21} & \frac{1}{22} & \frac{1}{23} & \frac{1}{24} & \frac{1}{25} & \frac{1}{26} & \frac{1}{27} & \frac{1}{28} \\
305 % \frac{1}{15} & \frac{1}{16} & \frac{1}{17} & \frac{1}{18} & \frac{1}{19} & \frac{1}{20} & \frac{1}{21} & \frac{1}{22} & \frac{1}{23} & \frac{1}{24} & \frac{1}{25} & \frac{1}{26} & \frac{1}{27} & \frac{1}{28} & \frac{1}{29} \\
306 % \end{array}
307 % \]
308 %
309 % \bigskip
310 %
311 % In addition to |\perlnewcommand| and |\perlrenewcommand|, \PerlTeX{}
312 % supports |\perlnewenvironment| and |\perlrenewenvironment| macros.
313 % These enable environments to be defined using Perl code. The
314 % following example, a |spreadsheet| environment, generates a |tabular|
315 % environment plus a predefined header row. This example would have
316 % been much more difficult to implement without \PerlTeX:
317 %
318 % \begin{verbatim}
319 % \newcounter{ssrow}
320 % \perlnewenvironment{spreadsheet}[1]{
321 % my $cols = $_[0];
322 % my $header = "A";
323 % my $tabular = "\\setcounter{ssrow}{1}\n";
324 % $tabular .= '\newcommand*{\rownum}{\thessrow\addtocounter{ssrow}{1}}' . "\n";
325 % $tabular .= '\begin{tabular}{@{}r|*{' . $cols . '}{r}@{}}' . "\n";
326 % $tabular .= '\\multicolumn{1}{@{}c}{} &' . "\n";
327 % foreach (1 .. $cols) {
328 % $tabular .= "\\multicolumn{1}{c";
329 % $tabular .= '@{}' if $_ == $cols;
330 % $tabular .= "}{" . $header++ . "}";
331 % if ($_ == $cols) {
332 % $tabular .= " \\\\ \\cline{2-" . ($cols+1) . "}"
333 % }
334 % else {
335 % $tabular .= " &";
336 % }
337 % $tabular .= "\n";
338 % }
339 % return $tabular;
340 % }{
341 % return "\\end{tabular}\n";
342 % }
343 %
344 % \begin{center}
345 % \begin{spreadsheet}{4}
346 % \rownum & 1 & 8 & 10 & 15 \\
347 % \rownum & 12 & 13 & 3 & 6 \\
348 % \rownum & 7 & 2 & 16 & 9 \\
349 % \rownum & 14 & 11 & 5 & 4
350 % \end{spreadsheet}
351 % \end{center}
352 % \end{verbatim}
353 %
354 % \begin{center}
355 % {\Huge$\Downarrow$}
356 % \end{center}
357 %
358 % \DeleteShortVerb{\|}
359 % \begin{center}
360 % \begin{tabular}{@{}r|*{4}{r}@{}}
361 % \multicolumn{1}{@{}c}{} &
362 % \multicolumn{1}{c}{A} &
363 % \multicolumn{1}{c}{B} &
364 % \multicolumn{1}{c}{C} &
365 % \multicolumn{1}{c@{}}{D} \\ \cline{2-5}
366 % 1 & 1 & 8 & 10 & 15 \\
367 % 2 & 12 & 13 & 3 & 6 \\
368 % 3 & 7 & 2 & 16 & 9 \\
369 % 4 & 14 & 11 & 5 & 4
370 % \end{tabular}
371 % \end{center}
372 % \MakeShortVerb{\|}
373 %
374 %
375 % \section{Usage}
376 %
377 % There are two components to using \PerlTeX\@. First, documents must
378 % include a ``|\usepackage{perltex}|'' line in their preamble in
379 % order to define |\perlnewcommand|, |\perlrenewcommand|,
380 % |\perlnewenvironment|, and |\perlrenewenvironment|. Second, \LaTeX{}
381 % documents must be compiled using the \perltex{} wrapper script.
382 %
383 % \subsection{Defining and redefining Perl macros}
384 %
385 % \DescribeMacro{\perlnewcommand}
386 % \DescribeMacro{\perlrenewcommand}
387 % \DescribeMacro{\perlnewenvironment}
388 % \DescribeMacro{\perlrenewenvironment}
389 % \DescribeMacro{\perldo}
390 % \perlmac{} defines five macros: |\perlnewcommand|,
391 % |\perlrenewcommand|, |\perlnewenvironment|, |\perlrenewenvironment|,
392 % and |\perldo|. The first four of these behave exactly like their
393 % \LaTeXe{} counterparts---|\newcommand|, |\renewcommand|,
394 % |\newenvironment|, and |\renewenvironment|---except that the macro
395 % body consists of Perl code that dynamically generates \LaTeX{} code.
396 % \perlmac{} even includes support for optional arguments and the
397 % starred forms of its commands (i.e.~|\perlnewcommand*|,
398 % |\perlrenewcommand*|, |\perlnewenvironment*|, and
399 % |\perlrenewenvironment*|). |\perldo| immediately executes a block of
400 % Perl code without (re)defining any macros or environments.
401 %
402 % A \PerlTeX-defined macro or environments is converted to a Perl
403 % subroutine named after the macro/environment but beginning with
404 % ``|latex_|''. For example, a \PerlTeX-defined \LaTeX{} macro called
405 % |\myMacro| internally produces a Perl subroutine called
406 % |latex_myMacro|. Macro arguments are converted to subroutine
407 % arguments. A \LaTeX{} macro's |#1| argument is referred to as |$_[0]|
408 % in Perl; |#2| is referred to as |$_[1]|; and so forth.
409 %
410 % Any valid Perl code can be used in the body of a macro. However,
411 % \PerlTeX{} executes the Perl code within a secure sandbox. This means
412 % that potentially harmful Perl operations, such as |unlink|, |rmdir|,
413 % and |system| will result in a run-time error. (It is possible to
414 % disable the safety checks, however, as is explained in
415 % Section~\ref{sec:perltex-man}.) Having a secure sandbox implies that
416 % it is safe to build \PerlTeX{} documents written by other people
417 % without worrying about what they may do to your computer system.
418 %
419 % A single sandbox is used for the entire |latex| run. This means that
420 % multiple macros defined by |\perlnewcommand| can invoke each other.
421 % It also means that global variables persist across macro calls:
422 %
423 % \bigskip
424 %
425 % \noindent| |^^A
426 % \begin{tabular}{@{}l@{}}
427 % |\perlnewcommand{\setX}[1]{$x = $_[0]; return ""}| \\
428 % |\perlnewcommand{\getX}{'$x$ was set to ' . $x . '.'}| \\
429 % |\setX{123}| \\
430 % |\getX| \\
431 % |\setX{456}| \\
432 % |\getX| \\
433 % |\perldo{$x = 789}| \\
434 % |\getX| \\[1ex]
435 % \multicolumn{1}{@{}c@{}}{\Huge$\Downarrow$} \\[2ex]
436 % \multicolumn{1}{@{}c@{}}{^^A
437 % $x$ was set to 123. $x$ was set to 456. $x$ was set to 789.^^A
438 % } \\
439 % \end{tabular}
440 %
441 % \bigskip
442 %
443 % Macro arguments are expanded by \LaTeX{} before being passed to Perl.
444 % Consider the following macro definition, which wraps its argument
445 % within |\begin{verbatim*}|\dots\linebreak[0]|\end{verbatim*}|:
446 %
447 % \begin{verbatim}
448 % \perlnewcommand{\verbit}[1]{
449 % "\\begin{verbatim*}\n$_[0]\n\\end{verbatim*}\n"
450 % }
451 % \end{verbatim}
452 %
453 % \noindent
454 % An invocation of
455 % ``|\verbit{\TeX}|'' would therefore typeset the \emph{expansion} of
456 % ``|\TeX|'', namely ``|T\kern| |-.1667em\lower| |.5ex\hbox| |{E}\kern|
457 % |-.125emX\spacefactor| |\@m|'', which might be a bit unexpected. The
458 % solution is to use |\noexpand|:
459 % |\verbit{\noexpand\TeX}|~$\Rightarrow$ |\TeX|\@. ``Robust'' macros as
460 % well as |\begin| and |\end| are implicitly preceded by |\noexpand|.
461 %
462 %
463 % \subsection{Making \perltex\ optional}
464 % \label{sec:perltex-opt}
465 %
466 % Normally, \perlmac\ issues a \texttt{Document must be compiled using
467 % perltex} error if a document specifies |\usepackage{perltex}| but is
468 % not compiled using \perltex. However, sometimes \PerlTeX\ may be
469 % needed merely to enhance a document's formatting without being
470 % mandatory for compiling the document. For such cases, the
471 % \DescribeOption{optional}
472 % \pkgoption{optional} package option instructs \perlmac\ only to note
473 % that \texttt{Document was compiled without using the perltex script}
474 % without aborting the compilation.
475 % \DescribeMacro{\ifperl}
476 % The author can then use the |\ifperl| macro to test if \perltex\ is
477 % being used and, if not, provide alternative definitions for macros and
478 % environments defined with |\perlnewcommand| and |\perlnewenvironment|.
479 %
480 % See Section~\ref{sec:complete-example} for a large \PerlTeX\ example
481 % that uses \pkgoption{optional} and |\ifperl| to define an environment
482 % one way if \perltex\ is detected and another way if not. The text
483 % preceding the example also shows how to enable a document to compile
484 % even if \perlmac\ is not even installed.
485 %
486 %
487 % \subsection{Invoking \perltex}
488 % \label{sec:perltex-man}
489 %
490 % The following pages reproduce the \perltex{} program documentation.
491 % Key parts of the documentation are excerpted when \perltex{} is
492 % invoked with the |--help| option. The various Perl
493 % |pod2|\meta{something} tools can be used to generate the complete
494 % program documentation in a variety of formats such as \LaTeX, HTML,
495 % plain text, or Unix man-page format. For example, the following
496 % command is the recommended way to produce a Unix man page from
497 % \perltex:
498 %
499 % \enlargethispage{4ex}
500 % \begin{verbatim}
501 % pod2man --center=" " --release=" " perltex.pl > perltex.1
502 % \end{verbatim}
503 %
504 % \clearpage
505 % \begingroup
506 % \def\index#1{}
507 % \def\section#1{}
508 % \let\subsection=\subsubsection
509 %
510 % ^^A ***************************************************************
511 % ^^A * The following was generated using pod2latex and touched up *
512 % ^^A * slightly to make it better match the rest of this document. *
513 % ^^A ***************************************************************
514 %
515 % \def\C++{{\rm C\kern-.05em\raise.3ex\hbox{\footnotesize ++}}}
516 % \def\underscore{\leavevmode\kern.04em\vbox{\hrule width 0.4em height 0.3pt}}
517 % \setlength{\parindent}{0pt}
518 %
519 % \section{PERLTEX.PL}%
520 % \index{PERLTEX.PL}
521 %
522 % \subsection*{NAME}
523 % perltex --- enable \LaTeX{} macros to be defined in terms of Perl code
524 %
525 % \subsection*{SYNOPSIS}
526 % perltex
527 % [\textbf{--help}]
528 % [\textbf{--latex}=\textit{program}]
529 % [\textbf{--}[\textbf{no}]\textbf{safe}]
530 % [\textbf{--permit}=\textit{feature}]
531 % [\textbf{--makesty}]
532 % [\textit{latex options}]
533 %
534 % \subsection*{DESCRIPTION}
535 % \LaTeX---through the underlying \TeX{} typesetting system---produces
536 % beautifully typeset documents but has a macro language that is
537 % difficult to program. In particular, support for complex string
538 % manipulation is largely lacking. Perl is a popular general-purpose
539 % programming language whose forte is string manipulation. However, it
540 % has no typesetting capabilities whatsoever.
541 %
542 % \bigskip
543 %
544 % Clearly, Perl's programmability could complement \LaTeX's typesetting
545 % strengths. \textbf{perltex} is the tool that enables a symbiosis
546 % between the two systems. All a user needs to do is compile a \LaTeX\
547 % document using \textbf{perltex} instead of \textbf{latex}.
548 % (\textbf{perltex} is actually a wrapper for \textbf{latex}, so no
549 % \textbf{latex} functionality is lost.) If the document includes a
550 % \texttt{\string\usepackage\{perltex\}} in its preamble, then
551 % \texttt{\string\perlnewcommand} and \texttt{\string\perlrenewcommand}
552 % macros will be made available. These behave just like \LaTeX's
553 % \texttt{\string\newcommand} and \texttt{\string\renewcommand} except
554 % that the macro body contains Perl code instead of \LaTeX\ code.
555 %
556 % \subsection*{OPTIONS}%
557 % \index{OPTIONS}
558 %
559 % {\bf perltex} accepts the following command-line options:
560 %
561 % \begin{description}
562 %
563 %
564 % \item[{\textbf{-{}-help}}] \mbox{}
565 %
566 % Display basic usage information.
567 %
568 %
569 % \item[{\textbf{-{}-latex}=\textit{program}}] \mbox{}
570 %
571 % Specify a program to use instead of \textbf{latex}. For example,
572 % \texttt{--latex=pdflatex} would typeset the given document using
573 % \textbf{pdflatex} instead of ordinary \textbf{latex}.
574 %
575 %
576 % \item[{\textbf{-{}-}[\textbf{no}]\textbf{safe}}] \mbox{}
577 %
578 % Enable or disable sandboxing. With the default of \textbf{-{}-safe},
579 % \textbf{perltex} executes the code from a
580 % \texttt{\string\perlnewcommand} or \texttt{\string\perlrenewcommand}
581 % macro within a protected environment that prohibits ``unsafe''
582 % operations such as accessing files or executing external programs.
583 % Specifying \textbf{-{}-nosafe} gives the \LaTeX\ document \textit{carte
584 % blanche} to execute any arbitrary Perl code, including that which can
585 % harm the user's files. See \emph{Safe} for more information.
586 %
587 % \item[{\textbf{-{}-permit}=\textit{feature}}] \mbox{}
588 %
589 % Permit particular Perl operations to be performed. The
590 % \textbf{-{}-permit} option, which can be specified more than once on
591 % the command line, enables finer-grained control over the
592 % \textbf{perltex} sandbox. See \emph{Opcode} for more information.
593 %
594 %
595 % \item[{\textbf{-{}-makesty}}] \mbox{}
596 %
597 % Generate a \LaTeX\ style file called \emph{noperltex.sty}. Replacing
598 % the document's \texttt{\string\usepackage\{perltex\}} line with
599 % \texttt{\string\usepackage\{noperltex\}} produces the same output
600 % but does not require \PerlTeX, making the document suitable for
601 % distribution to people who do not have \PerlTeX\ installed. The
602 % disadvantage is that \emph{noperltex.sty} is specific to the document
603 % that produced it. Any changes to the document's \PerlTeX\ macro
604 % definitions or macro invocations necessitates rerunning
605 % \textbf{perltex} with the \textbf{-{}-makesty} option.
606 %
607 % \end{description}
608 %
609 % These options are then followed by whatever options are normally
610 % passed to \textbf{latex} (or whatever program was specified with
611 % \texttt{--latex}), including, for instance, the name of the
612 % \emph{.tex} file to compile.
613 %
614 % \subsection*{EXAMPLES}
615 %
616 % In its simplest form, \textbf{perltex} is run just like \textbf{latex}:
617 %
618 % \begin{verbatim}
619 % perltex myfile.tex
620 % \end{verbatim}
621 %
622 %
623 % To use \textbf{pdflatex} instead of regular \textbf{latex}, use the
624 % \textbf{-{}-latex} option:
625 %
626 % \begin{verbatim}
627 % perltex --latex=pdflatex myfile.tex
628 % \end{verbatim}
629 %
630 %
631 % If \LaTeX\ gives a ``\texttt{trapped by operation mask}'' error and
632 % you trust the \emph{.tex} file you're trying to compile not to execute
633 % malicious Perl code (e.g., because you wrote it yourself), you can
634 % disable \textbf{perltex}'s safety mechansisms with
635 % \textbf{-{}-nosafe}:
636 %
637 % \begin{verbatim}
638 % perltex --nosafe myfile.tex
639 % \end{verbatim}
640 %
641 %
642 % The following command gives documents only \textbf{perltex}'s default
643 % permissions (\texttt{:browse}) plus the ability to open files and invoke the
644 % \texttt{time} command:
645 %
646 % \begin{verbatim}
647 % perltex --permit=:browse --permit=:filesys_open
648 % --permit=time myfile.tex
649 % \end{verbatim}
650 %
651 %
652 % \subsection*{ENVIRONMENT}
653 %
654 % \textbf{perltex} honors the following environment variables:
655 %
656 % \begin{description}
657 %
658 % \item[{PERLTEX}] \mbox{}
659 %
660 % Specify the filename of the \LaTeX\ compiler. The \LaTeX\ compiler
661 % defaults to ``\texttt{latex}''. The \texttt{PERLTEX} environment
662 % variable overrides this default, and the \textbf{-{}-latex}
663 % command-line option (see \textsf{OPTIONS}) overrides that.
664 %
665 % \end{description}
666 %
667 %
668 % \subsection*{FILES}
669 %
670 % While compiling \emph{jobname.tex}, \textbf{perltex} makes use of the
671 % following files:
672 %
673 % \begin{description}
674 %
675 % \item[{\emph{jobname.lgpl}}] \mbox{}
676 %
677 % log file written by Perl; helpful for debugging Perl macros
678 %
679 %
680 % \item[{\emph{jobname.topl}}] \mbox{}
681 %
682 % information sent from \LaTeX\ to Perl
683 %
684 %
685 % \item[{\emph{jobname.frpl}}] \mbox{}
686 %
687 % information sent from Perl to \LaTeX\
688 %
689 %
690 % \item[{\emph{jobname.tfpl}}] \mbox{}
691 %
692 % ``flag'' file whose existence indicates that \emph{jobname.topl} contains
693 % valid data
694 %
695 %
696 % \item[{\emph{jobname.ffpl}}] \mbox{}
697 %
698 % ``flag'' file whose existence indicates that \emph{jobname.frpl} contains
699 % valid data
700 %
701 %
702 % \item[{\emph{jobname.dfpl}}] \mbox{}
703 %
704 % ``flag'' file whose existence indicates that \emph{jobname.ffpl} has been
705 % deleted
706 %
707 %
708 % \item[{\emph{noperltex-\#.tex}}] \mbox{}
709 %
710 % file generated by \emph{noperltex.sty} for each \PerlTeX\ macro invocation
711 %
712 % \end{description}
713 %
714 %
715 % \subsection*{NOTES}
716 %
717 % \textbf{perltex}'s sandbox defaults to what \emph{Opcode} calls
718 % ``\texttt{:browse}''.
719 %
720 %
721 % \subsection*{SEE ALSO}
722 %
723 % latex(1), pdflatex(1), perl(1), Safe(3pm), Opcode(3pm)
724 %
725 %
726 % \subsection*{AUTHOR}
727 %
728 % Scott Pakin, \textit{[email protected]}
729 %
730 %
731 % ^^A ***********************************
732 % ^^A * End of generated pod2latex text *
733 % ^^A ***********************************
734 % \endgroup
735 % \clearpage
736 %
737 %
738 % \subsection{A large, complete example}
739 % \label{sec:complete-example}
740 %
741 % Suppose we want to define a |linkwords| environment that exhibits the
742 % following characteristics:
743 %
744 % \begin{enumerate}
745 % \item All words that appear within the environment's body are
746 % automatically hyperlinked to a given URL that incorporates the
747 % lowercase version of the word somewhere within that URL\@.
748 %
749 % \item The environment accepts an optional list of stop~words that
750 % should not be hyperlinked.
751 %
752 % \item Paragraph breaks, nested environments, and other
753 % \LaTeX\ markup are allowed within the environment's body.
754 % \end{enumerate}
755 %
756 % Because of the reliance on text manipulation (parsing the
757 % environment's body into words, comparing each word against the list of
758 % stop~words, distinguishing between text and \LaTeX\ markup, etc.),
759 % these requirements would be difficult to meet without \PerlTeX\@.
760 %
761 % We use three packages to help define the |linkwords| environment:
762 % \pkgname{perltex} for text manipulation, \pkgname{hyperref} for
763 % creating hyperlinks, and \pkgname{environ} for gathering up the body
764 % of an environment and passing it as an argument to a macro. Most of
765 % the work is performed by the \PerlTeX\ macro |\dolinkwords|, which
766 % takes three arguments: a URL template that contains ``|\%s|'' as a
767 % placeholder for a word from the text, a mandatory but possibly empty
768 % space-separated list of lowercase stop~words, and the input text to
769 % process. |\dolinkwords| first replaces all sequences of the form
770 % |\|\meta{letters}, |\begin{|\meta{letters}|}|, or
771 % |\end{|\meta{letters}|}| with dummy alphanumerics but remembers which
772 % dummy sequence corresponds with each original \LaTeX\ sequence. The
773 % macro then iterates over each word in the input text, formatting each
774 % non-stop-word using the URL template. Contractions (words containing
775 % apostrophes) are ignored. Finally, |\dolinkwords| replaces the dummy
776 % sequences with the corresponding \LaTeX\ text and returns the result.
777 %
778 % The |linkwords| environment itself is defined using the |\NewEnviron|
779 % macro from the \pkgname{environ} package. With |\NewEnviron|'s help,
780 % |linkwords| accumulates its body into a |\BODY| macro and passes that
781 % plus the URL template and the optional list of stop~words to
782 % |\dolinkwords|.
783 %
784 % As an added bonus,
785 % |\ifperl|\dots\linebreak[0]|\else|\dots\linebreak[0]|\fi| is used to
786 % surround the definition of the |\dolinkwords| macro and |linkwords|
787 % environment. If the document is not run through \perltex, |linkwords|
788 % is defined as a do-nothing environment that simply typesets its body
789 % as~is. Note that \perlmac\ is loaded with the \pkgoption{optional}
790 % option to indicate that the document can compile without \perltex.
791 % However, the user still needs \perlmac\ to avoid getting a
792 % \texttt{File `perltex.sty' not found} error from \LaTeX\@. To produce
793 % a document that can compile even without \perlmac\ installed, replace
794 % the |\usepackage[optional]{perltex}| line with the following
795 % \LaTeX\ code:
796 %
797 % \begin{samepage}
798 % \begin{verbatim}
799 % \IfFileExists{perltex.sty}
800 % {\usepackage[optional]{perltex}}
801 % {\newif\ifperl}
802 % \end{verbatim}
803 % \end{samepage}
804 %
805 % A complete \LaTeX\ document is presented below. This document, which
806 % includes the definition and a use of the |linkwords| environment, can be
807 % extracted from the \PerlTeX\ source code into a file called
808 % |example.tex| by running
809 %
810 % \begin{verbatim}
811 % tex perltex.ins
812 % \end{verbatim}
813 %
814 % In the following listing, line numbers are suffixed with ``X'' to
815 % distinguish them from line numbers associated with \PerlTeX's source
816 % code.
817 %
818 % \bigskip
819 %
820 % ^^A We want the doc package to number and index the lines in our
821 % ^^A code listing, but we want to keep line numbers and index entries
822 % ^^A distinct from those of the PerlTeX package code. The following
823 % ^^A machinations temporarily append an "X" to line numbers in the
824 % ^^A code listing and in the index.
825 % \makeatletter
826 % \let\theOldCodelineNo=\theCodelineNo
827 % \def\theCodelineNo{\reset@font\scriptsize \arabic{CodelineNo}X}
828 % \def\appendX#1{#1X}
829 % \def\codeline@wrindex@ex#1{\if@filesw
830 % \immediate\write\@indexfile
831 % {\string\indexentry{#1\encapchar appendX}^^A
832 % {\number\c@CodelineNo}}\fi}
833 % \ifcodeline@index
834 % \let\special@index=\codeline@wrindex@ex
835 % \fi
836 % \makeatother
837 % \iffalse
838 %<*example>
839 % \fi
840 %
841 % \begin{macrocode}
842 \documentclass{article}
843 \usepackage[optional]{perltex}
844 \usepackage{environ}
845 \usepackage{hyperref}
846
847 \ifperl
848
849 \perlnewcommand{\dolinkwords}[3]{
850 # Preprocess our arguments.
851 $url = $_[0];
852 $url =~ s/\\\%s/\%s/g;
853 %stopwords = map {lc $_ => 1} split " ", $_[1];
854 $stopwords{""} = 1;
855 $text = $_[2];
856
857 # Replace LaTeX code in the text with placeholders.
858 $placeholder = "ABCxyz123";
859 %substs = ();
860 $replace = sub {$substs{$placeholder} = $_[0]; $placeholder++};
861 $text =~ s/\\(begin|end)\s+\{[a-z]+\}/$replace->($&)/gse;
862 $text =~ s/\\[a-z]+/$replace->($&)/gse;
863
864 # Hyperlink each word that's not in the stop list.
865 $newtext = "";
866 foreach $word (split /((?<=[-\A\s])[\'a-z]+\b)/i, $text) {
867 $lcword = lc $word;
868 if (defined $stopwords{$lcword} || $lcword =~ /[^a-z]/) {
869 $newtext .= $word;
870 }
871 else {
872 $newtext .= sprintf "\\href{$url}{%s}", $lcword, $word;
873 }
874 }
875
876 # Restore original text from placeholders and return the new text.
877 while (($tag, $orig) = each %substs) {
878 $newtext =~ s/\Q$tag\E/$orig/gs;
879 }
880 return $newtext;
881 }
882
883 \NewEnviron{linkwords}[2][]{\dolinkwords{#2}{#1}{\BODY}}{}
884
885 \else
886
887 \newenvironment{linkwords}[2][]{}{}
888
889 \fi
890
891 \begin{document}
892
893 \newcommand{\stopwords}{a an the of in am and or but i we me you us them}
894
895 \begin{linkwords}[\stopwords]{http://www.google.com/search?q=define:\%s}
896 \begin{verse}
897 I'm very good at integral and differential calculus; \\
898 I know the scientific names of beings animalculous: \\
899 In short, in matters vegetable, animal, and mineral, \\
900 I am the very model of a modern Major-General.
901 \end{verse}
902 \end{linkwords}
903
904 \end{document}
905 % \end{macrocode}
906 %
907 % \iffalse
908 %</example>
909 % \fi
910 % \makeatletter
911 % \ifcodeline@index
912 % \let\special@index=\codeline@wrindex
913 % \fi
914 % \let\theCodelineNo=\theOldCodelineNo
915 % \makeatother
916 %
917 %
918 % \StopEventually{^^A
919 % \section{License agreement}
920 % \label{sec:license}
921 %
922 % Copyright \textcopyright{} 2003--2024 Scott Pakin \texttt{<[email protected]>}
923 %
924 % \providecommand{\url}[1]{\texttt{##1}}
925 %
926 % \bigskip
927 % \noindent
928 % These files may be distributed and/or modified under the conditions of
929 % the \LaTeX{} Project Public License, either version~1.3c of this
930 % license or (at your option) any later version. The latest version of
931 % this license is in \url{http://www.latex-project.org/lppl.txt} and
932 % version~1.3c or later is part of all distributions of \LaTeX{} version
933 % 2006/05/20 or later.
934 %
935 %
936 % \section*{Acknowledgments}
937 % \label{sec:acknowledgments}
938 %
939 % Thanks to Andrew Mertz for writing the first draft of the code that
940 % produces the \PerlTeX-free \noperlmac\ style file and for testing the
941 % final draft; to Andrei Alexandrescu for providing a few bug fixes; to
942 % Nick Andrewes for identifying and helping diagnose a problem running
943 % \PerlTeX\ with \XeTeX\ and to Jonathan Kew for suggesting a
944 % workaround; to Linus K\"allberg for reporting and helping diagnose
945 % some problems with running \PerlTeX\ on Windows; and to Ulrike Fischer
946 % for reporting and helping correct a bug encountered when using
947 % \noperlmac\ with newer versions of \LaTeX\@. Also, thanks to the many
948 % people who have sent me fan mail or submitted bug reports,
949 % documentation corrections, or feature requests. (The
950 % \texttt{\string\perldo} macro and the \texttt{--makesty} option were
951 % particularly popular requests.)
952 %
953 % \PrintChanges
954 % \PrintIndex
955 % }
956 %
957 % \section{Implementation}
958 % \label{sec:implementation}
959 %
960 % Users interested only in \emph{using} \PerlTeX{} can skip
961 % Section~\ref{sec:implementation}, which presents the complete
962 % \PerlTeX{} source code. This section should be of interest primarily
963 % to those who wish to extend \PerlTeX{} or modify it to use a language
964 % other than Perl.
965 %
966 % Section~\ref{sec:implementation} is split into two main parts.
967 % Section~\ref{sec:perlmacros} presents the source code for \perlmac,
968 % the \LaTeX{} side of \PerlTeX, and Section~\ref{sec:perltex} presents
969 % the source code for \perltex, the Perl side of \PerlTeX\@.
970 % \makeatletter
971 % \@ifundefined{perlmaclines}{}{^^A
972 % \newcount\perltex@lines
973 % \perltex@lines=\perltexlines
974 % \advance\perltex@lines by -\perlmaclines
975 % In toto, \PerlTeX{} consists of a relatively small amount of code.
976 % \perlmac{} is only \perlmaclines{} lines of \LaTeX{} and \perltex{}
977 % is only \the\perltex@lines{} lines of Perl.
978 % }
979 % \makeatother
980 % \perltex{} is fairly straightforward Perl code and shouldn't be too
981 % difficult to understand by anyone comfortable with Perl programming.
982 % \perlmac, in contrast, contains a bit of \LaTeX{} trickery and is
983 % probably impenetrable to anyone who hasn't already tried his hand at
984 % \LaTeX{} programming. Fortunately for the reader, the code is
985 % profusely commented so the aspiring \LaTeX{} guru may yet learn
986 % something from it.
987 %
988 % After documenting the \perlmac{} and \perltex{} source code, a few
989 % suggestions are provided for porting \PerlTeX{} to use a backend
990 % language other than Perl (Section~\ref{sec:porting}).
991 %
992 % \subsection{\perlmac}
993 % \label{sec:perlmacros}
994 %
995 % \iffalse
996 %<*package>
997 % \fi
998 %
999 % Although I've written a number of \LaTeX{} packages, \perlmac{} was
1000 % the most challenging to date. The key things I needed to learn how to
1001 % do include the following:
1002 %
1003 % \begin{enumerate}
1004 % \item storing brace-matched---but otherwise not valid \LaTeX---code
1005 % for later use
1006 %
1007 % \item iterating over a macro's arguments
1008 % \end{enumerate}
1009 %
1010 % Storing non-\LaTeX{} code in a variable involves beginning a group in
1011 % an argumentless macro, fiddling with category codes, using
1012 % |\afterassignment| to specify a continuation function, and storing the
1013 % subsequent brace-delimited tokens in the input stream into a token
1014 % register. The continuation function, which also takes no arguments,
1015 % ends the group begun in the first function and proceeds using the
1016 % correctly |\catcode|d token register. This technique appears in
1017 % |\plmac@haveargs| and |\plmac@havecode| and in a simpler form
1018 % (i.e.,~without the need for storing the argument) in
1019 % |\plmac@write@perl| and |\plmac@write@perl@i|.
1020 %
1021 % Iterating over a macro's arguments is hindered by \TeX's requirement
1022 % that ``|#|'' be followed by a number or another ``|#|''. The
1023 % technique I discovered (which is used by the Texinfo source code) is
1024 % first to |\let| a variable be |\relax|, thereby making it
1025 % unexpandable, then to define a macro that uses that variable followed
1026 % by a loop variable, and finally to expand the loop variable and |\let|
1027 % the |\relax|ed variable be ``|#|'' right before invoking the macro.
1028 % This technique appears in |\plmac@havecode|.
1029 %
1030 % I hope you find reading the \perlmac{} source code instructive.
1031 % Writing it certainly was.
1032 %
1033 %
1034 % \subsubsection{Package initialization}
1035 % \label{sec:package-init}
1036 %
1037 % \begin{macro}{\ifplmac@required}
1038 % \begin{macro}{\plmac@requiredtrue}
1039 % \begin{macro}{\plmac@requiredfalse}
1040 % The |optional| package option lets an author specify that the document
1041 % can be built successfully even without \PerlTeX\@. Typically, this
1042 % means that the document uses |\ifperl| to help define
1043 % reduced-functionality equivalents of any document-defined
1044 % \PerlTeX\ macros and environments. When |optional| is not specified,
1045 % \perlmac\ issues an error message if the document is compiled without
1046 % using \perltex. When |optional| is specified, \perlmac\ suppresses
1047 % the error message.
1048 % \changes{v1.8}{2009/03/26}{Introduced an \texttt{optional} package
1049 % option to suppress the ``must be compiled using perltex'' error
1050 % message}
1051 % \begin{macrocode}
1052 \newif\ifplmac@required
1053 \plmac@requiredtrue
1054 \DeclareOption{optional}{\plmac@requiredfalse}
1055 \ProcessOptions\relax
1056 % \end{macrocode}
1057 % \end{macro}
1058 % \end{macro}
1059 % \end{macro}
1060 %
1061 % \PerlTeX{} defines six macros that are used for communication between
1062 % Perl and \LaTeX\@. |\plmac@tag| is a string of characters that should
1063 % never occur within one of the user's macro names, macro arguments, or
1064 % macro bodies. \perltex{} therefore defines |\plmac@tag| as a long
1065 % string of random uppercase letters. |\plmac@tofile| is the name of a
1066 % file used for communication from \LaTeX{} to Perl. |\plmac@fromfile|
1067 % is the name of a file used for communication from Perl to \LaTeX.
1068 % |\plmac@toflag| signals that |\plmac@tofile| can be read safely.
1069 % |\plmac@fromflag| signals that |\plmac@fromfile| can be read safely.
1070 % |\plmac@doneflag| signals that |\plmac@fromflag| has been deleted.
1071 % Table~\ref{tbl:variables} lists all of these variables along with the
1072 % value assigned to each by \perltex.
1073 %
1074 % \begin{table}[htbp]
1075 % \centering
1076 % \caption{Variables used for communication between Perl and \LaTeX}
1077 % \label{tbl:variables}
1078 % \begin{tabular}{@{}lll@{}}
1079 % \hline
1080 % Variable & Purpose & \perltex{} assignment \\
1081 % \hline
1082 %
1083 % |\plmac@tag| & |\plmac@tofile| field separator &
1084 % (20 random letters) \\
1085 %
1086 % |\plmac@tofile| & \LaTeX{} $\rightarrow$ Perl communication &
1087 % |\jobname.topl| \\
1088 %
1089 % |\plmac@fromfile| & Perl $\rightarrow$ \LaTeX{} communication &
1090 % |\jobname.frpl| \\
1091 %
1092 % |\plmac@toflag| & |\plmac@tofile| synchronization &
1093 % |\jobname.tfpl| \\
1094 %
1095 % |\plmac@fromflag| & |\plmac@fromfile| synchronization &
1096 % |\jobname.ffpl| \\
1097 %
1098 % |\plmac@doneflag| & |\plmac@fromflag| synchronization &
1099 % |\jobname.dfpl| \\
1100 %
1101 % \hline
1102 % \end{tabular}
1103 % \end{table}
1104 %
1105 % \begin{macro}{\ifperl}
1106 % \begin{macro}{\perltrue}
1107 % \begin{macro}{\perlfalse}
1108 % The following block of code checks the existence of each of the
1109 % variables listed in Table~\ref{tbl:variables} plus |\plmac@pipe|, a
1110 % Unix named pipe used for to improve performance. If any variable is
1111 % not defined, \perlmac{} gives an error message and---as we shall see
1112 % on page~\pageref{page:define-dummies}---defines dummy versions of
1113 % |\perl|[|re|]|newcommand| and |\perl|[|re|]|newenvironment|.
1114 % \changes{v2.2}{2019/09/14}{Let-bind \cs{plmac@tag} to \cs{relax} if
1115 % \cs{plmac@tag} is undefined. This corrects a problem when
1116 % \noexpand\texttt{noperltex} is used with newer versions of
1117 % \noexpand\LaTeX}
1118 % \begin{macrocode}
1119 \newif\ifperl
1120 \perltrue
1121 \@ifundefined{plmac@tag}{\perlfalse\let\plmac@tag=\relax}{}
1122 \@ifundefined{plmac@tofile}{\perlfalse}{}
1123 \@ifundefined{plmac@fromfile}{\perlfalse}{}
1124 \@ifundefined{plmac@toflag}{\perlfalse}{}
1125 \@ifundefined{plmac@fromflag}{\perlfalse}{}
1126 \@ifundefined{plmac@doneflag}{\perlfalse}{}
1127 \@ifundefined{plmac@pipe}{\perlfalse}{}
1128 \ifperl
1129 \else
1130 \ifplmac@required
1131 \PackageError{perltex}{Document must be compiled using perltex}
1132 {Instead of compiling your document directly with latex, you need
1133 to\MessageBreak use the perltex script. \space perltex sets up
1134 a variety of macros needed by\MessageBreak the perltex
1135 package as well as a listener process needed for\MessageBreak
1136 communication between LaTeX and Perl.}
1137 \else
1138 \bgroup
1139 \obeyspaces
1140 \typeout{perltex: Document was compiled without using the perltex script;}
1141 \typeout{ it may not print as desired.}
1142 \egroup
1143 \fi
1144 \fi
1145 % \end{macrocode}
1146 % \end{macro}
1147 % \end{macro}
1148 % \end{macro}
1149 %
1150 % \subsubsection{Defining Perl macros}
1151 % \label{sec:perl-mac}
1152 %
1153 % \PerlTeX{} defines five macros intended to be called by the author.
1154 % Section~\ref{sec:perl-mac} details the implementation of two of them:
1155 % |\perlnewcommand| and |\perlrenewcommand|.
1156 % (Section~\ref{sec:perl-env} details the implementation of the next
1157 % two, |\perlnewenvironment| and |\perlrenewenvironment|; and,
1158 % Section~\ref{sec:perl-run} details the implementation of the final
1159 % macro, |\perldo|.) The goal is for these two macros to behave
1160 % \emph{exactly} like |\newcommand| and |\renewcommand|, respectively,
1161 % except that the author macros they in turn define have Perl bodies
1162 % instead of \LaTeX{} bodies.
1163 %
1164 % The sequence of the operations defined in this section is as follows:
1165 %
1166 % \begin{enumerate}
1167 % \item The user invokes |\perl|[|re|]|newcommand|, which stores
1168 % |\|[|re|]|newcommand| in |\plmac@command|. The
1169 % |\perl|[|re|]|newcommand| macro then invokes |\plmac@newcommand@i|
1170 % with a first argument of ``|*|'' for |\perl|[|re|]|newcommand*| or
1171 % ``|!|'' for ordinary |\perl|[|re|]|newcommand|.
1172 %
1173 % \item |\plmac@newcommand@i| defines |\plmac@starchar| as ``|*|'' if
1174 % it was passed a ``|*|'' or \meta{empty} if it was passed a ``|!|''.
1175 % It then stores the name of the user's macro in |\plmac@macname|, a
1176 % |\write|able version of the name in |\plmac@cleaned@macname|, and
1177 % the macro's previous definition (needed by |\perlrenewcommand|) in
1178 % |\plmac@oldbody|. Finally, |\plmac@newcommand@i| invokes
1179 % |\plmac@newcommand@ii|.
1180 %
1181 % \item |\plmac@newcommand@ii| stores the number of arguments to the
1182 % user's macro (which may be zero) in |\plmac@numargs|. It then
1183 % invokes |\plmac@newcommand@iii@opt| if the first argument is
1184 % supposed to be optional or |\plmac@newcommand@iii@no@opt| if all
1185 % arguments are supposed to be required.
1186 %
1187 % \item |\plmac@newcommand@iii@opt| defines |\plmac@defarg| as the
1188 % default value of the optional argument.
1189 % |\plmac@newcommand@iii@no@opt| defines it as \meta{empty}. Both
1190 % functions then call |\plmac@haveargs|.
1191 %
1192 % \item |\plmac@haveargs| stores the user's macro body (written in
1193 % Perl) verbatim in |\plmac@perlcode|. |\plmac@haveargs| then invokes
1194 % |\plmac@havecode|.
1195 %
1196 % \item By the time |\plmac@havecode| is invoked all of the
1197 % information needed to define the user's macro is available. Before
1198 % defining a \LaTeX{} macro, however, |\plmac@havecode| invokes
1199 % |\plmac@write@perl| to tell \perltex{} to define a Perl subroutine
1200 % with a name based on |\plmac@cleaned@macname| and the code contained
1201 % in |\plmac@perlcode|. Figure~\ref{fig:tofile-define} illustrates
1202 % the data that |\plmac@write@perl| passes to \perltex.
1203 %
1204 % \begin{figure}[htbp]
1205 % \centering
1206 % \DeleteShortVerb\|
1207 % \begin{tabular}{|l|}
1208 % \hline
1209 % \verb|DEF| \\ \hline
1210 % \verb|\plmac@tag| \\ \hline
1211 % \verb|\plmac@cleaned@macname| \\ \hline
1212 % \verb|\plmac@tag| \\ \hline
1213 % \verb|\plmac@perlcode| \\ \hline
1214 % \end{tabular}
1215 % \MakeShortVerb\|
1216 % \caption{Data written to \texttt{\string\plmac@tofile} to define a
1217 % Perl subroutine}
1218 % \label{fig:tofile-define}
1219 % \end{figure}
1220 %
1221 % \item |\plmac@havecode| invokes |\newcommand| or |\renewcommand|, as
1222 % appropriate, defining the user's macro as a call to
1223 % |\plmac@write@perl|. An invocation of the user's \LaTeX{} macro
1224 % causes |\plmac@write@perl| to pass the information shown in
1225 % Figure~\ref{fig:tofile-use} to \perltex.
1226 %
1227 % \begin{figure}[htbp]
1228 % \centering
1229 % \DeleteShortVerb\|
1230 % \begin{tabular}{|l|}
1231 % \hline
1232 % \verb|USE| \\ \hline
1233 % \verb|\plmac@tag| \\ \hline
1234 % \verb|\plmac@cleaned@macname| \\ \hline
1235 % \verb|\plmac@tag| \\ \hline
1236 % \verb|#1| \\ \hline
1237 % \verb|\plmac@tag| \\ \hline
1238 % \verb|#2| \\ \hline
1239 % \verb|\plmac@tag| \\ \hline
1240 % \verb|#3| \\ \hline
1241 % \multicolumn{1}{c}{$\vdots$} \\ \hline
1242 % \verb|#|\meta{last} \\ \hline
1243 % \end{tabular}
1244 % \MakeShortVerb\|
1245 % \caption{Data written to \texttt{\string\plmac@tofile} to invoke a
1246 % Perl subroutine}
1247 % \label{fig:tofile-use}
1248 % \end{figure}
1249 %
1250 % \item Whenever |\plmac@write@perl| is invoked it writes its argument
1251 % verbatim to |\plmac@tofile|; \perltex{} evaluates the code and
1252 % writes |\plmac@fromfile|; finally, |\plmac@write@perl| |\input|s
1253 % |\plmac@fromfile|.
1254 % \end{enumerate}
1255 %
1256 % An example might help distinguish the myriad macros used internally by
1257 % \perlmac. Consider the following call made by the user's
1258 % document:\label{text:example-cmd}
1259 %
1260 % \begin{center}
1261 % |\perlnewcommand*{\example}[3][frobozz]{join("---", @_)}|
1262 % \end{center}
1263 %
1264 % \noindent
1265 % Table~\ref{tbl:example-cmd} shows how \perlmac{} parses that command
1266 % into its constituent components and which components are bound to
1267 % which \perlmac{} macros.
1268 %
1269 % \begin{table}[htbp]
1270 % \centering
1271 % \caption{Macro assignments corresponding to an sample
1272 % \texttt{\string\perlnewcommand*}}
1273 % \label{tbl:example-cmd}
1274 % \begin{tabular}{@{}lll@{}}
1275 % \hline
1276 % Macro & \multicolumn{2}{l@{}}{Sample definition} \\
1277 % \hline
1278 % |\plmac@command| & |\newcommand| \\
1279 % |\plmac@starchar| & |*| \\
1280 % |\plmac@macname| & |\example| \\
1281 % |\plmac@cleaned@macname| & |\example| & (catcode~11) \\
1282 % |\plmac@oldbody| & |\relax| & (presumably) \\
1283 % |\plmac@numargs| & |3| \\
1284 % |\plmac@defarg| & |frobozz| \\
1285 % |\plmac@perlcode| & |join("---", @_)| & (catcode~11) \\
1286 % \hline
1287 % \end{tabular}
1288 % \end{table}
1289 %
1290 % \bigskip
1291 %
1292 % \begin{macro}{\perlnewcommand}
1293 % \begin{macro}{\perlrenewcommand}
1294 % \begin{macro}{\plmac@command}
1295 % \begin{macro}{\plmac@next}
1296 % |\perlnewcommand| and |\perlrenewcommand| are the first two commands
1297 % exported to the user by \perlmac. |\perlnewcommand| is analogous to
1298 % |\newcommand| except that the macro body consists of Perl code instead
1299 % of \LaTeX{} code. Likewise, |\perlrenewcommand| is analogous to
1300 % |\renewcommand| except that the macro body consists of Perl code
1301 % instead of \LaTeX{} code. |\perlnewcommand| and |\perlrenewcommand|
1302 % merely define |\plmac@command| and |\plmac@next| and invoke
1303 % |\plmac@newcommand@i|.
1304 % \begin{macrocode}
1305 \def\perlnewcommand{%
1306 \let\plmac@command=\newcommand
1307 \let\plmac@next=\relax
1308 \@ifnextchar*{\plmac@newcommand@i}{\plmac@newcommand@i!}%
1309 }
1310 % \end{macrocode}
1311 % \begin{macrocode}
1312 \def\perlrenewcommand{%
1313 \let\plmac@next=\relax
1314 \let\plmac@command=\renewcommand
1315 \@ifnextchar*{\plmac@newcommand@i}{\plmac@newcommand@i!}%
1316 }
1317 % \end{macrocode}
1318 % \end{macro}
1319 % \end{macro}
1320 % \end{macro}
1321 % \end{macro}
1322 %
1323 % \begin{macro}{\plmac@newcommand@i}
1324 % \begin{macro}{\plmac@starchar}
1325 % \begin{macro}{\plmac@macname}
1326 % \begin{macro}{\plmac@oldbody}
1327 % \begin{macro}{\plmac@cleaned@macname}
1328 % If\label{page:newcommand-i} the user invoked
1329 % |\perl|[|re|]|newcommand*| then |\plmac@newcommand@i| is passed a
1330 % ``|*|'' and, in turn, defines |\plmac@starchar| as ``|*|''. If the
1331 % user invoked |\perl|[|re|]|newcommand| (no ``|*|'') then
1332 % |\plmac@newcommand@i| is passed a ``|!|'' and, in turn, defines
1333 % |\plmac@starchar| as \meta{empty}. In either case,
1334 % |\plmac@newcommand@i| defines |\plmac@macname| as the name of the
1335 % user's macro, |\plmac@cleaned@macname| as a |\write|able
1336 % (i.e.,~category code~11) version of |\plmac@macname|, and
1337 % |\plmac@oldbody| and the previous definition of the user's macro.
1338 % (|\plmac@oldbody| is needed by |\perlrenewcommand|.) It then invokes
1339 % |\plmac@newcommand@ii|.
1340 % \begin{macrocode}
1341 \def\plmac@newcommand@i#1#2{%
1342 \ifx#1*%
1343 \def\plmac@starchar{*}%
1344 \else
1345 \def\plmac@starchar{}%
1346 \fi
1347 \def\plmac@macname{#2}%
1348 \let\plmac@oldbody=#2\relax
1349 \expandafter\def\expandafter\plmac@cleaned@macname\expandafter{%
1350 \expandafter\string\plmac@macname}%
1351 \@ifnextchar[{\plmac@newcommand@ii}{\plmac@newcommand@ii[0]}%]
1352 }
1353 % \end{macrocode}
1354 % \end{macro}
1355 % \end{macro}
1356 % \end{macro}
1357 % \end{macro}
1358 % \end{macro}
1359 %
1360 % \begin{macro}{\plmac@newcommand@ii}
1361 % \begin{macro}{\plmac@numargs}
1362 % |\plmac@newcommand@i| invokes |\plmac@newcommand@ii| with the number
1363 % of arguments to the user's macro in brackets. |\plmac@newcommand@ii|
1364 % stores that number in |\plmac@numargs| and invokes
1365 % |\plmac@newcommand@iii@opt| if the first argument is to be optional or
1366 % |\plmac@newcommand@iii@no@opt| if all arguments are to be mandatory.
1367 % \begin{macrocode}
1368 \def\plmac@newcommand@ii[#1]{%
1369 \def\plmac@numargs{#1}%
1370 \@ifnextchar[{\plmac@newcommand@iii@opt}
1371 {\plmac@newcommand@iii@no@opt}%]
1372 }
1373 % \end{macrocode}
1374 % \end{macro}
1375 % \end{macro}
1376 %
1377 % \begin{macro}{\plmac@newcommand@iii@opt}
1378 % \begin{macro}{\plmac@newcommand@iii@no@opt}
1379 % \begin{macro}{\plmac@defarg}
1380 % Only one of these two macros is executed per invocation of
1381 % |\perl|[|re|]|newcommand|, depending on whether or not the first
1382 % argument of the user's macro is an optional argument.
1383 % |\plmac@newcommand@iii@opt| is invoked if the argument is optional.
1384 % It defines |\plmac@defarg| to the default value of the optional
1385 % argument. |\plmac@newcommand@iii@no@opt| is invoked if all arguments
1386 % are mandatory. It defines |\plmac@defarg| as |\relax|. Both
1387 % |\plmac@newcommand@iii@opt| and |\plmac@newcommand@iii@no@opt| then
1388 % invoke |\plmac@haveargs|.
1389 % \begin{macrocode}
1390 \def\plmac@newcommand@iii@opt[#1]{%
1391 \def\plmac@defarg{#1}%
1392 \plmac@haveargs
1393 }
1394 % \end{macrocode}
1395 % \begin{macrocode}
1396 \def\plmac@newcommand@iii@no@opt{%
1397 \let\plmac@defarg=\relax
1398 \plmac@haveargs
1399 }
1400 % \end{macrocode}
1401 % \end{macro}
1402 % \end{macro}
1403 % \end{macro}
1404 %
1405 % \begin{macro}{\plmac@perlcode}
1406 % \begin{macro}{\plmac@haveargs}
1407 % Now things start to get tricky. We have all of the arguments we need
1408 % to define the user's command so all that's left is to grab the macro
1409 % body. But there's a catch: Valid Perl code is unlikely to be valid
1410 % \LaTeX{} code. We therefore have to read the macro body in a
1411 % |\verb|-like mode. Furthermore, we actually need to \emph{store} the
1412 % macro body in a variable, as we don't need it right away.
1413 %
1414 % The approach we take in |\plmac@haveargs| is as follows. First, we
1415 % give all ``special'' characters category code~12 (``other''). We then
1416 % indicate that the carriage return character (control-M) marks the end
1417 % of a line and that curly braces retain their normal meaning. With the
1418 % aforementioned category-code definitions, we now have to store the
1419 % next curly-brace-delimited fragment of text, end the current group to
1420 % reset all category codes to their previous value, and continue
1421 % processing the user's macro definition. How do we do that? The
1422 % answer is to assign the upcoming text fragment to a token register
1423 % (|\plmac@perlcode|) while an |\afterassignment| is in effect. The
1424 % |\afterassignment| causes control to transfer to |\plmac@havecode|
1425 % right after |\plmac@perlcode| receives the macro body with all of the
1426 % ``special'' characters made impotent.
1427 % \begin{macrocode}
1428 \newtoks\plmac@perlcode
1429 % \end{macrocode}
1430 % \begin{macrocode}
1431 \def\plmac@haveargs{%
1432 \begingroup
1433 \let\do\@makeother\dospecials
1434 \catcode`\^^M=\active
1435 \newlinechar`\^^M
1436 \endlinechar=`\^^M
1437 \catcode`\{=1
1438 \catcode`\}=2
1439 \afterassignment\plmac@havecode
1440 \global\plmac@perlcode
1441 }
1442 % \end{macrocode}
1443 % \end{macro}
1444 % \end{macro}
1445 %
1446 % Control is transfered to |\plmac@havecode| from |\plmac@haveargs|
1447 % right after the user's macro body is assigned to |\plmac@perlcode|.
1448 % We now have everything we need to define the user's macro. The goal
1449 % is to define it as ``|\plmac@write@perl{|\meta{contents of
1450 % Figure~\ref{fig:tofile-use}}|}|''. This is easier said than done
1451 % because the number of arguments in the user's macro is not known
1452 % statically, yet we need to iterate over however many arguments there
1453 % are. Because of this complexity, we will explain |\plmac@perlcode|
1454 % piece-by-piece.
1455 %
1456 % \begin{macro}{\plmac@sep}
1457 % Define a character to separate each of the items presented in
1458 % Figures~\ref{fig:tofile-define} and~\ref{fig:tofile-use}. Perl will
1459 % need to strip this off each argument. For convenience in porting to
1460 % languages with less powerful string manipulation than Perl's, we
1461 % define |\plmac@sep| as a carriage-return character of category code~11
1462 % (``letter'').
1463 % \begin{macrocode}
1464 {\catcode`\^^M=11\gdef\plmac@sep{^^M}}
1465 % \end{macrocode}
1466 % \end{macro}
1467 %
1468 % \begin{macro}{\plmac@argnum}
1469 % Define a loop variable that will iterate from |1| to the number of
1470 % arguments in the user's function, i.e.,~|\plmac@numargs|.
1471 % \begin{macrocode}
1472 \newcount\plmac@argnum
1473 % \end{macrocode}
1474 % \end{macro}
1475 %
1476 % \begin{macro}{\plmac@havecode}
1477 % Now comes the final piece of what started as a call to
1478 % |\perl|[|re|]|newcommand|. First, to reset all category codes back to
1479 % normal, |\plmac@havecode| ends the group that was begun in
1480 % |\plmac@haveargs|.
1481 % \changes{v1.1}{2004/02/24}{Added a \texttt{\string\string\string\plmac@next}
1482 % hook to support \PerlTeX's new environment-defining macros}
1483 % \begin{macrocode}
1484 \def\plmac@havecode{%
1485 \endgroup
1486 % \end{macrocode}
1487 %
1488 % \begin{macro}{\plmac@define@sub}
1489 % We invoke |\plmac@write@perl| to define a Perl subroutine named after
1490 % |\plmac@cleaned@macname|. |\plmac@define@sub| sends Perl the
1491 % information shown in Figure~\vref{fig:tofile-define}.
1492 % \begin{macrocode}
1493 \edef\plmac@define@sub{%
1494 \noexpand\plmac@write@perl{DEF\plmac@sep
1495 \plmac@tag\plmac@sep
1496 \plmac@cleaned@macname\plmac@sep
1497 \plmac@tag\plmac@sep
1498 \the\plmac@perlcode
1499 }%
1500 }%
1501 \plmac@define@sub
1502 % \end{macrocode}
1503 % \end{macro}
1504 %
1505 % \begin{macro}{\plmac@body}
1506 % The rest of |\plmac@havecode| is preparation for defining the user's
1507 % macro. (\LaTeXe's |\newcommand| or |\renewcommand| will do the actual
1508 % work, though.) |\plmac@body| will eventually contain the complete
1509 % (\LaTeX) body of the user's macro. Here, we initialize it to the
1510 % first three items listed in Figure~\vref{fig:tofile-use} (with
1511 % intervening |\plmac@sep|s).
1512 % \begin{macrocode}
1513 \edef\plmac@body{%
1514 USE\plmac@sep
1515 \plmac@tag\plmac@sep
1516 \plmac@cleaned@macname
1517 }%
1518 % \end{macrocode}
1519 %
1520 % \begin{macro}{\plmac@hash}
1521 % Now, for each argument |#1|, |#2|,~\dots, |#\plmac@numargs| we append
1522 % a |\plmac@tag| plus the argument to |\plmac@body| (as always, with a
1523 % |\plmac@sep| after each item). This requires more trickery, as \TeX{}
1524 % requires a macro-parameter character (``|#|'') to be followed by a
1525 % literal number, not a variable. The approach we take, which I first
1526 % discovered in the Texinfo source code (although it's used by \LaTeX{}
1527 % and probably other \TeX-based systems as well), is to |\let|-bind
1528 % |\plmac@hash| to |\relax|. This makes |\plmac@hash| unexpandable, and
1529 % because it's not a ``|#|'', \TeX{} doesn't complain. After
1530 % |\plmac@body| has been extended to include |\plmac@hash1|,
1531 % |\plmac@hash2|,~\dots, |\plmac@hash\plmac@numargs|, we then
1532 % |\let|-bind |\plmac@hash| to |##|, which \TeX{} lets us do because
1533 % we're within a macro definition (|\plmac@havecode|). |\plmac@body|
1534 % will then contain |#1|, |#2|,~\dots, |#\plmac@numargs|, as desired.
1535 % \begin{macrocode}
1536 \let\plmac@hash=\relax
1537 \plmac@argnum=\@ne
1538 \loop
1539 \ifnum\plmac@numargs<\plmac@argnum
1540 \else
1541 \edef\plmac@body{%
1542 \plmac@body\plmac@sep\plmac@tag\plmac@sep
1543 \plmac@hash\plmac@hash\number\plmac@argnum}%
1544 \advance\plmac@argnum by \@ne
1545 \repeat
1546 \let\plmac@hash=##%
1547 % \end{macrocode}
1548 %
1549 % \begin{macro}{\plmac@define@command}
1550 % We're ready to execute a |\|[|re|]|newcommand|. Because we need to
1551 % expand many of our variables, we |\edef| |\plmac@define@command| to
1552 % the appropriate |\|[|re|]|newcommand| call, which we will soon
1553 % execute. The user's macro must first be |\let|-bound to |\relax| to
1554 % prevent it from expanding. Then, we handle two cases: either all
1555 % arguments are mandatory (and |\plmac@defarg| is |\relax|) or the
1556 % user's macro has an optional argument (with default value
1557 % |\plmac@defarg|).
1558 % \begin{macrocode}
1559 \expandafter\let\plmac@macname=\relax
1560 \ifx\plmac@defarg\relax
1561 \edef\plmac@define@command{%
1562 \noexpand\plmac@command\plmac@starchar{\plmac@macname}%
1563 [\plmac@numargs]{%
1564 \noexpand\plmac@write@perl{\plmac@body}%
1565 }%
1566 }%
1567 \else
1568 \edef\plmac@define@command{%
1569 \noexpand\plmac@command\plmac@starchar{\plmac@macname}%
1570 [\plmac@numargs][\plmac@defarg]{%
1571 \noexpand\plmac@write@perl{\plmac@body}%
1572 }%
1573 }%
1574 \fi
1575 % \end{macrocode}
1576 %
1577 % The final steps are to restore the previous definition of the user's
1578 % macro---we had set it to |\relax| above to make the name
1579 % unexpandable---then redefine it by invoking |\plmac@define@command|.
1580 % Why do we need to restore the previous definition if we're just going
1581 % to redefine it? Because |\newcommand| needs to produce an error if
1582 % the macro was previously defined and |\renewcommand| needs to produce
1583 % an error if the macro was \emph{not} previously defined.
1584 %
1585 % |\plmac@havecode| concludes by invoking |\plmac@next|, which is a
1586 % no-op for |\perlnewcommand| and |\perlrenewcommand| but processes the
1587 % end-environment code for |\perlnewenvironment| and
1588 % |\perlrenewenvironment|.
1589 % \begin{macrocode}
1590 \expandafter\let\plmac@macname=\plmac@oldbody
1591 \plmac@define@command
1592 \plmac@next
1593 }
1594 % \end{macrocode}
1595 % \end{macro}
1596 % \end{macro}
1597 % \end{macro}
1598 % \end{macro}
1599 %
1600 %
1601 % \subsubsection{Defining Perl environments}
1602 % \label{sec:perl-env}
1603 %
1604 % \changes{v1.1}{2004/02/24}{Added new
1605 % \texttt{\string\string\string\perlnewenvironment} and
1606 % \texttt{\string\string\string\perlrenewenvironment} macros}
1607 %
1608 % Section~\ref{sec:perl-mac} detailed the implementation of
1609 % |\perlnewcommand| and |\perlrenewcommand|. Section~\ref{sec:perl-env}
1610 % does likewise for |\perlnewenvironment| and |\perlrenewenvironment|,
1611 % which are the Perl-bodied analogues of |\newenvironment| and
1612 % |\renewenvironment|. This section is significantly shorter than the
1613 % previous because |\perlnewenvironment| and |\perlrenewenvironment| are
1614 % largely built atop the macros already defined in
1615 % Section~\ref{sec:perl-mac}.
1616 %
1617 % \begin{macro}{\perlnewenvironment}
1618 % \begin{macro}{\perlrenewenvironment}
1619 % \begin{macro}{\plmac@command}
1620 % \begin{macro}{\plmac@next}
1621 % |\perlnewenvironment| and |\perlrenewenvironment| are the remaining
1622 % two commands exported to the user by \perlmac. |\perlnewenvironment|
1623 % is analogous to |\newenvironment| except that the macro body consists
1624 % of Perl code instead of \LaTeX{} code. Likewise,
1625 % |\perlrenewenvironment| is analogous to |\renewenvironment| except
1626 % that the macro body consists of Perl code instead of \LaTeX{} code.
1627 % |\perlnewenvironment| and |\perlrenewenvironment| merely define
1628 % |\plmac@command| and |\plmac@next| and invoke
1629 % |\plmac@newenvironment@i|.
1630 %
1631 % The significance of |\plmac@next| (which was let-bound to |\relax| for
1632 % |\perl|[|re|]|newcommand| but is let-bound to |\plmac@end@environment|
1633 % here) is that a \LaTeX{} environment definition is really two macro
1634 % definitions: |\|\meta{name} and |\end|\meta{name}. Because we want to
1635 % reuse as much code as possible the idea is to define the ``begin''
1636 % code as one macro, then inject---by way of |plmac@next|---a call to
1637 % |\plmac@end@environment|, which defines the ``end'' code as a second
1638 % macro.
1639 % \begin{macrocode}
1640 \def\perlnewenvironment{%
1641 \let\plmac@command=\newcommand
1642 \let\plmac@next=\plmac@end@environment
1643 \@ifnextchar*{\plmac@newenvironment@i}{\plmac@newenvironment@i!}%
1644 }
1645 % \end{macrocode}
1646 % \begin{macrocode}
1647 \def\perlrenewenvironment{%
1648 \let\plmac@command=\renewcommand
1649 \let\plmac@next=\plmac@end@environment
1650 \@ifnextchar*{\plmac@newenvironment@i}{\plmac@newenvironment@i!}%
1651 }
1652 % \end{macrocode}
1653 % \end{macro}
1654 % \end{macro}
1655 % \end{macro}
1656 % \end{macro}
1657 %
1658 % \begin{macro}{\plmac@newenvironment@i}
1659 % \begin{macro}{\plmac@starchar}
1660 % \begin{macro}{\plmac@envname}
1661 % \begin{macro}{\plmac@macname}
1662 % \begin{macro}{\plmac@oldbody}
1663 % \begin{macro}{\plmac@cleaned@macname}
1664 % The |\plmac@newenvironment@i| macro is analogous to
1665 % |\plmac@newcommand@i|; see the description of
1666 % |\plmac@newcommand@i|~\vpageref{page:newcommand-i} to understand the
1667 % basic structure. The primary difference is that the environment name
1668 % (|#2|) is just text, not a control sequence. We store this text in
1669 % |\plmac@envname| to facilitate generating the names of the two macros
1670 % that constitute an environment definition. Note that there is no
1671 % |\plmac@newenvironment@ii|; control passes instead to
1672 % |\plmac@newcommand@ii|.
1673 % \begin{macrocode}
1674 \def\plmac@newenvironment@i#1#2{%
1675 \ifx#1*%
1676 \def\plmac@starchar{*}%
1677 \else
1678 \def\plmac@starchar{}%
1679 \fi
1680 \def\plmac@envname{#2}%
1681 \expandafter\def\expandafter\plmac@macname\expandafter{\csname#2\endcsname}%
1682 \expandafter\let\expandafter\plmac@oldbody\plmac@macname\relax
1683 \expandafter\def\expandafter\plmac@cleaned@macname\expandafter{%
1684 \expandafter\string\plmac@macname}%
1685 \@ifnextchar[{\plmac@newcommand@ii}{\plmac@newcommand@ii[0]}%]
1686 }
1687 % \end{macrocode}
1688 % \end{macro}
1689 % \end{macro}
1690 % \end{macro}
1691 % \end{macro}
1692 % \end{macro}
1693 % \end{macro}
1694 %
1695 % \begin{macro}{\plmac@end@environment}
1696 % \begin{macro}{\plmac@next}
1697 % \begin{macro}{\plmac@macname}
1698 % \begin{macro}{\plmac@oldbody}
1699 % \begin{macro}{\plmac@cleaned@macname}
1700 % Recall that an environment definition is a shortcut for two macro
1701 % definitions: |\|\meta{name} and |\end|\meta{name} (where \meta{name}
1702 % was stored in |\plmac@envname| by |\plmac@newenvironment@i|). After
1703 % defining |\|\meta{name}, |\plmac@havecode| transfers control to
1704 % |\plmac@end@environment| because |\plmac@next| was let-bound to
1705 % |\plmac@end@environment| in |\perl|[|re|]|newenvironment|.
1706 %
1707 % |\plmac@end@environment|'s purpose is to define |\end|\meta{name}.
1708 % This is a little tricky, however, because \LaTeX's
1709 % |\|[|re|]|newcommand| refuses to (re)define a macro whose name begins
1710 % with ``|end|''. The solution that |\plmac@end@environment| takes is
1711 % first to define a |\plmac@end@macro| macro then (in |plmac@next|)
1712 % let-bind |\end|\meta{name} to it. Other than that,
1713 % |\plmac@end@environment| is a combined and simplified version of
1714 % |\perlnewenvironment|, |\perlrenewenvironment|, and
1715 % |\plmac@newenvironment@i|.
1716 % \begin{macrocode}
1717 \def\plmac@end@environment{%
1718 \expandafter\def\expandafter\plmac@next\expandafter{\expandafter
1719 \let\csname end\plmac@envname\endcsname=\plmac@end@macro
1720 \let\plmac@next=\relax
1721 }%
1722 \def\plmac@macname{\plmac@end@macro}%
1723 \expandafter\let\expandafter\plmac@oldbody\csname end\plmac@envname\endcsname
1724 \expandafter\def\expandafter\plmac@cleaned@macname\expandafter{%
1725 \expandafter\string\plmac@macname}%
1726 \@ifnextchar[{\plmac@newcommand@ii}{\plmac@newcommand@ii[0]}%]
1727 }
1728 % \end{macrocode}
1729 % \end{macro}
1730 % \end{macro}
1731 % \end{macro}
1732 % \end{macro}
1733 % \end{macro}
1734 %
1735 %
1736 % \subsubsection{Executing top-level Perl code}
1737 % \label{sec:perl-run}
1738 %
1739 % The macros defined in Sections~\ref{sec:perl-mac}
1740 % and~\ref{sec:perl-env} enable an author to inject subroutines into the
1741 % Perl sandbox. The final \PerlTeX\ macro, |\perldo|, instructs the
1742 % Perl sandbox to execute a block of code outside of all subroutines.
1743 % |\perldo|'s implementation is much simpler than that of the other
1744 % author macros because |\perldo| does not have to process subroutine
1745 % arguments. Figure~\ref{fig:tofile-run} illustrates the data that gets
1746 % written to |plmac@tofile| (indirectly) by |\perldo|.
1747 %
1748 % \begin{figure}[htbp]
1749 % \centering
1750 % \DeleteShortVerb\|
1751 % \begin{tabular}{|l|}
1752 % \hline
1753 % \verb|RUN| \\ \hline
1754 % \verb|\plmac@tag| \\ \hline
1755 % \textit{Ignored} \\ \hline
1756 % \verb|\plmac@tag| \\ \hline
1757 % \verb|\plmac@perlcode| \\ \hline
1758 % \end{tabular}
1759 % \MakeShortVerb\|
1760 % \caption{Data written to \texttt{\string\plmac@tofile} to execute
1761 % Perl code}
1762 % \label{fig:tofile-run}
1763 % \end{figure}
1764 %
1765 %
1766 % \begin{macro}{\perldo}
1767 % Execute a block of Perl code and pass the result to \LaTeX\ for
1768 % further processing. This code is nearly identical to that of
1769 % Section~\ref{sec:perl-mac}'s |\plmac@haveargs| but ends by invoking
1770 % |\plmac@have@run@code| instead of |\plmac@havecode|.
1771 % \changes{v1.3}{2006/06/23}{Introduced \texttt{\string\string\string\perldo}
1772 % to support code execution outside of all subroutines.}
1773 % \begin{macrocode}
1774 \def\perldo{%
1775 \begingroup
1776 \let\do\@makeother\dospecials
1777 \catcode`\^^M=\active
1778 \newlinechar`\^^M
1779 \endlinechar=`\^^M
1780 \catcode`\{=1
1781 \catcode`\}=2
1782 \afterassignment\plmac@have@run@code
1783 \global\plmac@perlcode
1784 }
1785 % \end{macrocode}
1786 % \end{macro}
1787 %
1788 % \begin{macro}{\plmac@have@run@code}
1789 % \begin{macro}{\plmac@run@code}
1790 % Pass a block of code to Perl to execute. |\plmac@have@run@code| is
1791 % identical to |\plmac@havecode| but specifies the |RUN| tag instead of
1792 % the |DEF| tag.
1793 % \changes{v1.3}{2006/06/23}{Added to assist
1794 % \texttt{\string\string\string\perldo}}
1795 % \begin{macrocode}
1796 \def\plmac@have@run@code{%
1797 \endgroup
1798 \edef\plmac@run@code{%
1799 \noexpand\plmac@write@perl{RUN\plmac@sep
1800 \plmac@tag\plmac@sep
1801 N/A\plmac@sep
1802 \plmac@tag\plmac@sep
1803 \the\plmac@perlcode
1804 }%
1805 }%
1806 \plmac@run@code
1807 }
1808 % \end{macrocode}
1809 % \end{macro}
1810 % \end{macro}
1811 %
1812 %
1813 % \subsubsection{Communication between \LaTeX{} and Perl}
1814 %
1815 % As shown in the previous section, when a document invokes
1816 % |\perl|[|re|]|newcommand| to define a macro, \perlmac{} defines the
1817 % macro in terms of a call to |\plmac@write@perl|. In this section, we
1818 % learn how |\plmac@write@perl| operates.
1819 %
1820 % At the highest level, \LaTeX-to-Perl communication is performed via
1821 % the filesystem. In essence, \LaTeX{} writes a file (|\plmac@tofile|)
1822 % corresponding to the information in either
1823 % Figure~\ref{fig:tofile-define} or Figure~\ref{fig:tofile-use}; Perl
1824 % reads the file, executes the code within it, and writes a |.tex| file
1825 % (|\plmac@fromfile|); and, finally, \LaTeX{} reads and executes the new
1826 % |.tex| file. However, the actual communication protocol is a bit more
1827 % involved than that. The problem is that Perl needs to know when
1828 % \LaTeX{} has finished writing Perl code and \LaTeX{} needs to know
1829 % when Perl has finished writing \LaTeX{} code. The solution involves
1830 % introducing three extra files---|\plmac@toflag|, |\plmac@fromflag|,
1831 % and |\plmac@doneflag|---which are used exclusively for \LaTeX-to-Perl
1832 % synchronization.
1833 %
1834 % There's a catch: Although Perl can create and delete files, \LaTeX{}
1835 % can only create them. Even worse, \LaTeX{} (more specifically,
1836 % te\TeX, which is the \TeX{} distribution under which I developed
1837 % \PerlTeX) cannot reliably poll for a file's \emph{non}existence; if a
1838 % file is deleted in the middle of an |\immediate\openin|, |latex|
1839 % aborts with an error message. These restrictions led to the
1840 % regrettably convoluted protocol illustrated in
1841 % Figure~\ref{fig:comm-protocol}. In the figure, ``Touch'' means
1842 % ``create a zero-length file''; ``Await'' means ``wait until the file
1843 % exists''; and, ``Read'', ``Write'', and ``Delete'' are defined as
1844 % expected. Assuming the filesystem performs these operations in a
1845 % sequentially consistent order (not necessarily guaranteed on all
1846 % filesystems, unfortunately), \PerlTeX{} should behave as expected.
1847 %
1848 % \begin{figure}[htbp]
1849 % \centering
1850 % \makeatletter\setlength{\unitlength}{\baselineskip}\makeatother
1851 % \DeleteShortVerb\|
1852 % \def\topl{\texttt{\string\plmac@tofile}}
1853 % \def\frpl{\texttt{\string\plmac@fromfile}}
1854 % \def\tfpl{\texttt{\string\plmac@toflag}}
1855 % \def\ffpl{\texttt{\string\plmac@fromflag}}
1856 % \def\dfpl{\texttt{\string\plmac@doneflag}}
1857 % \begin{tabular}{@{}c@{\hspace*{1cm}}|l@{~}l|c|l@{~}l|@{}}
1858 % \multicolumn{1}{@{}c@{\hspace*{1cm}}}{Time} &
1859 % \multicolumn{2}{c}{\LaTeX} &
1860 % \multicolumn{1}{c}{} &
1861 % \multicolumn{2}{c@{}}{Perl} \\
1862 %
1863 % \cline{2-3}\cline{5-6}
1864 % \smash{\vector(0,-1){11}}
1865 % & Write & \topl & & & \\
1866 % & Touch & \tfpl & $\rightarrow$ & Await & \tfpl \\
1867 % & & & & Read & \topl \\
1868 % & & & & Write & \frpl \\
1869 % & & & & Delete & \tfpl \\
1870 % & & & & Delete & \topl \\
1871 % & & & & Delete & \dfpl \\
1872 % & Await & \ffpl & $\leftarrow$ & Touch & \ffpl \\
1873 % & Touch & \topl & $\rightarrow$ & Await & \topl \\
1874 % & & & & Delete & \ffpl \\
1875 % & Await & \dfpl & $\leftarrow$ & Touch & \dfpl \\
1876 % & Read & \frpl & & & \\
1877 % \cline{2-3}\cline{5-6}
1878 % \end{tabular}
1879 % \MakeShortVerb\|
1880 % \caption{\LaTeX-to-Perl communication protocol}
1881 % \label{fig:comm-protocol}
1882 % \end{figure}
1883 %
1884 % Although Figure~\ref{fig:comm-protocol} shows the read of
1885 % |\plmac@fromfile| as the final step of the protocol, the file's
1886 % contents are in fact valid as soon as \LaTeX{} detects that
1887 % |\plmac@fromflag| exists. Deferring the read to the end, however,
1888 % enables \PerlTeX{} to support recursive macro invocations.
1889 %
1890 % \begin{macro}{\plmac@infile}
1891 % \begin{macro}{\plmac@IfFileExists}
1892 % \changes{v2.3}{2024/12/03}{Introduce this macro, which implements a
1893 % non-caching version of \string\cs{IfFileExists}}
1894 % The Await operations in Figure~\ref{fig:comm-protocol} require testing
1895 % if a file exists. On the \LaTeX\ side, this normally would be
1896 % achieved using \LaTeX's \cs{IfFileExists} macro, and this is indeed
1897 % what \PerlTeX\ did until version~2.2. However, the \mbox{1-Jun-2023}
1898 % release of \LaTeX3 introduced a performance optimization that lets
1899 % \cs{IfFileExists} cache prior results. (See
1900 % \url{https://www.latex-project.org/news/latex2e-news/ltnews37.pdf}.)
1901 % In other words, once \cs{IfFileExists} determines that a file exists,
1902 % it will follow the \textsc{true} branch on all subsequent calls
1903 % without ever re-checking if the file still exists. This semantics
1904 % breaks the protocol described in Figure~\ref{fig:comm-protocol} by
1905 % enabling Await to return before the file being waited for actually
1906 % exists.
1907 %
1908 % To work around \LaTeX3's new behavior, we define our own version of
1909 % \cs{IfFileExists} called \cs{plmac@IfFileExists}, which is derived
1910 % from \cs{IfFileExists}'s simpler, more straightforward
1911 % \LaTeXe\ implementation. In particular, file existence is checked
1912 % explicitly on each invocation.
1913 % \begin{macrocode}
1914 \newread\plmac@infile
1915 % \end{macrocode}
1916 % \begin{macrocode}
1917 \newcommand{\plmac@IfFileExists}[3]{%
1918 \openin\plmac@infile=#1 %
1919 \ifeof\plmac@infile
1920 \def\plmac@next{#3}%
1921 \else
1922 \closein\plmac@infile
1923 \def\plmac@next{#2}%
1924 \fi
1925 \plmac@next
1926 }
1927 % \end{macrocode}
1928 % \end{macro}
1929 % \end{macro}
1930 %
1931 % \begin{macro}{\plmac@await@existence}
1932 % \changes{v1.9}{2009/09/13}{Put the
1933 % \texttt{\string\string\string\input\string\string\string\plmac@pipe}
1934 % within an \texttt{lrbox} environment to prevent a partial read from
1935 % introducing spurious text into the document}
1936 % \begin{macro}{\ifplmac@file@exists}
1937 % \begin{macro}{\plmac@file@existstrue}
1938 % \begin{macro}{\plmac@file@existsfalse}
1939 % The purpose of the \cs{plmac@await@existence} macro is repeatedly to
1940 % check the existence of a given file until the file actually exists.
1941 % We use \cs{plmac@IfFileExists} (defined above) to check if the file
1942 % exists and accordingly either continue or exit the loop.
1943 %
1944 % As a performance optimization we |\input| a named pipe. This causes
1945 % the |latex| process to relinquish the CPU until the |perltex| process
1946 % writes data (always just a comment plus ``|\endinput|'') into the
1947 % named pipe. On systems that don't support persistent named pipes
1948 % (e.g.,~Microsoft Windows), |\plmac@pipe| is an ordinary file
1949 % containing only a comment plus ``|\endinput|''. While reading that
1950 % file is not guaranteed to relinquish the CPU, it should not hurt the
1951 % performance or correctness of the communication protocol between
1952 % \LaTeX\ and Perl.
1953 % \changes{v1.5}{2007/10/13}{Modified to read from a named pipe before
1954 % checking file existence}
1955 % \begin{macrocode}
1956 \newif\ifplmac@file@exists
1957 % \end{macrocode}
1958 % \begin{macrocode}
1959 \newcommand{\plmac@await@existence}[1]{%
1960 \begin{lrbox}{\@tempboxa}%
1961 \input\plmac@pipe
1962 \end{lrbox}%
1963 \loop
1964 \plmac@IfFileExists{#1}%
1965 {\plmac@file@existstrue}%
1966 {\plmac@file@existsfalse}%
1967 \ifplmac@file@exists
1968 \else
1969 \repeat
1970 }
1971 % \end{macrocode}
1972 % \end{macro}
1973 % \end{macro}
1974 % \end{macro}
1975 % \end{macro}
1976 %
1977 % \begin{macro}{\plmac@outfile}
1978 % We define a file handle for |\plmac@write@perl@i| to use to create and
1979 % write |\plmac@tofile| and |\plmac@toflag|.
1980 % \begin{macrocode}
1981 \newwrite\plmac@outfile
1982 % \end{macrocode}
1983 % \end{macro}
1984 %
1985 % \begin{macro}{\plmac@write@perl}
1986 % |\plmac@write@perl| begins the \LaTeX-to-Perl data exchange, following
1987 % the protocol illustrated in Figure~\ref{fig:comm-protocol}.
1988 % |\plmac@write@perl| prepares for the next piece of text in the input
1989 % stream to be read with ``special'' characters marked as category
1990 % code~12 (``other''). This prevents \LaTeX{} from complaining if the
1991 % Perl code contains invalid \LaTeX{} (which it usually will).
1992 % |\plmac@write@perl| ends by passing control to |\plmac@write@perl@i|,
1993 % which performs the bulk of the work.
1994 % \begin{macrocode}
1995 \newcommand{\plmac@write@perl}{%
1996 \begingroup
1997 \let\do\@makeother\dospecials
1998 \catcode`\^^M=\active
1999 \newlinechar`\^^M
2000 \endlinechar=`\^^M
2001 \catcode`\{=1
2002 \catcode`\}=2
2003 \plmac@write@perl@i
2004 }
2005 % \end{macrocode}
2006 % \end{macro}
2007 %
2008 % \begin{macro}{\plmac@write@perl@i}
2009 % When |\plmac@write@perl@i| begins executing, the category codes are
2010 % set up so that the macro's argument will be evaluated ``verbatim''
2011 % except for the part consisting of the \LaTeX\ code passed in by the
2012 % author, which is partially expanded. Thus, everything is in place for
2013 % |\plmac@write@perl@i| to send its argument to Perl and read back the
2014 % (\LaTeX) result.
2015 %
2016 % Because\label{page:define-dummies} all of \perlmac's protocol
2017 % processing is encapsulated within |\plmac@write@perl@i|, this is the
2018 % only macro that strictly requires \perltex. Consequently, we wrap the
2019 % entire macro definition within a check for \perltex.
2020 % \changes{v1.8}{2009/03/25}{Renamed
2021 % \texttt{\string\string\string\ifplmac@have@perltex} to
2022 % \texttt{\char`\\ ifperl} to help authors write
2023 % mixed \string\LaTeX\string\slash\space \string\PerlTeX\ documents}
2024 % \begin{macrocode}
2025 \ifperl
2026 \newcommand{\plmac@write@perl@i}[1]{%
2027 % \end{macrocode}
2028 % The first step is to write argument |#1| to |\plmac@tofile|:
2029 % \changes{v1.1}{2004/02/19}{Made argument-handling more rational by
2030 % making \texttt{\string\string\string\protect},
2031 % \texttt{\string\string\string\begin}, and
2032 % \texttt{\string\string\string\end} non-expandable}
2033 % \begin{macrocode}
2034 \immediate\openout\plmac@outfile=\plmac@tofile\relax
2035 \let\protect=\noexpand
2036 \def\begin{\noexpand\begin}%
2037 \def\end{\noexpand\end}%
2038 \immediate\write\plmac@outfile{#1}%
2039 \immediate\closeout\plmac@outfile
2040 % \end{macrocode}
2041 % \noindent
2042 % (In the future, it might be worth redefining |\def|, |\edef|, |\gdef|,
2043 % |\xdef|, |\let|, and maybe some other control sequences as
2044 % ``|\noexpand|\meta{control sequence}|\noexpand|'' so that |\write|
2045 % doesn't try to expand an undefined control sequence.)
2046 %
2047 % We're now finished using |#1| so we can end the group begun by
2048 % |\plmac@write@perl|, thereby resetting each character's category code
2049 % back to its previous value.
2050 % \begin{macrocode}
2051 \endgroup
2052 % \end{macrocode}
2053 %
2054 % Continuing the protocol illustrated in Figure~\ref{fig:comm-protocol},
2055 % we create a zero-byte |\plmac@toflag| in order to notify \perltex{}
2056 % that it's now safe to read |\plmac@tofile|.
2057 % \begin{macrocode}
2058 \immediate\openout\plmac@outfile=\plmac@toflag\relax
2059 \immediate\closeout\plmac@outfile
2060 % \end{macrocode}
2061 %
2062 % To avoid reading |\plmac@fromfile| before \perltex{} has finished
2063 % writing it we must wait until \perltex{} creates |\plmac@fromflag|,
2064 % which it does only after it has written |\plmac@fromfile|.
2065 % \begin{macrocode}
2066 \plmac@await@existence\plmac@fromflag
2067 % \end{macrocode}
2068 %
2069 % At this point, |\plmac@fromfile| should contain valid \LaTeX{} code.
2070 % However, we defer inputting it until we the very end. Doing so
2071 % enables recursive and mutually recursive invocations of \PerlTeX{}
2072 % macros.
2073 % \changes{v1.2}{2004/10/07}{Moved the
2074 % \texttt{\string\string\string\input} of the generated Perl code to
2075 % the end of the routine in order to support recursive \PerlTeX{}
2076 % macro invocations.}
2077 %
2078 % Because \TeX{} can't delete files we require an additional
2079 % \LaTeX-to-Perl synchronization step. For convenience, we recycle
2080 % |\plmac@tofile| as a synchronization file rather than introduce yet
2081 % another flag file to complement |\plmac@toflag|, |\plmac@fromflag|,
2082 % and |\plmac@doneflag|.
2083 % \begin{macrocode}
2084 \immediate\openout\plmac@outfile=\plmac@tofile\relax
2085 \immediate\closeout\plmac@outfile
2086 \plmac@await@existence\plmac@doneflag
2087 % \end{macrocode}
2088 %
2089 % The only thing left to do is to |\input| and evaluate
2090 % |\plmac@fromfile|, which contains the \LaTeX{} output from the Perl
2091 % subroutine.
2092 % \begin{macrocode}
2093 \input\plmac@fromfile\relax
2094 }
2095 % \end{macrocode}
2096 % \end{macro}
2097 %
2098 % \begin{macro}{\plmac@write@perl@i}
2099 % \changes{v1.1}{2004/02/24}{Added a dummy version of the macro to use
2100 % if \texttt{latex} was launched directly, without \perltex}
2101 % The foregoing code represents the ``real'' definition of
2102 % |\plmac@write@perl@i|. For the user's convenience, we define a dummy
2103 % version of |\plmac@write@perl@i| so that a document which utilizes
2104 % \perlmac{} can still compile even if not built using \perltex. All
2105 % calls to macros defined with |\perl|[|re|]|newcommand| and all
2106 % invocations of environments defined with |\perl|[|re|]|newenvironment|
2107 % are replaced with ``\fbox{Perl\TeX}''. A minor complication is that
2108 % text can't be inserted before the |\begin{document}|. Hence, we
2109 % initially define |\plmac@write@perl@i| as a do-nothing macro and
2110 % redefine it as ``|\fbox{Perl\TeX}|'' at the |\begin{document}|.
2111 % \begin{macrocode}
2112 \else
2113 \newcommand{\plmac@write@perl@i}[1]{\endgroup}
2114 % \end{macrocode}
2115 % \begin{macro}{\plmac@show@placeholder}
2116 % There's really no point in outputting a framed ``Perl\TeX'' when a
2117 % macro is defined \emph{and} when it's used. |\plmac@show@placeholder|
2118 % checks the first character of the protocol header. If it's
2119 % ``D''~(|DEF|), nothing is output. Otherwise, it'll be ``U''~(|USE|)
2120 % and ``Perl\TeX'' will be output.
2121 % \begin{macrocode}
2122 \gdef\plmac@show@placeholder#1#2\@empty{%
2123 \ifx#1D\relax
2124 \endgroup
2125 \else
2126 \endgroup
2127 \fbox{Perl\TeX}%
2128 \fi
2129 }%
2130 % \end{macrocode}
2131 % \end{macro}
2132 % \begin{macrocode}
2133 \AtBeginDocument{%
2134 \renewcommand{\plmac@write@perl@i}[1]{%
2135 \plmac@show@placeholder#1\@empty
2136 }%
2137 }
2138 \fi
2139 % \end{macrocode}
2140 % \end{macro}
2141 %
2142 % \iffalse
2143 %</package>
2144 % \fi
2145 %
2146 % ^^A Keep track of the number of lines of code in perltex.
2147 % \makeatletter
2148 % \immediate\write\@auxout{^^A
2149 % \noexpand\gdef\noexpand\perlmaclines{\the\c@CodelineNo}}
2150 % \makeatother
2151 %
2152 %
2153 % \subsection{\perltex}
2154 % \label{sec:perltex}
2155 %
2156 % \perltex{} is a wrapper script for |latex| (or any other \LaTeX{}
2157 % compiler). It sets up client-server communication between \LaTeX{}
2158 % and Perl, with \LaTeX{} as the client and Perl as the server. When a
2159 % \LaTeX{} document sends a piece of Perl code to \perltex{} (with the
2160 % help of \perlmac, as detailed in Section~\ref{sec:perlmacros}),
2161 % \perltex{} executes it within a secure sandbox and transmits the
2162 % resulting \LaTeX{} code back to the document.
2163 % \changes{v1.0a}{2003/08/21}{Made all \texttt{unlink} calls wait for the
2164 % file to actually disappear}
2165 %
2166 % \iffalse
2167 %<*perltex>
2168 % \fi
2169 %
2170 % \subsubsection{Header comments}
2171 %
2172 % Because \perltex{} is generated without a \textsf{DocStrip}
2173 % preamble or postamble we have to manually include the desired
2174 % text as Perl comments.
2175 %
2176 % \begin{macrocode}
2177 #! /usr/bin/env perl
2178
2179 ###########################################################
2180 # Prepare a LaTeX run for two-way communication with Perl #
2181 # By Scott Pakin <[email protected]> #
2182 ###########################################################
2183
2184 #-------------------------------------------------------------------
2185 # This is file `perltex.pl',
2186 # generated with the docstrip utility.
2187 #
2188 # The original source files were:
2189 #
2190 # perltex.dtx (with options: `perltex')
2191 #
2192 # This is a generated file.
2193 #
2194 # Copyright (C) 2003-2024 Scott Pakin <[email protected]>
2195 #
2196 # This file may be distributed and/or modified under the conditions
2197 # of the LaTeX Project Public License, either version 1.3c of this
2198 # license or (at your option) any later version. The latest
2199 # version of this license is in:
2200 #
2201 # http://www.latex-project.org/lppl.txt
2202 #
2203 # and version 1.3c or later is part of all distributions of LaTeX
2204 # version 2006/05/20 or later.
2205 #-------------------------------------------------------------------
2206
2207 % \end{macrocode}
2208 %
2209 % \subsubsection{Top-level code evaluation}
2210 %
2211 % In previous versions of \perltex, the |--nosafe| option created and
2212 % ran code within a sandbox in which all operations are allowed (via
2213 % |Opcode::full_opset()|). Unfortunately, certain operations still fail
2214 % to work within such a sandbox. We therefore define a top-level
2215 % ``non-sandbox'', |top_level_eval()|, in which to execute code.
2216 % |top_level_eval()| merely calls |eval()| on its argument. However, it
2217 % needs to be declared top-level and before anything else because
2218 % |eval()| runs in the lexical scope of its caller.
2219 % \changes{v1.3}{2006/06/24}{Modified \perltex\ to eschew the sandbox
2220 % altogether when \texttt{--nosafe} is specified}
2221 %
2222 % \begin{macrocode}
2223 sub top_level_eval ($)
2224 {
2225 return eval $_[0];
2226 }
2227 % \end{macrocode}
2228 %
2229 % \subsubsection{Perl modules and pragmas}
2230 %
2231 % We use |Safe| and |Opcode| to implement the secure sandbox,
2232 % |Getopt::Long| and |Pod::Usage| to parse the command line, and
2233 % various other modules and pragmas for miscellaneous things.
2234 % \begin{macrocode}
2235 use Safe;
2236 use Opcode;
2237 use Getopt::Long;
2238 use Pod::Usage;
2239 use File::Basename;
2240 use Fcntl;
2241 use POSIX;
2242 use File::Spec;
2243 use IO::Handle;
2244 use warnings;
2245 use strict;
2246 % \end{macrocode}
2247 %
2248 % \subsubsection{Variable declarations}
2249 %
2250 % With |use strict| in effect, we need to declare all of our variables.
2251 % For clarity, we separate our global-variable declarations into
2252 % variables corresponding to command-line options and other global
2253 % variables.
2254 %
2255 % \paragraph{Variables corresponding to command-line arguments}
2256 % \begin{perlvar}{$latexprog}
2257 % \begin{perlvar}{$runsafely}
2258 % \begin{perlvar}{@permittedops}
2259 % \begin{perlvar}{$usepipe}
2260 % |$latexprog| is the name of the \LaTeX{} executable
2261 % (e.g.,~``|latex|''). If |$runsafely| is~|1| (the default), then the
2262 % user's Perl code runs in a secure sandbox; if it's~|0|, then arbitrary
2263 % Perl code is allowed to run. |@permittedops| is a list of features
2264 % made available to the user's Perl code. Valid values are described in
2265 % Perl's |Opcode| manual page. \perltex's default is a list containing
2266 % only |:browse|. |$usepipe| is~|1| if \perltex\ should attempt to use
2267 % a named pipe for communicating with |latex| or~|0| if an ordinary file
2268 % should be used instead.
2269 % \begin{macrocode}
2270 my $latexprog;
2271 my $runsafely = 1;
2272 my @permittedops;
2273 my $usepipe = 1;
2274 % \end{macrocode}
2275 % \end{perlvar}
2276 % \end{perlvar}
2277 % \end{perlvar}
2278 % \end{perlvar}
2279 %
2280 % \paragraph{Filename variables}
2281 % \begin{perlvar}{$progname}
2282 % \begin{perlvar}{$jobname}
2283 % \begin{perlvar}{$toperl}
2284 % \begin{perlvar}{$fromperl}
2285 % \begin{perlvar}{$toflag}
2286 % \begin{perlvar}{$fromflag}
2287 % \begin{perlvar}{$doneflag}
2288 % \begin{perlvar}{$logfile}
2289 % \begin{perlvar}{$pipe}
2290 % |$progname| is the run-time name of the \perltex{} program.
2291 % |$jobname| is the base name of the user's |.tex| file, which defaults
2292 % to the \TeX{} default of |texput|. |$toperl| defines the filename
2293 % used for \LaTeX-to-Perl communication. |$fromperl| defines the
2294 % filename used for Perl-to-\LaTeX{} communication. |$toflag| is the
2295 % name of a file that will exist only after \LaTeX{} creates |$tofile|.
2296 % |$fromflag| is the name of a file that will exist only after Perl
2297 % creates |$fromfile|. |$doneflag| is the name of a file that will
2298 % exist only after Perl deletes |$fromflag|. |$logfile| is the name of
2299 % a log file to which \perltex{} writes verbose execution information.
2300 % |$pipe| is the name of a Unix named pipe (or ordinary file on
2301 % operating systems that lack support for persistent named pipes or in
2302 % the case that |$usepipe| is set to~|0|) used to convince the |latex|
2303 % process to yield control of the CPU\@.
2304 % \begin{macrocode}
2305 my $progname = basename $0;
2306 my $jobname = "texput";
2307 my $toperl;
2308 my $fromperl;
2309 my $toflag;
2310 my $fromflag;
2311 my $doneflag;
2312 my $logfile;
2313 my $pipe;
2314 % \end{macrocode}
2315 % \end{perlvar}
2316 % \end{perlvar}
2317 % \end{perlvar}
2318 % \end{perlvar}
2319 % \end{perlvar}
2320 % \end{perlvar}
2321 % \end{perlvar}
2322 % \end{perlvar}
2323 % \end{perlvar}
2324 %
2325 % \paragraph{Other global variables}
2326 % \begin{perlvar}{@latexcmdline}
2327 % \begin{perlvar}{$styfile}
2328 % \begin{perlvar}{@macroexpansions}
2329 % \begin{perlvar}{$sandbox}
2330 % \begin{perlvar}{$sandbox_eval}
2331 % \begin{perlvar}{$latexpid}
2332 % |@latexcmdline| is the command line to pass to the \LaTeX{}
2333 % executable. |$styfile| is the string \noperlmac{} if \perltex{} is run
2334 % with \texttt{--makesty}, otherwise undefined. |@macroexpansions| is a
2335 % list of \PerlTeX{} macro expansions in the order they were encountered.
2336 % It is used for creating a \noperlmac{} file when \texttt{--makesty} is
2337 % specified. |$sandbox| is a secure sandbox in which to run code that
2338 % appeared in the \LaTeX{} document. |$sandbox_eval| is a subroutine
2339 % that evalutes a string within |$sandbox| (normally) or outside of all
2340 % sandboxes (if |--nosafe| is specified). |$latexpid| is the process~ID
2341 % of the |latex| process.
2342 % \begin{macrocode}
2343 my @latexcmdline;
2344 my $styfile;
2345 my @macroexpansions;
2346 my $sandbox = new Safe;
2347 my $sandbox_eval;
2348 my $latexpid;
2349 % \end{macrocode}
2350 % \end{perlvar}
2351 % \end{perlvar}
2352 % \end{perlvar}
2353 % \end{perlvar}
2354 % \end{perlvar}
2355 % \end{perlvar}
2356 %
2357 % \begin{perlvar}{$pipestring}
2358 % |$pipestring| is a constant string to write to the |$pipe| named pipe
2359 % (or file) at each \LaTeX{} synchronization point. Its particular
2360 % definition is really a bug workaround for \XeTeX\@. The current
2361 % version of \XeTeX{} reads the first few bytes of a file to determine
2362 % the character encoding (\mbox{UTF-8} or \mbox{UTF-16}, big-endian or
2363 % little-endian) then attempts to rewind the file pointer. Because
2364 % pipes can't be rewound, the effect is that the first two bytes of
2365 % |$pipe| are discarded and the rest are input. Hence, the
2366 % ``|\endinput|'' used in prior versions of \PerlTeX{} inserted a
2367 % spurious ``|ndinput|'' into the author's document. We therefore
2368 % define |$pipestring| such that it will not interfere with the document
2369 % even if the first few bytes are discarded.
2370 % \changes{v1.7}{2007/12/09}{Introduced this variable as a workaround for
2371 % \protect\XeTeX's attempt to rewind \texttt{\$pipe}}
2372 % \begin{macrocode}
2373 my $pipestring = "\%\%\%\%\% Generated by $progname\n\\endinput\n";
2374 % \end{macrocode}
2375 % \end{perlvar}
2376 %
2377 % \subsubsection{Command-line conversion}
2378 %
2379 % In this section, \perltex{} parses its own command line and prepares a
2380 % command line to pass to |latex|.
2381 %
2382 % \paragraph{Parsing \perltex's command line}
2383 % We first set |$latexprog| to be the contents of the environment
2384 % variable |PERLTEX| or the value ``|latex|'' if |PERLTEX| is not
2385 % specified. We then use |Getopt::Long| to parse the command line,
2386 % leaving any parameters we don't recognize in the argument vector
2387 % (|@ARGV|) because these are presumably |latex| options.
2388 % \changes{v1.6}{2007/12/07}{Added an (undocumented) \texttt{--nopipe}
2389 % option to \protect\perltex\ to help it work with \protect\XeTeX}
2390 % \changes{v1.7}{2007/12/09}{Added an (undocumented) \texttt{--synctext}
2391 % option to alter the text written to \texttt{\$pipe}}
2392 % \begin{macrocode}
2393 $latexprog = $ENV{"PERLTEX"} || "latex";
2394 Getopt::Long::Configure("require_order", "pass_through");
2395 GetOptions("help" => sub {pod2usage(-verbose => 1)},
2396 "latex=s" => \$latexprog,
2397 "safe!" => \$runsafely,
2398 % \end{macrocode}
2399 % The following two options are undocumented because the defaults should
2400 % always suffice. We're not yet removing these options, however, in
2401 % case they turn out to be useful for diagnostic purposes.
2402 % \begin{macrocode}
2403 "pipe!" => \$usepipe,
2404 "synctext=s" => \$pipestring,
2405 % \end{macrocode}
2406 % \begin{macrocode}
2407 "makesty" => sub {$styfile = "noperltex.sty"},
2408 "permit=s" => \@permittedops) || pod2usage(2);
2409 % \end{macrocode}
2410 %
2411 % \paragraph{Preparing a \LaTeX{} command line}
2412 % \begin{perlvar}{$firstcmd}
2413 % \begin{perlvar}{$option}
2414 % We start by searching |@ARGV| for the first string that does not start
2415 % with ``|-|'' or ``|\|''. This string, which represents a filename, is
2416 % used to set |$jobname|.
2417 % \begin{macrocode}
2418 @latexcmdline = @ARGV;
2419 my $firstcmd = 0;
2420 for ($firstcmd=0; $firstcmd<=$#latexcmdline; $firstcmd++) {
2421 my $option = $latexcmdline[$firstcmd];
2422 next if substr($option, 0, 1) eq "-";
2423 if (substr ($option, 0, 1) ne "\\") {
2424 $jobname = basename $option, ".tex" ;
2425 $latexcmdline[$firstcmd] = "\\input $option";
2426 }
2427 last;
2428 }
2429 push @latexcmdline, "" if $#latexcmdline==-1;
2430 % \end{macrocode}
2431 % \end{perlvar}
2432 % \end{perlvar}
2433 %
2434 % \begin{perlvar}{$separator}
2435 % To avoid conflicts with the code and parameters passed to Perl from
2436 % \LaTeX{} (see Figure~\vref{fig:tofile-define} and
2437 % Figure~\vref{fig:tofile-use}) we define a separator string,
2438 % |$separator|, containing 20 random uppercase letters.
2439 % \begin{macrocode}
2440 my $separator = "";
2441 foreach (1 .. 20) {
2442 $separator .= chr(ord("A") + rand(26));
2443 }
2444 % \end{macrocode}
2445 % \end{perlvar}
2446 %
2447 % Now that we have the name of the \LaTeX{} job (|$jobname|) we can
2448 % assign |$toperl|, |$fromperl|, |$toflag|, |$fromflag|, |$doneflag|,
2449 % |$logfile|, and |$pipe| in terms of |$jobname| plus a suitable
2450 % extension.
2451 % \begin{macrocode}
2452 $toperl = $jobname . ".topl";
2453 $fromperl = $jobname . ".frpl";
2454 $toflag = $jobname . ".tfpl";
2455 $fromflag = $jobname . ".ffpl";
2456 $doneflag = $jobname . ".dfpl";
2457 $logfile = $jobname . ".lgpl";
2458 $pipe = $jobname . ".pipe";
2459 % \end{macrocode}
2460 %
2461 % We now replace the filename of the |.tex| file passed to \perltex{}
2462 % with a |\def|inition of the separator character, |\def|initions of the
2463 % various files, and the original file with |\input| prepended if
2464 % necessary.
2465 % \begin{macrocode}
2466 $latexcmdline[$firstcmd] =
2467 sprintf '\makeatletter' . '\def%s{%s}' x 7 . '\makeatother%s',
2468 '\plmac@tag', $separator,
2469 '\plmac@tofile', $toperl,
2470 '\plmac@fromfile', $fromperl,
2471 '\plmac@toflag', $toflag,
2472 '\plmac@fromflag', $fromflag,
2473 '\plmac@doneflag', $doneflag,
2474 '\plmac@pipe', $pipe,
2475 $latexcmdline[$firstcmd];
2476 % \end{macrocode}
2477 %
2478 % \subsubsection{Increasing \PerlTeX's robustness}
2479 %
2480 % \changes{v2.0}{2009/11/24}{Refer to each communication file using
2481 % its absolute path. This makes \perltex\ robust to user code
2482 % that changes the current directory}
2483 % \changes{v2.1}{2010/07/10}{Replaced \texttt{abs\_path()} with
2484 % \texttt{File::Spec-\char"3Erel2abs()} because the latter seems
2485 % to be more robust to nonexistent files}
2486 % \begin{macrocode}
2487 $toperl = File::Spec->rel2abs($toperl);
2488 $fromperl = File::Spec->rel2abs($fromperl);
2489 $toflag = File::Spec->rel2abs($toflag);
2490 $fromflag = File::Spec->rel2abs($fromflag);
2491 $doneflag = File::Spec->rel2abs($doneflag);
2492 $logfile = File::Spec->rel2abs($logfile);
2493 $pipe = File::Spec->rel2abs($pipe);
2494 % \end{macrocode}
2495 %
2496 % \changes{v1.9}{2009/09/13}{Introduced handlers for \textsc{sigalrm}
2497 % and \textsc{sigpipe} to make \perltex\ more robust to \texttt{latex}
2498 % exiting at an inopportune time}
2499 %
2500 % \perltex\ may hang if |latex| exits right before the final pipe
2501 % communication. We therefore define a simple \signal{ALRM} handler
2502 % that lets \perltex\ exit after a given length of time has
2503 % elapsed.\label{code:sigalrm}
2504 % \begin{macrocode}
2505 $SIG{"ALRM"} = sub {
2506 undef $latexpid;
2507 exit 0;
2508 };
2509 % \end{macrocode}
2510 %
2511 % To prevent Perl from aborting with a ``\texttt{Broken pipe}'' error
2512 % message if |latex| exits during the final pipe communication we tell
2513 % Perl to ignore \signal{PIPE} errors. |latex|'s exiting will be
2514 % caught via other means (the preceding \signal{ALRM} handler or the
2515 % following call to |waitpid|).
2516 % \begin{macrocode}
2517 $SIG{"PIPE"} = "IGNORE";
2518 % \end{macrocode}
2519 %
2520 % \begin{perlsub}{delete_files}
2521 % On some operating systems and some filesystems, deleting a file may
2522 % not cause the file to disappear immediately. Because
2523 % \PerlTeX\ synchronizes Perl and \LaTeX\ via the filesystem it is
2524 % critical that file deletions be performed when requested. We
2525 % therefore define a |delete_files| subroutine that waits until each
2526 % file named in the argument list is truly deleted.
2527 % \changes{v1.9}{2009/09/13}{Replaced all
2528 % \texttt{unlink}\dots\texttt{while~-e} statements with calls to a new
2529 % \texttt{delete\_files} subroutine}
2530 % \begin{macrocode}
2531 sub delete_files (@)
2532 {
2533 foreach my $filename (@_) {
2534 unlink $filename;
2535 while (-e $filename) {
2536 unlink $filename;
2537 sleep 0;
2538 }
2539 }
2540 }
2541 % \end{macrocode}
2542 % \end{perlsub}
2543 %
2544 % \begin{perlsub}{awaitexists}
2545 % We define an |awaitexists| subroutine that waits for a given file to
2546 % exist. If |latex| exits while |awaitexists| is waiting, then
2547 % \perltex{} cleans up and exits, too.
2548 % \changes{v1.0a}{2003/08/06}{Bug fix: Added ``\texttt{undef
2549 % \$latexpid}'' to make the \texttt{END} block correctly return a
2550 % status code of~0 on success}
2551 % \changes{v1.9}{2009/09/13}{Hoisted \texttt{\$awaitexists} from the
2552 % main loop and made it a top-level subroutine}
2553 % \begin{macrocode}
2554 sub awaitexists ($)
2555 {
2556 while (!-e $_[0]) {
2557 sleep 0;
2558 if (waitpid($latexpid, &WNOHANG)==-1) {
2559 delete_files($toperl, $fromperl, $toflag,
2560 $fromflag, $doneflag, $pipe);
2561 undef $latexpid;
2562 exit 0;
2563 }
2564 }
2565 }
2566 % \end{macrocode}
2567 % \end{perlsub}
2568 %
2569 % \subsubsection{Launching \LaTeX}
2570 %
2571 % We start by deleting the |$toperl|, |$fromperl|, |$toflag|,
2572 % |$fromflag|, |$doneflag|, and |$pipe| files, in case any of these were
2573 % left over from a previous (aborted) run. We also create a log file
2574 % (|$logfile|), a named pipe (|$pipe|)---or a file containing only
2575 % |\endinput| if we can't create a named pipe---and, if |$styfile| is
2576 % defined, a \LaTeXe\ style file. As |@latexcmdline| contains the
2577 % complete command line to pass to |latex| we need only |fork| a new
2578 % process and have the child process overlay itself with |latex|.
2579 % \perltex{} continues running as the parent.
2580 % \begin{macrocode}
2581 delete_files($toperl, $fromperl, $toflag, $fromflag, $doneflag, $pipe);
2582 open (LOGFILE, ">$logfile") || die "open(\"$logfile\"): $!\n";
2583 autoflush LOGFILE 1;
2584 if (defined $styfile) {
2585 open (STYFILE, ">$styfile") || die "open(\"$styfile\"): $!\n";
2586 }
2587 % \end{macrocode}
2588 % \begin{macrocode}
2589 if (!$usepipe || !eval {mkfifo($pipe, 0600)}) {
2590 sysopen PIPE, $pipe, O_WRONLY|O_CREAT, 0755;
2591 autoflush PIPE 1;
2592 print PIPE $pipestring;
2593 close PIPE;
2594 $usepipe = 0;
2595 }
2596 % \end{macrocode}
2597 % \begin{macrocode}
2598 defined ($latexpid = fork) || die "fork: $!\n";
2599 unshift @latexcmdline, $latexprog;
2600 if (!$latexpid) {
2601 exec {$latexcmdline[0]} @latexcmdline;
2602 die "exec('@latexcmdline'): $!\n";
2603 }
2604 % \end{macrocode}
2605 %
2606 % \subsubsection{Preparing a sandbox}
2607 %
2608 % \perltex{} uses Perl's |Safe| and |Opcode| modules to declare a secure
2609 % sandbox (|$sandbox|) in which to run Perl code passed to it from
2610 % \LaTeX{}\@. When the sandbox compiles and executes Perl code, it
2611 % permits only operations that are deemed safe. For example, the Perl
2612 % code is allowed by default to assign variables, call functions, and
2613 % execute loops. However, it is not normally allowed to delete files,
2614 % kill processes, or invoke other programs. If \perltex\ is run with
2615 % the |--nosafe| option we bypass the sandbox entirely and execute Perl
2616 % code using an ordinary |eval()| statement.
2617 % \begin{macrocode}
2618 if ($runsafely) {
2619 @permittedops=(":browse") if $#permittedops==-1;
2620 $sandbox->permit_only (@permittedops);
2621 $sandbox_eval = sub {$sandbox->reval($_[0])};
2622 }
2623 else {
2624 $sandbox_eval = \&top_level_eval;
2625 }
2626 % \end{macrocode}
2627 %
2628 % \subsubsection{Communicating with \LaTeX{}}
2629 %
2630 % The following code constitutes \perltex's main loop. Until |latex|
2631 % exits, the loop repeatedly reads Perl code from \LaTeX{}, evaluates
2632 % it, and returns the result as per the protocol described in
2633 % Figure~\vref{fig:comm-protocol}.
2634 % \changes{v1.0a}{2003/08/21}{Undefined \texttt{\string\string\string$/}
2635 % only locally}
2636 %
2637 % \begin{macrocode}
2638 while (1) {
2639 % \end{macrocode}
2640 %
2641 % \begin{perlvar}{$entirefile}
2642 % Wait for |$toflag| to exist. When it does, this implies that
2643 % |$toperl| must exist as well. We read the entire contents of
2644 % |$toperl| into the |$entirefile| variable and process it.
2645 % Figures~\ref{fig:tofile-define} and~\ref{fig:tofile-use} illustrate
2646 % the contents of |$toperl|.
2647 % \begin{macrocode}
2648 awaitexists($toflag);
2649 my $entirefile;
2650 {
2651 local $/ = undef;
2652 open (TOPERL, "<$toperl") || die "open($toperl): $!\n";
2653 $entirefile = <TOPERL>;
2654 close TOPERL;
2655 }
2656 % \end{macrocode}
2657 % \end{perlvar}
2658 %
2659 % \begin{perlvar}{$optag}
2660 % \begin{perlvar}{$macroname}
2661 % \begin{perlvar}{@otherstuff}
2662 % We split the contents of |$entirefile| into an operation tag (either
2663 % |DEF|, |USE|, or |RUN|), the macro name, and everything else
2664 % (|@otherstuff|). If |$optag| is |DEF| then |@otherstuff| will contain
2665 % the Perl code to define. If |$optag| is |USE| then |@otherstuff| will
2666 % be a list of subroutine arguments. If |$optag| is |RUN| then
2667 % |@otherstuff| will be a block of Perl code to run.
2668 % \changes{v2.1}{2010/07/10}{Normalized line endings across
2669 % Unix\slash Windows\slash Macintosh}
2670 % \begin{macrocode}
2671 $entirefile =~ s/\r//g;
2672 my ($optag, $macroname, @otherstuff) =
2673 map {chomp; $_} split "$separator\n", $entirefile;
2674 % \end{macrocode}
2675 % \end{perlvar}
2676 % \end{perlvar}
2677 % \end{perlvar}
2678 %
2679 % We clean up the macro name by deleting all leading non-letters,
2680 % replacing all subsequent non-alphanumerics with ``|_|'', and
2681 % prepending ``|latex_|'' to the macro name.
2682 % \begin{macrocode}
2683 $macroname =~ s/^[^A-Za-z]+//;
2684 $macroname =~ s/\W/_/g;
2685 $macroname = "latex_" . $macroname;
2686 % \end{macrocode}
2687 %
2688 % If we're calling a subroutine, then we make the arguments more
2689 % palatable to Perl by single-quoting them and replacing every
2690 % occurrence of ``|\|'' with ``|\\|'' and every occurrence of ``|'|''
2691 % with ``|\'|''.
2692 % \begin{macrocode}
2693 if ($optag eq "USE") {
2694 foreach (@otherstuff) {
2695 s/\\/\\\\/g;
2696 s/\'/\\\'/g;
2697 $_ = "'$_'";
2698 }
2699 }
2700 % \end{macrocode}
2701 %
2702 % \begin{perlvar}{$perlcode}
2703 % There are three possible values that can be assigned to |$perlcode|.
2704 % If |$optag| is |DEF|, then |$perlcode| is made to contain a definition
2705 % of the user's subroutine, named |$macroname|. If |$optag| is |USE|,
2706 % then |$perlcode| becomes an invocation of |$macroname| which gets
2707 % passed all of the macro arguments. Finally, if |$optag| is |RUN|,
2708 % then |$perlcode| is the unmodified Perl code passed to us from
2709 % \perlmac. Figure~\ref{fig:latex-perl-define} presents an example
2710 % of how the following code converts a \PerlTeX{} macro definition into
2711 % a Perl subroutine definition and Figure~\ref{fig:latex-perl-use}
2712 % presents an example of how the following code converts a \PerlTeX{}
2713 % macro invocation into a Perl subroutine invocation.
2714 %
2715 % \begin{figure}[tbp]
2716 % \centering
2717 % \DeleteShortVerb\|
2718 % \begin{tabular}{l|l|}
2719 % \cline{2-2}
2720 % \LaTeX: & \verb|\perlnewcommand{\mymacro}[2]{%| \\
2721 % & \verb| sprintf "Isn't $_[0] %s $_[1]?\n",| \\
2722 % & \verb| $_[0]>=$_[1] ? ">=" : "<"| \\
2723 % & \verb|}| \\
2724 % \cline{2-2}
2725 % \multicolumn{2}{c}{} \\
2726 % \multicolumn{1}{c}{} & \multicolumn{1}{c}{\Huge$\Downarrow$} \\
2727 % \multicolumn{2}{c}{} \\
2728 % \cline{2-2}
2729 % Perl: & \verb|sub latex_mymacro {| \\
2730 % & \verb| sprintf "Isn't $_[0] %s $_[1]?\n",| \\
2731 % & \verb| $_[0]>=$_[1] ? ">=" : "<"| \\
2732 % & \verb|}| \\
2733 % \cline{2-2}
2734 % \end{tabular}
2735 % \MakeShortVerb\|
2736 % \caption{Conversion from \LaTeX{} to Perl (subroutine definition)}
2737 % \label{fig:latex-perl-define}
2738 % \end{figure}
2739 %
2740 % \begin{figure}[tbp]
2741 % \centering
2742 % \DeleteShortVerb\|
2743 % \begin{tabular}{l|l|}
2744 % \cline{2-2}
2745 % \LaTeX: & \verb|\mymacro{12}{34}| \\
2746 % \cline{2-2}
2747 % \multicolumn{2}{c}{} \\
2748 % \multicolumn{1}{c}{} & \multicolumn{1}{c}{\Huge$\Downarrow$} \\
2749 % \multicolumn{2}{c}{} \\
2750 % \cline{2-2}
2751 % Perl: & \verb|latex_mymacro ('12', '34');| \\
2752 % \cline{2-2}
2753 % \end{tabular}
2754 % \MakeShortVerb\|
2755 % \caption{Conversion from \LaTeX{} to Perl (subroutine invocation)}
2756 % \label{fig:latex-perl-use}
2757 % \end{figure}
2758 %
2759 % \begin{macrocode}
2760 my $perlcode;
2761 if ($optag eq "DEF") {
2762 $perlcode =
2763 sprintf "sub %s {%s}\n",
2764 $macroname, $otherstuff[0];
2765 }
2766 elsif ($optag eq "USE") {
2767 $perlcode = sprintf "%s (%s);\n", $macroname, join(", ", @otherstuff);
2768 }
2769 elsif ($optag eq "RUN") {
2770 $perlcode = $otherstuff[0];
2771 }
2772 else {
2773 die "${progname}: Internal error -- unexpected operation tag \"$optag\"\n";
2774 }
2775 % \end{macrocode}
2776 % \end{perlvar}
2777 %
2778 % Log what we're about to evaluate.
2779 % \begin{macrocode}
2780 print LOGFILE "#" x 31, " PERL CODE ", "#" x 32, "\n";
2781 print LOGFILE $perlcode, "\n";
2782 % \end{macrocode}
2783 %
2784 % \begin{perlvar}{$result}
2785 % \begin{perlvar}{$msg}
2786 % We're now ready to execute the user's code using the |$sandbox_eval|
2787 % function. If a warning occurs we write it as a Perl comment to the
2788 % log file. If an error occurs (i.e.,~|$@| is defined) we replace the
2789 % result (|$result|) with a call to \LaTeXe's |\PackageError| macro to
2790 % return a suitable error message. We produce one error message for
2791 % sandbox policy violations (detected by the error message, |$@|,
2792 % containing the string ``\texttt{trapped by}'') and a different error
2793 % message for all other errors caused by executing the user's code. For
2794 % clarity of reading both warning and error messages, we elide the
2795 % string ``\texttt{at (eval} \meta{number}\texttt{) line}
2796 % \meta{number}''. Once |$result| is defined---as either the resulting
2797 % \LaTeX\ code or as a |\PackageError|---we store it in
2798 % |@macroexpansions| in preparation for writing it to \noperlmac\
2799 % (when \perltex\ is run with \texttt{--makesty}).
2800 % \changes{v2.0}{2009/11/21}{Substituted
2801 % \texttt{\string\string\string\MessageBreak} for newline when
2802 % reporting error messages produced by user code}
2803 % \begin{macrocode}
2804 undef $_;
2805 my $result;
2806 {
2807 my $warningmsg;
2808 local $SIG{__WARN__} =
2809 sub {chomp ($warningmsg=$_[0]); return 0};
2810 $result = $sandbox_eval->($perlcode);
2811 if (defined $warningmsg) {
2812 $warningmsg =~ s/at \(eval \d+\) line \d+\W+//;
2813 print LOGFILE "# ===> $warningmsg\n\n";
2814 }
2815 }
2816 $result = "" if !$result || $optag eq "RUN";
2817 if ($@) {
2818 my $msg = $@;
2819 $msg =~ s/at \(eval \d+\) line \d+\W+//;
2820 $msg =~ s/\n/\\MessageBreak\n/g;
2821 $msg =~ s/\s+/ /;
2822 $result = "\\PackageError{perltex}{$msg}";
2823 my @helpstring;
2824 if ($msg =~ /\btrapped by\b/) {
2825 @helpstring =
2826 ("The preceding error message comes from Perl. Apparently,",
2827 "the Perl code you tried to execute attempted to perform an",
2828 "`unsafe' operation. If you trust the Perl code (e.g., if",
2829 "you wrote it) then you can invoke perltex with the --nosafe",
2830 "option to allow arbitrary Perl code to execute.",
2831 "Alternatively, you can selectively enable Perl features",
2832 "using perltex's --permit option. Don't do this if you don't",
2833 "trust the Perl code, however; malicious Perl code can do a",
2834 "world of harm to your computer system.");
2835 }
2836 else {
2837 @helpstring =
2838 ("The preceding error message comes from Perl. Apparently,",
2839 "there's a bug in your Perl code. You'll need to sort that",
2840 "out in your document and re-run perltex.");
2841 }
2842 my $helpstring = join ("\\MessageBreak\n", @helpstring);
2843 $helpstring =~ s/\. /.\\space\\space /g;
2844 $result .= "{$helpstring}";
2845 }
2846 push @macroexpansions, $result if defined $styfile && $optag eq "USE";
2847 % \end{macrocode}
2848 % \end{perlvar}
2849 % \end{perlvar}
2850 %
2851 % Log the resulting \LaTeX{} code.
2852 % \begin{macrocode}
2853 print LOGFILE "%" x 30, " LATEX RESULT ", "%" x 30, "\n";
2854 print LOGFILE $result, "\n\n";
2855 % \end{macrocode}
2856 %
2857 % We add |\endinput| to the generated \LaTeX{} code to suppress an
2858 % extraneous end-of-line character that \TeX{} would otherwise insert.
2859 % \begin{macrocode}
2860 $result .= '\endinput';
2861 % \end{macrocode}
2862 %
2863 % Continuing the protocol described in Figure~\vref{fig:comm-protocol}
2864 % we now write |$result| (which contains either the result of executing
2865 % the user's or a |\PackageError|) to the |$fromperl| file, delete
2866 % |$toflag|, |$toperl|, and |$doneflag|, and notify \LaTeX{} by touching
2867 % the |$fromflag| file. As a performance optimization, we also write
2868 % |\endinput| into |$pipe| to wake up the |latex| process.
2869 % \begin{macrocode}
2870 open (FROMPERL, ">$fromperl") || die "open($fromperl): $!\n";
2871 syswrite FROMPERL, $result;
2872 close FROMPERL;
2873 % \end{macrocode}
2874 % \begin{macrocode}
2875 delete_files($toflag, $toperl, $doneflag);
2876 % \end{macrocode}
2877 % \begin{macrocode}
2878 open (FROMFLAG, ">$fromflag") || die "open($fromflag): $!\n";
2879 close FROMFLAG;
2880 % \end{macrocode}
2881 % \begin{macrocode}
2882 if (open (PIPE, ">$pipe")) {
2883 autoflush PIPE 1;
2884 print PIPE $pipestring;
2885 close PIPE;
2886 }
2887 % \end{macrocode}
2888 %
2889 % We have to perform one final \LaTeX-to-Perl synchronization step.
2890 % Otherwise, a subsequent |\perl|[|re|]|newcommand| would see that
2891 % |$fromflag| already exists and race ahead, finding that |$fromperl|
2892 % does not contain what it's supposed to.
2893 % \begin{macrocode}
2894 awaitexists($toperl);
2895 delete_files($fromflag);
2896 open (DONEFLAG, ">$doneflag") || die "open($doneflag): $!\n";
2897 close DONEFLAG;
2898 % \end{macrocode}
2899 % Again, we awaken the |latex| process, which is blocked on |$pipe|. If
2900 % writing to the pipe takes more than one second we assume that |latex|
2901 % has exited and trigger the \signal{ALRM} handler
2902 % (page~\pageref{code:sigalrm}).
2903 % \begin{macrocode}
2904 alarm 1;
2905 if (open (PIPE, ">$pipe")) {
2906 autoflush PIPE 1;
2907 print PIPE $pipestring;
2908 close PIPE;
2909 }
2910 alarm 0;
2911 }
2912 % \end{macrocode}
2913 %
2914 % \subsubsection{Final cleanup}
2915 %
2916 % If we exit abnormally we should do our best to kill the child |latex|
2917 % process so that it doesn't continue running forever, holding onto
2918 % system resources.
2919 % \begin{macrocode}
2920 END {
2921 close LOGFILE;
2922 if (defined $latexpid) {
2923 kill (9, $latexpid);
2924 exit 1;
2925 }
2926
2927 if (defined $styfile) {
2928 % \end{macrocode}
2929 % \changes{v1.4}{2007/09/29}{Added support for a \texttt{--makesty}
2930 % option that generates a \PerlTeX-free style file called
2931 % \texttt{noperltex.sty}}
2932 % This is the big moment for the \texttt{--makesty} option. We've
2933 % accumulated the output from each \PerlTeX\ macro invocation into
2934 % |@macroexpansions|, and now we need to produce a
2935 % \noperlmac\ file. We start by generating a boilerplate
2936 % header in which we set up the package and load both \pkgname{perltex}
2937 % and \pkgname{filecontents}.
2938 % \begin{macrocode}
2939 print STYFILE <<"STYFILEHEADER1";
2940 \\NeedsTeXFormat{LaTeX2e}[1999/12/01]
2941 \\ProvidesPackage{noperltex}
2942 [2007/09/29 v1.4 Perl-free version of PerlTeX specific to $jobname.tex]
2943 STYFILEHEADER1
2944 ;
2945 print STYFILE <<'STYFILEHEADER2';
2946 \RequirePackage{filecontents}
2947
2948 % Suppress the "Document must be compiled using perltex" error from perltex.
2949 \let\noperltex@PackageError=\PackageError
2950 \renewcommand{\PackageError}[3]{}
2951 \RequirePackage{perltex}
2952 \let\PackageError=\noperltex@PackageError
2953
2954 % \end{macrocode}
2955 % \begin{macro}{\plmac@macro@invocation@num}
2956 % \begin{macro}{\plmac@show@placeholder}
2957 % \noperlmac\ works by redefining the |\plmac@show@placeholder| macro,
2958 % which normally outputs a framed ``\PerlTeX'' when \perltex\ isn't
2959 % running, changing it to input |noperltex-|\meta{number}|.tex| instead
2960 % (where \meta{number} is the contents of the
2961 % |\plmac@macro@invocation@num| counter). Each
2962 % |noperltex-|\meta{number}|.tex| file contains the output from a single
2963 % invocation of a \PerlTeX-defined macro.
2964 % \begin{macrocode}
2965 % Modify \plmac@show@placeholder to input the next noperltex-*.tex file
2966 % each time a PerlTeX-defined macro is invoked.
2967 \newcount\plmac@macro@invocation@num
2968 \gdef\plmac@show@placeholder#1#2\@empty{%
2969 \ifx#1U\relax
2970 \endgroup
2971 \advance\plmac@macro@invocation@num by 1\relax
2972 \global\plmac@macro@invocation@num=\plmac@macro@invocation@num
2973 \input{noperltex-\the\plmac@macro@[email protected]}%
2974 \else
2975 \endgroup
2976 \fi
2977 }
2978 STYFILEHEADER2
2979 ;
2980 % \end{macrocode}
2981 % \end{macro}
2982 % \end{macro}
2983 %
2984 % Finally, we need to have \noperlmac\ generate each of the
2985 % |noperltex-|\meta{number}|.tex| files. For each element of
2986 % |@macroexpansions| we use one |filecontents| environment to write the
2987 % macro expansion verbatim to a file.
2988 % \begin{macrocode}
2989 foreach my $e (0 .. $#macroexpansions) {
2990 print STYFILE "\n";
2991 printf STYFILE "%% Invocation #%d\n", 1+$e;
2992 printf STYFILE "\\begin{filecontents}{noperltex-%d.tex}\n", 1+$e;
2993 print STYFILE $macroexpansions[$e], "\\endinput\n";
2994 print STYFILE "\\end{filecontents}\n";
2995 }
2996 print STYFILE "\\endinput\n";
2997 close STYFILE;
2998 }
2999
3000 exit 0;
3001 }
3002
3003 __END__
3004 % \end{macrocode}
3005 %
3006 % \subsubsection{\perltex{} POD documentation}
3007 %
3008 % \perltex{} includes documentation in Perl's POD (Plain Old
3009 % Documentation) format. This is used both to produce manual pages and
3010 % to provide usage information when \perltex{} is invoked with the
3011 % |--help| option. The POD documentation is not listed here as part of
3012 % the documented \perltex{} source code because it contains essentially
3013 % the same information as that shown in Section~\ref{sec:perltex-man}.
3014 % If you're curious what the POD source looks like then see the
3015 % generated \perltex{} file.
3016 %
3017 % \iffalse
3018 % \begin{macrocode}
3019
3020 =head1 NAME
3021
3022 perltex - enable LaTeX macros to be defined in terms of Perl code
3023
3024
3025 =head1 SYNOPSIS
3026
3027 perltex
3028 [B<--help>]
3029 [B<--latex>=I<program>]
3030 [B<-->[B<no>]B<safe>]
3031 [B<--permit>=I<feature>]
3032 [B<--makesty>]
3033 [I<latex options>]
3034
3035
3036 =head1 DESCRIPTION
3037
3038 LaTeX -- through the underlying TeX typesetting system -- produces
3039 beautifully typeset documents but has a macro language that is
3040 difficult to program. In particular, support for complex string
3041 manipulation is largely lacking. Perl is a popular general-purpose
3042 programming language whose forte is string manipulation. However, it
3043 has no typesetting capabilities whatsoever.
3044
3045 Clearly, Perl's programmability could complement LaTeX's typesetting
3046 strengths. B<perltex> is the tool that enables a symbiosis between
3047 the two systems. All a user needs to do is compile a LaTeX document
3048 using B<perltex> instead of B<latex>. (B<perltex> is actually a
3049 wrapper for B<latex>, so no B<latex> functionality is lost.) If the
3050 document includes a C<\usepackage{perltex}> in its preamble, then
3051 C<\perlnewcommand> and C<\perlrenewcommand> macros will be made
3052 available. These behave just like LaTeX's C<\newcommand> and
3053 C<\renewcommand> except that the macro body contains Perl code instead
3054 of LaTeX code.
3055
3056
3057 =head1 OPTIONS
3058
3059 B<perltex> accepts the following command-line options:
3060
3061 =over 4
3062
3063 =item B<--help>
3064
3065 Display basic usage information.
3066
3067 =item B<--latex>=I<program>
3068
3069 Specify a program to use instead of B<latex>. For example,
3070 C<--latex=pdflatex> would typeset the given document using
3071 B<pdflatex> instead of ordinary B<latex>.
3072
3073 =item B<-->[B<no>]B<safe>
3074
3075 Enable or disable sandboxing. With the default of B<--safe>,
3076 B<perltex> executes the code from a C<\perlnewcommand> or
3077 C<\perlrenewcommand> macro within a protected environment that
3078 prohibits ``unsafe'' operations such as accessing files or executing
3079 external programs. Specifying B<--nosafe> gives the LaTeX document
3080 I<carte blanche> to execute any arbitrary Perl code, including that
3081 which can harm the user's files. See L<Safe> for more information.
3082
3083 =item B<--permit>=I<feature>
3084
3085 Permit particular Perl operations to be performed. The B<--permit>
3086 option, which can be specified more than once on the command line,
3087 enables finer-grained control over the B<perltex> sandbox. See
3088 L<Opcode> for more information.
3089
3090 =item B<--makesty>
3091
3092 Generate a LaTeX style file called F<noperltex.sty>. Replacing the
3093 document's C<\usepackage{perltex}> line with C<\usepackage{noperltex}>
3094 produces the same output but does not require PerlTeX, making the
3095 document suitable for distribution to people who do not have PerlTeX
3096 installed. The disadvantage is that F<noperltex.sty> is specific to
3097 the document that produced it. Any changes to the document's PerlTeX
3098 macro definitions or macro invocations necessitates rerunning
3099 B<perltex> with the B<--makesty> option.
3100
3101 =back
3102
3103 These options are then followed by whatever options are normally
3104 passed to B<latex> (or whatever program was specified with
3105 C<--latex>), including, for instance, the name of the F<.tex> file to
3106 compile.
3107
3108
3109 =head1 EXAMPLES
3110
3111 In its simplest form, B<perltex> is run just like B<latex>:
3112
3113 perltex myfile.tex
3114
3115 To use B<pdflatex> instead of regular B<latex>, use the B<--latex>
3116 option:
3117
3118 perltex --latex=pdflatex myfile.tex
3119
3120 If LaTeX gives a ``C<trapped by operation mask>'' error and you trust
3121 the F<.tex> file you're trying to compile not to execute malicious
3122 Perl code (e.g., because you wrote it yourself), you can disable
3123 B<perltex>'s safety mechansisms with B<--nosafe>:
3124
3125 perltex --nosafe myfile.tex
3126
3127 The following command gives documents only B<perltex>'s default
3128 permissions (C<:browse>) plus the ability to open files and invoke the
3129 C<time> command:
3130
3131 perltex --permit=:browse --permit=:filesys_open
3132 --permit=time myfile.tex
3133
3134
3135 =head1 ENVIRONMENT
3136
3137 B<perltex> honors the following environment variables:
3138
3139 =over 4
3140
3141 =item PERLTEX
3142
3143 Specify the filename of the LaTeX compiler. The LaTeX compiler
3144 defaults to ``C<latex>''. The C<PERLTEX> environment variable
3145 overrides this default, and the B<--latex> command-line option (see
3146 L</OPTIONS>) overrides that.
3147
3148 =back
3149
3150
3151 =head1 FILES
3152
3153 While compiling F<jobname.tex>, B<perltex> makes use of the following
3154 files:
3155
3156 =over 4
3157
3158 =item F<jobname.lgpl>
3159
3160 log file written by Perl; helpful for debugging Perl macros
3161
3162 =item F<jobname.topl>
3163
3164 information sent from LaTeX to Perl
3165
3166 =item F<jobname.frpl>
3167
3168 information sent from Perl to LaTeX
3169
3170 =item F<jobname.tfpl>
3171
3172 ``flag'' file whose existence indicates that F<jobname.topl> contains
3173 valid data
3174
3175 =item F<jobname.ffpl>
3176
3177 ``flag'' file whose existence indicates that F<jobname.frpl> contains
3178 valid data
3179
3180 =item F<jobname.dfpl>
3181
3182 ``flag'' file whose existence indicates that F<jobname.ffpl> has been
3183 deleted
3184
3185 =item F<noperltex-#.tex>
3186
3187 file generated by F<noperltex.sty> for each PerlTeX macro invocation
3188
3189 =back
3190
3191
3192 =head1 NOTES
3193
3194 B<perltex>'s sandbox defaults to what L<Opcode> calls ``C<:browse>''.
3195
3196
3197 =head1 SEE ALSO
3198
3199 latex(1), pdflatex(1), perl(1), Safe(3pm), Opcode(3pm)
3200
3201
3202 =head1 AUTHOR
3203
3204 Scott Pakin, I<[email protected]>
3205 % \end{macrocode}
3206 % \fi
3207 %
3208 % \iffalse
3209 %</perltex>
3210 % \fi
3211 %
3212 % ^^A Keep track of the number of lines of code in perltex.
3213 % \makeatletter
3214 % \immediate\write\@auxout{^^A
3215 % \noexpand\gdef\noexpand\perltexlines{\the\c@CodelineNo}}
3216 % \makeatother
3217 %
3218 %
3219 % \subsection{Porting to other languages}
3220 % \label{sec:porting}
3221 %
3222 % Perl is a natural choice for a \LaTeX{} macro language because of its
3223 % excellent support for text manipulation including extended regular
3224 % expressions, string interpolation, and ``here'' strings, to name a few
3225 % nice features. However, Perl's syntax is unusual and its semantics
3226 % are rife with annoying special cases. Some users will therefore long
3227 % for a \meta{some-language-other-than-Perl}\TeX\@. Fortunately,
3228 % porting \PerlTeX{} to use a different language should be fairly
3229 % straightforward. \perltex{} will need to be rewritten in the target
3230 % language, of course, but \perlmac{} modifications will likely be
3231 % fairly minimal. In all probability, only the following changes will
3232 % need to be made:
3233 %
3234 % \begin{itemize}
3235 % \item Rename \perlmac{} and \perltex{} (and choose a package name
3236 % other than ``\PerlTeX'') as per the \PerlTeX{} license agreement
3237 % (Section~\ref{sec:license}).
3238 %
3239 % \item In your replacement for \perlmac, replace all occurrences of
3240 % ``|plmac|'' with a different string.
3241 %
3242 % \item In your replacement for \perltex, choose different file
3243 % extensions for the various helper files.
3244 % \end{itemize}
3245 %
3246 % The importance of these changes is that they help ensure version
3247 % consistency and that they make it possible to run
3248 % \meta{some-language-other-than-Perl}\TeX{} alongside \PerlTeX,
3249 % enabling multiple programming languages to be utilized in the same
3250 % \LaTeX{} document.
3251 %
3252 % \Finale
3253 \endinput