summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/l3basics.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3basics.dtx')
-rw-r--r--Master/texmf-dist/source/latex/l3kernel/l3basics.dtx219
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:}