summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/l3token.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3token.dtx')
-rw-r--r--Master/texmf-dist/source/latex/l3kernel/l3token.dtx216
1 files changed, 127 insertions, 89 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3token.dtx b/Master/texmf-dist/source/latex/l3kernel/l3token.dtx
index e539f0bfcec..6e3ef14d414 100644
--- a/Master/texmf-dist/source/latex/l3kernel/l3token.dtx
+++ b/Master/texmf-dist/source/latex/l3kernel/l3token.dtx
@@ -35,7 +35,7 @@
%
%<*driver|package>
\RequirePackage{l3bootstrap}
-\GetIdInfo$Id: l3token.dtx 4251 2012-11-01 16:30:06Z joseph $
+\GetIdInfo$Id: l3token.dtx 4384 2012-12-20 15:47:56Z bruno $
{L3 Experimental token manipulation}
%</driver|package>
%<*driver>
@@ -730,7 +730,7 @@
% as described above.
% \end{variable}
%
-% \begin{function}[updated = 2011-07-02, TF]{\peek_catcode:N}
+% \begin{function}[updated = 2012-12-20, TF]{\peek_catcode:N}
% \begin{syntax}
% \cs{peek_catcode:NTF} \meta{test token} \Arg{true code} \Arg{false code}
% \end{syntax}
@@ -742,19 +742,20 @@
% result of the test).
% \end{function}
%
-% \begin{function}[updated = 2011-07-02, TF]{\peek_catcode_ignore_spaces:N}
+% \begin{function}[updated = 2012-12-20, TF]{\peek_catcode_ignore_spaces:N}
% \begin{syntax}
% \cs{peek_catcode_ignore_spaces:NTF} \meta{test token} \Arg{true code} \Arg{false code}
% \end{syntax}
-% Tests if the next \meta{token} in the input stream has the same
-% category code as the \meta{test token} (as defined by the test
-% \cs{token_if_eq_catcode:NNTF}). Spaces are ignored by the test
-% and the \meta{token} will be left in the input stream after
-% the \meta{true code} or \meta{false code} (as appropriate to the
-% result of the test).
+% Tests if the next non-space \meta{token} in the input stream has the
+% same category code as the \meta{test token} (as defined by the test
+% \cs{token_if_eq_catcode:NNTF}). Explicit and implicit space tokens
+% (with character code 32 and category code 10) are ignored and
+% removed by the test and the \meta{token} will be left in the input
+% stream after the \meta{true code} or \meta{false code} (as
+% appropriate to the result of the test).
% \end{function}
%
-% \begin{function}[updated = 2011-07-02, TF]{\peek_catcode_remove:N}
+% \begin{function}[updated = 2012-12-20, TF]{\peek_catcode_remove:N}
% \begin{syntax}
% \cs{peek_catcode_remove:NTF} \meta{test token} \Arg{true code} \Arg{false code}
% \end{syntax}
@@ -767,21 +768,22 @@
% appropriate to the result of the test).
% \end{function}
%
-% \begin{function}[updated = 2011-07-02, TF]
+% \begin{function}[updated = 2012-12-20, TF]
% {\peek_catcode_remove_ignore_spaces:N}
% \begin{syntax}
% \cs{peek_catcode_remove_ignore_spaces:NTF} \meta{test token} \Arg{true code} \Arg{false code}
% \end{syntax}
-% Tests if the next \meta{token} in the input stream has the same
-% category code as the \meta{test token} (as defined by the test
-% \cs{token_if_eq_catcode:NNTF}). Spaces are ignored by the test
-% and the \meta{token} will be removed from the input stream if the
-% test is true. The function will then place either the
-% \meta{true code} or \meta{false code} in the input stream (as
-% appropriate to the result of the test).
+% Tests if the next non-space \meta{token} in the input stream has the
+% same category code as the \meta{test token} (as defined by the test
+% \cs{token_if_eq_catcode:NNTF}). Explicit and implicit space tokens
+% (with character code 32 and category code 10) are ignored and
+% removed by the test and the \meta{token} will be removed from the
+% input stream if the test is true. The function will then place
+% either the \meta{true code} or \meta{false code} in the input stream
+% (as appropriate to the result of the test).
% \end{function}
%
-% \begin{function}[updated = 2011-07-02, TF]{\peek_charcode:N}
+% \begin{function}[updated = 2012-12-20, TF]{\peek_charcode:N}
% \begin{syntax}
% \cs{peek_charcode:NTF} \meta{test token} \Arg{true code} \Arg{false code}
% \end{syntax}
@@ -793,19 +795,20 @@
% result of the test).
% \end{function}
%
-% \begin{function}[updated = 2011-07-02, TF]{\peek_charcode_ignore_spaces:N}
+% \begin{function}[updated = 2012-12-20, TF]{\peek_charcode_ignore_spaces:N}
% \begin{syntax}
% \cs{peek_charcode_ignore_spaces:NTF} \meta{test token} \Arg{true code} \Arg{false code}
% \end{syntax}
-% Tests if the next \meta{token} in the input stream has the same
-% character code as the \meta{test token} (as defined by the test
-% \cs{token_if_eq_charcode:NNTF}). Spaces are ignored by the test
-% and the \meta{token} will be left in the input stream after
+% Tests if the next non-space \meta{token} in the input stream has the
+% same character code as the \meta{test token} (as defined by the test
+% \cs{token_if_eq_charcode:NNTF}). Explicit and implicit space tokens
+% (with character code 32 and category code 10) are ignored and removed by
+% the test and the \meta{token} will be left in the input stream after
% the \meta{true code} or \meta{false code} (as appropriate to the
% result of the test).
% \end{function}
%
-% \begin{function}[updated = 2011-07-02, TF]{\peek_charcode_remove:N}
+% \begin{function}[updated = 2012-12-20, TF]{\peek_charcode_remove:N}
% \begin{syntax}
% \cs{peek_charcode_remove:NTF} \meta{test token} \Arg{true code} \Arg{false code}
% \end{syntax}
@@ -818,19 +821,20 @@
% appropriate to the result of the test).
% \end{function}
%
-% \begin{function}[updated = 2011-07-02, TF]
+% \begin{function}[updated = 2012-12-20, TF]
% {\peek_charcode_remove_ignore_spaces:N}
% \begin{syntax}
% \cs{peek_charcode_remove_ignore_spaces:NTF} \meta{test token}
% ~~\Arg{true code} \Arg{false code}
% \end{syntax}
-% Tests if the next \meta{token} in the input stream has the same
-% character code as the \meta{test token} (as defined by the test
-% \cs{token_if_eq_charcode:NNTF}). Spaces are ignored by the test
-% and the \meta{token} will be removed from the input stream if the
-% test is true. The function will then place either the
-% \meta{true code} or \meta{false code} in the input stream (as
-% appropriate to the result of the test).
+% Tests if the next non-space \meta{token} in the input stream has the
+% same character code as the \meta{test token} (as defined by the test
+% \cs{token_if_eq_charcode:NNTF}). Explicit and implicit space tokens
+% (with character code 32 and category code 10) are ignored and
+% removed by the test and the \meta{token} will be removed from the
+% input stream if the test is true. The function will then place
+% either the \meta{true code} or \meta{false code} in the input stream
+% (as appropriate to the result of the test).
% \end{function}
%
% \begin{function}[updated = 2011-07-02, TF]{\peek_meaning:N}
@@ -845,16 +849,17 @@
% result of the test).
% \end{function}
%
-% \begin{function}[updated = 2011-07-02, TF]{\peek_meaning_ignore_spaces:N}
+% \begin{function}[updated = 2012-12-05, TF]{\peek_meaning_ignore_spaces:N}
% \begin{syntax}
% \cs{peek_meaning_ignore_spaces:NTF} \meta{test token} \Arg{true code} \Arg{false code}
% \end{syntax}
-% Tests if the next \meta{token} in the input stream has the same
-% meaning as the \meta{test token} (as defined by the test
-% \cs{token_if_eq_meaning:NNTF}). Spaces are ignored by the test
-% and the \meta{token} will be left in the input stream after
-% the \meta{true code} or \meta{false code} (as appropriate to the
-% result of the test).
+% Tests if the next non-space \meta{token} in the input stream has the
+% same meaning as the \meta{test token} (as defined by the test
+% \cs{token_if_eq_meaning:NNTF}). Explicit and implicit space tokens
+% (with character code 32 and category code 10) are ignored and
+% removed by the test and the \meta{token} will be left in the input
+% stream after the \meta{true code} or \meta{false code} (as
+% appropriate to the result of the test).
% \end{function}
%
% \begin{function}[updated = 2011-07-02, TF]{\peek_meaning_remove:N}
@@ -870,19 +875,20 @@
% appropriate to the result of the test).
% \end{function}
%
-% \begin{function}[updated = 2011-07-02, TF]
+% \begin{function}[updated = 2012-12-05, TF]
% {\peek_meaning_remove_ignore_spaces:N}
% \begin{syntax}
% \cs{peek_meaning_remove_ignore_spaces:NTF} \meta{test token}
% ~~\Arg{true code} \Arg{false code}
% \end{syntax}
-% Tests if the next \meta{token} in the input stream has the same
-% meaning as the \meta{test token} (as defined by the test
-% \cs{token_if_eq_meaning:NNTF}). Spaces are ignored by the test
-% and the \meta{token} will be removed from the input stream if the
-% test is true. The function will then place either the
-% \meta{true code} or \meta{false code} in the input stream (as
-% appropriate to the result of the test).
+% Tests if the next non-space \meta{token} in the input stream has the
+% same meaning as the \meta{test token} (as defined by the test
+% \cs{token_if_eq_meaning:NNTF}). Explicit and implicit space tokens
+% (with character code 32 and category code 10) are ignored and
+% removed by the test and the \meta{token} will be removed from the
+% input stream if the test is true. The function will then place
+% either the \meta{true code} or \meta{false code} in the input stream
+% (as appropriate to the result of the test).
% \end{function}
%
% \section{Decomposing a macro definition}
@@ -1852,7 +1858,7 @@
% \end{macro}
%
% \subsection{Peeking ahead at the next token}
-%
+%
% \begin{macrocode}
%<@@=peek>
% \end{macrocode}
@@ -1985,19 +1991,9 @@
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}
-% {\@@_execute_branches_catcode:, \@@_execute_branches_meaning:}
-% The category code and meaning tests are straight forward.
+% \begin{macro}{\@@_execute_branches_meaning:}
+% The meaning test is straight forward.
% \begin{macrocode}
-\cs_new_nopar:Npn \@@_execute_branches_catcode:
- {
- \if_catcode:w
- \exp_not:N \l_peek_token \exp_not:N \l_@@_search_token
- \exp_after:wN \@@_true:w
- \else:
- \exp_after:wN \@@_false:w
- \fi:
- }
\cs_new_nopar:Npn \@@_execute_branches_meaning:
{
\if_meaning:w \l_peek_token \l_@@_search_token
@@ -2009,35 +2005,71 @@
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}{\@@_execute_branches_charcode:}
-% \begin{macro}[aux]{\@@_execute_branches_charcode:NN}
-% First the character code test there is a need to worry about \TeX{}
-% grabbing brace group or skipping spaces. These are all tested for
-% using a category code check before grabbing what must be a real
-% single token and doing the comparison.
+% \begin{macro}{\@@_execute_branches_catcode:, \@@_execute_branches_charcode:}
+% \begin{macro}[aux]
+% {
+% \@@_execute_branches_catcode_aux: ,
+% \@@_execute_branches_catcode_auxii:N ,
+% \@@_execute_branches_catcode_auxiii:
+% }
+% The catcode and charcode tests are very similar, and in order to use
+% the same auxiliaries we do something a little bit odd, firing
+% \cs{if_catcode:w} and \cs{if_charcode:w} before finding the operands
+% for those tests, which will only be given in in the |auxii:N| and
+% |auxiii:| auxiliaries. For our purposes, three kinds of tokens may
+% follow the peeking function:
+% \begin{itemize}
+% \item control sequences which are not equal to a non-active
+% character token (\emph{e.g.}, macro, primitive);
+% \item active characters which are not equal to a non-active
+% character token (\emph{e.g.}, macro, primitive);
+% \item explicit non-active character tokens, or control sequences
+% or active characters set equal to a non-active character token.
+% \end{itemize}
+% The first two cases are not distinguishable simply using \TeX{}'s
+% \tn{futurelet}, because we can only access the \tn{meaning} of
+% tokens in that way. In those cases, detected thanks to a
+% comparison with \cs{scan_stop:}, we grab the following token, and
+% compare it explicitly with the explicit search token stored in
+% \cs{l_@@_search_tl}. The \cs{exp_not:N} prevents outer macros
+% (coming from non-\LaTeX3 code) from blowing up. In the third case,
+% \cs{l_peek_token} is good enough for the test, and we compare it
+% again with the explicit search token. Just like the peek token, the
+% search token may be of any of the three types above, hence the need
+% to use the explicit token that was given to the peek function.
% \begin{macrocode}
+\cs_new_nopar:Npn \@@_execute_branches_catcode:
+ { \if_catcode:w \@@_execute_branches_catcode_aux: }
\cs_new_nopar:Npn \@@_execute_branches_charcode:
+ { \if_charcode:w \@@_execute_branches_catcode_aux: }
+\cs_new_nopar:Npn \@@_execute_branches_catcode_aux:
{
- \bool_if:nTF
- {
- \token_if_eq_catcode_p:NN \l_peek_token \c_group_begin_token
- || \token_if_eq_catcode_p:NN \l_peek_token \c_group_end_token
- || \token_if_eq_meaning_p:NN \l_peek_token \c_space_token
- }
- { \@@_false:w }
- {
- \exp_after:wN \@@_execute_branches_charcode_aux:NN
- \l_@@_search_tl
- }
+ \if_catcode:w \exp_not:N \l_peek_token \scan_stop:
+ \exp_after:wN \exp_after:wN
+ \exp_after:wN \@@_execute_branches_catcode_auxii:N
+ \exp_after:wN \exp_not:N
+ \else:
+ \exp_after:wN \@@_execute_branches_catcode_auxiii:
+ \fi:
}
-\cs_new:Npn \@@_execute_branches_charcode_aux:NN #1#2
+\cs_new:Npn \@@_execute_branches_catcode_auxii:N #1
{
- \if:w \exp_not:N #1 \exp_not:N #2
+ \exp_not:N #1
+ \exp_after:wN \exp_not:N \l_@@_search_tl
+ \exp_after:wN \@@_true:w
+ \else:
+ \exp_after:wN \@@_false:w
+ \fi:
+ #1
+ }
+\cs_new_nopar:Npn \@@_execute_branches_catcode_auxiii:
+ {
+ \exp_not:N \l_peek_token
+ \exp_after:wN \exp_not:N \l_@@_search_tl
\exp_after:wN \@@_true:w
\else:
\exp_after:wN \@@_false:w
\fi:
- #2
}
% \end{macrocode}
% \end{macro}
@@ -2045,17 +2077,23 @@
%
% \begin{macro}{\@@_ignore_spaces_execute_branches:}
% \begin{macro}[aux]{\@@_ignore_spaces_execute_branches_aux:}
-% This function removes one token at a time with a mechanism that can
-% be applied to things other than spaces.
+% This function removes one token at a time with the same mechanism as
+% \cs{@@_true_remove:w}. We directly use the primitive meaning test
+% rather than \cs{token_if_eq_meaning:NNTF} because \cs{l_peek_token}
+% may be an outer macro (coming from non-\LaTeX3 packages). We cannot
+% replace \cs{@@_tmp:w} by \cs{l_peek_token} here because if the
+% latter is an outer macro, it may not appear in the skipped branch of
+% a conditional.
% \begin{macrocode}
\cs_new_protected_nopar:Npn \@@_ignore_spaces_execute_branches:
{
- \token_if_eq_meaning:NNTF \l_peek_token \c_space_token
- {
- \tex_afterassignment:D \@@_ignore_spaces_execute_branches_aux:
- \cs_set_eq:NN \@@_tmp:w
- }
- { \@@_execute_branches: }
+ \if_meaning:w \l_peek_token \c_space_token
+ \tex_afterassignment:D \@@_ignore_spaces_execute_branches_aux:
+ \exp_after:wN \cs_set_eq:NN
+ \exp_after:wN \@@_tmp:w
+ \else:
+ \exp_after:wN \@@_execute_branches:
+ \fi:
}
\cs_new_protected_nopar:Npn \@@_ignore_spaces_execute_branches_aux:
{ \peek_after:Nw \@@_ignore_spaces_execute_branches: }