| 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 |