Debian Codegraph @

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

raw
1 % \iffalse meta-comment
2 % (The MIT License)
3 %
4 % Copyright (c) 2021-2025 Yegor Bugayenko
5 %
6 % Permission is hereby granted, free of charge, to any person obtaining a copy
7 % of this software and associated documentation files (the 'Software'), to deal
8 % in the Software without restriction, including without limitation the rights
9 % to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10 % copies of the Software, and to permit persons to whom the Software is
11 % furnished to do so, subject to the following conditions:
12 %
13 % The above copyright notice and this permission notice shall be included in all
14 % copies or substantial portions of the Software.
15 %
16 % THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 % IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 % FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19 % AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 % LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21 % OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22 % SOFTWARE.
23 % \fi
24
25 % \CheckSum{0}
26 %
27 % \CharacterTable
28 % {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
29 % 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
30 % Digits \0\1\2\3\4\5\6\7\8\9
31 % Exclamation \! Double quote \" Hash (number) \#
32 % Dollar \$ Percent \% Ampersand \&
33 % Acute accent \' Left paren \( Right paren \)
34 % Asterisk \* Plus \+ Comma \,
35 % Minus \- Point \. Solidus \/
36 % Colon \: Semicolon \; Less than \<
37 % Equals \= Greater than \> Question mark \?
38 % Commercial at \@ Left bracket \[ Backslash \\
39 % Right bracket \] Circumflex \^ Underscore \_
40 % Grave accent \` Left brace \{ Vertical bar \|
41 % Right brace \} Tilde \~}
42
43 % \GetFileInfo{iexec.dtx}
44 % \DoNotIndex{\endgroup,\begingroup,\let,\else,\fi,\newcommand,\newenvironment}
45
46 % \iffalse
47 %<*driver>
48 \ProvidesFile{iexec.dtx}
49 %</driver>
50 %<package>\NeedsTeXFormat{LaTeX2e}
51 %<package>\ProvidesPackage{iexec}
52 %<*package>
53 [2025/01/16 0.15.0 Inputable Shell Executions]
54 %</package>
55 %<*driver>
56 \documentclass{ltxdoc}
57 \usepackage[tt=false, type1=true]{libertine}
58 \usepackage{microtype}
59 \AddToHook{env/verbatim/begin}{\microtypesetup{protrusion=false}}
60 \usepackage{xcolor}
61 \usepackage[dtx]{docshots}
62 \usepackage{iexec}
63 \usepackage{href-ul}
64 \PageIndex
65 \EnableCrossrefs
66 \CodelineIndex
67 \RecordChanges
68 \begin{document}
69 \DocInput{iexec.dtx}
70 \PrintChanges
71 \PrintIndex
72 \end{document}
73 %</driver>
74 % \fi
75
76 % \title{|iexec|: \LaTeX{} Package \\ for Inputable Shell Executions\thanks{The sources are in GitHub at \href{https://github.com/yegor256/iexec}{yegor256/iexec}}}
77 % \author{Yegor Bugayenko \\ \texttt{[email protected]}}
78 % \date{\filedate, \fileversion}
79 %
80 % \maketitle
81 %
82 % \textbf{\color{red}NB!}
83 % This package doesn't work on Windows!
84 %
85 % \section{Introduction}
86 %
87 % This package helps you execute shell commands right from the
88 % document and then put their output to the document:
89 %
90 % \begin{docshot}
91 % \documentclass{article}
92 % \usepackage{iexec}
93 % \usepackage[paperwidth=3in]{geometry}
94 % \pagestyle{empty}
95 % \begin{document}
96 % Today is \textbf{%
97 % \iexec{date +\%e-\%b-\%Y}}\unskip!
98 % \end{document}
99 % \end{docshot}
100
101 % \DescribeMacro{\iexec} The only command provided by this package is
102 % |\iexec| \oarg{options} \marg{cmd}.
103 % Its only mandatory argument \meta{cmd} is the command to be executed
104 % through the terminal shell (|bash|, or whatever is set as the default one
105 % in your console).
106
107 % You have to run |pdflatex| (or just |latex|)
108 % with the |--shell-escape| flag
109 % in order to let \href{https://ctan.org/pkg/shellesc}{shellesc}
110 % execute your shell command.
111
112 % It is important to remember that \LaTeX{} always uses ``|/bin/sh|'' shell.
113 % This can't be changed,
114 % as \href{https://tex.stackexchange.com/questions/698312}{explained here}.
115
116 % \section{Options}
117
118 % \DescribeMacro{quiet}
119 % If you don't want the output to be visible,
120 % use |\phantom\{\iexec{...}}|.
121 % Otherwise, you can use the ``|quiet|'' option:
122 %\iffalse
123 %<*verb>
124 %\fi
125 \begin{verbatim}
126 I just want to delete some file:
127 \iexec[quiet]{rm -f foo.txt}
128 \end{verbatim}
129 %\iffalse
130 %</verb>
131 %\fi
132 % In this case, whatever the shell command produces will not be included
133 % into the document.
134
135 % \DescribeMacro{stdout}
136 % The output of your code is saved into the file provided as an
137 % optional argument of |\iexec| (the default value is ``|iexec.tmp|''):
138 %\iffalse
139 %<*verb>
140 %\fi
141 \begin{verbatim}
142 Today is \iexec[stdout=date.txt]{date +\%e-\%b-\%Y | tr -d '\\n'}.
143 \end{verbatim}
144 %\iffalse
145 %</verb>
146 %\fi
147 % The tailing part of the command here removes all ends-of-line.
148
149 % \DescribeMacro{stderr}
150 % The error output of the code is saved into the file provided as an
151 % optional argument of |\iexec| (by default the error output
152 % is streamed into ``|stdout|''):
153 %\iffalse
154 %<*verb>
155 %\fi
156 \begin{verbatim}
157 Today is \iexec[stderr=my.txt]{broken-command}.
158 \end{verbatim}
159 %\iffalse
160 %</verb>
161 %\fi
162
163 % \DescribeMacro{exit}
164 % The exit code of the command is saved into a file. You can change the name of it
165 % using the ``|exit|'' option:
166 %\iffalse
167 %<*verb>
168 %\fi
169 \begin{verbatim}
170 Today is \iexec[exit=code.txt]{./broken-command.sh}.
171 \end{verbatim}
172 %\iffalse
173 %</verb>
174 %\fi
175
176 % \DescribeMacro{trace}
177 % The file specified will be deleted right after its usage. If you don't
178 % want this to happen, use the ``|trace|'' package option: all files will remain
179 % in the directory where they were created.
180 % It's possible to turn on the tracing globbaly, for the entire document, using
181 % the ``|trace|'' option of the package:
182 %\iffalse
183 %<*verb>
184 %\fi
185 \begin{verbatim}
186 \documentclass{article}
187 \usepackage[trace]{iexec}
188 \begin{document}
189 This file won't be deleted: \iexec[stdout=me.txt]{whoami}.
190 \end{document}
191 \end{verbatim}
192 %\iffalse
193 %</verb>
194 %\fi
195
196 % \DescribeMacro{append}
197 % The ``stdout'' produced will be appended to the file specified:
198 %\iffalse
199 %<*verb>
200 %\fi
201 \begin{verbatim}
202 \documentclass{article}
203 \usepackage[trace]{iexec}
204 \begin{document}
205 \iexec[append,stdout=foo.txt,quiet]{echo 'Hello, '}
206 \iexec[append,stdout=foo.txt,quiet]{echo 'Jeffrey!'}
207 \input{foo.txt}
208 \end{document}
209 \end{verbatim}
210 %\iffalse
211 %</verb>
212 %\fi
213
214 % \DescribeMacro{unskip}
215 % In order to remove the tailing spacing after the content, you may use |unskip| package option,
216 % which will append |\unskip| commmand to every |\iexec|:
217 %\iffalse
218 %<*verb>
219 %\fi
220 \begin{verbatim}
221 \documentclass{article}
222 \usepackage[unskip]{iexec}
223 \begin{document}
224 Today is \iexec{date +\%Y}!
225 \end{document}
226 \end{verbatim}
227 %\iffalse
228 %</verb>
229 %\fi
230
231 % \DescribeMacro{log}
232 % The ``stdout'' produced will be printed in the \TeX{} log:
233 %\iffalse
234 %<*verb>
235 %\fi
236 \begin{verbatim}
237 \iexec[log]{echo 'Hello, \\LaTeX!'}
238 \end{verbatim}
239 %\iffalse
240 %</verb>
241 %\fi
242
243 % \DescribeMacro{null}
244 % The ``stdout'' of the command will be sent to ``|/dev/null|'':
245 %\iffalse
246 %<*verb>
247 %\fi
248 \begin{verbatim}
249 \iexec[null]{rm some-file.txt}
250 \end{verbatim}
251 %\iffalse
252 %</verb>
253 %\fi
254
255 % \DescribeMacro{ignore}
256 % By default, we report an error if the exit code is not equal to zero. You can suppress
257 % this with the ``|ignore|'' option:
258 %\iffalse
259 %<*verb>
260 %\fi
261 \begin{verbatim}
262 \iexec[ignore]{broken-command}
263 \end{verbatim}
264 %\iffalse
265 %</verb>
266 %\fi
267
268 % \DescribeMacro{maybe}
269 % If |-shell-escape| is not set, the |\iexec| command will lead to compilation failure. This
270 % failure may be avoided with the help of the |maybe| option, which means that the execution
271 % of |\iexec| must be quietly skipped if |-shell-escape| is not set:
272 %\iffalse
273 %<*verb>
274 %\fi
275 \begin{verbatim}
276 \iexec[maybe]{echo 'Hello, world!'}
277 \end{verbatim}
278 %\iffalse
279 %</verb>
280 %\fi
281
282 % \StopEventually{}
283
284 % \section{Implementation}
285
286 % First, we include the \href{https://ctan.org/pkg/shellesc}{shellesc} package, which
287 % we use in order to execute shell commands:
288 % \begin{macrocode}
289 \RequirePackage{shellesc}
290 % \end{macrocode}
291
292 % Then, we parse package options, with the help
293 % of \href{https://ctan.org/pkg/pgfopts}{pgfopts}:
294 % \changes{0.14.0}{2024/01/14}{The \texttt{xkeyval} package is not used anymore. Instead, we use \texttt{pfgopts} in order to parse package options.}
295 % \begin{macrocode}
296 \RequirePackage{pgfopts}
297 \pgfkeys{
298 /iexec/.cd,
299 trace/.store in=\iexec@trace,
300 }
301 \ProcessPgfPackageOptions{/iexec}
302 % \end{macrocode}
303
304 % Then, we prepare to parse the options of the |\iexec| command, with the help
305 % of \href{https://ctan.org/pkg/pgfkeys}{pgfkeys}:
306 % \begin{macrocode}
307 \RequirePackage{pgfkeys}
308 \makeatletter\pgfkeys{
309 /iexec/.is family,
310 /iexec,
311 exit/.store in = \iexec@exit,
312 exit/.default = iexec.ret,
313 stdout/.store in = \iexec@stdout,
314 stdout/.default = iexec.tmp,
315 stderr/.store in = \iexec@stderr,
316 trace/.store in = \iexec@traceit,
317 append/.store in = \iexec@append,
318 log/.store in = \iexec@log,
319 null/.store in = \iexec@null,
320 unskip/.store in = \iexec@unskip,
321 quiet/.store in = \iexec@quiet,
322 ignore/.store in = \iexec@ignore,
323 maybe/.store in = \iexec@maybe,
324 stdout,exit
325 }\makeatother
326 % \end{macrocode}
327
328 % \begin{macro}{\iexec@typeout}
329 % Then, we define an internal command |\iexec@typeout| for printing the content of a file,
330 % as suggested \href{https://tex.stackexchange.com/questions/660808}{here}:
331 % \begin{macrocode}
332 \RequirePackage{expl3}
333 \makeatletter\ExplSyntaxOn
334 \NewDocumentCommand{\iexec@typeout}{m}{
335 \iexec_typeout_file:n { #1 }}
336 \ior_new:N \g_iexec_typeout_ior
337 \cs_new_protected:Nn \iexec_typeout_file:n
338 {
339 \ior_open:Nn \g_iexec_typeout_ior { #1 }
340 \ior_str_map_inline:Nn \g_iexec_typeout_ior
341 {\iow_term:n { ##1 }}
342 \ior_close:N \g_iexec_typeout_ior
343 }
344 \ExplSyntaxOff\makeatother
345 % \end{macrocode}
346 % \end{macro}
347
348 % \begin{macro}{\iexec}
349 % Then, we define |\iexec| command.
350 % It is implemented with the help of |\ShellEscape| from |shellesc| package:
351 % \changes{0.10.0}{2022/10/19}{The file "iexec.ret" is reused for all scripts.}
352 % \changes{0.10.0}{2022/10/19}{The option ``\texttt{ignore}'' suppresses the checking of ``\texttt{iexec.ret}'' value.}
353 % \changes{0.7.0}{2022/09/25}{The option "append" was introduced --- if it's turned on, stdout will be appended to the file, instead of rewriting it (this is how it was before).}
354 % \changes{0.7.0}{2022/09/25}{The option ``\texttt{log}'' was introduced, to turn on log/debug messages in TeX log (they were all visible always, which was sometimes annoying. Also, this option enables printing of the entire content of stdout to the log too (this may be pretty convenient for debugging).}
355 % \changes{0.11.0}{2022/10/22}{The option ``\texttt{exit}'' allows to change the name of the file with exit code.}
356 % \changes{0.12.0}{2023/10/12}{The option ``\texttt{unskip}'' adds \texttt{\char`\\unskip} after each \texttt{\char`\\iexec}, in order to trip the tailing end of line space.}
357 % \begin{macrocode}
358 \makeatletter
359 \newread\iexec@exitfile
360 \newcommand\iexec[2][]{%
361 \begingroup%
362 \pgfqkeys{/iexec}{#1}%
363 % \end{macrocode}
364 % First, we verify that |latex| is running with |--shell-escape| option, since without
365 % it nothing will work; so, it's better to throw an error earlier than later:
366 % \begin{macrocode}
367 \ifnum\ShellEscapeStatus=1%
368 \begingroup%
369 % \end{macrocode}
370 % Then, we start the log from a clean line:
371 % \begin{macrocode}
372 \ifdefined\iexec@log%
373 \message{^^J}%
374 \fi%
375 % \end{macrocode}
376 % Then, we define a few special chars in order to escape them in the shell
377 % (the full
378 % list of them is in \href{https://ctan.mirror.norbert-ruehl.de/info/macros2e/macros2e.pdf}{macros2e}):
379 % \begin{macrocode}
380 \let\%\@percentchar%
381 \let\\\@backslashchar%
382 \let\{\@charlb%
383 \let\}\@charrb%
384 % \end{macrocode}
385 % Then, we execute it and save exit code into a file (where we also add \texttt{\%} in order to trim the content to exactly one number, as suggested \href{https://tex.stackexchange.com/questions/662756}{here}):
386 % \changes{0.10.0}{2022/10/19}{The ability to track exit code was added. Now, the code is saved into ``\texttt{iexec.ret}'' file, which is then read and checked for zero value.}
387 % \changes{0.8.0}{2022/10/05}{The option "null" was introduced, allowing redirection of stdout to ``\texttt{/dev/null}''. Doesn't work on Windows, though.}
388 % \changes{0.9.0}{2022/10/15}{The option ``\texttt{stderr}'' was introduced, allowing redirection of stderr to a file. Without this option specified, stderr will go to stdout.}
389 % \changes{0.11.0}{2022/10/22}{The file with exit code now contains just numbers, without end of line.}
390 % \changes{0.11.1}{2022/10/23}{When exit code is printed to the file, we add percentchar at the end of line in order to avoid extra space when reading it back.}
391 % \changes{0.11.3}{2022/10/29}{Bug fixed, because of which we had an extra leading space.}
392 % \changes{0.11.4}{2022/11/01}{In this version we escape dollar sign with \texttt{\char`\\string} command.}
393 % \begin{macrocode}
394 \def\iexec@cmd{(#2)
395 \ifdefined\iexec@append>\fi>
396 \ifdefined\iexec@null/dev/null\else\iexec@stdout\fi
397 \space\ifdefined\iexec@stderr2>\iexec@stderr\else2>&1\fi;
398 /bin/echo -n \string$?\% >\iexec@exit}%
399 \ShellEscape{\iexec@cmd}%
400 % \end{macrocode}
401 % Then, a message is printed to \TeX{} log:
402 % \begin{macrocode}
403 \ifdefined\iexec@log%
404 \message{iexec: [\iexec@cmd]^^J}%
405 \fi%
406 \endgroup%
407 % \end{macrocode}
408 % Then, we read back the exit code, from the file:
409 % \begin{macrocode}
410 \immediate\openin\iexec@exitfile=\iexec@exit%
411 \read\iexec@exitfile to \iexec@code%
412 \immediate\closein\iexec@exitfile%
413 % \end{macrocode}
414 % Then, if required, we print the content of the stdout file to \TeX{} log:
415 % \changes{0.11.2}{2022/10/25}{If execution fails, we print the content of ``\texttt{stdout}'' anyway, even if the ``\texttt{log}'' is not turned on.}
416 % \begin{macrocode}
417 \ifdefined\iexec@null\else%
418 \IfFileExists
419 {\iexec@stdout}
420 {}
421 {\PackageError{iexec}{The "\iexec@stdout" file is absent
422 after processing, looks like some internal error}{}}%
423 \ifdefined\iexec@log%
424 \message{iexec: This is the content of '\iexec@stdout'\ifdefined\pdffilesize
425 \space(\pdffilesize{\iexec@stdout} bytes)\else\fi:^^J}%
426 \IfFileExists
427 {\iexec@stdout}
428 {\iexec@typeout{\iexec@stdout}}
429 {\PackageError{iexec}{The "\iexec@stdout" file is absent
430 after processing, looks like some internal error}{}}%
431 \message{<EOF>^^J}%
432 \else%
433 \ifnum\iexec@code=0\else%
434 \ifdefined\iexec@ignore\else%
435 \message{iexec: See the content of '\iexec@stdout'\ifdefined\pdffilesize
436 \space(\pdffilesize{\iexec@stdout} bytes)\fi
437 after failure:^^J}%
438 \iexec@typeout{\iexec@stdout}%
439 \message{<EOF>^^J}%
440 \fi%
441 \fi%
442 \fi%
443 \fi%
444 % \end{macrocode}
445 % Then, we check whether it's zero or not (if not zero, we either print a message or fail the build, depending on the presence of |ignore| option):
446 % \begin{macrocode}
447 \ifnum\iexec@code=0\else%
448 \ifdefined\iexec@ignore%
449 \ifdefined\iexec@log%
450 \message{iexec: Execution failure ignored,
451 the exit code was \iexec@code^^J}%
452 \fi%
453 \else%
454 \PackageError{iexec}{Execution failure,
455 the exit code was \iexec@code}{}%
456 \fi%
457 \fi%
458 % \end{macrocode}
459 % Then, we include the produced output into the current document:
460 % \begin{macrocode}
461 \ifdefined\iexec@null\else%
462 \ifdefined\iexec@quiet%
463 \ifdefined\iexec@log%
464 \message{iexec: Due to 'quiet' option we didn't read
465 the content of '\iexec@stdout'
466 \ifdefined\pdffilesize (\pdffilesize{\iexec@stdout}
467 bytes)\fi^^J}%
468 \fi%
469 \else%
470 \ifdefined\iexec@log%
471 \message{iexec: We are going to include the content of
472 '\iexec@stdout'\ifdefined\pdffilesize (\pdffilesize
473 {\iexec@stdout} bytes)\fi...^^J}%
474 \fi%
475 \input{\iexec@stdout}%
476 \ifdefined\iexec@unskip\unskip\fi%
477 \message{iexec: The content of '\iexec@stdout'
478 was included into the document^^J}%
479 \fi\fi%
480 % \end{macrocode}
481 % Then, we delete the file or leave it untouched:
482 % \begin{macrocode}
483 \ifdefined\iexec@null\else%
484 \ifdefined\iexec@trace%
485 \ifdefined\iexec@log%
486 \message{iexec: Due to package option 'trace',
487 the files '\iexec@stdout' and `\iexec@exit` were
488 not deleted^^J}%
489 \fi%
490 \else%
491 \ifdefined\iexec@traceit%
492 \ifdefined\iexec@log%
493 \message{iexec: Due to 'trace' package option,
494 the files '\iexec@stdout' and '\iexec@exit'
495 were not deleted^^J}%
496 \fi%
497 \else%
498 \ShellEscape{rm \iexec@stdout}%
499 \ifdefined\iexec@log%
500 \message{iexec: The file '\iexec@stdout' was deleted^^J}%
501 \fi%
502 \ShellEscape{rm \iexec@exit}%
503 \ifdefined\iexec@log%
504 \message{iexec: The file '\iexec@exit' was deleted^^J}%
505 \fi%
506 \fi%
507 \fi\fi%
508 % \end{macrocode}
509 % \changes{0.14.0}{2024/01/14}{The \texttt{maybe} option introduced, allowing the user to skip the entire execution of the \texttt{\char`\\iexec} command, when \texttt{-shell-escape} option is off.}
510 % Finally, we ignore the whole story if the |maybe| option is provided
511 % and the |-shell-escape| is not set:
512 % \begin{macrocode}
513 \else%
514 \ifdefined\iexec@maybe%
515 \message{iexec: The execution skipped because -shell-escape
516 is not set and 'maybe' option is provided^^J}%
517 \else%
518 \PackageError{iexec}{You must run TeX processor with
519 --shell-escape option}{}%
520 \fi%
521 \fi%
522 \endgroup%
523 }\makeatother
524 % \end{macrocode}
525 % \end{macro}
526
527 % \begin{macrocode}
528 \endinput
529 % \end{macrocode}
530
531 % \Finale
532
533 %\clearpage
534 %\PrintChanges
535
536 %\clearpage
537 %\PrintIndex