[latex3-commits] [git/LaTeX3-latex3-latex3] scan-quark: Document new \__kernel_quark_... functions (a04b28a5b)

[PhelypeOleinik]

Repository : https://github.com/latex3/latex3
On branch  : scan-quark
Link       : https://github.com/latex3/latex3/commit/a04b28a5bf4a3513bd8a9858a11a3f2cd5e5698a

>---------------------------------------------------------------

commit a04b28a5bf4a3513bd8a9858a11a3f2cd5e5698a
Author: PhelypeOleinik <tex.phelype at gmail.com>
Date:   Tue Mar 24 15:40:14 2020 -0300

    Document new \__kernel_quark_... functions


>---------------------------------------------------------------

a04b28a5bf4a3513bd8a9858a11a3f2cd5e5698a
 l3kernel/l3kernel-functions.dtx | 96 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 96 insertions(+)

diff --git a/l3kernel/l3kernel-functions.dtx b/l3kernel/l3kernel-functions.dtx
index b58d0fdc2..6b940091b 100644
--- a/l3kernel/l3kernel-functions.dtx
+++ b/l3kernel/l3kernel-functions.dtx
@@ -329,6 +329,102 @@
 %   and variable mappings.
 % \end{variable}
 %
+% \begin{function}{\__kernel_quark_test_generate:NNNn}
+%   \begin{syntax}
+%     \cs{__kernel_quark_test_generate:NNNn} \cs[no-index]{\meta{name}:\meta{arg spec}} \cs[no-index]{\meta{test-quark}} \cs[no-index]{\meta{delimit-quark}} \Arg{namespace}
+%   \end{syntax}
+%   Defines a quark-test function \cs[no-index]{\meta{name}:\meta{arg spec}}
+%   which tests if its argument is the \cs[no-index]{\meta{test-quark}},
+%   then acts accordingly, as described below for each possible
+%   \meta{arg spec}.
+%
+%   The \meta{arg spec} \emph{must} be one of the options listed
+%   below. \cs[no-index]{\meta{test-quark}} and \cs[no-index]{\meta{delimit-quark}}
+%   should be valid quarks, defined with \cs{quark_new:N}, and
+%   \meta{namespace} should be the name space to be used internally
+%   in the definition of auxiliaries (for example |__module|).
+%
+%   \cs{__kernel_quark_test_generate:NNNn} can define $6$ different
+%   types of quark-test functions. Which one is defined depends on
+%   the \meta{arg spec} of the given function:
+%   \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]{\meta{test-quark}}, and
+%       if so consumes all tokens up to \cs[no-index]{\meta{delimit-quark}}
+%       (\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]{\meta{test-quark}}, and
+%       if so consumes all tokens up to \cs[no-index]{\meta{delimit-quark}},
+%       then executes the code |#2| after that
+%       (\emph{c.f.}~\cs{quark_if_recursion_tail_stop_do:nn}).
+%     \item[nN] defines \cs[no-index]{\meta{name}:nN} such that it
+%       checks if |#1| contains only \cs[no-index]{\meta{test-quark}}, and
+%       if so uses the \cs[no-index]{\meta{type}_map_break:} function |#2|
+%       (\emph{c.f.}~\cs{quark_if_recursion_tail_break:nN}).
+%       \cs[no-index]{\meta{delimit-quark}} is not used in this case.
+%     \item[N]  defines \cs[no-index]{\meta{name}:N}  such that it
+%       checks if |#1| is \cs[no-index]{\meta{test-quark}}, and if so consumes
+%       all tokens up to \cs[no-index]{\meta{delimit-quark}}
+%       (\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]{\meta{test-quark}}, and if so consumes
+%       all tokens up to \cs[no-index]{\meta{delimit-quark}}, then executes
+%       the code |#2| after that
+%       (\emph{c.f.}~\cs{quark_if_recursion_tail_stop_do:Nn}).
+%     \item[NN] defines \cs[no-index]{\meta{name}:NN} such that it
+%       checks if |#1| is \cs[no-index]{\meta{test-quark}}, and if so uses
+%       the \cs[no-index]{\meta{type}_map_break:} function |#2|
+%       (\emph{c.f.}~\cs{quark_if_recursion_tail_break:NN}).
+%       \cs[no-index]{\meta{delimit-quark}} is not used in this case.
+%   \end{description}
+%   Any other signature, as well as a function without signature
+%   are errors, and in such case the definition is aborted.
+%
+%   \cs{__kernel_quark_test_generate:NNNn} does \emph{not} define
+%   the \cs[no-index]{\meta{test-quark}} and \cs[no-index]{\meta{delimit-quark}}.
+%   They should be manually defined with \cs{quark_new:N}.
+% \end{function}
+%
+% \begin{function}{\__kernel_quark_conditional_generate:NNnn}
+%   \begin{syntax}
+%     \cs{__kernel_quark_conditional_generate:NNnn} \cs[no-index]{\meta{name}:\meta{arg spec}} \cs[no-index]{\meta{test-quark}} \Arg{namespace} \Arg{conditions}
+%   \end{syntax}
+%   Defines a quark conditional \cs[no-index]{\meta{name}:\meta{arg spec}}
+%   which tests if its argument is the \cs[no-index]{\meta{test-quark}},
+%   and executes the appropriate \meta{condition}. \meta{conditions} is
+%   a comma-separated list of one or more of |p|, |T|, |F|, and |TF|, and
+%   defines one function for each \meta{condition} as described for
+%   \cs{prg_new_conditional:Npnn}.
+%
+%   The \meta{arg spec} \emph{must} be one of the options listed
+%   below. \cs[no-index]{\meta{test-quark}}
+%   should be a valid quark, defined with \cs{quark_new:N}, and
+%   \meta{namespace} should be the name space to be used internally
+%   in the definition of auxiliaries (for example |__module|).
+%
+%   \cs{__kernel_quark_conditional_generate:NNNn} can define $2$ different
+%   types of quark-test functions. Which one is defined depends on
+%   the \meta{arg spec} of the given function:
+%   \begin{description}
+%     \def\makelabel#1{\texttt{#1}}
+%     \item[n]  defines \cs[no-index]{\meta{name}:n(TF)}  such that it
+%       checks if |#1| contains only \cs[no-index]{\meta{test-quark}}, and
+%       executes the proper conditional branch.
+%       (\emph{c.f.}~\cs[no-index]{quark_if_nil:n(TF)}).
+%     \item[N]  defines \cs[no-index]{\meta{name}:N(TF)}  such that it
+%       checks if |#1| is \cs[no-index]{\meta{test-quark}}, and
+%       executes the proper conditional branch.
+%       (\emph{c.f.}~\cs[no-index]{quark_if_nil:N(TF)}).
+%   \end{description}
+%   Any other signature, as well as a function without signature
+%   are errors, and in such case the definition is aborted.
+%
+%   \cs{__kernel_quark_test_generate:NNNn} does \emph{not} define
+%   the \cs[no-index]{\meta{test-quark}}.
+%   It~should be manually defined with \cs{quark_new:N}.
+% \end{function}
+%
 % \begin{variable}{\c__kernel_randint_max_int}
 %   Maximal allowed argument to \cs{__kernel_randint:n}.  Equal to
 %   $2^{17}-1$.