summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/l3io.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3io.dtx')
-rw-r--r--Master/texmf-dist/source/latex/l3kernel/l3io.dtx177
1 files changed, 117 insertions, 60 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3io.dtx b/Master/texmf-dist/source/latex/l3kernel/l3io.dtx
index 4eb4829b4df..da17b8f5efb 100644
--- a/Master/texmf-dist/source/latex/l3kernel/l3io.dtx
+++ b/Master/texmf-dist/source/latex/l3kernel/l3io.dtx
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-%% File: l3io.dtx Copyright (C) 1990-2011 The LaTeX3 Project
+%% File: l3io.dtx Copyright (C) 1990-2012 The LaTeX3 Project
%%
%% It may be distributed and/or modified under the conditions of the
%% LaTeX Project Public License (LPPL), either version 1.3c of this
@@ -35,7 +35,7 @@
%
%<*driver|package>
\RequirePackage{l3names}
-\GetIdInfo$Id: l3io.dtx 3096 2011-12-27 09:09:18Z joseph $
+\GetIdInfo$Id: l3io.dtx 3160 2012-01-09 02:33:23Z bruno $
{L3 Experimental input-output operations}
%</driver|package>
%<*driver>
@@ -305,71 +305,36 @@
%
% \section{Reading from files}
%
-% \begin{function}{\ior_to:NN}
+% \begin{function}{\ior_to:NN,\ior_gto:NN}
% \begin{syntax}
% \cs{ior_to:NN} \meta{stream} \meta{token list variable}
% \end{syntax}
% Functions that reads one or more lines (until an equal number of left
% and right braces are found) from the input \meta{stream} and stores
-% the result locally in the \meta{token list} variable. If the
+% the result in the \meta{token list} variable, locally or globally. 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.
% \begin{texnote}
-% The is protected macro which expands to the \TeX{} primitive \tn{read}
-% along with the |to| keyword.
+% This protected macro expands to the \TeX{} primitives \tn{read}
+% or \tn{global}\tn{read} along with the |to| keyword.
% \end{texnote}
% \end{function}
%
-% \begin{function}{\ior_gto:NN}
-% \begin{syntax}
-% \cs{ior_gto:NN} \meta{stream} \meta{token list variable}
-% \end{syntax}
-% Functions that reads one or more lines (until an equal number of left
-% and right braces are found) from the input \meta{stream} and stores
-% the result globally 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.
-% \begin{texnote}
-% The is protected macro which expands to the \TeX{} primitives
-% \tn{global}\tn{read} along with the |to| keyword.
-% \end{texnote}
-% \end{function}
-%
-% \begin{function}{\ior_str_to:NN}
+% \begin{function}{\ior_str_to:NN,\ior_str_gto:NN}
% \begin{syntax}
% \cs{ior_str_to:NN} \meta{stream} \meta{token list variable}
% \end{syntax}
-% Functions that reads one or more lines (until an equal number of left
-% 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} as a series of tokens with
-% category code $12$ (other), with the exception of space
-% characters which are given category code $10$ (space).
-% \begin{texnote}
-% The is protected macro which expands to the \eTeX{} primitive
-% \tn{readline} along with the |to| keyword.
-% \end{texnote}
-% \end{function}
-%
-% \begin{function}{\ior_str_gto:NN}
-% \begin{syntax}
-% \cs{ior_str_gto:NN} \meta{stream} \meta{token list variable}
-% \end{syntax}
-% Functions that reads one or more lines (until an equal number of left
-% and right braces are found) from the input \meta{stream} and stores
-% the result globally in the \meta{token list} variable. If the
+% Functions that reads one line from the input \meta{stream} and stores
+% the result in the \meta{token list} variable, locally or globally. If the
% \meta{stream} is not open, input is requested from the terminal.
% The material 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).
% \begin{texnote}
-% The is protected macro which expands to the primitives
-% \tn{global}\tn{readline} along with the |to| keyword.
+% This protected macro expands to the \eTeX{} primitives \tn{readline}
+% or \tn{global}\tn{readline} along with the |to| keyword.
% \end{texnote}
% \end{function}
%
@@ -385,8 +350,8 @@
%\end{function}
%
% \section{Constants}
-%
-% \begin{variable}{\c_ior_term_ior}
+%
+% \begin{variable}{\c_term_ior}
% Constant input stream for reading from the terminal. Reading from this
% stream using \cs{ior_to:NN} or similar will result in a prompt from
% \TeX{} of the form
@@ -394,12 +359,40 @@
% <tl>=
% \end{verbatim}
% \end{variable}
-%
-% \begin{variable}{\c_iow_log_iow, \c_iow_term_iow}
+%
+% \begin{variable}{\c_log_iow, \c_term_iow}
% Constant output streams for writing to the log and to the terminal
% (plus the log), respectively.
% \end{variable}
%
+% \section{Experimental functions}
+%
+% \begin{function}{\ior_map_inline:nn}
+% \begin{syntax}
+% \cs{ior_map_inline:nn} \Arg{file name} \Arg{inline function}
+% \end{syntax}
+% Applies the \meta{inline function} to \meta{items} obtained by
+% reading one or more lines (until an equal number of left and right
+% braces are found) from the \meta{file}. The \meta{inline function}
+% should consist of code which will receive the \meta{line} as |#1|.
+% One in line mapping can be nested inside another.
+% If the file is not found, the \meta{inline function} is never called.
+% \end{function}
+%
+% \begin{function}{\ior_str_map_inline:nn}
+% \begin{syntax}
+% \cs{ior_str_map_inline:nn} \Arg{file name} \Arg{inline function}
+% \end{syntax}
+% Applies the \meta{inline function} to every \meta{line}
+% in the \meta{file}. The material is read from the \meta{file}
+% 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|.
+% One in line mapping can be nested inside another.
+% If the file is not found, the \meta{inline function} is never called.
+% \end{function}
+%
% \section{Internal input--output functions}
%
% \begin{function}[EXP]{\if_eof:w}
@@ -463,7 +456,7 @@
% \end{macro}
%
% \subsection{Variables and constants}
-%
+%
% \begin{variable}{\c_term_ior}
% Reading from the terminal (with a prompt) is done using a positive
% but non-existent stream number. Unlike writing, there is no concept
@@ -642,8 +635,8 @@
% \begin{macro}[aux]{\ior_stream_alloc:N}
% \begin{macro}[aux]{\iow_stream_alloc_aux:}
% \begin{macro}[aux]{\ior_stream_alloc_aux:}
-% \begin{variable}{\g_iow_tmp_stream}
-% \begin{variable}{\g_ior_tmp_stream}
+% \begin{variable}{\g_iow_internal_iow}
+% \begin{variable}{\g_ior_internal_ior}
% Allocating a raw stream is much easier in \IniTeX{} mode than for
% the package. For the format, all streams will be allocated by
% \pkg{l3io} and so there is a simple check to see if a raw
@@ -654,6 +647,8 @@
% one is needed, we get the number allocated by \LaTeXe{} to get
% \enquote{back on track} with allocation.
% \begin{macrocode}
+\iow_new:N \g_iow_internal_iow
+\ior_new:N \g_ior_internal_ior
\cs_new_protected:Npn \iow_stream_alloc:N #1
{
\cs_if_exist:cTF { g_iow_ \int_use:N \l_iow_stream_int _iow }
@@ -663,10 +658,10 @@
\iow_stream_alloc_aux:
\int_compare:nNnT \l_iow_stream_int = \c_sixteen
{
- \iow_raw_new:N \g_iow_tmp_iow
- \int_set:Nn \l_iow_stream_int { \g_iow_tmp_iow }
+ \iow_raw_new:N \g_iow_internal_iow
+ \int_set:Nn \l_iow_stream_int { \g_iow_internal_iow }
\cs_gset_eq:cN
- { g_iow_ \int_use:N \l_iow_stream_int _iow } \g_iow_tmp_iow
+ { g_iow_ \int_use:N \l_iow_stream_int _iow } \g_iow_internal_iow
}
%</package>
%<*initex>
@@ -699,10 +694,10 @@
\ior_stream_alloc_aux:
\int_compare:nNnT \l_ior_stream_int = \c_sixteen
{
- \ior_raw_new:N \g_ior_tmp_ior
- \int_set:Nn \l_ior_stream_int { \g_ior_tmp_ior }
+ \ior_raw_new:N \g_ior_internal_ior
+ \int_set:Nn \l_ior_stream_int { \g_ior_internal_ior }
\cs_gset_eq:cN
- { g_ior_ \int_use:N \l_iow_stream_int _ior } \g_ior_tmp_ior
+ { g_ior_ \int_use:N \l_iow_stream_int _ior } \g_ior_internal_ior
}
%</package>
%<*initex>
@@ -899,7 +894,7 @@
% available for other uses.
%
% \begin{macro}{\l_iow_line_length_int}
-% The is the \enquote{raw} length of a line which can be written to a
+% This is the \enquote{raw} length of a line which can be written to a
% file. The standard value is the line length typically used by
% \TeX{}Live and Mik\TeX{}.
% \begin{macrocode}
@@ -1300,6 +1295,68 @@
% \end{macro}
% \end{macro}
%
+% \subsection{Experimental functions}
+%
+% \begin{macro}{\ior_map_inline:nn}
+% \begin{macro}{\ior_str_map_inline:nn}
+% \begin{macro}[aux]{\ior_str_map_inline_aux:Nnn}
+% \begin{macro}[aux]{\ior_str_map_inline_aux:NNNnn}
+% \begin{macro}[aux]{\ior_str_map_inline_loop:NNN}
+% \begin{variable}{\l_ior_internal_tl}
+% The five arguments of \cs{ior_str_map_inline_aux:NNNnn} are:
+% the read stream used at this level of map nesting;
+% the control sequence which will hold the function to map;
+% either \cs{ior_to:NN} or \cs{ior_str_to:NN}; the file name;
+% and finally the inline function. We make sure to decrease
+% \cs{g_prg_map_int} and close the file after the mapping,
+% even if the mapping exits prematurely because of a
+% \cs{prg_map_break:} instruction. The \cs{ior_if_eof:nF}
+% tests are a little bit tricky to get right: if the file
+% does not exist, we should do nothing, hence the preliminary
+% test. Then the end-of-file test must be done after reading
+% each line.
+% \begin{macrocode}
+\tl_new:N \l_ior_internal_tl
+\cs_new_protected_nopar:Npn \ior_map_inline:nn
+ { \ior_map_inline_aux:Nnn \ior_to:NN }
+\cs_new_protected_nopar:Npn \ior_str_map_inline:nn
+ { \ior_map_inline_aux:Nnn \ior_str_to:NN }
+\cs_new_protected_nopar:Npn \ior_map_inline_aux:Nnn
+ {
+ \exp_args:Ncc \ior_map_inline_aux:NNNnn
+ { g_ior_map_ \int_use:N \g_prg_map_int _ior }
+ { ior_map_ \int_use:N \g_prg_map_int :n }
+ }
+\cs_new_protected:Npn \ior_map_inline_aux:NNNnn #1#2#3#4#5
+ {
+ \cs_if_exist:NF #1 { \ior_new:N #1 }
+ \cs_set:Npn #2 ##1 {#5}
+ \ior_open:Nn #1 {#4}
+ \int_gincr:N \g_prg_map_int
+ \ior_if_eof:NF #1 { \ior_map_inline_loop:NNN #1#2#3 }
+ \prg_break_point:n
+ {
+ \int_gdecr:N \g_prg_map_int
+ \ior_close:N #1
+ }
+ }
+\cs_new_protected:Npn \ior_map_inline_loop:NNN #1#2#3
+ {
+ #3 #1 \l_ior_internal_tl
+ \ior_if_eof:NF #1
+ {
+ \exp_args:No #2 \l_ior_internal_tl
+ \ior_map_inline_loop:NNN #1#2#3
+ }
+ }
+% \end{macrocode}
+% \end{variable}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
% \subsection{Deprecated functions}
%
% Deprecated on 2011-05-27, for removal by 2011-08-31.