summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/iexec/iexec.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/iexec/iexec.dtx')
-rw-r--r--macros/latex/contrib/iexec/iexec.dtx284
1 files changed, 284 insertions, 0 deletions
diff --git a/macros/latex/contrib/iexec/iexec.dtx b/macros/latex/contrib/iexec/iexec.dtx
new file mode 100644
index 0000000000..fb38432b0e
--- /dev/null
+++ b/macros/latex/contrib/iexec/iexec.dtx
@@ -0,0 +1,284 @@
+% \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}
+%</driver>
+%<package>\NeedsTeXFormat{LaTeX2e}
+%<package>\ProvidesPackage{iexec}
+%<*package>
+[01.10.2022 0.6.1 Inputable Shell Executions]
+%</package>
+%<*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}
+%</driver>
+% \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
+%</verb>
+%\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
+%</verb>
+%\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
+%</verb>
+%\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
+%</verb>
+%\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