summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/l3quark.dtx
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2012-08-16 22:41:08 +0000
committerKarl Berry <karl@freefriends.org>2012-08-16 22:41:08 +0000
commitca1c73f9a8de69e467230c4a57ccf8b07cd275a9 (patch)
tree6272657307f73c14327d6b8bce5d6b7ff97c3f66 /Master/texmf-dist/source/latex/l3kernel/l3quark.dtx
parent22c251adda514ed7b453066de05b2f89707d0fe6 (diff)
finish l3 update
git-svn-id: svn://tug.org/texlive/trunk@27427 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3quark.dtx')
-rw-r--r--Master/texmf-dist/source/latex/l3kernel/l3quark.dtx66
1 files changed, 63 insertions, 3 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3quark.dtx b/Master/texmf-dist/source/latex/l3kernel/l3quark.dtx
index b85b03440df..1abf6fa9693 100644
--- a/Master/texmf-dist/source/latex/l3kernel/l3quark.dtx
+++ b/Master/texmf-dist/source/latex/l3kernel/l3quark.dtx
@@ -34,8 +34,8 @@
%% -----------------------------------------------------------------------
%
%<*driver|package>
-\RequirePackage{l3names}
-\GetIdInfo$Id: l3quark.dtx 3986 2012-07-15 19:23:51Z joseph $
+\RequirePackage{l3bootstrap}
+\GetIdInfo$Id: l3quark.dtx 4065 2012-08-08 21:37:44Z bruno $
{L3 Quarks}
%</driver|package>
%<*driver>
@@ -198,7 +198,7 @@
%
% This module provides a uniform interface to intercepting and
% terminating loops as when one is doing tail recursion. The building
-% blocks follow below.
+% blocks follow below and an example is shown in Section~\ref{sec:quark-example}.
%
% \begin{variable}{/q_recursion_tail}
% This quark is appended to the data structure in question and
@@ -286,6 +286,66 @@
% stream after the end of the recursion.
% \end{function}
%
+% \section{An example of recursion with quarks}
+% \label{sec:quark-example}
+%
+% Quarks are mainly used internally in the \pkg{expl3} code to define
+% recursion functions such as \cs{tl_map_inline:nn} and so on.
+% Here is a small example to demonstrate how to use quarks in this fashion.
+% We shall define a command called |\my_map_dbl:nn| which takes a token list
+% and applies an operation to every \emph{pair} of tokens.
+% For example, |\my_map_dbl:nn {abcd} {[--#1--#2--]~}| would produce
+% \enquote{\ttfamily [--a--b--]~[--c--d--]~}.
+% Using quarks to define such functions simplifies their logic and ensures
+% robustness in many cases.
+%
+% \iffalse
+% \begin{macrocode}
+%<*exampleonly>
+% \end{macrocode}
+% \fi
+%
+% Here's the definition of |\my_map_dbl:nn|.
+% First of all, define the function that will do the processing based on the
+% inline function argument |#2|.
+% Then initiate the recursion using an internal function.
+% The token list |#1| is terminated using \cs{q_recursion_tail}, with
+% delimiters according to the type of recursion (here a pair of
+% \cs{q_recursion_tail}), concluding with \cs{q_recursion_stop}.
+% These quarks are used to mark the end of the token list being operated upon.
+% \begin{macrocode}
+\cs_new:Npn \my_map_dbl:nn #1#2
+ {
+ \cs_set:Npn \__my_map_dbl_fn:nn ##1 ##2 {#2}
+ \__my_map_dbl:nn #1 \q_recursion_tail \q_recursion_tail \q_recursion_stop
+ }
+% \end{macrocode}
+%
+% The definition of the internal recursion function follows.
+% First check if either of the input tokens are the termination quarks.
+% Then, if not, apply the inline function to the two arguments.
+% \begin{macrocode}
+\cs_new:Nn \__my_map_dbl:nn
+ {
+ \quark_if_recursion_tail_stop:n {#1}
+ \quark_if_recursion_tail_stop:n {#2}
+ \__my_map_dbl_fn:nn {#1} {#2}
+% \end{macrocode}
+% Finally, recurse:
+% \begin{macrocode}
+ \__my_map_dbl:nn
+ }
+% \end{macrocode}
+% Note that contrarily to \LaTeX3 built-in mapping functions, this
+% mapping function cannot be nested, since the second map will overwrite
+% the definition of |\__my_map_dbl_fn:nn|.
+%
+% \iffalse
+% \begin{macrocode}
+%</exampleonly>
+% \end{macrocode}
+% \fi
+%
% \section{Internal quark functions}
%
% \begin{function}