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.dtx102
1 files changed, 94 insertions, 8 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3quark.dtx b/Master/texmf-dist/source/latex/l3kernel/l3quark.dtx
index 1709da93420..cc865cccb6c 100644
--- a/Master/texmf-dist/source/latex/l3kernel/l3quark.dtx
+++ b/Master/texmf-dist/source/latex/l3kernel/l3quark.dtx
@@ -35,7 +35,7 @@
%
%<*driver|package>
\RequirePackage{l3names}
-\GetIdInfo$Id: l3quark.dtx 3014 2011-11-27 06:55:43Z bruno $
+\GetIdInfo$Id: l3quark.dtx 3086 2011-12-22 17:55:46Z bruno $
{L3 Experimental quarks}
%</driver|package>
%<*driver>
@@ -67,12 +67,17 @@
%
% \begin{documentation}
%
-% A special type of constants in \LaTeX3 are \enquote{quarks}. These are
-% control
-% sequences that expand to themselves and should therefore \emph{never} be
-% executed directly in the code. This would result in an endless loop!
+% 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_|.
%
-% They are meant to be used as delimiter is weird functions (for
+% \emph{Scan marks are an experimental feature.}
+%
+% Quarks are control sequences that expand to themselves and should
+% therefore \emph{never} be executed directly in the code.
+% This would result in an endless loop!
+%
+% They are meant to be used as delimiter in weird functions (for
% example as the stop token (\emph{i.e.}~\cs{q_stop}). They also permit the
% following ingenious trick: when you pick up a token in a temporary,
% and you want to know whether you have picked up a particular quark,
@@ -81,7 +86,15 @@
% below. All the quark testing functions are expandable although the
% ones testing only single tokens are much faster.
%
-% By convention all constants of type quark start out with |\q_|.
+% Scan marks are control sequences set equal to \cs{scan_stop:},
+% hence will never expand.
+%
+% 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}
%
@@ -243,6 +256,30 @@
% The recursion end should be marked by \cs{prg_break_point:n}.
% \end{function}
%
+% \section{Scan marks}
+%
+% \begin{function}{\scan_new:N}
+% \begin{syntax}
+% \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}
+% 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}.
+% \end{variable}
+%
+% \begin{function}{\use_none_delimit_by_s_stop:w}
+% \begin{variable}
+% \cs{use_none_delimit_by_s_stop:w} \meta{tokens} \cs{s_stop}
+% \end{variable}
+% 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}
@@ -285,11 +322,13 @@
%</package>
% \end{macrocode}
%
+% \subsection{Quarks}
+%
% \begin{macro}{\quark_new:N}
% \UnitTested
% Allocate a new quark.
% \begin{macrocode}
-\cs_new_protected_nopar:Npn \quark_new:N #1 { \tl_const:Nn #1 {#1} }
+\cs_new_protected:Npn \quark_new:N #1 { \tl_const:Nn #1 {#1} }
% \end{macrocode}
% \end{macro}
%
@@ -475,6 +514,53 @@
% \end{macrocode}
% \end{variable}
%
+% \subsection{Scan marks}
+%
+% \begin{variable}{\g_scan_marks_tl}
+% \UnitTested
+% The list of all scan marks currently declared.
+% \begin{macrocode}
+\tl_new:N \g_scan_marks_tl
+% \end{macrocode}
+% \end{variable}
+%
+% \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 \scan_new:N #1
+ {
+ \tl_if_in:NnTF \g_scan_marks_tl { #1 }
+ {
+ \msg_kernel_error:nnx { scan } { already-defined }
+ { \token_to_str:N #1 }
+ }
+ {
+ \tl_gput_right:Nn \g_scan_marks_tl {#1}
+ \cs_new_eq:NN #1 \scan_stop:
+ }
+ }
+% \end{macrocode}
+% \end{macro}
+%
+% \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
+% \end{macrocode}
+% \end{variable}
+%
+% \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 { }
+% \end{macrocode}
+% \end{macro}
+%
% \begin{macrocode}
%</initex|package>
% \end{macrocode}