summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/l3quark.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3quark.dtx')
-rw-r--r--Master/texmf-dist/source/latex/l3kernel/l3quark.dtx126
1 files changed, 56 insertions, 70 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3quark.dtx b/Master/texmf-dist/source/latex/l3kernel/l3quark.dtx
index f4ee8b13118..b42d4ebc67a 100644
--- a/Master/texmf-dist/source/latex/l3kernel/l3quark.dtx
+++ b/Master/texmf-dist/source/latex/l3kernel/l3quark.dtx
@@ -41,21 +41,17 @@
% }^^A
% }
%
-% \date{Released 2018/03/05}
+% \date{Released 2018-04-30}
%
% \maketitle
%
% \begin{documentation}
%
-% \section{Introduction to quarks and scan marks}
-%
% Two special types of constants in \LaTeX3 are \enquote{quarks} and
% \enquote{scan marks}. By convention all constants of type quark
-% start out with |\q_|, and scan marks start with |\s_|. Scan marks are
-% for internal use by the kernel: they are not intended for more general
-% use.
+% start out with |\q_|, and scan marks start with |\s_|.
%
-% \subsection{Quarks}
+% \section{Quarks}
%
% Quarks are control sequences that expand to themselves and should
% therefore \emph{never} be executed directly in the code.
@@ -247,6 +243,21 @@
% ended.
% \end{function}
%
+%
+% \begin{function}[added = 2018-04-10]
+% {
+% \quark_if_recursion_tail_break:NN,
+% \quark_if_recursion_tail_break:nN
+% }
+% \begin{syntax}
+% \cs{quark_if_recursion_tail_break:nN} \Arg{token list} \cs[no-index]{\meta{type}_map_break:}
+% \end{syntax}
+% Tests if \meta{token list} contains only \cs{q_recursion_tail}, and
+% if so terminates the recursion using \cs[no-index]{\meta{type}_map_break:}.
+% The recursion end should be marked by \cs{prg_break_point:Nn}
+% \cs[no-index]{\meta{type}_map_break:}.
+% \end{function}
+%
% \section{An example of recursion with quarks}
% \label{sec:l3quark:quark-example}
%
@@ -297,23 +308,6 @@
% mapping function cannot be nested, since the second map would overwrite
% the definition of |\__my_map_dbl_fn:nn|.
%
-%
-% \section{Internal quark functions}
-%
-% \begin{function}
-% {
-% \__quark_if_recursion_tail_break:NN,
-% \__quark_if_recursion_tail_break:nN
-% }
-% \begin{syntax}
-% \cs{__quark_if_recursion_tail_break:nN} \Arg{token list} \cs[no-index]{\meta{type}_map_break:}
-% \end{syntax}
-% Tests if \meta{token list} contains only \cs{q_recursion_tail}, and
-% if so terminates the recursion using \cs[no-index]{\meta{type}_map_break:}.
-% The recursion end should be marked by \cs{prg_break_point:Nn}
-% \cs[no-index]{\meta{type}_map_break:}.
-% \end{function}
-%
% \section{Scan marks}
%
% Scan marks are control sequences set equal to \cs{scan_stop:},
@@ -327,30 +321,26 @@
% This allows to skip to that point if the end of the instructions
% should not be performed (see \pkg{l3regex}).
%
-% The scan marks system is only for internal use by the kernel team in
-% a small number of very specific places. These functions should not be
-% used more generally.
-%
-% \begin{function}{\__scan_new:N}
+% \begin{function}[added = 2018-04-01]{\scan_new:N}
% \begin{syntax}
-% \cs{__scan_new:N} \meta{scan mark}
+% \cs{scan_new:N} \meta{scan mark}
% \end{syntax}
% Creates a new \meta{scan mark} which is set equal to \cs{scan_stop:}.
% The \meta{scan mark} is defined globally, and an error message
% is raised if the name was already taken by another scan mark.
% \end{function}
%
-% \begin{variable}{\s__stop}
+% \begin{variable}[added = 2018-04-01]{\s_stop}
% Used at the end of a set of instructions, as a marker
-% that can be jumped to using \cs{__use_none_delimit_by_s__stop:w}.
+% that can be jumped to using \cs{use_none_delimit_by_s_stop:w}.
% \end{variable}
%
-% \begin{function}{\__use_none_delimit_by_s__stop:w}
+% \begin{function}[added = 2018-04-01]{\use_none_delimit_by_s_stop:w}
% \begin{syntax}
-% \cs{__use_none_delimit_by_s__stop:w} \meta{tokens} \cs{s__stop}
+% \cs{use_none_delimit_by_s_stop:w} \meta{tokens} \cs{s_stop}
% \end{syntax}
-% Removes the \meta{tokens} and \cs{s__stop} from the input stream.
-% This leads to a low-level \TeX{} error if \cs{s__stop} is absent.
+% Removes the \meta{tokens} and \cs{s_stop} from the input stream.
+% This leads to a low-level \TeX{} error if \cs{s_stop} is absent.
% \end{function}
%
% \end{documentation}
@@ -378,7 +368,7 @@
\__kernel_patch:nnNNpn { \__kernel_chk_var_scope:NN q #1 } { }
\cs_new_protected:Npn \quark_new:N #1
{
- \__chk_if_free_cs:N #1
+ \__kernel_chk_if_free_cs:N #1
\cs_gset_nopar:Npn #1 {#1}
}
% \end{macrocode}
@@ -473,24 +463,23 @@
% \end{macro}
% \end{macro}
%
-% \begin{macro}{\__quark_if_recursion_tail_break:NN}
-% \begin{macro}{\__quark_if_recursion_tail_break:nN}
-% Analogs of the \cs[index=quark_if_recursion_tail_stop:n]
+% \begin{macro}{\quark_if_recursion_tail_break:NN}
+% \begin{macro}{\quark_if_recursion_tail_break:nN}
+% Analogues of the \cs[index=quark_if_recursion_tail_stop:n]
% {quark_if_recursion_tail_stop\ldots{}} functions.
% Break the mapping using |#2|.
% \begin{macrocode}
-\cs_new:Npn \__quark_if_recursion_tail_break:NN #1#2
+\cs_new:Npn \quark_if_recursion_tail_break:NN #1#2
{
\if_meaning:w \q_recursion_tail #1
\exp_after:wN #2
\fi:
}
-\cs_new:Npn \__quark_if_recursion_tail_break:nN #1#2
+\cs_new:Npn \quark_if_recursion_tail_break:nN #1#2
{
- \tl_if_empty:oTF
+ \tl_if_empty:oT
{ \@@_if_recursion_tail:w {} #1 {} ?! \q_recursion_tail ??! }
{#2}
- { }
}
% \end{macrocode}
% \end{macro}
@@ -533,6 +522,7 @@
% \begin{macro}[pTF]{\quark_if_no_value:n}
% \UnitTested
% \begin{macro}{\@@_if_nil:w, \@@_if_no_value:w}
+% \begin{macro}[EXP]{\@@_if_empty_return:o}
% Let us explain |\quark_if_nil:n(TF)|. Expanding \cs{@@_if_nil:w}
% once is safe thanks to the trailing \cs{q_nil} |??!|. The result of
% expanding once is empty if and only if both delimited arguments |#1|
@@ -546,35 +536,38 @@
% |{}\q_nil| |{}?| |!\q_nil|~|??!|, hence |#3|~is delimited by the
% final~|?!|, and the test returns \texttt{true} as wanted. In the
% second case, the result is not empty since the first~|?!| in the
-% definition of \cs{quark_if_nil:n} stop~|#3|.
+% definition of \cs{quark_if_nil:n} stop~|#3|. The auxiliary here
+% is the same as \cs{__tl_if_empty_return:o}, with the same comments
+% applying.
% \begin{macrocode}
\prg_new_conditional:Npnn \quark_if_nil:n #1 { p, T , F , TF }
{
- \__tl_if_empty_return:o
+ \@@_if_empty_return:o
{ \@@_if_nil:w {} #1 {} ? ! \q_nil ? ? ! }
}
\cs_new:Npn \@@_if_nil:w #1 \q_nil #2 ? #3 ? ! { #1 #2 }
\prg_new_conditional:Npnn \quark_if_no_value:n #1 { p, T , F , TF }
{
- \__tl_if_empty_return:o
+ \@@_if_empty_return:o
{ \@@_if_no_value:w {} #1 {} ? ! \q_no_value ? ? ! }
}
\cs_new:Npn \@@_if_no_value:w #1 \q_no_value #2 ? #3 ? ! { #1 #2 }
\prg_generate_conditional_variant:Nnn \quark_if_nil:n
{ V , o } { p , TF , T , F }
+\cs_new:Npn \@@_if_empty_return:o #1
+ {
+ \exp_after:wN \if_meaning:w \exp_after:wN \q_nil
+ \__kernel_tl_to_str:w \exp_after:wN {#1} \q_nil
+ \prg_return_true:
+ \else:
+ \prg_return_false:
+ \fi:
+ }
% \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
-%
-% \begin{variable}{\q__tl_act_mark, \q__tl_act_stop}
-% These private quarks are needed by \pkg{l3tl}, but that is loaded
-% before the quark module, hence their definition is deferred.
-% \begin{macrocode}
-\quark_new:N \q__tl_act_mark
-\quark_new:N \q__tl_act_stop
-% \end{macrocode}
-% \end{variable}
+% \end{macro}
%
% \subsection{Scan marks}
%
@@ -590,12 +583,13 @@
% \end{macrocode}
% \end{variable}
%
-% \begin{macro}{\@@_new:N}
+% \begin{macro}{\scan_new:N}
% \UnitTested
% Check whether the variable is already a scan mark,
% then declare it to be equal to \cs{scan_stop:} globally.
% \begin{macrocode}
-\cs_new_protected:Npn \@@_new:N #1
+\__kernel_patch:nnNNpn { \__kernel_chk_var_scope:NN s #1 } { }
+\cs_new_protected:Npn \scan_new:N #1
{
\tl_if_in:NnTF \g_@@_marks_tl { #1 }
{
@@ -610,31 +604,23 @@
% \end{macrocode}
% \end{macro}
%
-% \begin{variable}{\s__stop}
+% \begin{variable}{\s_stop}
% \UnitTested
% We only declare one scan mark here, more can be defined
% by specific modules.
% \begin{macrocode}
-\@@_new:N \s__stop
+\scan_new:N \s_stop
% \end{macrocode}
% \end{variable}
%
-% \begin{macro}{\__use_none_delimit_by_s__stop:w}
+% \begin{macro}{\use_none_delimit_by_s_stop:w}
% \UnitTested
% Similar to \cs{use_none_delimit_by_q_stop:w}.
% \begin{macrocode}
-\cs_new:Npn \__use_none_delimit_by_s__stop:w #1 \s__stop { }
+\cs_new:Npn \use_none_delimit_by_s_stop:w #1 \s_stop { }
% \end{macrocode}
% \end{macro}
%
-% \begin{variable}{\s__seq}
-% This private scan mark is needed by \pkg{l3seq}, but that is loaded
-% before the quark module, hence its definition is deferred.
-% \begin{macrocode}
-\__scan_new:N \s__seq
-% \end{macrocode}
-% \end{variable}
-%
% \begin{macrocode}
%</initex|package>
% \end{macrocode}