diff options
author | Karl Berry <karl@freefriends.org> | 2016-01-31 23:48:08 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2016-01-31 23:48:08 +0000 |
commit | 07aaa313db3abb8f932308307c9ca78bb1c3054d (patch) | |
tree | de018a29452c3b2131a23c228458012b15686e79 /Master/texmf-dist/source/latex/tools/shellesc.dtx | |
parent | 326c162a7ec8088d104101b4739c727d824ae5f7 (diff) |
latex2e 2016/02/01
git-svn-id: svn://tug.org/texlive/trunk@39528 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/tools/shellesc.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/tools/shellesc.dtx | 235 |
1 files changed, 235 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/tools/shellesc.dtx b/Master/texmf-dist/source/latex/tools/shellesc.dtx new file mode 100644 index 00000000000..636167d3504 --- /dev/null +++ b/Master/texmf-dist/source/latex/tools/shellesc.dtx @@ -0,0 +1,235 @@ +% \iffalse +%% Source File: shellesc.dtx +%% Copyright 2015-2016 LaTeX3 project +%% +%% This file may be distributed under the terms of the LPPL. +%% See README for details. +% +%<*dtx> + \ProvidesFile{shellesc.dtx} +%</dtx> +%<package>\ifx\ProvidesPackage\undefined +%<package>\def\next#1#2[#3]{\wlog{#2 #3}} +%<package>\expandafter\next\fi +%<package>\ProvidesPackage{shellesc} +%<driver> \ProvidesFile{shellesc.drv} +% \fi +% \ProvidesFile{shellesc.dtx} + [2015/12/05 v0.01 unified shell escape interface for LaTeX] +% +% \iffalse +%<*driver> +\documentclass{ltxdoc} +\begin{document} +\DocInput{shellesc.dtx} +\end{document} +%</driver> +% \fi +% +% \GetFileInfo{shellesc.dtx} +% +% \title{The \textsf{shellesc} Package\thanks{This file +% has version number \fileversion, last +% revised \filedate. +% Please report any issues at https://github.com/josephwright/luatex85/issues}} +% \author{LaTeX3 project} +% \date{\filedate} +% \maketitle +% +% \section{Introduction} +% +% +% For many yeas web2c based \TeX\ implementations have used the syntax +% of the \verb|\write| command to access system commands by using a +% special stream 18 (streams above 15 can not be allocated to files in +% classical \TeX\ so stream 18 would otherwise just print to the +% terminal). +% +% This is a useful extension that did not break the strict rules on +% extensions in classical \TeX. This package provides a simple +% macro level interface hiding the \verb|write18| implementation +% so a command to remove a file on a unix-like system could be +% specified using \verb|\ShellEscape{rm file.txt}| (or \verb|del| in +% windows). Note that by default system access is not allowed and +% latex will typically need to be called with the \verb|--shell-escape| +% command line option. +% +% The package may be used with standard \texttt{latex} or +% \texttt{pdflatex} or \texttt{xetex}, however it is mostly motivated by +% \texttt{lualatex} as from Lua\TeX~0.87 onwards Lua\TeX\ does \emph{not} +% support the \verb|\write18| syntax to access system commands: it has +% 256 write streams and stream 18 can be associated to a file and +% (without this package) has no special significance. This packge +% defines the same \verb|\ShellEscape| syntax in Lua\LaTeX, but the +% implementation is via Lua and the \verb|os.execute| function. +% +% \verb|\ShellEscape| in fact corresponds to \verb|\immediate\write18| +% (or \verb|\directlua|). Very rarely you may need to delay a system +% command until the current page is output (when page numbers are +% known) for this classically you could use \verb|\write18| (or +% (\verb|\latelua|). This package provides \verb|\DelayedShellEscape| +% as a common syntax for this use. +% +% To aid porting existing documents to Lua\TeX~0.87 this package does +% overload the \verb|\write| command so that +% \verb|\write18{rm file.txt}| +% will work with Lua\TeX. Note that the redefinition of \verb|\write| +% can not detect whether \verb|\immediate| has been used, +% \verb|\immediate| will work as normal when writing to file streams +% or the terminal but the specal case of stream 18 which is defined to +% use \verb|os.execute| always uses \verb|\directlua| (so corresponds +% to \verb|\immediate\write18|. In the rare situations that you need +% non-immedate \verb|\write18| in a document being ported to current +% Lua\TeX, you will need to change to use the +% \verb|DelayedShellescape| command. +% +% \section{Implementation} +% +% \begin{macrocode} +%<*package> +% \end{macrocode} +% +% \subsection{Status Check} +% +% +% \begin{macrocode} +\ifcase + \ifx\pdfshellescape\@undefined + \ifx\shellescape\@undefined + \ifx\directlua\@undefined + \z@ + \else + \directlua{% + tex.sprint((status.shell_escape or os.execute()) .. " ")} + \fi + \else + \shellescape + \fi + \else + \pdfshellescape + \fi + \PackageWarning{shellesc}{Shell escape disabled} +\or + \PackageInfo {shellesc}{Unrestricted shell escape ensabled} +\else + \PackageInfo {shellesc}{Restricted shell escape ensabled} +\fi +% \end{macrocode} +% +% \subsection{The shellesc package interface} +% +% \begin{macro}{\ShellEscape} +% Execute the supplied tokens as a system dependent command, assuming +% such execution is allowed. +% \begin{macrocode} +\ifx\lastsavedimageresourcepages\@undefined + \protected\def\ShellEscape{\immediate\write18 } +% \end{macrocode} +% +% \begin{macrocode} +\else + \protected\def\ShellEscape#1{% + \directlua{os.execute("\luaescapestring{#1}")}} +\fi +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\DelayedShellEscape} +% Execute the supplied tokens as a system dependent command, when this +% node is shipped out with the completed page, assuming +% such execution is allowed. +% \begin{macrocode} +\ifx\lastsavedimageresourcepages\@undefined + \protected\def\ShellEscape{\relax\write18 } +% \end{macrocode} +% +% \begin{macrocode} +\else + \protected\def\DelayedShellEscape#1{% + \latelua{os.execute("\luaescapestring{#1}")}} +\fi +% \end{macrocode} +% \end{macro} +% +% +% +% \subsection{The write18 package interface} +% +% In web2c based engines other than Lua\TeX, |\write18| may be used +% directly. The same was true in older LuaTeX, but from version 0.85 +% onwards that is not available. +% +% The above |shellesc| package interface is recommended for new code, +% however for ease of porting existing documents and packages to newer +% Lua\TeX\ releases, a |\write18| interface is provided here via a +% call to Lua's |os.execute|. +% +% Note that as currently written this always does an \emph{immediate} +% call to the system. +% +% |\immediate| is supported but ignored, |\immediate\write18| and +% |\write18| both execute immediately. To use a delayed execution at +% the next shipout, use the |\DelayedShellEscape| command defined +% above. +% +% Note that it would be easy to make |\wriete18| defined here use +% delayed execution, just use |\DelayedShellEscape| instead of +% |ShellEscape| in the definition below. However detecting +% |\immediate| is tricky so the choice here is to always use the +% immediate form, which is overwhelmingly more commonly used with +% |\write18|. +% +% stop at this point if not a recent Lua\TeX. +% \begin{macrocode} +\ifx\lastsavedimageresourcepages\@undefined\expandafter\endinput\fi +% \end{macrocode} +% +% \begin{macrocode} +\directlua{% +% \end{macrocode} +% +% \begin{macrocode} +shellesc = shellesc or {} +% \end{macrocode} +% +% Lua function to use the token scanner to grab the following \TeX\ +% number, and then test if stream 18 is being used, and then insert an +% appropriate \TeX\ command to handle the following brace group in +% each case. +% \begin{macrocode} +local function write_or_execute() + local s = token.scan_int() + if (s==18) then + tex.sprint(\the\numexpr\catcodetable@atletter\relax, + "\string\\ShellEscape ") + else + tex.sprint(\the\numexpr\catcodetable@atletter\relax, + "\string\\shellesc@write " .. s) + end +end +% \end{macrocode} +% +% \begin{macrocode} +shellesc.write_or_execute=write_or_execute +% \end{macrocode} +% +% \begin{macrocode} +} +% \end{macrocode} +% +% \begin{macrocode} +\let\shellesc@write\write +% \end{macrocode} +% +% \begin{macrocode} +\protected\def\write{\directlua{shellesc.write_or_execute()}} +% \end{macrocode} +% +% +% +% \begin{macrocode} +%</package> +% \end{macrocode} +% +% \Finale +% |