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.dtx161
1 files changed, 87 insertions, 74 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3io.dtx b/Master/texmf-dist/source/latex/l3kernel/l3io.dtx
index 991e02e6af8..4eb4829b4df 100644
--- a/Master/texmf-dist/source/latex/l3kernel/l3io.dtx
+++ b/Master/texmf-dist/source/latex/l3kernel/l3io.dtx
@@ -35,7 +35,7 @@
%
%<*driver|package>
\RequirePackage{l3names}
-\GetIdInfo$Id: l3io.dtx 3005 2011-11-25 13:19:47Z bruno $
+\GetIdInfo$Id: l3io.dtx 3096 2011-12-27 09:09:18Z joseph $
{L3 Experimental input-output operations}
%</driver|package>
%<*driver>
@@ -87,8 +87,8 @@
% the file name is needed when the file is opened).
%
% \section{Managing streams}
-%
-% \begin{function}[added = 2011-09-26]
+%
+% \begin{function}[added = 2011-09-26, updated = 2011-12-27]
% {\ior_new:N, \ior_new:c, \iow_new:N, \io_new:c}
% \begin{syntax}
% \cs{ior_new:Nn} \meta{stream}
@@ -100,7 +100,7 @@
% error.
% \end{function}
%
-% \begin{function}[updated = 2011-09-26]{\ior_open:Nn, \ior_open:cn}
+% \begin{function}[updated = 2011-12-27]{\ior_open:Nn, \ior_open:cn}
% \begin{syntax}
% \cs{ior_open:Nn} \meta{stream} \Arg{file name}
% \end{syntax}
@@ -112,7 +112,7 @@
% is given or the file ends.
% \end{function}
%
-% \begin{function}[updated = 2011-09-26]{\iow_open:Nn, \iow_open:cn}
+% \begin{function}[updated = 2011-12-27]{\iow_open:Nn, \iow_open:cn}
% \begin{syntax}
% \cs{iow_open:Nn} \meta{stream} \Arg{file name}
% \end{syntax}
@@ -126,7 +126,7 @@
% additive).
% \end{function}
%
-% \begin{function}[updated = 2011-09-26]{\ior_close:N, \ior_close:c}
+% \begin{function}[updated = 2011-12-27]{\ior_close:N, \ior_close:c}
% \begin{syntax}
% \cs{ior_close:N} \meta{stream}
% \end{syntax}
@@ -135,7 +135,7 @@
% to other programmer.
% \end{function}
%
-% \begin{function}[updated = 2011-09-26]{\iow_close:N, \iow_close:c}
+% \begin{function}[updated = 2011-12-27]{\iow_close:N, \iow_close:c}
% \begin{syntax}
% \cs{iow_close:N} \meta{stream}
% \end{syntax}
@@ -228,7 +228,7 @@
% write difficult characters such as "%", "{", "}",
% \emph{etc}.~in messages, for example:
% \begin{verbatim}
-% \iow_now:Nx \g_my_stream { \iow_char:N \{ text \iow_char:N \} }
+% \iow_now:Nx \g_my_iow { \iow_char:N \{ text \iow_char:N \} }
% \end{verbatim}
% The function has no effect if writing is taking place without
% expansion (\emph{e.g.}~in the second argument of \cs{iow_now:Nn}).
@@ -384,6 +384,22 @@
% a \meta{stream} does not exist at all.
%\end{function}
%
+% \section{Constants}
+%
+% \begin{variable}{\c_ior_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
+% \begin{verbatim}
+% <tl>=
+% \end{verbatim}
+% \end{variable}
+%
+% \begin{variable}{\c_iow_log_iow, \c_iow_term_iow}
+% Constant output streams for writing to the log and to the terminal
+% (plus the log), respectively.
+% \end{variable}
+%
% \section{Internal input--output functions}
%
% \begin{function}[EXP]{\if_eof:w}
@@ -447,21 +463,25 @@
% \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
+% of reading from the log.
+% \begin{macrocode}
+\cs_new_eq:NN \c_term_ior \c_sixteen
+% \end{macrocode}
+% \end{variable}
%
-% \begin{variable}{\c_iow_term_stream, \c_ior_term_stream}
-% \begin{variable}{\c_iow_log_stream, \c_ior_log_stream}
+% \begin{variable}{\c_log_iow, \c_term_iow}
% Here we allocate two output streams for writing to the transcript
-% file only (\cs{c_iow_log_stream}) and to both the terminal and
-% transcript file (\cs{c_iow_term_stream}). Both can be used to read
-% from and have equivalent \cs{c_ior} versions.
+% file only (\cs{c_log_iow}) and to both the terminal and
+% transcript file (\cs{c_term_iow}).
% \begin{macrocode}
-\cs_new_eq:NN \c_iow_term_stream \c_sixteen
-\cs_new_eq:NN \c_ior_term_stream \c_sixteen
-\cs_new_eq:NN \c_iow_log_stream \c_minus_one
-\cs_new_eq:NN \c_ior_log_stream \c_minus_one
+\cs_new_eq:NN \c_log_iow \c_minus_one
+\cs_new_eq:NN \c_term_iow \c_sixteen
% \end{macrocode}
% \end{variable}
-% \end{variable}
%
% \begin{variable}{\c_iow_streams_tl, \c_ior_streams_tl}
% The list of streams available, by number.
@@ -525,10 +545,10 @@
% \begin{macrocode}
%<*initex>
\alloc_setup_type:nnn { ior } \c_zero \c_sixteen
-\cs_new_protected_nopar:Npn \ior_raw_new:N #1
+\cs_new_protected:Npn \ior_raw_new:N #1
{ \alloc_reg:nNN { ior } \tex_chardef:D #1 }
\alloc_setup_type:nnn { iow } \c_zero \c_sixteen
-\cs_new_protected_nopar:Npn \iow_raw_new:N #1
+\cs_new_protected:Npn \iow_raw_new:N #1
{ \alloc_reg:nNN { iow } \tex_chardef:D #1 }
%</initex>
%<*package>
@@ -540,18 +560,14 @@
% \end{macrocode}
% \end{macro}
% \end{macro}
-%
+%
% \begin{macro}{\ior_new:N, \ior_new:c, \iow_new:N, \iow_new:c}
-% Reserving a new stream is done by defining the stream as the $16$ (which
-% must be in error).
+% Reserving a new stream is done by defining the name as equal to using the
+% terminal.
% \begin{macrocode}
-\cs_new_protected_nopar:Npn \ior_new:N #1
- {
- \chk_if_free_cs:N #1
- \tex_global:D \tex_chardef:D #1 16 ~
- }
-\cs_new_eq:NN \iow_new:N \ior_new:N
+\cs_new_protected:Npn \ior_new:N #1 { \cs_new_eq:NN #1 \c_term_ior }
\cs_generate_variant:Nn \ior_new:N { c }
+\cs_new_protected:Npn \iow_new:N #1 { \cs_new_eq:NN #1 \c_term_iow }
\cs_generate_variant:Nn \iow_new:N { c }
% \end{macrocode}
% \end{macro}
@@ -564,26 +580,26 @@
% When one is found the allocation can take place, the information
% can be stored and finally the file can actually be opened.
% \begin{macrocode}
-\cs_new_protected_nopar:Npn \ior_open:Nn #1#2
+\cs_new_protected:Npn \ior_open:Nn #1#2
{
\ior_close:N #1
\int_set:Nn \l_ior_stream_int \c_sixteen
\tl_map_function:NN \c_ior_streams_tl \ior_alloc_read:n
\int_compare:nNnTF \l_ior_stream_int = \c_sixteen
- { \msg_kernel_error:nn { ior } { streams-exhausted } }
+ { \msg_kernel_fatal:nn { ior } { streams-exhausted } }
{
\ior_stream_alloc:N #1
\prop_gput:NVn \g_ior_streams_prop \l_ior_stream_int {#2}
\tex_openin:D #1#2 \scan_stop:
}
}
-\cs_new_protected_nopar:Npn \iow_open:Nn #1#2
+\cs_new_protected:Npn \iow_open:Nn #1#2
{
\iow_close:N #1
\int_set:Nn \l_iow_stream_int \c_sixteen
\tl_map_function:NN \c_iow_streams_tl \iow_alloc_write:n
\int_compare:nNnTF \l_iow_stream_int = \c_sixteen
- { \msg_kernel_error:nn { iow } { streams-exhausted } }
+ { \msg_kernel_fatal:nn { iow } { streams-exhausted } }
{
\iow_stream_alloc:N #1
\prop_gput:NVn \g_iow_streams_prop \l_iow_stream_int {#2}
@@ -602,7 +618,7 @@
% The property list contains file names for streams in use, so
% any unused ones are for the taking.
% \begin{macrocode}
-\cs_new_protected_nopar:Npn \iow_alloc_write:n #1
+\cs_new_protected:Npn \iow_alloc_write:n #1
{
\prop_if_in:NnF \g_iow_streams_prop {#1}
{
@@ -610,7 +626,7 @@
\tl_map_break:
}
}
-\cs_new_protected_nopar:Npn \ior_alloc_read:n #1
+\cs_new_protected:Npn \ior_alloc_read:n #1
{
\prop_if_in:NnF \g_iow_streams_prop {#1}
{
@@ -638,26 +654,25 @@
% one is needed, we get the number allocated by \LaTeXe{} to get
% \enquote{back on track} with allocation.
% \begin{macrocode}
-\cs_new_protected_nopar:Npn \iow_stream_alloc:N #1
+\cs_new_protected:Npn \iow_stream_alloc:N #1
{
- \cs_if_exist:cTF { g_iow_ \int_use:N \l_iow_stream_int _stream }
- { \cs_gset_eq:Nc #1 { g_iow_ \int_use:N \l_iow_stream_int _stream } }
+ \cs_if_exist:cTF { g_iow_ \int_use:N \l_iow_stream_int _iow }
+ { \cs_gset_eq:Nc #1 { g_iow_ \int_use:N \l_iow_stream_int _iow } }
{
%<*package>
\iow_stream_alloc_aux:
\int_compare:nNnT \l_iow_stream_int = \c_sixteen
{
- \iow_raw_new:N \g_iow_tmp_stream
- \int_set:Nn \l_iow_stream_int { \g_iow_tmp_stream }
+ \iow_raw_new:N \g_iow_tmp_iow
+ \int_set:Nn \l_iow_stream_int { \g_iow_tmp_iow }
\cs_gset_eq:cN
- { g_iow_ \int_use:N \l_iow_stream_int _stream }
- \g_iow_tmp_stream
+ { g_iow_ \int_use:N \l_iow_stream_int _iow } \g_iow_tmp_iow
}
%</package>
%<*initex>
- \iow_raw_new:c { g_iow_ \int_use:N \l_iow_stream_int _stream }
+ \iow_raw_new:c { g_iow_ \int_use:N \l_iow_stream_int _iow }
%</initex>
- \cs_gset_eq:Nc #1 { g_iow_ \int_use:N \l_iow_stream_int _stream }
+ \cs_gset_eq:Nc #1 { g_iow_ \int_use:N \l_iow_stream_int _iow }
}
}
%<*package>
@@ -666,7 +681,7 @@
\int_incr:N \l_iow_stream_int
\int_compare:nNnT \l_iow_stream_int < \c_sixteen
{
- \cs_if_exist:cTF { g_iow_ \int_use:N \l_iow_stream_int _stream }
+ \cs_if_exist:cTF { g_iow_ \int_use:N \l_iow_stream_int _iow }
{
\prop_if_in:NVT \g_iow_streams_prop \l_iow_stream_int
{ \iow_stream_alloc_aux: }
@@ -675,26 +690,25 @@
}
}
%</package>
-\cs_new_protected_nopar:Npn \ior_stream_alloc:N #1
+\cs_new_protected:Npn \ior_stream_alloc:N #1
{
- \cs_if_exist:cTF { g_ior_ \int_use:N \l_ior_stream_int _stream }
- { \cs_gset_eq:Nc #1 { g_ior_ \int_use:N \l_ior_stream_int _stream } }
+ \cs_if_exist:cTF { g_ior_ \int_use:N \l_ior_stream_int _ior }
+ { \cs_gset_eq:Nc #1 { g_ior_ \int_use:N \l_ior_stream_int _ior } }
{
%<*package>
\ior_stream_alloc_aux:
\int_compare:nNnT \l_ior_stream_int = \c_sixteen
{
- \ior_raw_new:N \g_ior_tmp_stream
- \int_set:Nn \l_ior_stream_int { \g_ior_tmp_stream }
+ \ior_raw_new:N \g_ior_tmp_ior
+ \int_set:Nn \l_ior_stream_int { \g_ior_tmp_ior }
\cs_gset_eq:cN
- { g_ior_ \int_use:N \l_iow_stream_int _stream }
- \g_ior_tmp_stream
+ { g_ior_ \int_use:N \l_iow_stream_int _ior } \g_ior_tmp_ior
}
%</package>
%<*initex>
- \ior_raw_new:c { g_ior_ \int_use:N \l_ior_stream_int _stream }
+ \ior_raw_new:c { g_ior_ \int_use:N \l_ior_stream_int _ior }
%</initex>
- \cs_gset_eq:Nc #1 { g_ior_ \int_use:N \l_ior_stream_int _stream }
+ \cs_gset_eq:Nc #1 { g_ior_ \int_use:N \l_ior_stream_int _ior }
}
}
%<*package>
@@ -703,7 +717,7 @@
\int_incr:N \l_ior_stream_int
\int_compare:nNnT \l_ior_stream_int < \c_sixteen
{
- \cs_if_exist:cTF { g_ior_ \int_use:N \l_ior_stream_int _stream }
+ \cs_if_exist:cTF { g_ior_ \int_use:N \l_ior_stream_int _ior }
{
\prop_if_in:NVT \g_ior_streams_prop \l_ior_stream_int
{ \ior_stream_alloc_aux: }
@@ -727,7 +741,7 @@
% stream is actually a number we can use it directly to show that the
% slot has been freed up.
% \begin{macrocode}
-\cs_new_protected_nopar:Npn \ior_close:N #1
+\cs_new_protected:Npn \ior_close:N #1
{
\cs_if_exist:NT #1
{
@@ -736,11 +750,11 @@
\int_compare:nNnF #1 = \c_sixteen
{ \tex_closein:D #1 }
\prop_gdel:NV \g_ior_streams_prop #1
- \tex_global:D \tex_chardef:D #1 16 ~
+ \cs_gset_eq:NN #1 \c_term_ior
}
}
}
-\cs_new_protected_nopar:Npn \iow_close:N #1
+\cs_new_protected:Npn \iow_close:N #1
{
\cs_if_exist:NT #1
{
@@ -749,7 +763,7 @@
\int_compare:nNnF #1 = \c_sixteen
{ \tex_closein:D #1 }
\prop_gdel:NV \g_iow_streams_prop #1
- \tex_global:D \tex_chardef:D #1 16 ~
+ \cs_gset_eq:NN #1 \c_term_iow
}
}
}
@@ -759,7 +773,6 @@
% \end{macro}
% \end{macro}
%
-%
% \begin{macro}{\ior_list_streams:}
% Show the property lists, but with some \enquote{pretty printing}.
% See the \pkg{l3msg} module. If there are no open read streams,
@@ -813,7 +826,7 @@
% \begin{macro}{\iow_shipout:Nn, \iow_shipout:Nx}
% With \eTeX{} available deferred writing is easy.
% \begin{macrocode}
-\cs_new_protected_nopar:Npn \iow_shipout:Nn #1#2
+\cs_new_protected:Npn \iow_shipout:Nn #1#2
{ \iow_shipout_x:Nn #1 { \exp_not:n {#2} } }
\cs_generate_variant:Nn \iow_shipout:Nn { Nx }
% \end{macrocode}
@@ -835,7 +848,7 @@
% instead. If the first argument is no output stream at all, we get an
% internal error.
% \begin{macrocode}
-\cs_new_protected_nopar:Npn \iow_now:Nn #1#2
+\cs_new_protected:Npn \iow_now:Nn #1#2
{ \iow_now:Nx #1 { \exp_not:n {#2} } }
% \end{macrocode}
% \end{macro}
@@ -844,10 +857,10 @@
% \begin{macro}{\iow_term:n, \iow_term:x}
% Writing to the log and the terminal directly are relatively easy.
% \begin{macrocode}
-\cs_set_protected_nopar:Npn \iow_log:x { \iow_now:Nx \c_iow_log_stream }
-\cs_new_protected_nopar:Npn \iow_log:n { \iow_now:Nn \c_iow_log_stream }
-\cs_set_protected_nopar:Npn \iow_term:x { \iow_now:Nx \c_iow_term_stream }
-\cs_new_protected_nopar:Npn \iow_term:n { \iow_now:Nn \c_iow_term_stream }
+\cs_set_protected_nopar:Npn \iow_log:x { \iow_now:Nx \c_log_iow }
+\cs_new_protected_nopar:Npn \iow_log:n { \iow_now:Nn \c_log_iow }
+\cs_set_protected_nopar:Npn \iow_term:x { \iow_now:Nx \c_term_iow }
+\cs_new_protected_nopar:Npn \iow_term:n { \iow_now:Nn \c_term_iow }
% \end{macrocode}
%\end{macro}
%\end{macro}
@@ -855,9 +868,9 @@
% \begin{macro}{\iow_now_when_avail:Nn, \iow_now_when_avail:Nx}
% For writing only if the stream requested is open at all.
% \begin{macrocode}
-\cs_new_protected_nopar:Npn \iow_now_when_avail:Nn #1
+\cs_new_protected:Npn \iow_now_when_avail:Nn #1
{ \cs_if_free:NTF #1 { \use_none:n } { \iow_now:Nn #1 } }
-\cs_new_protected_nopar:Npn \iow_now_when_avail:Nx #1
+\cs_new_protected:Npn \iow_now_when_avail:Nx #1
{ \cs_if_free:NTF #1 { \use_none:n } { \iow_now:Nx #1 } }
% \end{macrocode}
% \end{macro}
@@ -1167,7 +1180,7 @@
% At the end, we simply save the last line (without the run-on text),
% and prevent the loop.
% \begin{macrocode}
-\cs_new_protected_nopar:Npn \iow_wrap_special:w #1 ~ #2 ~ #3 ~ %
+\cs_new_protected:Npn \iow_wrap_special:w #1 ~ #2 ~ #3 ~ %
{
\use:c { iow_wrap_#1: }
\str_if_eq:xxTF { #2~#3 } { ~ \c_iow_wrap_marker_tl }
@@ -1250,7 +1263,7 @@
{
\if_int_compare:w #1 = \c_sixteen
\prg_return_true:
- \else:
+ \else:
\if_eof:w #1
\prg_return_true:
\else:
@@ -1267,9 +1280,9 @@
% \begin{macro}{\ior_gto:NN}
% And here we read from files.
% \begin{macrocode}
-\cs_new_protected_nopar:Npn \ior_to:NN #1#2
+\cs_new_protected:Npn \ior_to:NN #1#2
{ \tex_read:D #1 to #2 }
-\cs_new_protected_nopar:Npn \ior_gto:NN #1#2
+\cs_new_protected:Npn \ior_gto:NN #1#2
{ \tex_global:D \tex_read:D #1 to #2 }
% \end{macrocode}
% \end{macro}
@@ -1279,9 +1292,9 @@
% \begin{macro}{\ior_str_gto:NN}
% Reading as strings is also a primitive wrapper.
% \begin{macrocode}
-\cs_new_protected_nopar:Npn \ior_str_to:NN #1#2
+\cs_new_protected:Npn \ior_str_to:NN #1#2
{ \etex_readline:D #1 to #2 }
-\cs_new_protected_nopar:Npn \ior_str_gto:NN #1#2
+\cs_new_protected:Npn \ior_str_gto:NN #1#2
{ \tex_global:D \etex_readline:D #1 to #2 }
% \end{macrocode}
% \end{macro}