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