diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3quark.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/l3kernel/l3quark.dtx | 179 |
1 files changed, 100 insertions, 79 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3quark.dtx b/Master/texmf-dist/source/latex/l3kernel/l3quark.dtx index 3cb65a59b33..b85b03440df 100644 --- a/Master/texmf-dist/source/latex/l3kernel/l3quark.dtx +++ b/Master/texmf-dist/source/latex/l3kernel/l3quark.dtx @@ -35,8 +35,8 @@ % %<*driver|package> \RequirePackage{l3names} -\GetIdInfo$Id: l3quark.dtx 3384 2012-02-12 13:13:11Z will $ - {L3 Experimental quarks} +\GetIdInfo$Id: l3quark.dtx 3986 2012-07-15 19:23:51Z joseph $ + {L3 Quarks} %</driver|package> %<*driver> \documentclass[full]{l3doc} @@ -71,8 +71,9 @@ % % 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_|. -% \emph{Scan marks are an experimental feature.} +% 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. % % \subsection{Quarks} % @@ -114,22 +115,6 @@ % An example of the quark testing functions and their use in recursion % can be seen in the implementation of \cs{clist_map_function:NN}. % -% -% \subsection{Scan marks} -% -% Scan marks are control sequences set equal to \cs{scan_stop:}, -% hence will never expand in an expansion context and will be (largely) -% invisible if they are encountered in a typesetting context. -% -% Like quarks, they can be used as delimiters in weird functions -% and are often safer to use for this purpose. -% Since they are harmless when executed by \TeX{} in non-expandable -% contexts, they can be used to mark the end of a set of instructions. -% This allows to skip to that point if the end of the instructions -% should not be performed (see \pkg{l3regex}). -% -%^^A todo: talk about the use of scan marks in galley and fp. -% % \section{Defining quarks} % % \begin{function}{\quark_new:N} @@ -279,63 +264,81 @@ % ended. % \end{function} % +% \section{Clearing quarks away} +% +% \begin{function}{\use_none_delimit_by_q_recursion_stop:w} +% \begin{syntax} +% \cs{use_none_delimit_by_q_recursion_stop:w} \meta{tokens} \cs{q_recursion_stop} +% \end{syntax} +% Used to prematurely terminate a recursion using \cs{q_recursion_stop} +% as the end marker, removing any remaining \meta{tokens} from the +% input stream. +% \end{function} +% +% \begin{function}{\use_i_delimit_by_q_recursion_stop:nw} +% \begin{syntax} +% \cs{use_i_delimit_by_q_recursion_stop:nw} \Arg{insertion} +% ~~\meta{tokens} \cs{q_recursion_stop} +% \end{syntax} +% Used to prematurely terminate a recursion using \cs{q_recursion_stop} +% as the end marker, removing any remaining \meta{tokens} from the +% input stream. The \meta{insertion} is then made into the input +% stream after the end of the recursion. +% \end{function} +% +% \section{Internal quark functions} +% % \begin{function} % { -% \quark_if_recursion_tail_break:N, -% \quark_if_recursion_tail_break:n +% \__quark_if_recursion_tail_break:NN, +% \__quark_if_recursion_tail_break:nN % } % \begin{syntax} -% \cs{quark_if_recursion_tail_break:n} \Arg{token list} +% \cs{__quark_if_recursion_tail_break:nN} \Arg{token list} \cs{\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{prg_map_break:}. -% The recursion end should be marked by \cs{prg_break_point:n}. +% Tests if \meta{token list} contains only \cs{q_recursion_tail}, and +% if so terminates the recursion using \cs{\meta{type}_map_break:}. +% The recursion end should be marked by \cs{prg_break_point:Nn} +% \cs{\meta{type}_map_break:}. % \end{function} % % \section{Scan marks} % -% \begin{function}{\scan_new:N} +% Scan marks are control sequences set equal to \cs{scan_stop:}, +% hence will never expand in an expansion context and will be (largely) +% invisible if they are encountered in a typesetting context. +% +% Like quarks, they can be used as delimiters in weird functions +% and are often safer to use for this purpose. +% Since they are harmless when executed by \TeX{} in non-expandable +% contexts, they can be used to mark the end of a set of instructions. +% 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{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} will be defined globally, and an error message % will be raised if the name was already taken by another scan mark. % \end{function} % -% \begin{variable}{\s_stop} +% \begin{variable}{\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}{\__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. -% \end{function} -% -% \section{Internal quark functions} -% -% \begin{function}{\use_none_delimit_by_q_recursion_stop:w} -% \begin{syntax} -% \cs{use_none_delimit_by_q_recursion_stop:w} \meta{tokens} \cs{q_recursion_stop} -% \end{syntax} -% Used to prematurely terminate a recursion using \cs{q_recursion_stop} -% as the end marker, removing any remaining \meta{tokens} from the -% input stream. -% \end{function} -% -% \begin{function}{\use_i_delimit_by_q_recursion_stop:nw} -% \begin{syntax} -% \cs{use_i_delimit_by_q_recursion_stop:nw} \Arg{insertion} -% ~~\meta{tokens} \cs{q_recursion_stop} -% \end{syntax} -% Used to prematurely terminate a recursion using \cs{q_recursion_stop} -% as the end marker, removing any remaining \meta{tokens} from the -% input stream. The \meta{insertion} is then made into the input -% stream after the end of the recursion. +% 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} @@ -354,7 +357,7 @@ %<*package> \ProvidesExplPackage {\ExplFileName}{\ExplFileDate}{\ExplFileVersion}{\ExplFileDescription} -\package_check_loaded_expl: +\__expl_package_check: %</package> % \end{macrocode} % @@ -453,22 +456,22 @@ % \end{macro} % \end{macro} % -% \begin{macro}{\quark_if_recursion_tail_break:N} -% \begin{macro}{\quark_if_recursion_tail_break:n} +% \begin{macro}{\__quark_if_recursion_tail_break:NN} +% \begin{macro}{\__quark_if_recursion_tail_break:nN} % Analogs of the \cs{quark_if_recursion_tail_stop\ldots{}} functions. -% Break the mapping using \cs{prg_map_break:}. +% Break the mapping using |#2|. % \begin{macrocode} -\cs_new:Npn \quark_if_recursion_tail_break:N #1 +\cs_new:Npn \__quark_if_recursion_tail_break:NN #1#2 { \if_meaning:w \q_recursion_tail #1 - \exp_after:wN \prg_map_break: + \exp_after:wN #2 \fi: } -\cs_new:Npn \quark_if_recursion_tail_break:n #1 +\cs_new:Npn \__quark_if_recursion_tail_break:nN #1#2 { \if_int_compare:w \pdftex_strcmp:D { \exp_not:N \q_recursion_tail } { \exp_not:n {#1} } = \c_zero - \exp_after:wN \prg_map_break: + \exp_after:wN #2 \fi: } % \end{macrocode} @@ -477,7 +480,7 @@ % % \begin{macro}[pTF]{\quark_if_nil:N} % \UnitTested -% \begin{macro}[pTF]{\quark_if_no_value:N., \quark_if_no_value:c} +% \begin{macro}[pTF]{\quark_if_no_value:N, \quark_if_no_value:c} % \UnitTested % Here we test if we found a special quark as the first argument. % We better start with \cs{q_no_value} as the first argument since @@ -541,59 +544,77 @@ % \end{macro} % \end{macro} % -% \begin{variable}{\q_tl_act_mark,\q_tl_act_stop} +% \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 +\quark_new:N \q__tl_act_mark +\quark_new:N \q__tl_act_stop % \end{macrocode} % \end{variable} % % \subsection{Scan marks} +% +% \begin{macrocode} +%<@@=scan> +% \end{macrocode} % -% \begin{variable}{\g_scan_marks_tl} +% \begin{variable}{\g_@@_marks_tl} % \UnitTested % The list of all scan marks currently declared. % \begin{macrocode} -\tl_new:N \g_scan_marks_tl +\tl_new:N \g_@@_marks_tl % \end{macrocode} % \end{variable} % -% \begin{macro}{\scan_new:N} +% \begin{macro}[int]{\@@_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 \scan_new:N #1 +\cs_new_protected:Npn \@@_new:N #1 { - \tl_if_in:NnTF \g_scan_marks_tl { #1 } + \tl_if_in:NnTF \g_@@_marks_tl { #1 } { - \msg_kernel_error:nnx { scan } { already-defined } + \__msg_kernel_error:nnx { kernel } { scanmark-already-defined } { \token_to_str:N #1 } } { - \tl_gput_right:Nn \g_scan_marks_tl {#1} + \tl_gput_right:Nn \g_@@_marks_tl {#1} \cs_new_eq:NN #1 \scan_stop: } } % \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} -\scan_new:N \s_stop +\@@_new:N \s__stop % \end{macrocode} % \end{variable} % -% \begin{macro}{\use_none_delimit_by_s_stop:w} +% \begin{macro}[int]{\__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} +% +% \subsection{Deprecated quark functions} +% +% \begin{macro} +% {\quark_if_recursion_tail_break:N, \quark_if_recursion_tail_break:n} +% It's not clear what breaking function we should be using here, so +% I'm picking one somewhat arbitrarily. +% \begin{macrocode} +\cs_new:Npn \quark_if_recursion_tail_break:N #1 + { \__quark_if_recursion_tail_break:NN #1 \prg_break: } +\cs_new:Npn \quark_if_recursion_tail_break:n #1 + { \__quark_if_recursion_tail_break:nN {#1} \prg_break: } % \end{macrocode} % \end{macro} % |