summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/l3file.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3file.dtx')
-rw-r--r--Master/texmf-dist/source/latex/l3kernel/l3file.dtx181
1 files changed, 162 insertions, 19 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3file.dtx b/Master/texmf-dist/source/latex/l3kernel/l3file.dtx
index 12ffc79a8c5..a3ceb04d1cf 100644
--- a/Master/texmf-dist/source/latex/l3kernel/l3file.dtx
+++ b/Master/texmf-dist/source/latex/l3kernel/l3file.dtx
@@ -41,7 +41,7 @@
% }^^A
% }
%
-% \date{Released 2017/05/13}
+% \date{Released 2017/05/29}
%
% \maketitle
%
@@ -232,28 +232,34 @@
% and right braces are found) from the input \meta{stream} and stores
% the result locally in the \meta{token list} variable. If the
% \meta{stream} is not open, input is requested from the terminal.
-% The material read from the \meta{stream} will be tokenized by
-% \TeX{} according to the category codes in force when the function
-% is used. Note that any blank lines will be converted to the token
-% \cs{par}. Therefore, if skipping blank lines is requires a test such as
+% The material read from the \meta{stream} will be tokenized by \TeX{}
+% according to the category codes and \tn{endlinechar} in force when
+% the function is used. Assuming normal settings, any lines which do
+% not end in a comment character~|%| will have the line ending
+% converted to a space, so for example input
+% \begin{verbatim}
+% a b c
+% \end{verbatim}
+% will result in a token list \verb*|a b c |. Any blank line is
+% converted to the token \cs{par}. Therefore, blank lines can be
+% skipped by using a test such as
% \begin{verbatim}
% \ior_get:NN \l_my_stream \l_tmpa_tl
% \tl_set:Nn \l_tmpb_tl { \par }
% \tl_if_eq:NNF \l_tmpa_tl \l_tmpb_tl
% ...
% \end{verbatim}
-% may be used. Also notice that if multiple lines are read to match braces
-% then the resulting token list will contain \cs{par} tokens. As normal
-% \TeX{} tokenization is in force, any lines which do not end in a comment
-% character (usually |%|) will have the line ending converted to a space,
-% so for example input
-% \begin{verbatim}
-% a b c
-% \end{verbatim}
-% will result in a token list |a b c |.
+% Also notice that if multiple lines are read to match braces
+% then the resulting token list can contain \cs{par} tokens.
% \begin{texnote}
-% This protected macro expands to the \TeX{} primitive \tn{read}
-% along with the |to| keyword.
+% This protected macro is a wrapper around the \TeX{} primitive
+% \tn{read}. Regardless of settings, \TeX{} replaces trailing space
+% and tab characters (character codes 32 and~9) in each line by an
+% end-of-line character (character code \tn{endlinechar}, omitted if
+% \tn{endlinechar} is negative or too large) before turning
+% characters into tokens according to current category codes. With
+% default settings, spaces appearing at the beginning of lines are
+% also ignored.
% \end{texnote}
% \end{function}
%
@@ -279,9 +285,91 @@
% having category code~12.
% \begin{texnote}
% This protected macro is a wrapper around the \eTeX{} primitive
-% \tn{readline}. However, the end-line character normally added by
-% this primitive is not included in the result of
-% \cs{ior_str_get:NN}.
+% \tn{readline}. Regardless of settings, \TeX{} removes trailing
+% space and tab characters (character codes 32 and~9). However, the
+% end-line character normally added by this primitive is not
+% included in the result of \cs{ior_str_get:NN}.
+% \end{texnote}
+% \end{function}
+%
+% \begin{function}[added = 2012-02-11]{\ior_map_inline:Nn}
+% \begin{syntax}
+% \cs{ior_map_inline:Nn} \meta{stream} \Arg{inline function}
+% \end{syntax}
+% Applies the \meta{inline function} to each set of \meta{lines}
+% obtained by calling \cs{ior_get:NN} until reaching the end of the
+% file. \TeX{} ignores any trailing new-line marker from the file it
+% reads. The \meta{inline function} should consist of code which will
+% receive the \meta{line} as |#1|.
+% \end{function}
+%
+% \begin{function}[added = 2012-02-11]{\ior_str_map_inline:Nn}
+% \begin{syntax}
+% \cs{ior_str_map_inline:Nn} \Arg{stream} \Arg{inline function}
+% \end{syntax}
+% Applies the \meta{inline function} to every \meta{line}
+% in the \meta{stream}. The material is read from the \meta{stream}
+% as a series of tokens with category code $12$ (other), with the
+% exception of space characters which are given category code $10$
+% (space). The \meta{inline function} should consist of code which
+% will receive the \meta{line} as |#1|.
+% Note that \TeX{} removes trailing space and tab characters
+% (character codes 32 and 9) from every line upon input. \TeX{} also
+% ignores any trailing new-line marker from the file it reads.
+% \end{function}
+%
+% \begin{function}[added = 2012-06-29]{\ior_map_break:}
+% \begin{syntax}
+% \cs{ior_map_break:}
+% \end{syntax}
+% Used to terminate a \cs[no-index]{ior_map_\ldots} function before all
+% lines from the \meta{stream} have been processed. This will
+% normally take place within a conditional statement, for example
+% \begin{verbatim}
+% \ior_map_inline:Nn \l_my_ior
+% {
+% \str_if_eq:nnTF { #1 } { bingo }
+% { \ior_map_break: }
+% {
+% % Do something useful
+% }
+% }
+% \end{verbatim}
+% Use outside of a \cs[no-index]{ior_map_\ldots} scenario will lead to low
+% level \TeX{} errors.
+% \begin{texnote}
+% When the mapping is broken, additional tokens may be inserted by the
+% internal macro \cs{__prg_break_point:Nn} before further items are taken
+% from the input stream. This will depend on the design of the mapping
+% function.
+% \end{texnote}
+% \end{function}
+%
+% \begin{function}[added = 2012-06-29]{\ior_map_break:n}
+% \begin{syntax}
+% \cs{ior_map_break:n} \Arg{tokens}
+% \end{syntax}
+% Used to terminate a \cs[no-index]{ior_map_\ldots} function before all
+% lines in the \meta{stream} have been processed, inserting
+% the \meta{tokens} after the mapping has ended. This will
+% normally take place within a conditional statement, for example
+% \begin{verbatim}
+% \ior_map_inline:Nn \l_my_ior
+% {
+% \str_if_eq:nnTF { #1 } { bingo }
+% { \ior_map_break:n { <tokens> } }
+% {
+% % Do something useful
+% }
+% }
+% \end{verbatim}
+% Use outside of a \cs[no-index]{ior_map_\ldots} scenario will lead to low
+% level \TeX{} errors.
+% \begin{texnote}
+% When the mapping is broken, additional tokens may be inserted by the
+% internal macro \cs{__prg_break_point:Nn} before the \meta{tokens} are
+% inserted into the input stream.
+% This will depend on the design of the mapping function.
% \end{texnote}
% \end{function}
%
@@ -1183,6 +1271,61 @@
% \end{macrocode}
% \end{macro}
%
+% \begin{macro}[EXP]{\ior_map_break:, \ior_map_break:n}
+% Usual map breaking functions.
+% \begin{macrocode}
+\cs_new:Npn \ior_map_break:
+ { \__prg_map_break:Nn \ior_map_break: { } }
+\cs_new:Npn \ior_map_break:n
+ { \__prg_map_break:Nn \ior_map_break: }
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\ior_map_inline:Nn, \ior_str_map_inline:Nn}
+% \begin{macro}[aux]{\@@_map_inline:NNn}
+% \begin{macro}[aux]{\@@_map_inline:NNNn}
+% \begin{macro}[aux]{\@@_map_inline_loop:NNN}
+% \begin{variable}{\l_@@_internal_tl}
+% Mapping to an input stream can be done on either a token or a string
+% basis, hence the set up. Within that, there is a check to avoid reading
+% past the end of a file, hence the two applications of \cs{ior_if_eof:N}.
+% This mapping cannot be nested with twice the same stream, as the
+% stream has only one \enquote{current line}.
+% \begin{macrocode}
+\cs_new_protected:Npn \ior_map_inline:Nn
+ { \@@_map_inline:NNn \ior_get:NN }
+\cs_new_protected:Npn \ior_str_map_inline:Nn
+ { \@@_map_inline:NNn \ior_str_get:NN }
+\cs_new_protected:Npn \@@_map_inline:NNn
+ {
+ \int_gincr:N \g__prg_map_int
+ \exp_args:Nc \@@_map_inline:NNNn
+ { __prg_map_ \int_use:N \g__prg_map_int :n }
+ }
+\cs_new_protected:Npn \@@_map_inline:NNNn #1#2#3#4
+ {
+ \cs_gset_protected:Npn #1 ##1 {#4}
+ \ior_if_eof:NF #3 { \@@_map_inline_loop:NNN #1#2#3 }
+ \__prg_break_point:Nn \ior_map_break:
+ { \int_gdecr:N \g__prg_map_int }
+ }
+\cs_new_protected:Npn \@@_map_inline_loop:NNN #1#2#3
+ {
+ #2 #3 \l_@@_internal_tl
+ \ior_if_eof:NF #3
+ {
+ \exp_args:No #1 \l_@@_internal_tl
+ \@@_map_inline_loop:NNN #1#2#3
+ }
+ }
+\tl_new:N \l_@@_internal_tl
+% \end{macrocode}
+% \end{variable}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
% \begin{variable}{\g__file_internal_ior}
% Needed by the higher-level code, but cannot be created until here.
% \begin{macrocode}