[latex3-commits] [latex3/latex3] main: Tighten up "clist var" vs "comma list" (fixes #1163) (cc6e47802)
github at latex-project.org
github at latex-project.org
Tue May 16 18:56:00 CEST 2023
Repository : https://github.com/latex3/latex3
On branch : main
Link : https://github.com/latex3/latex3/commit/cc6e47802ab6334b56b3418f5ff1dc2f6265b3c4
>---------------------------------------------------------------
commit cc6e47802ab6334b56b3418f5ff1dc2f6265b3c4
Author: Joseph Wright <joseph.wright at morningstar2.co.uk>
Date: Tue May 16 17:56:00 2023 +0100
Tighten up "clist var" vs "comma list" (fixes #1163)
>---------------------------------------------------------------
cc6e47802ab6334b56b3418f5ff1dc2f6265b3c4
l3kernel/l3clist.dtx | 156 +++++++++++++++++++++++++--------------------------
1 file changed, 78 insertions(+), 78 deletions(-)
diff --git a/l3kernel/l3clist.dtx b/l3kernel/l3clist.dtx
index 5abf32d8f..5448765ea 100644
--- a/l3kernel/l3clist.dtx
+++ b/l3kernel/l3clist.dtx
@@ -114,10 +114,10 @@
%
% \begin{function}{\clist_new:N, \clist_new:c}
% \begin{syntax}
-% \cs{clist_new:N} \meta{comma list}
+% \cs{clist_new:N} \meta{clist~var}
% \end{syntax}
-% Creates a new \meta{comma list} or raises an error if the name is
-% already taken. The declaration is global. The \meta{comma list}
+% Creates a new \meta{clist~var} or raises an error if the name is
+% already taken. The declaration is global. The \meta{clist~var}
% initially contains no items.
% \end{function}
%
@@ -138,9 +138,9 @@
% \begin{function}
% {\clist_clear:N, \clist_clear:c, \clist_gclear:N, \clist_gclear:c}
% \begin{syntax}
-% \cs{clist_clear:N} \meta{comma list}
+% \cs{clist_clear:N} \meta{clist~var}
% \end{syntax}
-% Clears all items from the \meta{comma list}.
+% Clears all items from the \meta{clist~var}.
% \end{function}
%
% \begin{function}
@@ -149,9 +149,9 @@
% \clist_gclear_new:N, \clist_gclear_new:c
% }
% \begin{syntax}
-% \cs{clist_clear_new:N} \meta{comma list}
+% \cs{clist_clear_new:N} \meta{clist~var}
% \end{syntax}
-% Ensures that the \meta{comma list} exists globally by applying
+% Ensures that the \meta{clist~var} exists globally by applying
% \cs{clist_new:N} if necessary, then applies
% \cs[index=clist_clear:N]{clist_(g)clear:N} to leave
% the list empty.
@@ -182,9 +182,9 @@
% \clist_gset_from_seq:Nc, \clist_gset_from_seq:cc
% }
% \begin{syntax}
-% \cs{clist_set_from_seq:NN} \meta{comma list} \meta{sequence}
+% \cs{clist_set_from_seq:NN} \meta{clist~var} \meta{sequence}
% \end{syntax}
-% Converts the data in the \meta{sequence} into a \meta{comma list}:
+% Converts the data in the \meta{sequence} into a \meta{clist~var}:
% the original \meta{sequence} is unchanged.
% Items which contain either spaces or commas are surrounded by braces.
% \end{function}
@@ -205,11 +205,11 @@
% \begin{function}[EXP, pTF, added=2012-03-03]
% {\clist_if_exist:N, \clist_if_exist:c}
% \begin{syntax}
-% \cs{clist_if_exist_p:N} \meta{comma list}
-% \cs{clist_if_exist:NTF} \meta{comma list} \Arg{true code} \Arg{false code}
+% \cs{clist_if_exist_p:N} \meta{clist~var}
+% \cs{clist_if_exist:NTF} \meta{clist~var} \Arg{true code} \Arg{false code}
% \end{syntax}
-% Tests whether the \meta{comma list} is currently defined. This does
-% not check that the \meta{comma list} really is a comma list.
+% Tests whether the \meta{clist~var} is currently defined. This does
+% not check that the \meta{clist~var} really is a comma list.
% \end{function}
%
% \section{Adding data to comma lists}
@@ -226,16 +226,16 @@
% \clist_gset:co, \clist_gset:cx
% }
% \begin{syntax}
-% \cs{clist_set:Nn} \meta{comma list} |{|\meta{item_1},\ldots{},\meta{item_n}|}|
+% \cs{clist_set:Nn} \meta{clist~var} |{|\meta{item_1},\ldots{},\meta{item_n}|}|
% \end{syntax}
-% Sets \meta{comma list} to contain the \meta{items},
+% Sets \meta{clist~var} to contain the \meta{items},
% removing any previous content from the variable.
% Blank items are omitted, spaces are removed from both sides of each
% item, then a set of braces is removed if the resulting space-trimmed
% item is braced.
% To store some \meta{tokens} as a single \meta{item} even if the
% \meta{tokens} contain commas or spaces, add a set of braces:
-% \cs{clist_set:Nn} \meta{comma list} |{| \Arg{tokens} |}|.
+% \cs{clist_set:Nn} \meta{clist~var} |{| \Arg{tokens} |}|.
% \end{function}
%
% \begin{function}[updated = 2011-09-05]
@@ -250,15 +250,15 @@
% \clist_gput_left:co, \clist_gput_left:cx
% }
% \begin{syntax}
-% \cs{clist_put_left:Nn} \meta{comma list} |{|\meta{item_1},\ldots{},\meta{item_n}|}|
+% \cs{clist_put_left:Nn} \meta{clist~var} |{|\meta{item_1},\ldots{},\meta{item_n}|}|
% \end{syntax}
-% Appends the \meta{items} to the left of the \meta{comma list}.
+% Appends the \meta{items} to the left of the \meta{clist~var}.
% Blank items are omitted, spaces are removed from both sides of each
% item, then a set of braces is removed if the resulting space-trimmed
% item is braced.
% To append some \meta{tokens} as a single \meta{item} even if the
% \meta{tokens} contain commas or spaces, add a set of braces:
-% \cs{clist_put_left:Nn} \meta{comma list} |{| \Arg{tokens} |}|.
+% \cs{clist_put_left:Nn} \meta{clist~var} |{| \Arg{tokens} |}|.
% \end{function}
%
% \begin{function}[updated = 2011-09-05]
@@ -273,15 +273,15 @@
% \clist_gput_right:co, \clist_gput_right:cx
% }
% \begin{syntax}
-% \cs{clist_put_right:Nn} \meta{comma list} |{|\meta{item_1},\ldots{},\meta{item_n}|}|
+% \cs{clist_put_right:Nn} \meta{clist~var} |{|\meta{item_1},\ldots{},\meta{item_n}|}|
% \end{syntax}
-% Appends the \meta{items} to the right of the \meta{comma list}.
+% Appends the \meta{items} to the right of the \meta{clist~var}.
% Blank items are omitted, spaces are removed from both sides of each
% item, then a set of braces is removed if the resulting space-trimmed
% item is braced.
% To append some \meta{tokens} as a single \meta{item} even if the
% \meta{tokens} contain commas or spaces, add a set of braces:
-% \cs{clist_put_right:Nn} \meta{comma list} |{| \Arg{tokens} |}|.
+% \cs{clist_put_right:Nn} \meta{clist~var} |{| \Arg{tokens} |}|.
% \end{function}
%
% \section{Modifying comma lists}
@@ -297,17 +297,17 @@
% \clist_gremove_duplicates:N, \clist_gremove_duplicates:c
% }
% \begin{syntax}
-% \cs{clist_remove_duplicates:N} \meta{comma list}
+% \cs{clist_remove_duplicates:N} \meta{clist~var}
% \end{syntax}
-% Removes duplicate items from the \meta{comma list}, leaving the
-% left most copy of each item in the \meta{comma list}. The \meta{item}
+% Removes duplicate items from the \meta{clist~var}, leaving the
+% left most copy of each item in the \meta{clist~var}. The \meta{item}
% comparison takes place on a token basis, as for \cs{tl_if_eq:nnTF}.
% \begin{texnote}
-% This function iterates through every item in the \meta{comma list} and
+% This function iterates through every item in the \meta{clist~var} and
% does a comparison with the \meta{items} already checked. It is therefore
% relatively slow with large comma lists.
% Furthermore, it may fail if any of the items in the
-% \meta{comma list} contains |{|, |}|, or |#|
+% \meta{clist~var} contains |{|, |}|, or |#|
% (assuming the usual \TeX{} category codes apply).
% \end{texnote}
% \end{function}
@@ -320,9 +320,9 @@
% \clist_gremove_all:NV, \clist_gremove_all:cV
% }
% \begin{syntax}
-% \cs{clist_remove_all:Nn} \meta{comma list} \Arg{item}
+% \cs{clist_remove_all:Nn} \meta{clist~var} \Arg{item}
% \end{syntax}
-% Removes every occurrence of \meta{item} from the \meta{comma list}.
+% Removes every occurrence of \meta{item} from the \meta{clist~var}.
% The \meta{item} comparison takes place on a token basis, as for
% \cs{tl_if_eq:nnTF}.
% \begin{texnote}
@@ -337,9 +337,9 @@
% \clist_greverse:N, \clist_greverse:c
% }
% \begin{syntax}
-% \cs{clist_reverse:N} \meta{comma list}
+% \cs{clist_reverse:N} \meta{clist~var}
% \end{syntax}
-% Reverses the order of items stored in the \meta{comma list}.
+% Reverses the order of items stored in the \meta{clist~var}.
% \end{function}
%
% \begin{function}[added = 2014-07-18]{\clist_reverse:n}
@@ -372,10 +372,10 @@
%
% \begin{function}[EXP,pTF]{\clist_if_empty:N, \clist_if_empty:c}
% \begin{syntax}
-% \cs{clist_if_empty_p:N} \meta{comma list}
-% \cs{clist_if_empty:NTF} \meta{comma list} \Arg{true code} \Arg{false code}
+% \cs{clist_if_empty_p:N} \meta{clist~var}
+% \cs{clist_if_empty:NTF} \meta{clist~var} \Arg{true code} \Arg{false code}
% \end{syntax}
-% Tests if the \meta{comma list} is empty (containing no items).
+% Tests if the \meta{clist~var} is empty (containing no items).
% \end{function}
%
% \begin{function}[EXP, pTF, added = 2014-07-05]{\clist_if_empty:n}
@@ -383,7 +383,7 @@
% \cs{clist_if_empty_p:n} \Arg{comma list}
% \cs{clist_if_empty:nTF} \Arg{comma list} \Arg{true code} \Arg{false code}
% \end{syntax}
-% Tests if the \meta{comma list} is empty (containing no items).
+% Tests if the \meta{clist~var} is empty (containing no items).
% The rules for space trimming are as for other \texttt{n}-type
% comma-list functions, hence the comma list |{~,~,,~}| (without
% outer braces) is empty, while |{~,{},}| (without outer braces)
@@ -398,9 +398,9 @@
% \clist_if_in:nn, \clist_if_in:nV, \clist_if_in:no
% }
% \begin{syntax}
-% \cs{clist_if_in:NnTF} \meta{comma list} \Arg{item} \Arg{true code} \Arg{false code}
+% \cs{clist_if_in:NnTF} \meta{clist~var} \Arg{item} \Arg{true code} \Arg{false code}
% \end{syntax}
-% Tests if the \meta{item} is present in the \meta{comma list}.
+% Tests if the \meta{item} is present in the \meta{clist~var}.
% In the case of an \texttt{n}-type \meta{comma list}, the usual rules
% of space trimming and brace stripping apply. Hence,
% \begin{verbatim}
@@ -438,10 +438,10 @@
% \begin{function}[rEXP, updated = 2012-06-29]
% {\clist_map_function:NN, \clist_map_function:cN, \clist_map_function:nN}
% \begin{syntax}
-% \cs{clist_map_function:NN} \meta{comma list} \meta{function}
+% \cs{clist_map_function:NN} \meta{clist~var} \meta{function}
% \end{syntax}
% Applies \meta{function} to every \meta{item} stored in the
-% \meta{comma list}. The \meta{function} receives one argument for
+% \meta{clist~var}. The \meta{function} receives one argument for
% 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}.
@@ -450,10 +450,10 @@
% \begin{function}[updated = 2012-06-29]
% {\clist_map_inline:Nn, \clist_map_inline:cn, \clist_map_inline:nn}
% \begin{syntax}
-% \cs{clist_map_inline:Nn} \meta{comma list} \Arg{inline function}
+% \cs{clist_map_inline:Nn} \meta{clist~var} \Arg{inline function}
% \end{syntax}
% Applies \meta{inline function} to every \meta{item} stored
-% within the \meta{comma list}. The \meta{inline function} should
+% within the \meta{clist~var}. The \meta{inline function} should
% consist of code which receives the \meta{item} as |#1|.
% The \meta{items} are returned from left to right.
% \end{function}
@@ -461,9 +461,9 @@
% \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{variable} \Arg{code}
+% \cs{clist_map_variable:NNn} \meta{clist~var} \meta{variable} \Arg{code}
% \end{syntax}
-% Stores each \meta{item} of the \meta{comma list} in turn in the
+% Stores each \meta{item} of the \meta{clist~var} 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.
@@ -479,7 +479,7 @@
% \cs{clist_map_tokens:nn} \Arg{comma list} \Arg{code}
% \end{syntax}
% Calls \meta{code} \Arg{item} for every \meta{item} stored in the
-% \meta{comma list}. The \meta{code} receives each \meta{item} as a
+% \meta{clist~var}. The \meta{code} receives each \meta{item} as a
% trailing brace group. If the \meta{code} consists of a single
% function this is equivalent to \cs{clist_map_function:nN}.
% \end{function}
@@ -542,12 +542,12 @@
% \begin{function}[EXP, added = 2012-07-13]
% {\clist_count:N, \clist_count:c, \clist_count:n}
% \begin{syntax}
-% \cs{clist_count:N} \meta{comma list}
+% \cs{clist_count:N} \meta{clist~var}
% \end{syntax}
-% Leaves the number of items in the \meta{comma list} in the input
+% Leaves the number of items in the \meta{clist~var} in the input
% stream as an \meta{integer denotation}. The total number of items
-% in a \meta{comma list} includes those which are duplicates,
-% \emph{i.e.}~every item in a \meta{comma list} is counted.
+% in a \meta{clist~var} includes those which are duplicates,
+% \emph{i.e.}~every item in a \meta{clist~var} is counted.
% \end{function}
%
% \section{Using the content of comma lists directly}
@@ -640,20 +640,20 @@
% \begin{function}[noTF, added = 2012-05-14, updated = 2019-02-16]
% {\clist_get:NN, \clist_get:cN}
% \begin{syntax}
-% \cs{clist_get:NN} \meta{comma list} \meta{token list variable}
+% \cs{clist_get:NN} \meta{clist~var} \meta{token list variable}
% \end{syntax}
-% Stores the left-most item from a \meta{comma list} in the
+% Stores the left-most item from a \meta{clist~var} in the
% \meta{token list variable} without removing it from the
-% \meta{comma list}. The \meta{token list variable} is assigned locally.
-% In the non-branching version, if the \meta{comma list} is empty the
+% \meta{clist~var}. The \meta{token list variable} is assigned locally.
+% In the non-branching version, if the \meta{clist~var} is empty the
% \meta{token list variable} is set to the marker value \cs{q_no_value}.
% \end{function}
%
% \begin{function}[updated = 2011-09-06]{\clist_pop:NN, \clist_pop:cN}
% \begin{syntax}
-% \cs{clist_pop:NN} \meta{comma list} \meta{token list variable}
+% \cs{clist_pop:NN} \meta{clist~var} \meta{token list variable}
% \end{syntax}
-% Pops the left-most item from a \meta{comma list} into the
+% Pops the left-most item from a \meta{clist~var} into the
% \meta{token list variable}, \emph{i.e.}~removes the item from the
% comma list and stores it in the \meta{token list variable}.
% Both of the variables are assigned locally.
@@ -661,38 +661,38 @@
%
% \begin{function}{\clist_gpop:NN, \clist_gpop:cN}
% \begin{syntax}
-% \cs{clist_gpop:NN} \meta{comma list} \meta{token list variable}
+% \cs{clist_gpop:NN} \meta{clist~var} \meta{token list variable}
% \end{syntax}
-% Pops the left-most item from a \meta{comma list} into the
+% Pops the left-most item from a \meta{clist~var} into the
% \meta{token list variable}, \emph{i.e.}~removes the item from the
% comma list and stores it in the \meta{token list variable}.
-% The \meta{comma list} is modified globally, while the assignment of
+% The \meta{clist~var} is modified globally, while the assignment of
% the \meta{token list variable} is local.
% \end{function}
%
% \begin{function}[TF, added = 2012-05-14]{\clist_pop:NN, \clist_pop:cN}
% \begin{syntax}
-% \cs{clist_pop:NNTF} \meta{comma list} \meta{token list variable} \Arg{true code} \Arg{false code}
+% \cs{clist_pop:NNTF} \meta{clist~var} \meta{token list variable} \Arg{true code} \Arg{false code}
% \end{syntax}
-% If the \meta{comma list} is empty, leaves the \meta{false code} in the
+% If the \meta{clist~var} is empty, leaves the \meta{false code} in the
% input stream. The value of the \meta{token list variable} is
% not defined in this case and should not be relied upon. If the
-% \meta{comma list} is non-empty, pops the top item from the
-% \meta{comma list} in the \meta{token list variable}, \emph{i.e.}~removes
-% the item from the \meta{comma list}. Both the \meta{comma list} and the
+% \meta{clist~var} is non-empty, pops the top item from the
+% \meta{clist~var} in the \meta{token list variable}, \emph{i.e.}~removes
+% the item from the \meta{clist~var}. Both the \meta{clist~var} and the
% \meta{token list variable} are assigned locally.
% \end{function}
%
% \begin{function}[TF, added = 2012-05-14]{\clist_gpop:NN, \clist_gpop:cN}
% \begin{syntax}
-% \cs{clist_gpop:NNTF} \meta{comma list} \meta{token list variable} \Arg{true code} \Arg{false code}
+% \cs{clist_gpop:NNTF} \meta{clist~var} \meta{token list variable} \Arg{true code} \Arg{false code}
% \end{syntax}
-% If the \meta{comma list} is empty, leaves the \meta{false code} in the
+% If the \meta{clist~var} is empty, leaves the \meta{false code} in the
% input stream. The value of the \meta{token list variable} is
% not defined in this case and should not be relied upon. If the
-% \meta{comma list} is non-empty, pops the top item from the
-% \meta{comma list} in the \meta{token list variable}, \emph{i.e.}~removes
-% the item from the \meta{comma list}. The \meta{comma list} is modified
+% \meta{clist~var} is non-empty, pops the top item from the
+% \meta{clist~var} in the \meta{token list variable}, \emph{i.e.}~removes
+% the item from the \meta{clist~var}. The \meta{clist~var} is modified
% globally, while the \meta{token list variable} is assigned locally.
% \end{function}
%
@@ -704,9 +704,9 @@
% \clist_gpush:cn, \clist_gpush:cV, \clist_gpush:co, \clist_gpush:cx
% }
% \begin{syntax}
-% \cs{clist_push:Nn} \meta{comma list} \Arg{items}
+% \cs{clist_push:Nn} \meta{clist~var} \Arg{items}
% \end{syntax}
-% Adds the \Arg{items} to the top of the \meta{comma list}.
+% Adds the \Arg{items} to the top of the \meta{clist~var}.
% Spaces are removed from both sides of each item as for any
% \texttt{n}-type comma list.
% \end{function}
@@ -716,14 +716,14 @@
% \begin{function}[added = 2014-07-17, EXP]
% {\clist_item:Nn, \clist_item:cn, \clist_item:nn}
% \begin{syntax}
-% \cs{clist_item:Nn} \meta{comma list} \Arg{int expr}
+% \cs{clist_item:Nn} \meta{clist~var} \Arg{int expr}
% \end{syntax}
-% Indexing items in the \meta{comma list} from~$1$ at the top (left), this
+% Indexing items in the \meta{clist~var} from~$1$ at the top (left), this
% function evaluates the \meta{int expr} and leaves the
% appropriate item from the comma list in the input stream. If the
% \meta{int expr} is negative, indexing occurs from the
% bottom (right) of the comma list. When the \meta{int expr}
-% is larger than the number of items in the \meta{comma list} (as
+% is larger than the number of items in the \meta{clist~var} (as
% calculated by \cs{clist_count:N}) then the function expands to
% nothing.
% \begin{texnote}
@@ -740,8 +740,8 @@
% \cs{clist_rand_item:N} \meta{clist~var}
% \cs{clist_rand_item:n} \Arg{comma list}
% \end{syntax}
-% Selects a pseudo-random item of the \meta{comma list}. If the
-% \meta{comma list} has no item, the result is empty.
+% Selects a pseudo-random item of the \meta{clist~var}/\meta{comma list}.
+% If the \meta{comma list} has no item, the result is empty.
% \begin{texnote}
% The result is returned within the \tn{unexpanded}
% primitive (\cs{exp_not:n}), which means that the \meta{item}
@@ -754,9 +754,9 @@
%
% \begin{function}[updated = 2021-04-29]{\clist_show:N, \clist_show:c}
% \begin{syntax}
-% \cs{clist_show:N} \meta{comma list}
+% \cs{clist_show:N} \meta{clist~var}
% \end{syntax}
-% Displays the entries in the \meta{comma list} in the terminal.
+% Displays the entries in the \meta{clist~var} in the terminal.
% \end{function}
%
% \begin{function}[updated = 2013-08-03]{\clist_show:n}
@@ -768,9 +768,9 @@
%
% \begin{function}[added = 2014-08-22, updated = 2021-04-29]{\clist_log:N, \clist_log:c}
% \begin{syntax}
-% \cs{clist_log:N} \meta{comma list}
+% \cs{clist_log:N} \meta{clist~var}
% \end{syntax}
-% Writes the entries in the \meta{comma list} in the log file. See
+% Writes the entries in the \meta{clist~var} in the log file. See
% also \cs{clist_show:N} which displays the result in the terminal.
% \end{function}
%
More information about the latex3-commits
mailing list.