diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3expan.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/l3kernel/l3expan.dtx | 157 |
1 files changed, 82 insertions, 75 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3expan.dtx b/Master/texmf-dist/source/latex/l3kernel/l3expan.dtx index c96720f149b..ba6f3b4eb7a 100644 --- a/Master/texmf-dist/source/latex/l3kernel/l3expan.dtx +++ b/Master/texmf-dist/source/latex/l3kernel/l3expan.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -%% File: l3expan.dtx Copyright (C) 1990-2015 The LaTeX3 project +%% File: l3expan.dtx Copyright (C) 1990-2016 The LaTeX3 project %% %% It may be distributed and/or modified under the conditions of the %% LaTeX Project Public License (LPPL), either version 1.3c of this @@ -37,7 +37,7 @@ \documentclass[full]{l3doc} %</driver> %<*driver|package> -\GetIdInfo$Id: l3expan.dtx 5983 2015-09-10 18:57:56Z joseph $ +\GetIdInfo$Id: l3expan.dtx 6684 2016-08-19 15:21:49Z bruno $ {L3 Argument expansion} %</driver|package> %<*driver> @@ -105,11 +105,15 @@ % how the variants are defined. They just expand into the appropriate % |\exp_| function followed by the desired base function, \emph{e.g.} % \begin{quote} -% |\cs_new_nopar:Npn \seq_gpush:No { \exp_args:NNo \seq_gpush:Nn }| +% |\cs_generate_variant:Nn \seq_gpush:Nn { No } | +% \end{quote} +% results in the definition of |\seq_gpush:No| +% \begin{quote} +% |\cs_new:Npn \seq_gpush:No { \exp_args:NNo \seq_gpush:Nn }| % \end{quote} % Providing variants in this way in style files is uncritical as the -% \cs{cs_new_nopar:Npn} function will silently accept definitions whenever the -% new definition is identical to an already given one. Therefore adding +% \cs{cs_generate_variant:Nn} function will only create new definitions if +% there is not already one available. Therefore adding % such definition to later releases of the kernel will not make such % style files obsolete. % @@ -119,6 +123,10 @@ % \section{Methods for defining variants} % \label{sec:l3expan:variants-method} % +% ^^A Bruno: Should we put a table of variant types (N, c, n, V, v, o, f, x) for reference here? +% +% ^^A Bruno: Should \cs_generate_variant:Nn \foo:n { c } and \foo:N { o } really be ok? +% % \begin{function}[updated = 2015-08-06]{\cs_generate_variant:Nn} % \begin{syntax} % \cs{cs_generate_variant:Nn} \meta{parent control sequence} \Arg{variant argument specifiers} @@ -143,19 +151,22 @@ % \begin{verbatim} % \cs_generate_variant:Nn \foo:Nn { NV , cV } % \end{verbatim} -% would generate 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. If -% the \meta{parent control sequence} is protected then the new sequence -% will also be protected. The \meta{variant} is created globally, as -% is any \cs{exp_args:N\meta{variant}} function needed to carry out -% the expansion. +% would generate 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 +% protected. The \meta{variant} is created globally, as is any +% \cs{exp_args:N\meta{variant}} function needed to carry out the +% expansion. % \end{function} % % \section{Introducing the variants} % % The available internal functions for argument expansion come in two -% flavours, some of them are faster then others. Therefore it is usually +% flavours, some of them are faster then others. Therefore +% (when speed is important) it is usually % best to follow the following guidelines when defining new functions % that are supposed to come with variant forms: % \begin{itemize} @@ -180,15 +191,11 @@ % not expanded. % \end{itemize} % -% ^^A Bruno: We should drop part of that paragraph eventually. % The |V| type returns the value of a register, which can be one of -% |tl|, |num|, |int|, |skip|, |dim|, |toks|, or built-in \TeX{} +% |tl|, |int|, |skip|, |dim|, |toks|, or built-in \TeX{} % registers. The |v| type is the same except it first creates a % control sequence out of its argument before returning the -% value. This recent addition to the argument specifiers may shake -% things up a bit as most places where |o| is used will be replaced by -% |V|. The documentation you are currently reading will therefore -% require a fair bit of re-writing. +% value. % % In general, the programmer should not need to be concerned with % expansion control. When simply using the content of a variable, @@ -238,13 +245,13 @@ % At the same time, \texttt{f}-type expansion stops at the emph{first} % non-expandable token. This means for example that both % \begin{verbatim} -% \tl_set:No \l_tmpa_tl { { \l_tmpa_tl } } +% \tl_set:No \l_tmpa_tl { { \g_tmpb_tl } } % \end{verbatim} % and % \begin{verbatim} -% \tl_set:Nf \l_tmpa_tl { { \l_tmpa_tl } } +% \tl_set:Nf \l_tmpa_tl { { \g_tmpb_tl } } % \end{verbatim} -% leave |\l_tmpa_tl| unchanged: |{| is the first token in the +% leave |\g_tmpb_tl| unchanged: |{| is the first token in the % argument and is non-expandable. % % \section{Manipulating the first argument} @@ -455,8 +462,8 @@ % % \begin{function}[EXP, updated = 2012-02-12] % { -% \exp_last_unbraced:Nf, % \exp_last_unbraced:NV, +% \exp_last_unbraced:Nf, % \exp_last_unbraced:No, % \exp_last_unbraced:Nv, % \exp_last_unbraced:Nco, @@ -625,7 +632,7 @@ % % The \pkg{expl3} language makes all efforts to hide the complexity of % \TeX{} expansion from the programmer by providing concepts that -% evaluate/expand arguments of functions prior to calling the ``base'' +% evaluate/expand arguments of functions prior to calling the \enquote{base} % functions. Thus, instead of using many \tn{expandafter} calls and % other trickery it is usually a matter of choosing the right variant % of a function to achieve a desired result. @@ -674,10 +681,10 @@ % \cs{exp_end:} gets generated. % \end{function} % \footnotetext{Due to the implementation you might get the character -% in position 0 in the current font (typically ``\texttt`'') +% in position 0 in the current font (typically \enquote{\texttt{`}}) % in the output without any error message!} % -% \begin{function}[added=2015-08-23,EXP] +% \begin{function}[added=2015-08-23, EXP, label = \exp_end_continue_f:w] % { % \exp:w , % \exp_end_continue_f:w @@ -729,7 +736,7 @@ % \footnotetext{In this particular case you may get a character into % the output as well as an error message.} % -% \begin{function}[added=2015-08-23,EXP] +% \begin{function}[added=2015-08-23, EXP, label = \exp_end_continue_f:nw] % { % \exp:w , % \exp_end_continue_f:nw @@ -755,7 +762,7 @@ % % \begin{function}{\::n, \::N, \::p, \::c, \::o, \::f, \::x, \::v, \::V, \:::} % \begin{syntax} -% |\cs_set_nopar:Npn \exp_args:Ncof { \::c \::o \::f \::: }| +% |\cs_set:Npn \exp_args:Ncof { \::c \::o \::f \::: }| % \end{syntax} % Internal forms for the base expansion types. These names do \emph{not} % conform to the general \LaTeX3 approach as this makes them more readily @@ -789,7 +796,7 @@ % In this section a general mechanism for defining functions to handle % argument handling is defined. These general expansion functions are % expandable unless |x| is used. (Any version of |x| is going to have -% to use one of the \LaTeX3 names for \cs{cs_set_nopar:Npx} at some +% to use one of the \LaTeX3 names for \cs{cs_set:Npx} at some % point, and so is never going to be expandable.) % % The definition of expansion functions with this technique happens @@ -1180,7 +1187,7 @@ % % \begin{macro}{\exp_args:Nx} % \begin{macrocode} -\cs_new_protected_nopar:Npn \exp_args:Nx { \::x \::: } +\cs_new_protected:Npn \exp_args:Nx { \::x \::: } % \end{macrocode} % \end{macro} % @@ -1198,21 +1205,21 @@ % Here are the actual function definitions, using the helper functions % above. % \begin{macrocode} -\cs_new_nopar:Npn \exp_args:Nnc { \::n \::c \::: } -\cs_new_nopar:Npn \exp_args:Nfo { \::f \::o \::: } -\cs_new_nopar:Npn \exp_args:Nff { \::f \::f \::: } -\cs_new_nopar:Npn \exp_args:Nnf { \::n \::f \::: } -\cs_new_nopar:Npn \exp_args:Nno { \::n \::o \::: } -\cs_new_nopar:Npn \exp_args:NnV { \::n \::V \::: } -\cs_new_nopar:Npn \exp_args:Noo { \::o \::o \::: } -\cs_new_nopar:Npn \exp_args:Nof { \::o \::f \::: } -\cs_new_nopar:Npn \exp_args:Noc { \::o \::c \::: } -\cs_new_protected_nopar:Npn \exp_args:NNx { \::N \::x \::: } -\cs_new_protected_nopar:Npn \exp_args:Ncx { \::c \::x \::: } -\cs_new_protected_nopar:Npn \exp_args:Nnx { \::n \::x \::: } -\cs_new_protected_nopar:Npn \exp_args:Nox { \::o \::x \::: } -\cs_new_protected_nopar:Npn \exp_args:Nxo { \::x \::o \::: } -\cs_new_protected_nopar:Npn \exp_args:Nxx { \::x \::x \::: } +\cs_new:Npn \exp_args:Nnc { \::n \::c \::: } +\cs_new:Npn \exp_args:Nfo { \::f \::o \::: } +\cs_new:Npn \exp_args:Nff { \::f \::f \::: } +\cs_new:Npn \exp_args:Nnf { \::n \::f \::: } +\cs_new:Npn \exp_args:Nno { \::n \::o \::: } +\cs_new:Npn \exp_args:NnV { \::n \::V \::: } +\cs_new:Npn \exp_args:Noo { \::o \::o \::: } +\cs_new:Npn \exp_args:Nof { \::o \::f \::: } +\cs_new:Npn \exp_args:Noc { \::o \::c \::: } +\cs_new_protected:Npn \exp_args:NNx { \::N \::x \::: } +\cs_new_protected:Npn \exp_args:Ncx { \::c \::x \::: } +\cs_new_protected:Npn \exp_args:Nnx { \::n \::x \::: } +\cs_new_protected:Npn \exp_args:Nox { \::o \::x \::: } +\cs_new_protected:Npn \exp_args:Nxo { \::x \::o \::: } +\cs_new_protected:Npn \exp_args:Nxx { \::x \::x \::: } % \end{macrocode} % \end{macro} % \end{macro} @@ -1229,19 +1236,19 @@ % \exp_args:Nccx, \exp_args:Ncnx, \exp_args:Noox, % } % \begin{macrocode} -\cs_new_nopar:Npn \exp_args:NNno { \::N \::n \::o \::: } -\cs_new_nopar:Npn \exp_args:NNoo { \::N \::o \::o \::: } -\cs_new_nopar:Npn \exp_args:Nnnc { \::n \::n \::c \::: } -\cs_new_nopar:Npn \exp_args:Nnno { \::n \::n \::o \::: } -\cs_new_nopar:Npn \exp_args:Nooo { \::o \::o \::o \::: } -\cs_new_protected_nopar:Npn \exp_args:NNNx { \::N \::N \::x \::: } -\cs_new_protected_nopar:Npn \exp_args:NNnx { \::N \::n \::x \::: } -\cs_new_protected_nopar:Npn \exp_args:NNox { \::N \::o \::x \::: } -\cs_new_protected_nopar:Npn \exp_args:Nnnx { \::n \::n \::x \::: } -\cs_new_protected_nopar:Npn \exp_args:Nnox { \::n \::o \::x \::: } -\cs_new_protected_nopar:Npn \exp_args:Nccx { \::c \::c \::x \::: } -\cs_new_protected_nopar:Npn \exp_args:Ncnx { \::c \::n \::x \::: } -\cs_new_protected_nopar:Npn \exp_args:Noox { \::o \::o \::x \::: } +\cs_new:Npn \exp_args:NNno { \::N \::n \::o \::: } +\cs_new:Npn \exp_args:NNoo { \::N \::o \::o \::: } +\cs_new:Npn \exp_args:Nnnc { \::n \::n \::c \::: } +\cs_new:Npn \exp_args:Nnno { \::n \::n \::o \::: } +\cs_new:Npn \exp_args:Nooo { \::o \::o \::o \::: } +\cs_new_protected:Npn \exp_args:NNNx { \::N \::N \::x \::: } +\cs_new_protected:Npn \exp_args:NNnx { \::N \::n \::x \::: } +\cs_new_protected:Npn \exp_args:NNox { \::N \::o \::x \::: } +\cs_new_protected:Npn \exp_args:Nnnx { \::n \::n \::x \::: } +\cs_new_protected:Npn \exp_args:Nnox { \::n \::o \::x \::: } +\cs_new_protected:Npn \exp_args:Nccx { \::c \::c \::x \::: } +\cs_new_protected:Npn \exp_args:Ncnx { \::c \::n \::x \::: } +\cs_new_protected:Npn \exp_args:Noox { \::o \::o \::x \::: } % \end{macrocode} % \end{macro} % \end{macro} @@ -1338,11 +1345,11 @@ } \cs_new:Npn \exp_last_unbraced:NNNo #1#2#3#4 { \exp_after:wN #1 \exp_after:wN #2 \exp_after:wN #3 #4 } -\cs_new_nopar:Npn \exp_last_unbraced:Nno { \::n \::o_unbraced \::: } -\cs_new_nopar:Npn \exp_last_unbraced:Noo { \::o \::o_unbraced \::: } -\cs_new_nopar:Npn \exp_last_unbraced:Nfo { \::f \::o_unbraced \::: } -\cs_new_nopar:Npn \exp_last_unbraced:NnNo { \::n \::N \::o_unbraced \::: } -\cs_new_protected_nopar:Npn \exp_last_unbraced:Nx { \::x_unbraced \::: } +\cs_new:Npn \exp_last_unbraced:Nno { \::n \::o_unbraced \::: } +\cs_new:Npn \exp_last_unbraced:Noo { \::o \::o_unbraced \::: } +\cs_new:Npn \exp_last_unbraced:Nfo { \::f \::o_unbraced \::: } +\cs_new:Npn \exp_last_unbraced:NnNo { \::n \::N \::o_unbraced \::: } +\cs_new_protected:Npn \exp_last_unbraced:Nx { \::x_unbraced \::: } % \end{macrocode} % \end{macro} % \end{macro} @@ -1414,7 +1421,7 @@ % \begin{macro}{\exp_end_continue_f:w} % \begin{macro}{\exp_end_continue_f:nw} % -% To trigger a sequence of ``arbitrary'' many expansions we need a +% To trigger a sequence of \enquote{arbitrary} many expansions we need a % method to invoke \TeX's expansion mechanism in such a way that a) % we are able to stop it in a controlled manner and b) that the % result of what triggered the expansion in the first place is @@ -1441,7 +1448,7 @@ % (Note that according to our specification all tokens we expand % initiated by \cs{exp:w} are supposed to be expandable (as well as % their replacement text in the expansion) so we will not encounter -% a ``number'' that actually result in a roman numeral being +% a \enquote{number} that actually result in a roman numeral being % generated. Or if we do then the programmer made a mistake.) % % If on the other hand we want to stop the initial expansion @@ -1485,7 +1492,7 @@ % \end{arguments} % After making sure that the base form exists, test whether it is % protected or not and define \cs{@@_tmp:w} as either -% \cs{cs_new_nopar:Npx} or \cs{cs_new_protected_nopar:Npx}, which is +% \cs{cs_new:Npx} or \cs{cs_new_protected:Npx}, which is % then used to define all the variants (except those involving % \texttt{x}-expansion, always protected). Split up the original base % function only once, to grab its name and signature. Then we wish to @@ -1526,21 +1533,21 @@ % |\bot|, |\splittop|, or |\splitbot|, with |\| replaced by the % appropriate escape character. If |pr| appears in the part before % |ma|, the first \cs{q_mark} is taken as an argument of the |wwNw| -% auxiliary, and |#3| is \cs{cs_new_protected_nopar:Npx}, otherwise it -% is \cs{cs_new_nopar:Npx}. +% auxiliary, and |#3| is \cs{cs_new_protected:Npx}, otherwise it +% is \cs{cs_new:Npx}. % \begin{macrocode} \cs_new_protected:Npx \@@_generate_variant:N #1 { \exp_not:N \exp_after:wN \exp_not:N \if_meaning:w \exp_not:N \exp_not:N #1 #1 - \cs_set_eq:NN \exp_not:N \@@_tmp:w \cs_new_protected_nopar:Npx + \cs_set_eq:NN \exp_not:N \@@_tmp:w \cs_new_protected:Npx \exp_not:N \else: \exp_not:N \exp_after:wN \exp_not:N \@@_generate_variant:ww \exp_not:N \token_to_meaning:N #1 \tl_to_str:n { ma } \exp_not:N \q_mark - \exp_not:N \q_mark \cs_new_protected_nopar:Npx + \exp_not:N \q_mark \cs_new_protected:Npx \tl_to_str:n { pr } - \exp_not:N \q_mark \cs_new_nopar:Npx + \exp_not:N \q_mark \cs_new:Npx \exp_not:N \q_stop \exp_not:N \fi: } @@ -1800,7 +1807,7 @@ % If the variant form has already been defined, log its existence. % 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_nopar:Npx}. Then define the variant by +% \cs{cs_new_protected:Npx}. Then define the variant by % combining the |\exp_args:N #3| variant and the base function. % \begin{macrocode} \cs_new_protected:Npn \@@_generate_variant:wwNN @@ -1839,11 +1846,11 @@ { \exp_not:N \@@_generate_internal_variant:wwnNwnn #1 \exp_not:N \q_mark - { \cs_set_eq:NN \exp_not:N \@@_tmp:w \cs_new_protected_nopar:Npx } - \cs_new_protected_nopar:cpx + { \cs_set_eq:NN \exp_not:N \@@_tmp:w \cs_new_protected:Npx } + \cs_new_protected:cpx \token_to_str:N x \exp_not:N \q_mark { } - \cs_new_nopar:cpx + \cs_new:cpx \exp_not:N \q_stop { exp_args:N #1 } { |