summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/expl3/l3clist.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/expl3/l3clist.dtx')
-rw-r--r--Master/texmf-dist/source/latex/expl3/l3clist.dtx250
1 files changed, 103 insertions, 147 deletions
diff --git a/Master/texmf-dist/source/latex/expl3/l3clist.dtx b/Master/texmf-dist/source/latex/expl3/l3clist.dtx
index a4acbe592cd..bfec9e082b6 100644
--- a/Master/texmf-dist/source/latex/expl3/l3clist.dtx
+++ b/Master/texmf-dist/source/latex/expl3/l3clist.dtx
@@ -1,5 +1,5 @@
% \iffalse
-%% File: l3clist.dtx Copyright (C) 2005-2010 Frank Mittelbach, LaTeX3 project
+%% File: l3clist.dtx Copyright (C) 2005-2011 Frank Mittelbach, 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
@@ -36,7 +36,7 @@
\RequirePackage{l3names}
%</driver|package>
%\fi
-\GetIdInfo$Id: l3clist.dtx 2071 2010-10-09 09:48:48Z joseph $
+\GetIdInfo$Id: l3clist.dtx 2178 2011-03-06 09:03:44Z mittelba $
{L3 Experimental comma separated lists}
%\iffalse
%<*driver>
@@ -560,6 +560,8 @@
%
% \section{\pkg{l3clist} implementation}
%
+% \TestFiles{m3clist002.lvt}
+%
% We start by ensuring that the required packages are loaded.
% \begin{macrocode}
%<*package>
@@ -572,20 +574,19 @@
%
% \subsection{Allocation and initialisation}
%
-% \begin{macro}{\clist_new:N}
-% \begin{macro}{\clist_new:c}
+% \begin{macro}{\clist_new:N, \clist_new:c}
+% \UnitTested
% Comma-Lists are implemented using token lists.
% \begin{macrocode}
\cs_new_eq:NN \clist_new:N \tl_new:N
\cs_generate_variant:Nn \clist_new:N {c}
% \end{macrocode}
% \end{macro}
-% \end{macro}
%
-% \begin{macro}{\clist_clear:N}
-% \begin{macro}{\clist_clear:c}
-% \begin{macro}{\clist_gclear:N}
-% \begin{macro}{\clist_gclear:c}
+% \begin{macro}{\clist_clear:N, \clist_clear:c }
+% \UnitTested
+% \begin{macro}{\clist_gclear:N, \clist_gclear:c }
+% \UnitTested
% Clearing a comma-list is the same as clearing a token list.
% \begin{macrocode}
\cs_new_eq:NN \clist_clear:N \tl_clear:N
@@ -595,14 +596,12 @@
% \end{macrocode}
% \end{macro}
% \end{macro}
-% \end{macro}
-% \end{macro}
%
%
-% \begin{macro}{\clist_clear_new:N}
-% \begin{macro}{\clist_clear_new:c}
-% \begin{macro}{\clist_gclear_new:N}
-% \begin{macro}{\clist_gclear_new:c}
+% \begin{macro}{\clist_clear_new:N, \clist_clear_new:c }
+% \UnitTested
+% \begin{macro}{\clist_gclear_new:N, \clist_gclear_new:c }
+% \UnitTested
% Clearing a comma-list is the same as clearing a token list.
% \begin{macrocode}
\cs_new_eq:NN \clist_clear_new:N \tl_clear_new:N
@@ -612,13 +611,10 @@
% \end{macrocode}
% \end{macro}
% \end{macro}
-% \end{macro}
-% \end{macro}
%
-% \begin{macro}{\clist_set_eq:NN}
-% \begin{macro}{\clist_set_eq:cN}
-% \begin{macro}{\clist_set_eq:Nc}
-% \begin{macro}{\clist_set_eq:cc}
+% \begin{macro}{\clist_set_eq:NN, \clist_set_eq:cN,
+% \clist_set_eq:Nc, \clist_set_eq:cc }
+% \UnitTested
% We can set one \meta{clist} equal to another.
% \begin{macrocode}
\cs_new_eq:NN \clist_set_eq:NN \tl_set_eq:NN
@@ -627,15 +623,11 @@
\cs_new_eq:NN \clist_set_eq:cc \tl_set_eq:cc
% \end{macrocode}
% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
%
%
-% \begin{macro}{\clist_gset_eq:NN}
-% \begin{macro}{\clist_gset_eq:cN}
-% \begin{macro}{\clist_gset_eq:Nc}
-% \begin{macro}{\clist_gset_eq:cc}
+% \begin{macro}{\clist_gset_eq:NN, \clist_gset_eq:cN,
+% \clist_gset_eq:Nc, \clist_gset_eq:cc }
+% \UnitTested
% An of course globally which seems to be needed far more often.
% \begin{macrocode}
\cs_new_eq:NN \clist_gset_eq:NN \tl_gset_eq:NN
@@ -644,14 +636,14 @@
\cs_new_eq:NN \clist_gset_eq:cc \tl_gset_eq:cc
% \end{macrocode}
% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
+%
+%
%
% \subsection{Predicates and conditionals}
%
% \begin{macro}{\clist_if_empty_p:N,\clist_if_empty_p:c}
% \begin{macro}[TF]{\clist_if_empty:N,\clist_if_empty:c}
+% \UnitTested
% \begin{macrocode}
\prg_new_eq_conditional:NNn \clist_if_empty:N \tl_if_empty:N {p,TF,T,F}
\prg_new_eq_conditional:NNn \clist_if_empty:c \tl_if_empty:c {p,TF,T,F}
@@ -672,6 +664,7 @@
% \end{macrocode}
% \end{macro}
%
+%
% \begin{macro}{\clist_if_eq_p:NN,\clist_if_eq_p:Nc,
% \clist_if_eq_p:cN,\clist_if_eq_p:cc}
% \begin{macro}[TF]{\clist_if_eq:NN,\clist_if_eq:cN,
@@ -686,9 +679,12 @@
% \end{macro}
% \end{macro}
%
+%
% \begin{macro}[TF]{\clist_if_in:Nn}
+% \UnitTested
% \begin{macro}[TF]{\clist_if_in:NV,\clist_if_in:No,\clist_if_in:cn,
% \clist_if_in:cV,\clist_if_in:co}
+% \UnitTested
% |\clist_if_in:NnTF| \m{clist}\m{item} \m{true~case} \m{false~case}
% will check whether \m{item} is in \m{clist} and then either execute
% the \m{true~case} or the \m{false~case}. \m{true~case} and
@@ -714,8 +710,8 @@
%
% \subsection{Retrieving data}
%
-% \begin{macro}{\clist_use:N}
-% \begin{macro}{\clist_use:c}
+% \begin{macro}{\clist_use:N, \clist_use:c}
+% \UnitTested
% Using a \meta{clist} is just executing it but
% if \m{clist} equals |\scan_stop:| it is probably stemming
% from a |\cs:w ... \cs_end:| that was created by mistake somewhere.
@@ -731,11 +727,9 @@
\cs_generate_variant:Nn \clist_use:N {c}
% \end{macrocode}
% \end{macro}
-% \end{macro}
%
-% \begin{macro}{\clist_get:NN}
-% \begin{macro}{\clist_get:cN}
-% \begin{macro}{\clist_get_aux:w}
+% \begin{macro}{\clist_get:NN, \clist_get:cN}
+% \UnitTested
% |\clist_get:NN |\meta{comma-list}\meta{cmd} defines \meta{cmd} to be the
% left-most element of \meta{comma-list}.
% \begin{macrocode}
@@ -743,20 +737,22 @@
\clist_if_empty_err:N #1
\exp_after:wN \clist_get_aux:w #1,\q_stop
}
+\cs_generate_variant:Nn \clist_get:NN {cN}
% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}[aux]{\clist_get_aux:w}
% \begin{macrocode}
\cs_new_protected:Npn \clist_get_aux:w #1,#2\q_stop #3 { \tl_set:Nn #3{#1} }
% \end{macrocode}
-% \begin{macrocode}
-\cs_generate_variant:Nn \clist_get:NN {cN}
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
% \end{macro}
%
-% \begin{macro}{\clist_pop_aux:nnNN}
-% \begin{macro}{\clist_pop_aux:w}
-% \begin{macro}{\clist_pop_auxi:w}
+%
+%
+%
+% \begin{macro}[aux]{\clist_pop_aux:nnNN}
+% \begin{macro}[aux]{\clist_pop_aux:w}
+% \begin{macro}[aux]{\clist_pop_auxi:w}
% |\clist_pop_aux:nnNN| \meta{def$\sb1$} \meta{def$\sb2$} \meta{comma-list}
% \meta{cmd} assigns the left-most element of \meta{comma-list} to
% \meta{cmd} using \meta{def$\sb2$}, and assigns the tail of
@@ -783,6 +779,9 @@
% \end{macro}
% \end{macro}
%
+%
+%
+%
% \begin{macro}{\clist_show:N}
% \begin{macro}{\clist_show:c}
% \begin{macrocode}
@@ -816,7 +815,7 @@
%
% \subsection{Storing data}
%
-% \begin{macro}{\clist_put_aux:NNnnNn}
+% \begin{macro}[aux]{\clist_put_aux:NNnnNn}
% The generic put function.
% When adding we have to distinguish between an empty \meta{clist}
% and one that contains at least one item (otherwise we accumulate
@@ -835,13 +834,11 @@
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}{\clist_put_left:Nn}
-% \begin{macro}{\clist_put_left:NV}
-% \begin{macro}{\clist_put_left:No}
-% \begin{macro}{\clist_put_left:Nx}
-% \begin{macro}{\clist_put_left:cn}
-% \begin{macro}{\clist_put_left:cV}
-% \begin{macro}{\clist_put_left:co}
+% \begin{macro}{\clist_put_left:Nn, \clist_put_left:NV,
+% \clist_put_left:No, \clist_put_left:Nx,
+% \clist_put_left:cn, \clist_put_left:cV,
+% \clist_put_left:co}
+% \UnitTested
% The operations for adding to the left.
% \begin{macrocode}
\cs_new_protected_nopar:Npn \clist_put_left:Nn {
@@ -850,20 +847,13 @@
\cs_generate_variant:Nn \clist_put_left:Nn {NV,No,Nx,cn,cV,co}
% \end{macrocode}
% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
%
-% \begin{macro}{\clist_gput_left:Nn}
-% \begin{macro}{\clist_gput_left:NV}
-% \begin{macro}{\clist_gput_left:No}
-% \begin{macro}{\clist_gput_left:Nx}
-% \begin{macro}{\clist_gput_left:cn}
-% \begin{macro}{\clist_gput_left:cV}
-% \begin{macro}{\clist_gput_left:co}
+%
+% \begin{macro}{\clist_gput_left:Nn, \clist_gput_left:NV,
+% \clist_gput_left:No, \clist_gput_left:Nx,
+% \clist_gput_left:cn, \clist_gput_left:cV,
+% \clist_gput_left:co}
+% \UnitTested
% Global versions.
% \begin{macrocode}
\cs_new_protected_nopar:Npn \clist_gput_left:Nn {
@@ -872,20 +862,14 @@
\cs_generate_variant:Nn \clist_gput_left:Nn {NV,No,Nx,cn,cV,co}
% \end{macrocode}
% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
%
-% \begin{macro}{\clist_put_right:Nn}
-% \begin{macro}{\clist_put_right:NV}
-% \begin{macro}{\clist_put_right:No}
-% \begin{macro}{\clist_put_right:Nx}
-% \begin{macro}{\clist_put_right:cn}
-% \begin{macro}{\clist_put_right:cV}
-% \begin{macro}{\clist_put_right:co}
+%
+%
+% \begin{macro}{\clist_put_right:Nn, \clist_put_right:NV,
+% \clist_put_right:No, \clist_put_right:Nx,
+% \clist_put_right:cn, \clist_put_right:cV,
+% \clist_put_right:co}
+% \UnitTested
% Adding something to the right side is almost the same.
% \begin{macrocode}
\cs_new_protected_nopar:Npn \clist_put_right:Nn {
@@ -894,20 +878,12 @@
\cs_generate_variant:Nn \clist_put_right:Nn {NV,No,Nx,cn,cV,co}
% \end{macrocode}
% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
%
-% \begin{macro}{\clist_gput_right:Nn}
-% \begin{macro}{\clist_gput_right:NV}
-% \begin{macro}{\clist_gput_right:No}
-% \begin{macro}{\clist_gput_right:Nx}
-% \begin{macro}{\clist_gput_right:cn}
-% \begin{macro}{\clist_gput_right:cV}
-% \begin{macro}{\clist_gput_right:co}
+% \begin{macro}{\clist_gput_right:Nn, \clist_gput_right:NV,
+% \clist_gput_right:No, \clist_gput_right:Nx,
+% \clist_gput_right:cn, \clist_gput_right:cV,
+% \clist_gput_right:co}
+% \UnitTested
% And here the global variants.
% \begin{macrocode}
\cs_new_protected_nopar:Npn \clist_gput_right:Nn {
@@ -916,25 +892,16 @@
\cs_generate_variant:Nn \clist_gput_right:Nn {NV,No,Nx,cn,cV,co}
% \end{macrocode}
% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
%
%
% \subsection{Mapping}
%
-%\begin{macro}{\clist_map_function:NN}
-%\begin{macro}{\clist_map_function:Nc}
-%\begin{macro}{\clist_map_function:cN}
-%\begin{macro}{\clist_map_function:cc}
-%\begin{macro}{\clist_map_function:nN}
-%\begin{macro}{\clist_map_function:nc}
-%\begin{macro}{\clist_map_inline:Nn}
-%\begin{macro}{\clist_map_inline:cn}
-%\begin{macro}{\clist_map_inline:nn}
+% \begin{macro}{\clist_map_function:NN, \clist_map_function:Nc,
+% \clist_map_function:cN, \clist_map_function:cc,
+% \clist_map_function:nN,\clist_map_function:nc }
+% \UnitTested
+% \begin{macro}{\clist_map_inline:Nn, \clist_map_inline:nn }
+% \UnitTested
%\begin{macro}{\clist_map_break:}
% Using the above creating the comma mappings is easy..
% \begin{macrocode}
@@ -945,20 +912,14 @@
\cs_generate_variant:Nn \clist_map_inline:Nn { c }
\cs_generate_variant:Nn \clist_map_inline:Nn { nc }
% \end{macrocode}
-%\end{macro}
-%\end{macro}
-%\end{macro}
-%\end{macro}
-%\end{macro}
-%\end{macro}
-%\end{macro}
-%\end{macro}
-%\end{macro}
-%\end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
%
-% \begin{macro}{\clist_map_variable:nNn}
-% \begin{macro}{\clist_map_variable:NNn}
-% \begin{macro}{\clist_map_variable:cNn}
+%
+% \begin{macro}{\clist_map_variable:nNn, \clist_map_variable:NNn,
+% \clist_map_variable:cNn}
+% \UnitTested
% |\clist_map_variable:NNn| \meta{comma-list} \meta{temp} \meta{action} assigns
% \meta{temp} to each element and executes \meta{action}.
% \begin{macrocode}
@@ -975,8 +936,8 @@
\cs_generate_variant:Nn\clist_map_variable:NNn {cNn}
% \end{macrocode}
% \end{macro}
-% \end{macro}
-% \end{macro}
+%
+%
%
% \begin{macro}[aux]{\clist_map_variable_aux:Nnw}
% The general loop. Assign the temp variable |#1| to the current item
@@ -991,11 +952,15 @@
% \end{macrocode}
% \end{macro}
%
+%
+%
% \subsection{Higher level functions}
%
-% \begin{macro}[aux]{\clist_concat_aux:NNNN}
-% \begin{macro}{\clist_concat:NNN,\clist_concat:ccc}
+% \begin{macro}{\clist_concat:NNN, \clist_concat:ccc}
+% \UnitTested
% \begin{macro}{\clist_gconcat:NNN,\clist_gconcat:ccc}
+% \UnitTested
+% \begin{macro}[aux]{\clist_concat_aux:NNNN}
% |\clist_gconcat:NNN| \m{clist~1} \m{clist~2} \m{clist~3} will globally
% assign \m{clist~1} the concatenation of \m{clist~2} and
% \m{clist~3}.
@@ -1032,7 +997,9 @@
% \begin{macro}[aux]{\clist_remove_duplicates_aux:NN}
% \begin{macro}[aux]{\clist_remove_duplicates_aux:n}
% \begin{macro}{\clist_remove_duplicates:N}
+% \UnitTested
% \begin{macro}{\clist_gremove_duplicates:N}
+% \UnitTested
% Removing duplicate entries in a \meta{clist} is fairly straight
% forward. We use a temporary variable and then go through the list
% from left to right. For each element check if the element is
@@ -1100,12 +1067,11 @@
% specific functions together.
%
%
-% \begin{macro}{\clist_push:Nn}
-% \begin{macro}{\clist_push:No}
-% \begin{macro}{\clist_push:NV}
-% \begin{macro}{\clist_push:cn}
-% \begin{macro}{\clist_pop:NN}
-% \begin{macro}{\clist_pop:cN}
+% \begin{macro}{\clist_push:Nn, \clist_push:No,
+% \clist_push:NV, \clist_push:cn}
+% \UnitTested
+% \begin{macro}{\clist_pop:NN, \clist_pop:cN}
+% \UnitTested
% Since comma-lists can be used as stacks, we ought to have both
% `push' and `pop'. In most cases they are nothing more then new
% names for old functions.
@@ -1119,19 +1085,14 @@
% \end{macrocode}
% \end{macro}
% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
%
%
%
-% \begin{macro}{\clist_gpush:Nn}
-% \begin{macro}{\clist_gpush:No}
-% \begin{macro}{\clist_gpush:NV}
-% \begin{macro}{\clist_gpush:cn}
-% \begin{macro}{\clist_gpop:NN}
-% \begin{macro}{\clist_gpop:cN}
+% \begin{macro}{\clist_gpush:Nn, \clist_gpush:No,
+% \clist_gpush:NV, \clist_gpush:cn}
+% \UnitTested
+% \begin{macro}{\clist_gpop:NN, \clist_gpop:cN}
+% \UnitTested
% I don't agree with Denys that one needs only local stacks,
% actually I believe that one will probably need the functions
% here more often. In case of |\clist_gpop:NN| the value is
@@ -1149,14 +1110,10 @@
% \end{macrocode}
% \end{macro}
% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
%
%
-% \begin{macro}{\clist_top:NN}
-% \begin{macro}{\clist_top:cN}
+% \begin{macro}{\clist_top:NN,\clist_top:cN}
+% \UnitTested
% Looking at the top element of the stack without removing it is
% done with this operation.
% \begin{macrocode}
@@ -1164,7 +1121,6 @@
\cs_new_eq:NN \clist_top:cN \clist_get:cN
% \end{macrocode}
% \end{macro}
-% \end{macro}
%
% \begin{macrocode}
%</initex|package>