summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/l3kernel/l3file.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/l3kernel/l3file.dtx')
-rw-r--r--macros/latex/contrib/l3kernel/l3file.dtx110
1 files changed, 94 insertions, 16 deletions
diff --git a/macros/latex/contrib/l3kernel/l3file.dtx b/macros/latex/contrib/l3kernel/l3file.dtx
index 5d7a60824f..4d1b0660b7 100644
--- a/macros/latex/contrib/l3kernel/l3file.dtx
+++ b/macros/latex/contrib/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,