diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3file.dtx')
| -rw-r--r-- | Master/texmf-dist/source/latex/l3kernel/l3file.dtx | 195 |
1 files changed, 108 insertions, 87 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3file.dtx b/Master/texmf-dist/source/latex/l3kernel/l3file.dtx index d7d94f5cf3a..271a66e704f 100644 --- a/Master/texmf-dist/source/latex/l3kernel/l3file.dtx +++ b/Master/texmf-dist/source/latex/l3kernel/l3file.dtx @@ -7,7 +7,7 @@ % license or (at your option) any later version. The latest version % of this license is in the file % -% http://www.latex-project.org/lppl.txt +% https://www.latex-project.org/lppl.txt % % This file is part of the "l3kernel bundle" (The Work in LPPL) % and all files in that bundle must be distributed together. @@ -21,7 +21,7 @@ % for those people who are interested. % %<*driver> -\documentclass[full]{l3doc} +\documentclass[full,kernel]{l3doc} \begin{document} \DocInput{\jobname.dtx} \PrintIndex @@ -42,7 +42,7 @@ % }^^A % } % -% \date{Released 2017/11/14} +% \date{Released 2017/12/05} % % \maketitle % @@ -381,8 +381,8 @@ % Use outside of a \cs[no-index]{ior_map_\ldots} scenario leads 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 +% When the mapping is broken, additional tokens may be inserted +% before further items are taken % from the input stream. This depends on the design of the mapping % function. % \end{texnote} @@ -390,17 +390,17 @@ % % \begin{function}[added = 2012-06-29]{\ior_map_break:n} % \begin{syntax} -% \cs{ior_map_break:n} \Arg{tokens} +% \cs{ior_map_break:n} \Arg{code} % \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 +% the \meta{code} after the mapping has ended. This % normally takes 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> } } +% { \ior_map_break:n { <code> } } % { % % Do something useful % } @@ -409,8 +409,8 @@ % Use outside of a \cs[no-index]{ior_map_\ldots} scenario leads 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 +% When the mapping is broken, additional tokens may be inserted +% before the \meta{code} is % inserted into the input stream. % This depends on the design of the mapping function. % \end{texnote} @@ -532,7 +532,7 @@ % % \subsection{Wrapping lines in output} % -% \begin{function}[added = 2012-06-28, updated = 2017-07-17]{\iow_wrap:nnnN} +% \begin{function}[added = 2012-06-28, updated = 2017-12-04]{\iow_wrap:nnnN} % \begin{syntax} % \cs{iow_wrap:nnnN} \Arg{text} \Arg{run-on text} \Arg{set up} \meta{function} % \end{syntax} @@ -546,7 +546,7 @@ % \meta{text} and \meta{run-on text} are exhaustively expanded by the % function, with the following substitutions: % \begin{itemize} -% \item |\\| may be used to force a new line, +% \item |\\| or \cs{iow_newline:} may be used to force a new line, % \item \verb*|\ | may be used to represent a forced space % (for example after a control sequence), % \item |\#|, |\%|, |\{|, |\}|, |\~| may be used to represent @@ -841,9 +841,9 @@ % \end{macrocode} % \end{variable} % -% \begin{macro}[int]{\__file_name_sanitize:nN} -% \begin{macro}[int]{\__file_name_quote:nN} -% \begin{macro}[int, aux]{\@@_name_sanitize_aux:n} +% \begin{macro}{\__file_name_sanitize:nN} +% \begin{macro}{\__file_name_quote:nN} +% \begin{macro}{\@@_name_sanitize_aux:n} % For converting a token list to a string where active characters are treated % as strings from the start. The logic to the quoting normalisation is the % same as used by \texttt{lualatexquotejobname}: check for balanced |"|, and @@ -885,7 +885,7 @@ % \end{macro} % % \begin{macro}{\file_get_full_name:nN, \file_get_full_name:VN} -% \begin{macro}[aux]{\@@_get_full_name_search:nN} +% \begin{macro}{\@@_get_full_name_search:nN} % The way to test if a file exists is to try to open it: if it does % not exist then \TeX{} reports end-of-file. A search is made % looking at each potential path in turn (starting from the current @@ -955,7 +955,7 @@ % \end{macrocode} % \end{macro} % -% \begin{macro}[int]{\__file_missing:n} +% \begin{macro}{\__file_missing:n} % An error message for a missing file, also used in \cs{ior_open:Nn}. % \begin{macrocode} \cs_new_protected:Npn \__file_missing:n #1 @@ -968,10 +968,10 @@ % \end{macro} % % \begin{macro}{\file_input:n} -% \begin{macro}[aux]{\@@_input:n, \@@_input:V} -% \begin{macro}[aux]{\@@_input_push:n} -% \begin{macro}[aux]{\@@_input_pop:} -% \begin{macro}[aux]{\@@_input_pop:nnn} +% \begin{macro}{\@@_input:n, \@@_input:V} +% \begin{macro}{\@@_input_push:n} +% \begin{macro}{\@@_input_pop:} +% \begin{macro}{\@@_input_pop:nnn} % Loading a file is done in a safe way, checking first that the file % exists and loading only if it does. Push the file name on the % \cs{g_@@_stack_seq}, and add it to the file list, either @@ -1036,7 +1036,7 @@ % \end{macro} % % \begin{macro}{\file_parse_full_name:nNNN} -% \begin{macro}[aux] +% \begin{macro} % {\@@_parse_full_name_auxi:w, \@@_parse_full_name_split:nNNNTF} % Parsing starts by stripping off any surrounding quotes. Then find % the directory |#4| by splitting at the last~|/|. (The auxiliary @@ -1091,19 +1091,17 @@ % \end{macro} % \end{macro} % -% \begin{macro}{\file_show_list:, \file_log_list:} -% \begin{macro}[aux, EXP]{\@@_list_aux:n} +% \begin{macro}{\file_show_list:, \file_log_list:, \@@_list:N} +% \begin{macro}[EXP]{\@@_list_aux:n} % A function to list all files used to the log, without duplicates. % In package mode, if \cs{@filelist} is still defined, we need to take % this list of file names into account (we capture it % \cs{AtBeginDocument} into \cs{g_@@_record_seq}), turning it to a -% string (this does not affect the commas of this comma list). The -% message system is a bit finnicky (it can only display results that -% start with |>~| and end with a dot) so that constrains the possible -% markup. The advantage is that we get terminal and log outputs for -% free. +% string (this does not affect the commas of this comma list). % \begin{macrocode} -\cs_new_protected:Npn \file_show_list: +\cs_new_protected:Npn \file_show_list: { \@@_list:N \msg_show:nnxxxx } +\cs_new_protected:Npn \file_log_list: { \@@_list:N \msg_log:nnxxxx } +\cs_new_protected:Npn \@@_list:N #1 { \seq_clear:N \l_@@_tmp_seq %<*package> @@ -1115,16 +1113,10 @@ %</package> \seq_concat:NNN \l_@@_tmp_seq \l_@@_tmp_seq \g_@@_record_seq \seq_remove_duplicates:N \l_@@_tmp_seq - \__msg_show_wrap:n - { - >~File~List~< \\ - \seq_map_function:NN \l_@@_tmp_seq \@@_list_aux:n - ............ - } + #1 { LaTeX/kernel } { file-list } + { \seq_map_function:NN \l_@@_tmp_seq \@@_list_aux:n } { } { } { } } -\cs_new:Npn \@@_list_aux:n #1 { #1 \\ } -\cs_new_protected:Npn \file_log_list: - { \__msg_log_next: \file_show_list: } +\cs_new:Npn \@@_list_aux:n #1 { \iow_newline: #1 } % \end{macrocode} % \end{macro} % \end{macro} @@ -1255,7 +1247,7 @@ % \end{macrocode} % \end{macro} % -% \begin{macro}[int]{\@@_new:N} +% \begin{macro}{\@@_new:N} % In package mode, streams are reserved using \tn{newread} before they % can be managed by \pkg{ior}. To prevent \pkg{ior} from being % affected by redefinitions of \tn{newread} (such as done by the @@ -1271,8 +1263,8 @@ % \end{macrocode} % \end{macro} % -% \begin{macro}[int]{\@@_open:Nn, \@@_open:No} -% \begin{macro}[aux]{\@@_open_stream:Nn} +% \begin{macro}{\@@_open:Nn, \@@_open:No} +% \begin{macro}{\@@_open_stream:Nn} % The stream allocation itself uses the fact that there is a list of all of % those available, so allocation is simply a question of using the number at % the top of the list. In package mode, life gets more complex as it's @@ -1331,25 +1323,26 @@ % \end{macro} % % \begin{macro}{\ior_show_list:, \ior_log_list:} -% \begin{macro}[aux]{\@@_list:Nn} +% \begin{macro}{\@@_list:N} % Show the property lists, but with some \enquote{pretty printing}. % See the \pkg{l3msg} module. The first argument of the message is % |ior| (as opposed to |iow|) and the second is empty if no read -% stream is open and non-empty (in fact a question mark) otherwise. -% The code of the message \texttt{show-streams} takes care of -% translating |ior|/|iow| to English. The list of streams is -% formatted using \cs{__msg_show_item_unbraced:nn}. +% stream is open and non-empty (the list of streams formatted using +% \cs{msg_show_item_unbraced:nn}) otherwise. The code of the message +% \texttt{show-streams} takes care of translating |ior|/|iow| to +% English. % \begin{macrocode} -\cs_new_protected:Npn \ior_show_list: - { \@@_list:Nn \g_@@_streams_prop { ior } } -\cs_new_protected:Npn \ior_log_list: - { \__msg_log_next: \ior_show_list: } -\cs_new_protected:Npn \@@_list:Nn #1#2 +\cs_new_protected:Npn \ior_show_list: { \@@_list:N \msg_show:nnxxxx } +\cs_new_protected:Npn \ior_log_list: { \@@_list:N \msg_log:nnxxxx } +\cs_new_protected:Npn \@@_list:N #1 { - \__msg_show_pre:nnxxxx { LaTeX / kernel } { show-streams } - {#2} { \prop_if_empty:NF #1 { ? } } { } { } - \__msg_show_wrap:n - { \prop_map_function:NN #1 \__msg_show_item_unbraced:nn } + #1 { LaTeX / kernel } { show-streams } + { ior } + { + \prop_map_function:NN \g_@@_streams_prop + \msg_show_item_unbraced:nn + } + { } { } } % \end{macrocode} % \end{macro} @@ -1357,7 +1350,7 @@ % % \subsubsection{Reading input} % -% \begin{macro}[int]{\if_eof:w} +% \begin{macro}{\if_eof:w} % The primitive conditional % \begin{macrocode} \cs_new_eq:NN \if_eof:w \tex_ifeof:D @@ -1424,9 +1417,9 @@ % \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{macro}{\@@_map_inline:NNn} +% \begin{macro}{\@@_map_inline:NNNn} +% \begin{macro}{\@@_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 @@ -1567,7 +1560,7 @@ % \end{macrocode} % \end{macro} % -% \begin{macro}[int]{\@@_new:N} +% \begin{macro}{\@@_new:N} % As for read streams, copy \tn{newwrite} in package mode, making sure % that it is not \tn{outer}. % \begin{macrocode} @@ -1579,7 +1572,7 @@ % \end{macro} % % \begin{macro}{\iow_open:Nn, \iow_open:cn} -% \begin{macro}[aux]{\@@_open_stream:Nn, \@@_open_stream:NV} +% \begin{macro}{\@@_open_stream:Nn, \@@_open_stream:NV} % The same idea as for reading, but without the path and without the need % to allow for a conditional version. % \begin{macrocode} @@ -1634,14 +1627,21 @@ % \end{macro} % % \begin{macro}{\iow_show_list:, \iow_log_list:} -% \begin{macro}{\@@_list:Nn} +% \begin{macro}{\@@_list:N} % Done as for input, but with a copy of the auxiliary so the name is correct. % \begin{macrocode} -\cs_new_protected:Npn \iow_show_list: - { \@@_list:Nn \g_@@_streams_prop { iow } } -\cs_new_protected:Npn \iow_log_list: - { \__msg_log_next: \iow_show_list: } -\cs_new_eq:NN \@@_list:Nn \__ior_list:Nn +\cs_new_protected:Npn \iow_show_list: { \@@_list:N \msg_show:nnxxxx } +\cs_new_protected:Npn \iow_log_list: { \@@_list:N \msg_log:nnxxxx } +\cs_new_protected:Npn \@@_list:N #1 + { + #1 { LaTeX / kernel } { show-streams } + { iow } + { + \prop_map_function:NN \g_@@_streams_prop + \msg_show_item_unbraced:nn + } + { } { } + } % \end{macrocode} % \end{macro} % \end{macro} @@ -1669,8 +1669,8 @@ % % \subsubsection{Immediate writing} % -% \begin{macro}[int]{\@@_with:Nnn} -% \begin{macro}[aux]{\@@_with_aux:nNnn} +% \begin{macro}{\@@_with:Nnn} +% \begin{macro}{\@@_with_aux:nNnn} % If the integer~|#1| is equal to~|#2|, just leave~|#3| in the input % stream. Otherwise, pass the old value to an auxiliary, which sets % the integer to the new value, runs the code, and restores the @@ -1776,8 +1776,8 @@ % \end{macrocode} % \end{variable} % -% \begin{macro}[aux]{\@@_set_indent:n} -% \begin{macro}[aux]{\@@_unindent:w} +% \begin{macro}{\@@_set_indent:n} +% \begin{macro}{\@@_unindent:w} % \begin{variable}{\l_@@_one_indent_tl, \l_@@_one_indent_int} % The \texttt{one_indent} variables hold one indentation marker and % its length. The \cs{@@_unindent:w} auxiliary removes one @@ -1872,8 +1872,8 @@ % \end{variable} % % \begin{macro}{\iow_indent:n} -% \begin{macro}[EXP,aux]{\@@_indent:n} -% \begin{macro}[EXP,aux]{\@@_indent_error:n} +% \begin{macro}[EXP]{\@@_indent:n} +% \begin{macro}[EXP]{\@@_indent_error:n} % We set \cs{iow_indent:n} to produce an error when outside % messages. Within wrapped message, it is set to \cs{@@_indent:n} when % valid and otherwise to \cs{@@_indent_error:n}. The first places the @@ -1923,7 +1923,7 @@ \cs_set:Npx \% { \token_to_str:N \% } \cs_set:Npx \~ { \token_to_str:N \~ } \int_set:Nn \tex_escapechar:D { 92 } - \cs_set_eq:NN \\ \c_@@_wrap_newline_marker_tl + \cs_set_eq:NN \\ \iow_newline: \cs_set_eq:NN \ \c_catcode_other_space_tl \cs_set_eq:NN \iow_indent:n \@@_indent:n #3 @@ -1962,8 +1962,9 @@ % \end{macrocode} % \end{macro} % -% \begin{macro}[aux]{\@@_wrap_do:, \@@_wrap_start:w} -% Escape spaces. Set up a few variables, in particular the initial +% \begin{macro}{\@@_wrap_do:, \@@_wrap_fix_newline:w, \@@_wrap_start:w} +% Escape spaces and change newlines to \cs{c_@@_wrap_newline_marker_tl}. +% Set up a few variables, in particular the initial % value of \cs{l_@@_wrap_tl}: the space stops the % \texttt{f}-expansion of the main wrapping function and % \cs{use_none:n} removes a newline marker inserted by later code. @@ -1978,8 +1979,22 @@ \exp_args:No \__str_to_other_fast:n \l_@@_wrap_tl \c_@@_wrap_end_marker_tl } + \tl_set:Nx \l_@@_wrap_tl + { + \exp_after:wN \@@_wrap_fix_newline:w \l_@@_wrap_tl + ^^J \q_nil ^^J \q_stop + } \exp_after:wN \@@_wrap_start:w \l_@@_wrap_tl } +\cs_new:Npn \@@_wrap_fix_newline:w #1 ^^J #2 ^^J + { + #1 + \if_meaning:w \q_nil #2 + \use_i_delimit_by_q_stop:nw + \fi: + \c_@@_wrap_newline_marker_tl + \@@_wrap_fix_newline:w #2 ^^J + } \cs_new_protected:Npn \@@_wrap_start:w { \bool_set_false:N \l_@@_line_break_bool @@ -1993,7 +2008,7 @@ % \end{macrocode} % \end{macro} % -% \begin{macro}[aux]{\@@_wrap_chunk:nw, \@@_wrap_next:nw} +% \begin{macro}{\@@_wrap_chunk:nw, \@@_wrap_next:nw} % The \texttt{chunk} and \texttt{next} auxiliaries are defined % indirectly to obtain the expansions of \cs{c_catcode_other_space_tl} % and \cs{c_@@_wrap_marker_tl} in their definition. The \texttt{next} @@ -2035,8 +2050,8 @@ % \end{macrocode} % \end{macro} % -% \begin{macro}[aux]{\@@_wrap_line:nw} -% \begin{macro}[EXP,aux] +% \begin{macro}{\@@_wrap_line:nw} +% \begin{macro}[EXP] % { % \@@_wrap_line_loop:w, % \@@_wrap_line_aux:Nw, @@ -2126,8 +2141,8 @@ % \end{macro} % \end{macro} % -% \begin{macro}[EXP,aux]{\@@_wrap_break:w} -% \begin{macro}[EXP,aux] +% \begin{macro}[EXP]{\@@_wrap_break:w} +% \begin{macro}[EXP] % { % \@@_wrap_break_first:w, % \@@_wrap_break_none:w, @@ -2189,7 +2204,7 @@ % \end{macro} % \end{macro} % -% \begin{macro}[aux]{\@@_wrap_next_line:w} +% \begin{macro}{\@@_wrap_next_line:w} % The special case where the end of a line coincides with the end of a % chunk is detected here, to avoid a spurious empty line. Otherwise, % call \cs{@@_wrap_line:nw} to find characters for the next line @@ -2214,7 +2229,7 @@ % \end{macrocode} % \end{macro} % -% \begin{macro}[aux]{\@@_wrap_indent:, \@@_wrap_unindent:} +% \begin{macro}{\@@_wrap_indent:, \@@_wrap_unindent:} % These functions are called after a chunk has been wrapped, when % encountering \texttt{indent}/\texttt{unindent} markers. Add the % line part (last line part of the previous chunk) to the line so far @@ -2242,7 +2257,7 @@ % \end{macrocode} % \end{macro} % -% \begin{macro}[aux]{\@@_wrap_newline:, \@@_wrap_end:} +% \begin{macro}{\@@_wrap_newline:, \@@_wrap_end:} % These functions are called after a chunk has been line-wrapped, when % encountering a \texttt{newline}/\texttt{end} marker. Unless we just % took a line-break, store the line part and the line so far into the @@ -2266,7 +2281,7 @@ % \end{macrocode} % \end{macro} % -% \begin{macro}[aux]{\@@_wrap_store_do:n} +% \begin{macro}{\@@_wrap_store_do:n} % First add the last line part to the line, then append it to % \cs{l_@@_wrap_tl} with the appropriate new line (with % \enquote{run-on} text), possibly with its last space removed (|#1| @@ -2287,7 +2302,7 @@ % \end{macrocode} % \end{macro} % -% \begin{macro}[EXP, aux]{\@@_wrap_trim:N, \@@_wrap_trim:w} +% \begin{macro}[EXP]{\@@_wrap_trim:N, \@@_wrap_trim:w} % Remove one trailing \enquote{other} space from the argument. % \begin{macrocode} \cs_set_protected:Npn \@@_tmp:w #1 @@ -2309,6 +2324,12 @@ The~requested~file~could~not~be~found~in~the~current~directory,~ in~the~TeX~search~path~or~in~the~LaTeX~search~path. } +\__msg_kernel_new:nnn { kernel } { file-list } + { + >~File~List~< + #1 \\ + ............. + } \__msg_kernel_new:nnnn { kernel } { input-streams-exhausted } { Input~streams~exhausted } { |