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