% \iffalse meta-comment % (The MIT License) % % Copyright (c) 2021-2022 Yegor Bugayenko % % Permission is hereby granted, free of charge, to any person obtaining a copy % of this software and associated documentation files (the 'Software'), to deal % in the Software without restriction, including without limitation the rights % to use, copy, modify, merge, publish, distribute, sublicense, and/or sell % copies of the Software, and to permit persons to whom the Software is % furnished to do so, subject to the following conditions: % % The above copyright notice and this permission notice shall be included in all % copies or substantial portions of the Software. % % THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR % IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, % FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE % AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER % LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, % OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE % SOFTWARE. % \fi % \CheckSum{0} % % \CharacterTable % {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 % 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 % Digits \0\1\2\3\4\5\6\7\8\9 % Exclamation \! Double quote \" Hash (number) \# % Dollar \$ Percent \% Ampersand \& % Acute accent \' Left paren \( Right paren \) % Asterisk \* Plus \+ Comma \, % Minus \- Point \. Solidus \/ % Colon \: Semicolon \; Less than \< % Equals \= Greater than \> Question mark \? % Commercial at \@ Left bracket \[ Backslash \\ % Right bracket \] Circumflex \^ Underscore \_ % Grave accent \` Left brace \{ Vertical bar \| % Right brace \} Tilde \~} % \GetFileInfo{iexec.dtx} % \DoNotIndex{\endgroup,\begingroup,\let,\else,\fi,\newcommand,\newenvironment} % \iffalse %<*driver> \ProvidesFile{iexec.dtx} % %\NeedsTeXFormat{LaTeX2e} %\ProvidesPackage{iexec} %<*package> [01.10.2022 0.6.1 Inputable Shell Executions] % %<*driver> \documentclass{ltxdoc} \usepackage[tt=false, type1=true]{libertine} \usepackage{iexec} \usepackage{href-ul} \raggedbottom \setlength{\parindent}{0pt} \setlength{\columnsep}{32pt} \setlength{\parskip}{6pt} \PageIndex \EnableCrossrefs \CodelineIndex \RecordChanges \begin{document} \DocInput{iexec.dtx} \PrintChanges \PrintIndex \end{document} % % \fi % \title{|iexec|: \LaTeX{} Package \\ for Inputable Shell Executions\thanks{The sources are in GitHub at \href{https://github.com/yegor256/iexec}{yegor256/iexec}}} % \author{Yegor Bugayenko \\ \texttt{yegor256@gmail.com}} % \date{\filedate, \fileversion} % % \maketitle % % \section{Introduction} % % This package helps you execute shell commands right from the % document and then put their output to the document: % % \begin{multicols}{2} % \setlength{\parskip}{0pt} % \small % \raggedcolumns %\iffalse %<*verb> %\fi \begin{verbatim} \documentclass{article} \usepackage{iexec} \begin{document} Today is \iexec{date +\%e-\%b-\%Y} \end{document} \end{verbatim} %\iffalse % %\fi % % \columnbreak % % Today is \iexec{date +\%e-\%b-\%Y} % \end{multicols} % \begin{macro}{\iexec} % The only command provided by this package is |\iexec| \oarg{options} \marg{cmd}. % Its only mandatory argument \meta{cmd} is the command to be executed % through the terminal shell (bash, or whatever is set as the default one % on your user console). % \end{macro} % You have to run |pdflatex| (or just |latex|) % with the |--shell-escape| flag % in order to let |shellesc| (the package we use) % to execute your shell command. % \section{Options} % \begin{macro}{quiet} % If you don't want the output to be visible, % use |\phantom\{\iexec{...}}|. % Otherwise, you can use |quiet| option: %\iffalse %<*verb> %\fi \begin{verbatim} \documentclass{article} \usepackage{iexec} \begin{document} I just want to delete some file: \iexec[quiet]{rm -f foo.txt} \end{document} \end{verbatim} %\iffalse % %\fi % \end{macro} % In this case, whatever the shell command produces will not be included % into the document. % \begin{macro}{stdout} % The output of your code is saved into the file provided as the % second optional argument of |\iexec| (the default value is |iexec.tmp|): %\iffalse %<*verb> %\fi \begin{verbatim} \documentclass{article} \usepackage{iexec} \begin{document} Today is \iexec[stdout=date.txt]{date +\%e-\%b-\%Y | tr -d '\\n'}. \end{document} \end{verbatim} %\iffalse % %\fi % The tailing part of the command here removes all ends-of-line. % \end{macro} % \begin{macro}{trace} % The file specified will be deleted right after its usage. If you don't % want this to happen, use |trace| package option: all files will remain % in the directory where they were created. % It's possible to turn tracing on globbaly, for the entire document, using % |trace| option of the package: %\iffalse %<*verb> %\fi \begin{verbatim} \documentclass{article} \usepackage[trace]{iexec} \begin{document} This file won't be deleted: \iexec[stdout=me.txt]{whoami}. \end{document} \end{verbatim} %\iffalse % %\fi % \end{macro} % \StopEventually{} % \section{Implementation} % \changes{v0.2.0}{2021/07/10}{Initial version} % \changes{v0.4.0}{2021/08/01}{Runtime verification for --shell-escape option} % \changes{v0.4.1}{2021/08/08}{Options trace, stdout, and quiet added} % \changes{v0.5.0}{2022/01/08}{Major bug fixes} % \iffalse \RequirePackage{shellesc} \RequirePackage{pgfkeys} \RequirePackage{xkeyval} \makeatletter\newif\ifiexec@trace \DeclareOptionX{trace}{\iexec@tracetrue} \ProcessOptionsX\relax\makeatother \makeatletter\pgfkeys{ /iexec/.is family, /iexec, stdout/.estore in = \iexec@stdout, stdout/.default = iexec.tmp, trace/.estore in = \iexec@traceit, quiet/.estore in = \iexec@quiet, stdout }\makeatother % \fi % \begin{macro}{\iexec} % It is implemented with the help of |\ShellEscape| from |shellesc| package: % \begin{macrocode} \makeatletter\newcommand\iexec[2][]{% \begingroup \pgfqkeys{/iexec}{#1}% % \end{macrocode} % First, we verify that |latex| is running with |--shell-escape| option, since without % it nothing will work; so, it's better to throw an error earlier than later: % \begin{macrocode} \ifdefined\pdfshellescape\ifnum\pdfshellescape=1\else% \PackageError{iexec}{You must run latex with --shell-escape option}{}% \fi\fi% \begingroup% % \end{macrocode} % Then, we define a few special chars in order to escape them in the shell % (the full % list of them is in \href{https://ctan.mirror.norbert-ruehl.de/info/macros2e/macros2e.pdf}{macros2e}): % \begin{macrocode} \let\%\@percentchar% \let\\\@backslashchar% \let\{\@charlb% \let\}\@charrb% % \end{macrocode} % Then, we execute it: % \begin{macrocode} \ShellEscape{#2 > \iexec@stdout}% % \end{macrocode} % Then, a message is printed to TeX log: % \begin{macrocode} \message{^^Jiexec: [#2 > \iexec@stdout]^^J}% \endgroup% % \end{macrocode} % Then, include the produced output into the current document: % \begin{macrocode} \ifdefined\iexec@quiet \message{^^Jiexec: Due to 'quiet' we didn't read the content of '\iexec@stdout'^^J}% \else% \input{\iexec@stdout}% \message{^^Jiexec: The content of '\iexec@stdout' was included into the document^^J}% \fi% % \end{macrocode} % Finally, delete the file or leave it untouched: % \begin{macrocode} \ifiexec@trace% \message{^^Jiexec: Due to package option 'trace', the file '\iexec@stdout' was not deleted^^J}% \else% \ifdefined\iexec@traceit% \message{^^Jiexec: Due to 'trace' option, the file '\iexec@stdout' was not deleted^^J}% \else% \ShellEscape{rm \iexec@stdout}% \message{^^Jiexec: The file '\iexec@stdout' was deleted^^J}% \fi% \fi% \endgroup }\makeatother % \end{macrocode} % \end{macro} % \Finale %\clearpage % %\PrintChanges %\clearpage %\PrintIndex