diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3quark.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/l3kernel/l3quark.dtx | 126 |
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} |