diff options
author | Norbert Preining <norbert@preining.info> | 2022-10-02 03:04:14 +0000 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2022-10-02 03:04:14 +0000 |
commit | 097f244236b682cc77c6ecf25be4150091d8daf9 (patch) | |
tree | 26998e72d2b56a87033d9fb72923258fc93ebe53 /macros/latex/contrib/iexec/iexec.dtx | |
parent | 4043e29dc8ac56047ac45f872a2ea1f3031b6b05 (diff) |
CTAN sync 202210020304
Diffstat (limited to 'macros/latex/contrib/iexec/iexec.dtx')
-rw-r--r-- | macros/latex/contrib/iexec/iexec.dtx | 284 |
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 |