summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/l3kernel/l3kernel-functions.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/l3kernel/l3kernel-functions.dtx')
-rw-r--r--macros/latex/contrib/l3kernel/l3kernel-functions.dtx100
1 files changed, 99 insertions, 1 deletions
diff --git a/macros/latex/contrib/l3kernel/l3kernel-functions.dtx b/macros/latex/contrib/l3kernel/l3kernel-functions.dtx
index fa09742458..d5cc6170ad 100644
--- a/macros/latex/contrib/l3kernel/l3kernel-functions.dtx
+++ b/macros/latex/contrib/l3kernel/l3kernel-functions.dtx
@@ -43,7 +43,7 @@
% }^^A
% }
%
-% \date{Released 2020-05-05}
+% \date{Released 2020-05-11}
%
% \maketitle
%
@@ -329,6 +329,104 @@
% and variable mappings.
% \end{variable}
%
+% \begin{function}{\__kernel_quark_new_test:N}
+% \begin{syntax}
+% \cs{__kernel_quark_new_test:N} \cs[no-index]{\meta{name}:\meta{arg spec}}
+% \end{syntax}
+% Defines a quark-test function \cs[no-index]{\meta{name}:\meta{arg spec}}
+% which tests if its argument is \cs[no-index]{q__\meta{namespace}_recursion_tail},
+% then acts accordingly, as described below for each possible
+% \meta{arg spec}.
+%
+% The \meta{namespace} is determined as the first (nonempty)
+% |_|-delimited word in \meta{name} and is used internally
+% in the definition of auxiliaries. The function
+% \cs{__kernel_quark_new_test:N} does \emph{not} define
+% the \cs[no-index]{q__\meta{namespace}_recursion_tail} and
+% \cs[no-index]{q__\meta{namespace}_recursion_stop} quarks.
+% They should be manually defined with \cs{quark_new:N}.
+%
+% There are $6$ different types of quark-test functions. Which one is
+% defined depends on the \meta{arg spec}, which \emph{must} be one of
+% the options listed now. Four of them are modeled after
+% \cs[no-index]{quark_if_recursion_tail:(N|n)} and
+% \cs[no-index]{quark_if_recursion_tail_do:(N|n)n}.
+% \begin{description}
+% \def\makelabel#1{\texttt{#1}}
+% \item[n] defines \cs[no-index]{\meta{name}:n} such that it
+% checks if |#1| contains only \cs[no-index]{q__\meta{namespace}_recursion_tail}, and
+% if so consumes all tokens up to \cs[no-index]{q__\meta{namespace}_recursion_stop}
+% (\emph{c.f.}~\cs{quark_if_recursion_tail_stop:n}).
+% \item[nn] defines \cs[no-index]{\meta{name}:nn} such that it
+% checks if |#1| contains only \cs[no-index]{q__\meta{namespace}_recursion_tail}, and
+% if so consumes all tokens up to \cs[no-index]{q__\meta{namespace}_recursion_stop},
+% then executes the code |#2| after that
+% (\emph{c.f.}~\cs{quark_if_recursion_tail_stop_do:nn}).
+% \item[N] defines \cs[no-index]{\meta{name}:N} such that it
+% checks if |#1| is \cs[no-index]{q__\meta{namespace}_recursion_tail}, and if so consumes
+% all tokens up to \cs[no-index]{q__\meta{namespace}_recursion_stop}
+% (\emph{c.f.}~\cs{quark_if_recursion_tail_stop:N}).
+% \item[Nn] defines \cs[no-index]{\meta{name}:Nn} such that it
+% checks if |#1| is \cs[no-index]{q__\meta{namespace}_recursion_tail}, and if so consumes
+% all tokens up to \cs[no-index]{q__\meta{namespace}_recursion_stop}, then executes
+% the code |#2| after that
+% (\emph{c.f.}~\cs{quark_if_recursion_tail_stop_do:Nn}).
+% \end{description}
+% The last two are modeled after
+% \cs[no-index]{quark_if_recursion_tail_break:(n|N)N}, and in those
+% cases the quark \cs[no-index]{q__\meta{namespace}_recursion_stop} is
+% not used (and thus needs not be defined).
+% \begin{description}
+% \def\makelabel#1{\texttt{#1}}
+% \item[nN] defines \cs[no-index]{\meta{name}:nN} such that it
+% checks if |#1| contains only \cs[no-index]{q__\meta{namespace}_recursion_tail}, and
+% if so uses the \cs[no-index]{\meta{type}_map_break:} function |#2|.
+% \item[NN] defines \cs[no-index]{\meta{name}:NN} such that it
+% checks if |#1| is \cs[no-index]{q__\meta{namespace}_recursion_tail}, and if so uses
+% the \cs[no-index]{\meta{type}_map_break:} function |#2|.
+% \end{description}
+% Any other signature, as well as a function without signature
+% are errors, and in such case the definition is aborted.
+% \end{function}
+%
+% \begin{function}{\__kernel_quark_new_conditional:Nn}
+% \begin{syntax}
+% \cs{__kernel_quark_new_conditional:Nn} \cs[no-index]{__\meta{namespace}_quark_if_\meta{name}:\meta{arg spec}} \Arg{conditions}
+% \end{syntax}
+% Defines a collection of quark conditionals that test if their
+% argument is the quark \cs[no-index]{q__\meta{namespace}_\meta{name}}
+% and perform suitable actions. The \meta{conditions} are a
+% comma-separated list of one or more of |p|, |T|, |F|, and |TF|, and
+% one conditional is defined for each \meta{condition} in the list, as
+% described for \cs{prg_new_conditional:Npnn}. The conditionals are
+% defined using \cs{prg_new_conditional:Npnn}, so that their name is
+% obtained by adding |p|, |T|, |F|, or |TF| to the base name
+% \cs[no-index]{__\meta{namespace}_quark_if_\meta{name}:\meta{arg spec}}.
+%
+% The first argument of \cs{__kernel_quark_new_conditional:Nn} must
+% contain |_quark_if_| and |:|, as these markers are used to determine
+% the \meta{name} of the quark
+% \cs[no-index]{q__\meta{namespace}_\meta{name}} to be tested. This
+% quark should be manually defined with \cs{quark_new:N}, as
+% \cs{__kernel_quark_new_conditional:Nn} does \emph{not} define it.
+%
+% The function \cs{__kernel_quark_new_conditional:Nn} can define $2$
+% different types of quark conditionals. Which one is defined depends
+% on the \meta{arg spec}, which \emph{must} be one of the following
+% options, modeled after \cs[no-index]{quark_if_nil:(N|n)(TF)}.
+% \begin{description}
+% \def\makelabel#1{\texttt{#1}}
+% \item[n] defines \cs[no-index]{__\meta{namespace}_quark_if_\meta{name}:n(TF)} such that it
+% checks if |#1| contains only \cs[no-index]{q__\meta{namespace}_\meta{name}}, and
+% executes the proper conditional branch.
+% \item[N] defines \cs[no-index]{__\meta{namespace}_quark_if_\meta{name}:N(TF)} such that it
+% checks if |#1| is \cs[no-index]{q__\meta{namespace}_\meta{name}}, and
+% executes the proper conditional branch.
+% \end{description}
+% Any other signature, as well as a function without signature
+% are errors, and in such case the definition is aborted.
+% \end{function}
+%
% \begin{variable}{\c__kernel_randint_max_int}
% Maximal allowed argument to \cs{__kernel_randint:n}. Equal to
% $2^{17}-1$.