diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3basics.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/l3kernel/l3basics.dtx | 219 |
1 files changed, 130 insertions, 89 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3basics.dtx b/Master/texmf-dist/source/latex/l3kernel/l3basics.dtx index 7730ede1e34..06bb1880b17 100644 --- a/Master/texmf-dist/source/latex/l3kernel/l3basics.dtx +++ b/Master/texmf-dist/source/latex/l3kernel/l3basics.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2019-02-15} +% \date{Released 2019-03-05} % % \maketitle % @@ -163,7 +163,7 @@ % Create a new function with the \texttt{protected} restriction, % such as \cs{cs_set_protected:Npn}. The parameter may contain % \cs{par} tokens but the function will not expand within an -% \texttt{x}-type expansion. +% \texttt{x}-type or \texttt{e}-type expansion. % \end{description} % % Finally, the functions in @@ -244,7 +244,7 @@ % \emph{etc.}) will be replaced by those absorbed by the function. % When the \meta{function} is used the \meta{parameters} absorbed % cannot contain \cs{par} tokens. The \meta{function} will not -% expand within an \texttt{x}-type argument. The definition is global +% expand within an \texttt{x}-type or \texttt{e}-type argument. The definition is global % and an error results if the \meta{function} is already defined. % \end{function} % @@ -289,7 +289,7 @@ % \emph{etc.}) will be replaced by those absorbed by the function. % The assignment of a meaning to the \meta{function} is restricted to % the current \TeX{} group level. The \meta{function} will -% not expand within an \texttt{x}-type argument. +% not expand within an \texttt{x}-type or \texttt{e}-type argument. % \end{function} % % \begin{function} @@ -307,7 +307,7 @@ % cannot contain \cs{par} tokens. The assignment of a meaning % to the \meta{function} is restricted to the current \TeX{} group % level. The \meta{function} will not expand within an -% \texttt{x}-type argument. +% \texttt{x}-type or \texttt{e}-type argument. % \end{function} % % \begin{function}{\cs_gset:Npn, \cs_gset:cpn, \cs_gset:Npx, \cs_gset:cpx} @@ -353,7 +353,7 @@ % The assignment of a meaning to the \meta{function} is \emph{not} % restricted to the current \TeX{} group level: the assignment is % global. The \meta{function} will not expand within an -% \texttt{x}-type argument. +% \texttt{x}-type or \texttt{e}-type argument. % \end{function} % % \begin{function} @@ -441,7 +441,7 @@ % (|#1|, |#2|, \emph{etc.}) will be replaced by those absorbed by the % function. When the \meta{function} is used the \meta{parameters} % absorbed cannot contain \cs{par} tokens. The \meta{function} will not -% expand within an \texttt{x}-type argument. The definition is global and +% expand within an \texttt{x}-type or \texttt{e}-type argument. The definition is global and % an error results if the \meta{function} is already defined. % \end{function} % @@ -512,7 +512,7 @@ % (|#1|, |#2|, \emph{etc.}) will be replaced by those absorbed by the % function. When the \meta{function} is used the \meta{parameters} % absorbed cannot contain \cs{par} tokens. The \meta{function} will not -% expand within an \texttt{x}-type argument. +% expand within an \texttt{x}-type or \texttt{e}-type argument. % The assignment of a meaning to the \meta{function} is restricted to % the current \TeX{} group level. % \end{function} @@ -581,7 +581,7 @@ % (|#1|, |#2|, \emph{etc.}) will be replaced by those absorbed by the % function. When the \meta{function} is used the \meta{parameters} % absorbed cannot contain \cs{par} tokens. The \meta{function} will not -% expand within an \texttt{x}-type argument. +% expand within an \texttt{x}-type or \texttt{e}-type argument. % The assignment of a meaning to the \meta{function} is global. % \end{function} % @@ -794,7 +794,7 @@ % of category code $10$. The result does \emph{not} include % the current escape token, contrarily to \cs{token_to_str:N}. % Full expansion of this function requires exactly $2$ expansion -% steps, and so an \texttt{x}-type expansion, or two +% steps, and so an \texttt{x}-type or \texttt{e}-type expansion, or two % \texttt{o}-type expansions are required to % convert the \meta{control sequence} to a sequence of characters % in the input stream. In most cases, an \texttt{f}-expansion @@ -802,7 +802,7 @@ % of the result. % \end{function} % -% \section{Analysing control sequence names} +% \section{Analysing control sequences} % % \begin{function}[EXP, added = 2018-04-06]{\cs_split_function:N} % \begin{syntax} @@ -819,6 +819,70 @@ % (other). % \end{function} % +% The next three functions decompose \TeX{} macros into their +% constituent parts: if the \meta{token} passed is not a macro then no +% decomposition can occur. In the latter case, all three functions leave +% \cs{scan_stop:} in the input stream. +% +% \begin{function}[EXP, added = 2019-02-27]{\cs_prefix_spec:N} +% \begin{syntax} +% \cs{cs_prefix_spec:N} \meta{token} +% \end{syntax} +% If the \meta{token} is a macro, this function leaves the applicable +% \TeX{} prefixes in input stream as a string of tokens of category +% code $12$ (with spaces having category code $10$). Thus for example +% \begin{verbatim} +% \cs_set:Npn \next:nn #1#2 { x #1~y #2 } +% \cs_prefix_spec:N \next:nn +% \end{verbatim} +% leaves |\long| in the input stream. If the \meta{token} is +% not a macro then \cs{scan_stop:} is left in the input stream. +% \begin{texnote} +% The prefix can be empty, |\long|, |\protected| or +% |\protected\long| with backslash replaced by the current escape +% character. +% \end{texnote} +% \end{function} +% +% \begin{function}[EXP, added = 2019-02-27]{\cs_argument_spec:N} +% \begin{syntax} +% \cs{cs_argument_spec:N} \meta{token} +% \end{syntax} +% If the \meta{token} is a macro, this function leaves the primitive +% \TeX{} argument specification in input stream as a string of +% character tokens of category code $12$ (with spaces having category +% code $10$). Thus for example +% \begin{verbatim} +% \cs_set:Npn \next:nn #1#2 { x #1 y #2 } +% \cs_argument_spec:N \next:nn +% \end{verbatim} +% leaves |#1#2| in the input stream. If the \meta{token} is +% not a macro then \cs{scan_stop:} is left in the input stream. +% \begin{texnote} +% If the argument specification contains the string |->|, then the +% function produces incorrect results. +% \end{texnote} +% \end{function} +% +% \begin{function}[EXP, added = 2019-02-27]{\cs_replacement_spec:N} +% \begin{syntax} +% \cs{cs_replacement_spec:N} \meta{token} +% \end{syntax} +% If the \meta{token} is a macro, this function leaves the replacement +% text in input stream as a string of character tokens of category +% code $12$ (with spaces having category code $10$). Thus for example +% \begin{verbatim} +% \cs_set:Npn \next:nn #1#2 { x #1~y #2 } +% \cs_replacement_spec:N \next:nn +% \end{verbatim} +% leaves \verb*|x#1 y#2| in the input stream. If the \meta{token} is +% not a macro then \cs{scan_stop:} is left in the input stream. +% \begin{texnote} +% If the argument specification contains the string |->|, then the +% function produces incorrect results. +% \end{texnote} +% \end{function} +% % \section{Using or removing tokens and arguments} % % Tokens in the input can be read and used or read and discarded. @@ -1931,8 +1995,7 @@ % \begin{variable}{\g_@@_deprecation_on_tl, \g_@@_deprecation_off_tl} % Some commands were more recently deprecated and not yet removed; % only make these into errors if the user requests it. This relies on -% two token lists, mostly filled up by calls to -% \cs{__kernel_patch_deprecation:nnNNpn} in each module. +% two token lists, filled up in \pkg{l3deprecation}. % \begin{macrocode} \__kernel_if_debug:TF { @@ -1956,82 +2019,6 @@ % \end{macro} % \end{macro} % -% \begin{macro}{\__kernel_patch_deprecation:nnNNpn} -% \begin{macro}{\@@_deprecation_aux:nnNnn} -% Grab a definition (at present, must be \cs{cs_new_protected:Npn} or \cs{cs_new:Npn}). -% Add to \cs{g_@@_deprecation_on_tl} some code that makes the -% defined macro |#3| outer (and defines it as an error). Add to -% \cs{g_@@_deprecation_off_tl} the definition itself. In both -% cases we undefine the token with \cs{tex_let:D} to avoid taking a -% potentially outer macro as the argument of some \pkg{expl3} -% function. Finally, define the macro itself: if it is protected, -% make it produce a warning then redefine and call itself. The macro -% initially takes no parameters: -% together with the \texttt{x}-expanding assignment and \cs{exp_not:n} -% this gives a convenient way of storing the macro's definition in -% itself in order to only produce the warning once for each macro. -% If debugging is disabled, \cs{__kernel_patch_deprecation:nnNNpn} lets the -% definition happen. -% \begin{macrocode} -\__kernel_if_debug:TF - { - \cs_set_protected:Npn \__kernel_patch_deprecation:nnNNpn #1#2#3#4#5# - { - \if_meaning:w \cs_new_protected:Npn #3 - \exp_after:wN \use_i:nn - \else: - \if_meaning:w \cs_new:Npn #3 - \exp_after:wN \exp_after:wN \exp_after:wN \use_ii:nn - \else: - \__kernel_msg_error:nnx { kernel } { debug-unpatchable } - { \token_to_str:N #3 ~(for~deprecation) } - \exp_after:wN \exp_after:wN \exp_after:wN \use_none:nn - \fi: - \fi: - { \@@_deprecation_aux:nnNnn {#1} {#2} #4 {#5} } - { \@@_deprecation_expandable:nnNnn {#1} {#2} #4 {#5} } - } - \cs_set_protected:Npn \@@_deprecation_aux:nnNnn #1#2#3#4#5 - { - \tl_gput_right:Nn \g_@@_deprecation_on_tl - { - \tex_let:D #3 \scan_stop: - \__kernel_deprecation_error:Nnn #3 {#2} {#1} - } - \tl_gput_right:Nn \g_@@_deprecation_off_tl - { - \tex_let:D #3 \scan_stop: - \cs_set_protected:Npn #3 #4 {#5} - } - \cs_new_protected:Npx #3 - { - \exp_not:N \__kernel_msg_warning:nnxxx - { kernel } { deprecated-command } - {#1} { \token_to_str:N #3 } { \tl_to_str:n {#2} } - \exp_not:n { \cs_gset_protected:Npn #3 #4 {#5} } - \exp_not:N #3 - } - } - \cs_set_protected:Npn \@@_deprecation_expandable:nnNnn #1#2#3#4#5 - { - \tl_gput_right:Nn \g_@@_deprecation_on_tl - { - \tex_let:D #3 \scan_stop: - \__kernel_deprecation_error:Nnn #3 {#2} {#1} - } - \tl_gput_right:Nn \g_@@_deprecation_off_tl - { - \tex_let:D #3 \scan_stop: - \cs_set:Npn #3 #4 {#5} - } - \cs_new:Npn #3 #4 {#5} - } - } - { \cs_set_protected:Npn \__kernel_patch_deprecation:nnNNpn #1#2 { } } -% \end{macrocode} -% \end{macro} -% \end{macro} -% % \begin{macro} % {\__kernel_patch:nnNNpn, \__kernel_patch_conditional:nNNpnn} % \begin{macro} @@ -3470,6 +3457,60 @@ % \end{macrocode} % \end{macro} % +% \subsection{Decomposing a macro definition} +% +% \begin{macro}{\cs_prefix_spec:N} +% \begin{macro}{\cs_argument_spec:N} +% \begin{macro}{\cs_replacement_spec:N} +% \begin{macro}{\@@_prefix_arg_replacement:wN} +% We sometimes want to test if a control sequence can be expanded to +% reveal a hidden value. However, we cannot just expand the macro +% blindly as it may have arguments and none might be +% present. Therefore we define these functions to pick either the +% prefix(es), the argument specification, or the replacement text from +% a macro. All of this information is returned as characters with +% catcode~$12$. If the token in question isn't a macro, the token +% \cs{scan_stop:} is returned instead. +% \begin{macrocode} +\use:x + { + \exp_not:n { \cs_new:Npn \@@_prefix_arg_replacement:wN #1 } + \tl_to_str:n { macro : } \exp_not:n { #2 -> #3 \q_stop #4 } + } + { #4 {#1} {#2} {#3} } +\cs_new:Npn \cs_prefix_spec:N #1 + { + \token_if_macro:NTF #1 + { + \exp_after:wN \@@_prefix_arg_replacement:wN + \token_to_meaning:N #1 \q_stop \use_i:nnn + } + { \scan_stop: } + } +\cs_new:Npn \cs_argument_spec:N #1 + { + \token_if_macro:NTF #1 + { + \exp_after:wN \@@_prefix_arg_replacement:wN + \token_to_meaning:N #1 \q_stop \use_ii:nnn + } + { \scan_stop: } + } +\cs_new:Npn \cs_replacement_spec:N #1 + { + \token_if_macro:NTF #1 + { + \exp_after:wN \@@_prefix_arg_replacement:wN + \token_to_meaning:N #1 \q_stop \use_iii:nnn + } + { \scan_stop: } + } +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% % \subsection{Doing nothing functions} % % \begin{macro}[EXP]{\prg_do_nothing:} |