summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/l3expan.dtx
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2017-07-15 21:27:01 +0000
committerKarl Berry <karl@freefriends.org>2017-07-15 21:27:01 +0000
commitb1ce47fe4d0e1f06d1b019c3c6eb5f1b0ecd5e14 (patch)
tree58362abe4b603bb5f6db898b9b835bc8af730b3e /Master/texmf-dist/source/latex/l3kernel/l3expan.dtx
parent03b8dcfa3435f0265dfad4fd09aaab8f4ff9c617 (diff)
l3 (15jul17)
git-svn-id: svn://tug.org/texlive/trunk@44813 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3expan.dtx')
-rw-r--r--Master/texmf-dist/source/latex/l3kernel/l3expan.dtx122
1 files changed, 63 insertions, 59 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3expan.dtx b/Master/texmf-dist/source/latex/l3kernel/l3expan.dtx
index ae03bfb7cb8..c5c7a073aaa 100644
--- a/Master/texmf-dist/source/latex/l3kernel/l3expan.dtx
+++ b/Master/texmf-dist/source/latex/l3kernel/l3expan.dtx
@@ -41,7 +41,7 @@
% }^^A
% }
%
-% \date{Released 2017/05/29}
+% \date{Released 2017/07/15}
%
% \maketitle
%
@@ -68,7 +68,7 @@
% |\exp_| module. They all look alike, an example would be
% \cs{exp_args:NNo}. This function has three arguments, the first and the
% second are a single tokens, while the third argument should be given
-% in braces. Applying \cs{exp_args:NNo} will expand the content of third
+% in braces. Applying \cs{exp_args:NNo} expands the content of third
% argument once before any expansion of the first and second arguments.
% If \cs{seq_gpush:No} was not defined it could be coded in the following way:
% \begin{verbatim}
@@ -118,24 +118,24 @@
% then used to define variants of the
% \meta{original argument specifier} where these are not already
% defined. For each \meta{variant} given, a function is created
-% which will expand its arguments as detailed and pass them
+% which expands its arguments as detailed and passes them
% to the \meta{parent control sequence}. So for example
% \begin{verbatim}
% \cs_set:Npn \foo:Nn #1#2 { code here }
% \cs_generate_variant:Nn \foo:Nn { c }
% \end{verbatim}
-% will create a new function |\foo:cn| which will expand its first
-% argument into a control sequence name and pass the result to
+% creates a new function |\foo:cn| which expands its first
+% argument into a control sequence name and passes the result to
% |\foo:Nn|. Similarly
% \begin{verbatim}
% \cs_generate_variant:Nn \foo:Nn { NV , cV }
% \end{verbatim}
-% would generate the functions |\foo:NV| and |\foo:cV| in the same
+% generates the functions |\foo:NV| and |\foo:cV| in the same
% way. The \cs{cs_generate_variant:Nn} function can only be applied if
% the \meta{parent control sequence} is already defined. Only |n|~and
% |N| arguments can be changed to other types. If the \meta{parent
% control sequence} is protected or if the \meta{variant} involves
-% |x|~arguments, then the \meta{variant control sequence} will also be
+% |x|~arguments, then the \meta{variant control sequence} is also
% protected. The \meta{variant} is created globally, as is any
% \cs[no-index]{exp_args:N\meta{variant}} function needed to carry out the
% expansion.
@@ -157,12 +157,12 @@
% \item
% Arguments that need full expansion (\emph{i.e.}, are denoted
% with |x|) should be avoided if possible as they can not be
-% processed expandably, \emph{i.e.}, functions of this type will
-% not work correctly in arguments that are themselves subject to |x|
+% processed expandably, \emph{i.e.}, functions of this type
+% cannot work correctly in arguments that are themselves subject to |x|
% expansion.
% \item
% In general, unless in the last position, multi-token arguments
-% |n|, |f|, and |o| will need special processing when more than
+% |n|, |f|, and |o| need special processing when more than
% one argument is being expanded. This special processing is not fast.
% Therefore it is best to use the optimized functions, namely
% those that contain only |N|, |c|, |V|, and |v|, and, in the last
@@ -206,7 +206,7 @@
% \begin{quote}
% |\example:f { \int_eval:n { 1 + 2 } , \int_eval:n { 3 + 4 } }|
% \end{quote}
-% will result in the call |\example:n { 3 , \int_eval:n { 3 + 4 } }|
+% results in the call |\example:n { 3 , \int_eval:n { 3 + 4 } }|
% while using |\example:x| instead results in |\example:n { 3 , 7 }|
% at the cost of being protected.
% If you use this type of expansion in conditional processing then
@@ -246,7 +246,7 @@
% the \meta{tokens}). The \meta{tokens} are expanded once, and the result
% is inserted in braces into the input stream \emph{after} reinsertion
% of the \meta{function}. Thus the \meta{function} may take more than
-% one argument: all others will be left unchanged.
+% one argument: all others are left unchanged.
% \end{function}
%
% \begin{function}[EXP]{\exp_args:Nc, \exp_args:cc}
@@ -256,10 +256,10 @@
% This function absorbs two arguments (the \meta{function} name and
% the \meta{tokens}). The \meta{tokens} are expanded until only characters
% remain, and are then turned into a control sequence. (An internal error
-% will occur if such a conversion is not possible). The result
+% occurs if such a conversion is not possible). The result
% is inserted into the input stream \emph{after} reinsertion
% of the \meta{function}. Thus the \meta{function} may take more than
-% one argument: all others will be left unchanged.
+% one argument: all others are left unchanged.
%
% The |:cc| variant constructs the \meta{function} name in the same
% manner as described for the \meta{tokens}.
@@ -273,7 +273,7 @@
% the \meta{variable}). The content of the \meta{variable} are recovered
% and placed inside braces into the input stream \emph{after} reinsertion
% of the \meta{function}. Thus the \meta{function} may take more than
-% one argument: all others will be left unchanged.
+% one argument: all others are left unchanged.
% \end{function}
%
% \begin{function}[EXP]{\exp_args:Nv}
@@ -283,12 +283,12 @@
% This function absorbs two arguments (the \meta{function} name and
% the \meta{tokens}). The \meta{tokens} are expanded until only characters
% remain, and are then turned into a control sequence. (An internal error
-% will occur if such a conversion is not possible). This control sequence
+% occurs if such a conversion is not possible). This control sequence
% should
% be the name of a \meta{variable}. The content of the \meta{variable} are
% recovered and placed inside braces into the input stream \emph{after}
% reinsertion of the \meta{function}. Thus the \meta{function} may take more
-% than one argument: all others will be left unchanged.
+% than one argument: all others are left unchanged.
% \end{function}
%
% \begin{function}[EXP]{\exp_args:Nf}
@@ -300,7 +300,7 @@
% first non-expandable token or space is found, and the result
% is inserted in braces into the input stream \emph{after} reinsertion
% of the \meta{function}. Thus the \meta{function} may take more than
-% one argument: all others will be left unchanged.
+% one argument: all others are left unchanged.
% \end{function}
%
% \begin{function}{\exp_args:Nx}
@@ -312,7 +312,7 @@
% second. The result is inserted in braces into the input stream
% \emph{after} reinsertion of the \meta{function}.
% Thus the \meta{function} may take more
-% than one argument: all others will be left unchanged.
+% than one argument: all others are left unchanged.
% \end{function}
%
% \section{Manipulating two arguments}
@@ -499,10 +499,8 @@
% \cs{exp_after:wN} \meta{token_1} \meta{token_2}
% \end{syntax}
% Carries out a single expansion of \meta{token_2} (which may consume
-% arguments) prior to the expansion
-% of \meta{token_1}. If \meta{token_2} is a \TeX{} primitive, it will
-% be executed rather than expanded, while if \meta{token_2} has not
-% expansion (for example, if it is a character) then it will be left
+% arguments) prior to the expansion of \meta{token_1}. If \meta{token_2} has
+% no expansion (for example, if it is a character) then it is left
% unchanged. It is important to notice that \meta{token_1} may be
% \emph{any} single token, including group-opening and -closing
% tokens (|{| or |}| assuming normal \TeX{} category codes). Unless
@@ -519,7 +517,7 @@
%
% Despite the fact that the following functions are all about preventing
% expansion, they're designed to be used in an expandable context and hence
-% are all marked as being `expandable' since they themselves will not appear
+% are all marked as being `expandable' since they themselves disappear
% after the expansion has completed.
%
% \begin{function}[EXP]{\exp_not:N}
@@ -599,10 +597,10 @@
% \end{syntax}
% This function terminates an \texttt{f}-type expansion. Thus if
% a function |\foo_bar:f| starts an \texttt{f}-type expansion
-% and all of \meta{tokens} are expandable \cs{exp_stop_f:} will
-% terminate the expansion of tokens even if \meta{more tokens}
+% and all of \meta{tokens} are expandable \cs{exp_stop_f:}
+% terminates the expansion of tokens even if \meta{more tokens}
% are also expandable. The function itself is an implicit space
-% token. Inside an \texttt{x}-type expansion, it will retain its
+% token. Inside an \texttt{x}-type expansion, it retains its
% form, but when typeset it produces the underlying space (\verb*| |).
% \end{function}
%
@@ -619,8 +617,8 @@
% Of course, deep down \TeX{} is using expansion as always and there
% are cases where a programmer needs to control that expansion
% directly; typical situations are basic data manipulation tools. This
-% section documents the functions for that level. You will find these
-% commands used throughout the kernel code, but we hope that outside
+% section documents the functions for that level. These
+% commands are used throughout the kernel code, but we hope that outside
% the kernel there will be little need to resort to them. Instead the
% argument manipulation methods document above should usually be sufficient.
%
@@ -649,7 +647,7 @@
% prematurely and as a result \cs{exp_end:} will be misinterpreted
% later on.\footnotemark
%
-% In typical use cases the \cs{exp_end:} will be hidden somewhere
+% In typical use cases the \cs{exp_end:} is hidden somewhere
% in the replacement text of \meta{expandable-tokens} rather than
% being on the same expansion level than \cs{exp:w}, e.g., you may
% see code such as
@@ -672,11 +670,11 @@
% \cs{exp:w} \meta{expandable-tokens} \cs{exp_end_continue_f:w} \meta{further-tokens}
% \end{syntax}
% Expands \meta{expandable-tokens} until reaching \cs{exp_end_continue_f:w} at
-% which point expansion continues as an f-type expansion expanding
+% which point expansion continues as an \texttt{f}-type expansion expanding
% \meta{further-tokens} until an unexpandable token is encountered (or
-% the f-type expansion is explicitly terminated by
-% \cs{exp_stop_f:}). As with all f-type expansions a space ending
-% the expansion will get removed.
+% the \texttt{f}-type expansion is explicitly terminated by
+% \cs{exp_stop_f:}). As with all \texttt{f}-type expansions a space ending
+% the expansion gets removed.
%
% The full expansion of \meta{expandable-tokens} has to be empty.
% If any token in \meta{expandable-tokens} or any token generated by
@@ -701,7 +699,7 @@
% \begin{quote}
% \cs{exp:w} \meta{expandable-tokens} \cs{exp_end:}
% \end{quote}
-% can be alternatively achieved through an f-type expansion by using
+% can be alternatively achieved through an \texttt{f}-type expansion by using
% \cs{exp_stop_f:}, i.e.
% \begin{quote}
% \cs{exp:w} \cs{exp_end_continue_f:w} \meta{expandable-tokens} \cs{exp_stop_f:}
@@ -728,7 +726,7 @@
% \meta{further-tokens} starts with a brace group then the braces
% are removed. If on the other hand it starts with space tokens then
% these space tokens are removed while searching for the
-% argument. Thus such space tokens will not terminate the f-type expansion.
+% argument. Thus such space tokens will not terminate the \texttt{f}-type expansion.
% \end{function}
%
% \section{Internal functions and variables}
@@ -808,7 +806,7 @@
% argument manipulations and |#3| is the current result of the
% expansion chain. This auxiliary function moves |#1| back after
% |#3| in the input stream and checks if any expansion is left to
-% be done by calling |#2|. In by far the most cases we will require
+% be done by calling |#2|. In by far the most cases we need
% to add a set of braces to the result of an argument manipulation
% so it is more effective to do it directly here. Actually, so far
% only the |c| of the final argument manipulation variants does not
@@ -916,7 +914,7 @@
% expects a single token whereas |v| like |c| creates a csname from
% its argument given in braces and then evaluates it as if it was a
% |V|. The \cs{exp:w} sets off an expansion
-% similar to an |f| type expansion, which we will terminate using
+% similar to an |f|-type expansion, which we terminate using
% \cs{exp_end:}. The argument is returned in braces.
% \begin{macrocode}
\cs_new:Npn \::V #1 \::: #2#3
@@ -942,12 +940,12 @@
% register such as |\count|. For the \TeX{} registers we have to
% utilize a \tn{the} whereas for the macros we merely have to
% expand them once. The trick is to find out when to use
-% \tn{the} and when not to. What we do here is try to find out
-% whether the token will expand to something else when hit with
+% \tn{the} and when not to. What we want here is to find out
+% whether the token expands to something else when hit with
% \cs{exp_after:wN}. The technique is to compare the meaning of the
-% register in question when it has been prefixed with \cs{exp_not:N}
-% and the register itself. If it is a macro, the prefixed
-% \cs{exp_not:N} will temporarily turn it into the primitive
+% token in question when it has been prefixed with \cs{exp_not:N}
+% and the token itself. If it is a macro, the prefixed
+% \cs{exp_not:N} temporarily turns it into the primitive
% \cs{scan_stop:}.
% \begin{macrocode}
\cs_new:Npn \@@_eval_register:N #1
@@ -1419,7 +1417,7 @@
% \end{macrocode}
% So to stop the expansion sequence in a controlled way all we need
% to provide is a constant integer zero as part of expanded tokens. As this is
-% an integer constant it will immediately stop
+% an integer constant it immediately stops
% \cs{tex_romannumerl:D}'s search for a number.
% \begin{macrocode}
%\int_const:Nn \exp_end: { 0 }
@@ -1431,10 +1429,10 @@
% generated. Or if we do then the programmer made a mistake.)
%
% If on the other hand we want to stop the initial expansion
-% sequence but continue with an f-type expansion we provide the
+% sequence but continue with an \texttt{f}-type expansion we provide the
% alphabetic constant |`^^@| that also represents |0| but this time
-% \TeX's syntax for a \meta{number} will continue searching for an
-% optional space (and it will continue expansion doing that) ---
+% \TeX's syntax for a \meta{number} continues searching for an
+% optional space (and it continues expansion doing that) ---
% see \TeX{}book page~269 for details.
% \begin{macrocode}
\tex_catcode:D `\^^@=13
@@ -1612,7 +1610,7 @@
% signature} \cs{q_mark} \meta{errors} \cs{q_stop} \meta{base
% function} \meta{new function}. If all went well, \meta{errors}
% is empty; otherwise, it is a kernel error message, followed by
-% some clean-up code (\cs{use_none:nnnn}).
+% some clean-up code (\cs{use_none:nnn}).
%
% Note the space after |#3| and after the following brace group.
% Those are ignored by \TeX{} when fetching the last argument for
@@ -1737,7 +1735,7 @@
\q_mark
\__msg_kernel_error:nnxx { kernel } { variant-too-long }
{#5} { \token_to_str:N #3 }
- \use_none:nnnn
+ \use_none:nnn
\q_stop
#3
#3
@@ -1752,7 +1750,7 @@
\q_mark
\__msg_kernel_error:nnxxxx { kernel } { invalid-variant }
{#7} { \token_to_str:N #5 } {#1} {#2}
- \use_none:nnnn
+ \use_none:nnn
\q_stop
#5
#5
@@ -1783,30 +1781,36 @@
% \end{macro}
%
% \begin{macro}[aux]{\@@_generate_variant:wwNN}
-% If the variant form has already been defined, log its existence.
+% If the variant form has already been defined, log its existence
+% (provided \texttt{log-functions} is active).
% Otherwise, make sure that the |\exp_args:N #3| form is defined, and
% if it contains |x|, change \cs{@@_tmp:w} locally to
% \cs{cs_new_protected:Npx}. Then define the variant by
% combining the |\exp_args:N #3| variant and the base function.
% \begin{macrocode}
+\__debug_patch:nnNw
+ {
+ \cs_if_free:NF #4
+ {
+ \__debug_log:x
+ {
+ Variant~\token_to_str:N #4~%
+ already~defined;~ not~ changing~ it~ \msg_line_context:
+ }
+ }
+ }
+ { }
\cs_new_protected:Npn \@@_generate_variant:wwNN
#1 \q_mark #2 \q_stop #3#4
{
#2
- \cs_if_free:NTF #4
+ \cs_if_free:NT #4
{
\group_begin:
\@@_generate_internal_variant:n {#1}
\@@_tmp:w #4 { \exp_not:c { exp_args:N #1 } \exp_not:N #3 }
\group_end:
}
- {
- \__chk_log:x
- {
- Variant~\token_to_str:N #4~%
- already~defined;~ not~ changing~ it~ \msg_line_context:
- }
- }
}
% \end{macrocode}
% \end{macro}