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