diff options
author | Karl Berry <karl@freefriends.org> | 2011-12-29 23:03:42 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2011-12-29 23:03:42 +0000 |
commit | 7a50f35d6fd3bd705c78298b1ccc085991638f87 (patch) | |
tree | 7f749391d34aa12a37a30a33c00b3098b2320e7c /Master/texmf-dist/source/latex/l3kernel/l3quark.dtx | |
parent | 0bc9393ae50667d7ff769a76321a9548a70351fc (diff) |
l3kernel 3109 (29dec11)
git-svn-id: svn://tug.org/texlive/trunk@24971 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3quark.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/l3kernel/l3quark.dtx | 102 |
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} |