diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3clist.dtx')
| -rw-r--r-- | Master/texmf-dist/source/latex/l3kernel/l3clist.dtx | 153 |
1 files changed, 74 insertions, 79 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3clist.dtx b/Master/texmf-dist/source/latex/l3kernel/l3clist.dtx index ed70ce187a6..d7a063b7aae 100644 --- a/Master/texmf-dist/source/latex/l3kernel/l3clist.dtx +++ b/Master/texmf-dist/source/latex/l3kernel/l3clist.dtx @@ -9,7 +9,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. @@ -23,7 +23,7 @@ % for those people who are interested. % %<*driver> -\documentclass[full]{l3doc} +\documentclass[full,kernel]{l3doc} \begin{document} \DocInput{\jobname.dtx} \end{document} @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2017/11/14} +% \date{Released 2017/12/05} % % \maketitle % @@ -384,7 +384,6 @@ % each iteration. The \meta{items} are returned from left to right. % The function \cs{clist_map_inline:Nn} is in general more efficient % than \cs{clist_map_function:NN}. -% One mapping may be nested inside another. % \end{function} % % \begin{function}[updated = 2012-06-29] @@ -395,21 +394,19 @@ % Applies \meta{inline function} to every \meta{item} stored % within the \meta{comma list}. The \meta{inline function} should % consist of code which receives the \meta{item} as |#1|. -% One in line mapping can be nested inside another. The \meta{items} -% are returned from left to right. +% The \meta{items} are returned from left to right. % \end{function} % % \begin{function}[updated = 2012-06-29] % {\clist_map_variable:NNn, \clist_map_variable:cNn, \clist_map_variable:nNn} % \begin{syntax} -% \cs{clist_map_variable:NNn} \meta{comma list} \meta{tl~var.} \Arg{function using tl~var.} +% \cs{clist_map_variable:NNn} \meta{comma list} \meta{variable} \Arg{code} % \end{syntax} -% Stores each entry in the \meta{comma list} in turn in the -% \meta{tl~var.}\ and applies the \meta{function using tl~var.} -% The \meta{function} usually consists of code making use of -% the \meta{tl~var.}, but this is not enforced. One variable -% mapping can be nested inside another. The \meta{items} -% are returned from left to right. +% Stores each \meta{item} of the \meta{comma list} in turn in the +% (token list) \meta{variable} and applies the \meta{code}. The +% \meta{code} will usually make use of the \meta{variable}, but this +% is not enforced. The assignments to the \meta{variable} are local. +% The \meta{items} are returned from left to right. % \end{function} % % \begin{function}[rEXP, updated = 2012-06-29]{\clist_map_break:} @@ -432,8 +429,8 @@ % Use outside of a |\clist_map_...| 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} @@ -441,17 +438,17 @@ % % \begin{function}[updated = 2012-06-29, rEXP]{\clist_map_break:n} % \begin{syntax} -% \cs{clist_map_break:n} \Arg{tokens} +% \cs{clist_map_break:n} \Arg{code} % \end{syntax} % Used to terminate a |\clist_map_...| function before all % entries in the \meta{comma list} 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} % \clist_map_inline:Nn \l_my_clist % { % \str_if_eq:nnTF { #1 } { bingo } -% { \clist_map_break:n { <tokens> } } +% { \clist_map_break:n { <code> } } % { % % Do something useful % } @@ -460,8 +457,8 @@ % Use outside of a |\clist_map_...| 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} @@ -736,7 +733,7 @@ % \end{macrocode} % \end{variable} % -% \begin{macro}[aux]{\@@_tmp:w} +% \begin{macro}{\@@_tmp:w} % A temporary function for various purposes. % \begin{macrocode} \cs_new_protected:Npn \@@_tmp:w { } @@ -832,9 +829,9 @@ % \clist_gset_from_seq:Nc, \clist_gset_from_seq:cc % } % \UnitTested -% \begin{macro}[aux]{\@@_set_from_seq:NNNN} -% \begin{macro}[aux]{\@@_wrap_item:n} -% \begin{macro}[aux]{\@@_set_from_seq:w} +% \begin{macro}{\@@_set_from_seq:NNNN} +% \begin{macro}{\@@_wrap_item:n} +% \begin{macro}{\@@_set_from_seq:w} % Setting a comma list from a comma-separated list is done using a simple % mapping. We wrap most items with \cs{exp_not:n}, and a comma. Items which % contain a comma or a space are surrounded by an extra set of braces. The @@ -879,7 +876,7 @@ % \UnitTested % \begin{macro}{\clist_gconcat:NNN, \clist_gconcat:ccc} % \UnitTested -% \begin{macro}[aux]{\@@_concat:NNNN} +% \begin{macro}{\@@_concat:NNNN} % Concatenating comma lists is not quite as easy as it seems, as % there needs to be the correct addition of a comma to the output. So % a little work to do. @@ -916,8 +913,8 @@ % % \subsection{Removing spaces around items} % -% \begin{macro}[int,EXP]{\@@_trim_spaces_generic:nw} -% \begin{macro}[aux]{\@@_trim_spaces_generic:nn} +% \begin{macro}[EXP]{\@@_trim_spaces_generic:nw} +% \begin{macro}{\@@_trim_spaces_generic:nn} % \begin{syntax} % \cs{@@_trim_spaces_generic:nw} \Arg{code} \cs{q_mark} \meta{item} |,| % \end{syntax} @@ -941,8 +938,8 @@ % \end{macro} % \end{macro} % -% \begin{macro}[int,rEXP]{\@@_trim_spaces:n} -% \begin{macro}[aux]{\@@_trim_spaces:nn} +% \begin{macro}[rEXP]{\@@_trim_spaces:n} +% \begin{macro}{\@@_trim_spaces:nn} % The first argument of \cs{@@_trim_spaces:nn} is initially empty, % and later a comma, namely, as soon as we have added an item to the % resulting list. The auxiliary tests for the end of the list, @@ -1017,7 +1014,7 @@ % \clist_gput_left:co, \clist_gput_left:cx % } % \UnitTested -% \begin{macro}[aux]{\@@_put_left:NNNn} +% \begin{macro}{\@@_put_left:NNNn} % Comma lists cannot hold empty values: there are therefore a couple % of sanity checks to avoid accumulating commas. % \begin{macrocode} @@ -1055,7 +1052,7 @@ % \clist_gput_right:co, \clist_gput_right:cx % } % \UnitTested -% \begin{macro}[aux]{\@@_put_right:NNNn} +% \begin{macro}{\@@_put_right:NNNn} % \begin{macrocode} \cs_new_protected:Npn \clist_put_right:Nn { \@@_put_right:NNNn \clist_concat:NNN \clist_set:Nn } @@ -1079,7 +1076,7 @@ % % \begin{macro}{\clist_get:NN, \clist_get:cN} % \UnitTested -% \begin{macro}[aux]{\@@_get:wN} +% \begin{macro}{\@@_get:wN} % Getting an item from the left of a comma list is pretty easy: just % trim off the first item using the comma. % \begin{macrocode} @@ -1102,7 +1099,7 @@ % \UnitTested % \begin{macro}{\clist_gpop:NN, \clist_gpop:cN} % \UnitTested -% \begin{macro}[aux] +% \begin{macro} % {\@@_pop:NNN, \@@_pop:wwNNN, \@@_pop:wN} % An empty clist leads to \cs{q_no_value}, otherwise grab until the % first comma and assign to the variable. The second argument of @@ -1146,7 +1143,7 @@ % \begin{macro}[TF]{\clist_get:NN, \clist_get:cN} % \begin{macro}[TF]{\clist_pop:NN, \clist_pop:cN} % \begin{macro}[TF]{\clist_gpop:NN, \clist_gpop:cN} -% \begin{macro}[aux]{\@@_pop_TF:NNN} +% \begin{macro}{\@@_pop_TF:NNN} % The same, as branching code: very similar to the above. % \begin{macrocode} \prg_new_protected_conditional:Npnn \clist_get:NN #1#2 { T , F , TF } @@ -1231,7 +1228,7 @@ % \UnitTested % \begin{macro}{\clist_gremove_duplicates:N, \clist_gremove_duplicates:c} % \UnitTested -% \begin{macro}[aux]{\@@_remove_duplicates:NN} +% \begin{macro}{\@@_remove_duplicates:NN} % Removing duplicates means making a new list then copying it. % \begin{macrocode} \cs_new_protected:Npn \clist_remove_duplicates:N @@ -1259,9 +1256,9 @@ % \UnitTested % \begin{macro}{\clist_gremove_all:Nn, \clist_gremove_all:cn} % \UnitTested -% \begin{macro}[aux]{\@@_remove_all:NNn} -% \begin{macro}[aux]{\@@_remove_all:w} -% \begin{macro}[aux]{\@@_remove_all:} +% \begin{macro}{\@@_remove_all:NNn} +% \begin{macro}{\@@_remove_all:w} +% \begin{macro}{\@@_remove_all:} % The method used here is very similar to \cs{tl_replace_all:Nnn}. % Build a function delimited by the \meta{item} that should be removed, % surrounded with commas, and call that function followed by @@ -1342,7 +1339,7 @@ % \end{macro} % % \begin{macro}[EXP]{\clist_reverse:n} -% \begin{macro}[aux, EXP]{\@@_reverse:wwNww, \@@_reverse_end:ww} +% \begin{macro}[EXP]{\@@_reverse:wwNww, \@@_reverse_end:ww} % The reversed token list is built one item at a time, and stored % between \cs{q_stop} and \cs{q_mark}, in the form of |?| followed by % zero or more instances of \enquote{\meta{item}\texttt{,}}. We start from a comma @@ -1396,8 +1393,8 @@ % \end{macro} % % \begin{macro}[EXP, pTF]{\clist_if_empty:n} -% \begin{macro}[aux, EXP]{\@@_if_empty_n:w} -% \begin{macro}[aux, EXP]{\@@_if_empty_n:wNw} +% \begin{macro}[EXP]{\@@_if_empty_n:w} +% \begin{macro}[EXP]{\@@_if_empty_n:wNw} % As usual, we insert a token (here |?|) before grabbing % any argument: this avoids losing braces. The argument % of \cs{tl_if_empty:oTF} is empty if |#1| is |?| followed @@ -1434,7 +1431,7 @@ % \clist_if_in:cn, \clist_if_in:cV, \clist_if_in:co, % \clist_if_in:nn, \clist_if_in:nV, \clist_if_in:no % } -% \begin{macro}[aux]{\@@_if_in_return:nn} +% \begin{macro}{\@@_if_in_return:nn} % \UnitTested % See description of the \cs{tl_if_in:Nn} function for details. % We simply surround the comma list, and the item, with commas. @@ -1472,7 +1469,7 @@ % % \begin{macro}{\clist_map_function:NN, \clist_map_function:cN} % \UnitTested -% \begin{macro}[aux]{\@@_map_function:Nw} +% \begin{macro}{\@@_map_function:Nw} % If the variable is empty, the mapping is skipped (otherwise, % that comma-list would be seen as consisting of one empty item). % Then loop over the comma-list, grabbing one comma-delimited @@ -1502,8 +1499,8 @@ % % \begin{macro}{\clist_map_function:nN} % \UnitTested -% \begin{macro}[aux]{\@@_map_function_n:Nn} -% \begin{macro}[aux]{\@@_map_unbrace:Nw} +% \begin{macro}{\@@_map_function_n:Nn} +% \begin{macro}{\@@_map_unbrace:Nw} % The \texttt{n}-type mapping function is a bit more awkward, % since spaces must be trimmed from each item. % Space trimming is again based on \cs{@@_trim_spaces_generic:nw}. @@ -1575,7 +1572,7 @@ % \begin{macro}{\clist_map_variable:NNn, \clist_map_variable:cNn} % \UnitTested % \begin{macro}{\clist_map_variable:nNn} -% \begin{macro}[aux]{\@@_map_variable:Nnw} +% \begin{macro}{\@@_map_variable:Nnw} % As for other comma-list mappings, filter out the case of % an empty list. Same approach as \cs{clist_map_function:Nn}, % additionally we store each item in the given variable. @@ -1622,8 +1619,8 @@ % \end{macro} % % \begin{macro}{\clist_count:N, \clist_count:c, \clist_count:n} -% \begin{macro}[aux]{\@@_count:n} -% \begin{macro}[aux]{\@@_count:w} +% \begin{macro}{\@@_count:n} +% \begin{macro}{\@@_count:w} % Counting the items in a comma list is done using the same approach as for % other token count functions: turn each entry into a \texttt{+1} then use % integer evaluation to actually do the mathematics. @@ -1665,7 +1662,7 @@ % \subsection{Using comma lists} % % \begin{macro}[EXP]{\clist_use:Nnnn, \clist_use:cnnn} -% \begin{macro}[EXP, aux] +% \begin{macro}[EXP] % {\@@_use:wwn, \@@_use:nwwwwnwn, \@@_use:nwwn} % \begin{macro}[EXP]{\clist_use:Nn, \clist_use:cn} % First check that the variable exists. Then count the items in the @@ -1732,8 +1729,8 @@ % \subsection{Using a single item} % % \begin{macro}{\clist_item:Nn, \clist_item:cn} -% \begin{macro}[aux]{\@@_item:nnnN, \@@_item:ffoN, \@@_item:ffnN} -% \begin{macro}[aux]{\@@_item_N_loop:nw} +% \begin{macro}{\@@_item:nnnN, \@@_item:ffoN, \@@_item:ffnN} +% \begin{macro}{\@@_item_N_loop:nw} % To avoid needing to test the end of the list at each step, % we first compute the \meta{length} of the list. If the item number % is~$0$, less than $-\meta{length}$, or more than $\meta{length}$, @@ -1779,7 +1776,7 @@ % \end{macro} % % \begin{macro}{\clist_item:nn} -% \begin{macro}[aux]{ +% \begin{macro}{ % \@@_item_n:nw, % \@@_item_n_loop:nw, % \@@_item_n_end:n, @@ -1825,40 +1822,38 @@ % % \subsection{Viewing comma lists} % -% \begin{macro}{\clist_show:N, \clist_show:c} -% \begin{macro}{\clist_show:n} -% Apply the general \cs{__msg_show_variable:NNNnn}. In the case -% of an \texttt{n}-type comma-list, we must do things by hand, -% using the same message \texttt{show-clist} as for an -% \texttt{N}-type comma-list but with an empty name (first -% argument). +% \begin{macro}{\clist_show:N, \clist_show:c, \clist_log:N, \clist_log:c, \@@_show:NN} +% Apply the general \cs{__kernel_check_defined:NT} and +% \cs{msg_show:nnnnnn}. % \begin{macrocode} -\cs_new_protected:Npn \clist_show:N #1 - { - \__msg_show_variable:NNNnn #1 - \clist_if_exist:NTF \clist_if_empty:NTF { clist } - { \clist_map_function:NN #1 \__msg_show_item:n } - } -\cs_new_protected:Npn \clist_show:n #1 +\cs_new_protected:Npn \clist_show:N { \@@_show:NN \msg_show:nnxxxx } +\cs_generate_variant:Nn \clist_show:N { c } +\cs_new_protected:Npn \clist_log:N { \@@_show:NN \msg_log:nnxxxx } +\cs_generate_variant:Nn \clist_log:N { c } +\cs_new_protected:Npn \@@_show:NN #1#2 { - \__msg_show_pre:nnxxxx { LaTeX / kernel } { show-clist } - { } { \clist_if_empty:nF {#1} { ? } } { } { } - \__msg_show_wrap:n - { \clist_map_function:nN {#1} \__msg_show_item:n } + \__kernel_check_defined:NT #2 + { + #1 { LaTeX/kernel } { show-clist } + { \token_to_str:N #2 } + { \clist_map_function:NN #2 \msg_show_item:n } + { } { } + } } -\cs_generate_variant:Nn \clist_show:N { c } % \end{macrocode} % \end{macro} -% \end{macro} % -% \begin{macro}{\clist_log:N, \clist_log:c, \clist_log:n} -% Redirect output of \cs{clist_show:N} and \cs{clist_show:n} to the log. +% \begin{macro}{\clist_show:n, \clist_log:n, \@@_show:Nn} +% A variant of the above: no existence check, empty first argument for +% the message. % \begin{macrocode} -\cs_new_protected:Npn \clist_log:N - { \__msg_log_next: \clist_show:N } -\cs_new_protected:Npn \clist_log:n - { \__msg_log_next: \clist_show:n } -\cs_generate_variant:Nn \clist_log:N { c } +\cs_new_protected:Npn \clist_show:n { \@@_show:Nn \msg_show:nnxxxx } +\cs_new_protected:Npn \clist_log:n { \@@_show:Nn \msg_log:nnxxxx } +\cs_new_protected:Npn \@@_show:Nn #1#2 + { + #1 { LaTeX/kernel } { show-clist } + { } { \clist_map_function:nN {#2} \msg_show_item:n } { } { } + } % \end{macrocode} % \end{macro} % |