diff options
author | Karl Berry <karl@freefriends.org> | 2017-06-05 23:17:08 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2017-06-05 23:17:08 +0000 |
commit | 683004f8a1d94fc432fd8104903a431e27bfba93 (patch) | |
tree | 2450b41f4c918810556cbaec853ec48ddc2b949a /Master/texmf-dist/source/latex/l3kernel/l3file.dtx | |
parent | c684ba451bf548bdb24c40ed54caa9f11ac21422 (diff) |
latex3 (30may17)
git-svn-id: svn://tug.org/texlive/trunk@44483 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 | 181 |
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} |