diff options
author | Karl Berry <karl@freefriends.org> | 2023-05-05 21:23:26 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2023-05-05 21:23:26 +0000 |
commit | 847808083e98635eb04dad9a4fb45ee3936f5520 (patch) | |
tree | a1db51910bc0b3e2f49eb6fb17260dad92718979 /Master/texmf-dist/source/latex/l3kernel/l3file.dtx | |
parent | 7ba90ca45bbdc7354c25890431ec21f1a9f58ffd (diff) |
l3kernel (5may23)
git-svn-id: svn://tug.org/texlive/trunk@67026 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3file.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/l3kernel/l3file.dtx | 110 |
1 files changed, 94 insertions, 16 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3file.dtx b/Master/texmf-dist/source/latex/l3kernel/l3file.dtx index 5d7a60824fb..4d1b0660b7e 100644 --- a/Master/texmf-dist/source/latex/l3kernel/l3file.dtx +++ b/Master/texmf-dist/source/latex/l3kernel/l3file.dtx @@ -44,7 +44,7 @@ % }^^A % } % -% \date{Released 2023-04-20} +% \date{Released 2023-05-05} % % \maketitle % @@ -140,6 +140,23 @@ % additive). % \end{function} % +% \begin{function}[added = 2019-05-08]{\ior_shell_open:Nn} +% \begin{syntax} +% \cs{ior_shell_open:Nn} \meta{stream} \Arg{shell~command} +% \end{syntax} +% Opens the \emph{pseudo}-file created by the output of the +% \meta{shell command} for reading using \meta{stream} as the +% control sequence for access. If the \meta{stream} was already +% open it is closed before the new operation begins. The +% \meta{stream} is available for access immediately and will remain +% allocated to \meta{shell command} until a \cs{ior_close:N} instruction +% is given or the \TeX{} run ends. +% If piped system calls are disabled an error is raised. +% +% For details of handling of the \meta{shell command}, see +% \cs{sys_get_shell:nnNTF}. +% \end{function} +% % \begin{function}[updated = 2012-07-31] % {\ior_close:N, \ior_close:c, \iow_close:N, \iow_close:c} % \begin{syntax} @@ -390,6 +407,26 @@ % the \meta{stream} is not open. % \end{function} % +% \subsection{Reading from the terminal} +% +% \begin{function}[added = 2019-03-23]{\ior_get_term:nN, \ior_str_get_term:nN} +% \begin{syntax} +% \cs{ior_get_term:nN} \meta{prompt} \meta{token list variable} +% \end{syntax} +% Function that reads one or more lines (until an equal number of left +% and right braces are found) from the terminal and stores +% the result locally in the \meta{token list} variable. Tokenization +% occurs as described for \cs{ior_get:NN} or \cs{ior_str_get:NN}, respectively. +% When the \meta{prompt} +% is empty, \TeX{} will wait for input without any other indication: +% typically the programmer will have provided a suitable text using +% e.g.~\cs{iow_term:n}. Where the \meta{prompt} is given, it will appear +% in the terminal followed by an |=|, e.g. +% \begin{verbatim} +% prompt= +% \end{verbatim} +% \end{function} +% % \subsection{Writing to files} % % \begin{function}[updated = 2012-06-05]{\iow_now:Nn, \iow_now:Nx, \iow_now:cn, \iow_now:cx} @@ -516,8 +553,8 @@ % (for example after a control sequence), % \item |\#|, |\%|, |\{|, |\}|, |\~| may be used to represent % the corresponding character, -% \item \cs{iow_allow_break:} may be used to allow a line-break -% without inserting a space (this is experimental), +% \item \cs{iow_wrap_allow_break:} may be used to allow a line-break +% without inserting a space, % \item \cs{iow_indent:n} may be used to indent a part of the % \meta{text} (not the \meta{run-on text}). % \end{itemize} @@ -547,6 +584,15 @@ % \end{texnote} % \end{function} % +% \begin{function}[added = 2023-04-25]{\iow_wrap_allow_break:} +% \begin{syntax} +% \cs{iow_wrap_allow_break:} +% \end{syntax} +% In the first argument of \cs{iow_wrap:nnnN} (for instance in +% messages), inserts a break-point that allows a line break. If +% no break occurs, this function adds nothing to the output. +% \end{function} +% % \begin{function}[added = 2011-09-21]{\iow_indent:n} % \begin{syntax} % \cs{iow_indent:n} \Arg{text} @@ -1111,6 +1157,38 @@ % \end{macro} % \end{macro} % +% \begin{macro}{\ior_shell_open:Nn} +% \begin{macro}{\@@_shell_open:nN} +% Actually much easier than either the standard open or input versions! +% When calling \cs{__kernel_ior_open:Nn} the file the pipe is added to +% signal a shell command, but the quotes are not added yet---they are +% added later by \cs{__kernel_file_name_quote:n}. +% \begin{macrocode} +\cs_new_protected:Npn \ior_shell_open:Nn #1#2 + { + \sys_if_shell:TF + { \exp_args:No \@@_shell_open:nN { \tl_to_str:n {#2} } #1 } + { \msg_error:nn { ior } { pipe-failed } } + } +\cs_new_protected:Npn \@@_shell_open:nN #1#2 + { + \tl_if_in:nnTF {#1} { " } + { + \msg_error:nnx + { kernel } { quote-in-shell } {#1} + } + { \__kernel_ior_open:Nn #2 { |#1 } } + } +\msg_new:nnnn { ior } { pipe-failed } + { Cannot~run~piped~system~commands. } + { + LaTeX~tried~to~call~a~system~process~but~this~was~not~possible.\\ + Try~the~"--shell-escape"~(or~"--enable-pipes")~option. + } +% \end{macrocode} +% \end{macro} +% \end{macro} +% % \begin{macro}{\ior_close:N, \ior_close:c} % Closing a stream means getting rid of it at the \TeX{} level and % removing from the various data structures. Unless the name passed @@ -1846,24 +1924,24 @@ % \end{variable} % \end{variable} % -% \begin{macro}{\iow_allow_break:} -% \begin{macro}[EXP]{\@@_allow_break:} -% \begin{macro}[EXP]{\@@_allow_break_error:} -% We set \cs{iow_allow_break:n} to produce an error when outside -% messages. Within wrapped message, it is set to \cs{@@_allow_break:} -% when valid and otherwise to \cs{@@_allow_break_error:}. The second +% \begin{macro}{\iow_wrap_allow_break:} +% \begin{macro}[EXP]{\@@_wrap_allow_break:} +% \begin{macro}[EXP]{\@@_wrap_allow_break_error:} +% We set \cs{iow_wrap_allow_break:n} to produce an error when outside +% messages. Within wrapped message, it is set to \cs{@@_wrap_allow_break:} +% when valid and otherwise to \cs{@@_wrap_allow_break_error:}. The second % produces an error expandably. % \begin{macrocode} -\cs_new_protected:Npn \iow_allow_break: +\cs_new_protected:Npn \iow_wrap_allow_break: { \msg_error:nnnn { kernel } { iow-indent } - { \iow_wrap:nnnN } { \iow_allow_break: } + { \iow_wrap:nnnN } { \iow_wrap_allow_break: } } -\cs_new:Npx \@@_allow_break: { \c_@@_wrap_allow_break_marker_tl } -\cs_new:Npn \@@_allow_break_error: +\cs_new:Npx \@@_wrap_allow_break: { \c_@@_wrap_allow_break_marker_tl } +\cs_new:Npn \@@_wrap_allow_break_error: { \msg_expandable_error:nnnn { kernel } { iow-indent } - { \iow_wrap:nnnN } { \iow_allow_break: } + { \iow_wrap:nnnN } { \iow_wrap_allow_break: } } % \end{macrocode} % \end{macro} @@ -1928,7 +2006,7 @@ \int_set:Nn \tex_escapechar:D { 92 } \cs_set_eq:NN \\ \iow_newline: \cs_set_eq:NN \ \c_catcode_other_space_tl - \cs_set_eq:NN \iow_allow_break: \@@_allow_break: + \cs_set_eq:NN \iow_wrap_allow_break: \@@_wrap_allow_break: \cs_set_eq:NN \iow_indent:n \@@_indent:n #3 % \end{macrocode} @@ -1941,7 +2019,7 @@ % \begin{macrocode} \cs_set_eq:NN \protect \token_to_str:N \__kernel_tl_set:Nx \l_@@_wrap_tl {#1} - \cs_set_eq:NN \iow_allow_break: \@@_allow_break_error: + \cs_set_eq:NN \iow_wrap_allow_break: \@@_wrap_allow_break_error: \cs_set_eq:NN \iow_indent:n \@@_indent_error:n % \end{macrocode} % Afterwards, set the newline marker (two assignments to fully expand, |