summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/l3expan.dtx
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2011-09-16 22:35:41 +0000
committerKarl Berry <karl@freefriends.org>2011-09-16 22:35:41 +0000
commit6d95b4a2c1bbdaea1a3802c822808f476ac5703b (patch)
tree1abf9117bf53f2de53fbcc62c352acc92780365b /Master/texmf-dist/source/latex/l3kernel/l3expan.dtx
parentb7f762397f5df2d732326713423e31e1bf91b903 (diff)
l3kernel 2828 (15sep11)
git-svn-id: svn://tug.org/texlive/trunk@23983 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.dtx83
1 files changed, 45 insertions, 38 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3expan.dtx b/Master/texmf-dist/source/latex/l3kernel/l3expan.dtx
index 915e48dec15..ee3d43b91b9 100644
--- a/Master/texmf-dist/source/latex/l3kernel/l3expan.dtx
+++ b/Master/texmf-dist/source/latex/l3kernel/l3expan.dtx
@@ -9,7 +9,7 @@
%%
%% http://www.latex-project.org/lppl.txt
%%
-%% This file is part of the "expl3 bundle" (The Work in LPPL)
+%% This file is part of the "l3kernel bundle" (The Work in LPPL)
%% and all files in that bundle must be distributed together.
%%
%% The released version of this bundle is available from CTAN.
@@ -35,7 +35,7 @@
%
%<*driver|package>
\RequirePackage{l3names}
-\GetIdInfo$Id: l3expan.dtx 2545 2011-08-11 13:47:19Z bruno $
+\GetIdInfo$Id: l3expan.dtx 2812 2011-09-12 09:19:26Z bruno $
{L3 Experimental argument expansion}
%</driver|package>
%<*driver>
@@ -117,8 +117,7 @@
%
% \begin{function}{\cs_generate_variant:Nn}
% \begin{syntax}
-% \cs{cs_generate_variant:Nn} \meta{parent control sequence}
-% ~~\Arg{variant argument specifiers}
+% \cs{cs_generate_variant:Nn} \meta{parent control sequence} \Arg{variant argument specifiers}
% \end{syntax}
% This function is used to define argument-specifier variants of the
% \meta{parent control sequence} for \LaTeX3 code-level macros. The
@@ -203,7 +202,7 @@
% \end{quote}
% Unfortunately this only puts
% |\exp_args:NNc \cs_set_eq:NN \aaa {b \l_tmpa_tl b}| into |\l_tmpb_tl|
-% and not |\cs_set_eq:NwN \aaa = \blurb| as we probably wanted. Using
+% and not |\cs_set_eq:NN \aaa = \blurb| as we probably wanted. Using
% |\tl_set:Nx| is not an option as that will die horribly. Instead
% we can do a
% \begin{quote}
@@ -343,7 +342,7 @@
% by the expansion of the second and third arguments.
% These functions need special (slower) processing.
% \end{function}
-%
+%
% \begin{function}
% {
% \exp_args:NNx,
@@ -375,8 +374,7 @@
% \exp_args:Ncco
% }
% \begin{syntax}
-% \cs{exp_args:NNNo} \meta{token1} \meta{token2} \meta{token3}
-% ~~\Arg{tokens}
+% \cs{exp_args:NNNo} \meta{token1} \meta{token2} \meta{token3} \Arg{tokens}
% \end{syntax}
% These optimized functions absorb four arguments and expand the second, third
% and fourth as detailed by their argument specifier. The first
@@ -393,8 +391,7 @@
% \exp_args:Nooo,
% }
% \begin{syntax}
-% \cs{exp_args:NNNo} \meta{token1} \meta{token2} \meta{token3}
-% ~~\Arg{tokens}
+% \cs{exp_args:NNNo} \meta{token1} \meta{token2} \meta{token3} \Arg{tokens}
% \end{syntax}
% These functions absorb four arguments and expand the second, third
% and fourth as detailed by their argument specifier. The first
@@ -414,8 +411,7 @@
% \exp_args:Nccx
% }
% \begin{syntax}
-% \cs{exp_args:NNnx} \meta{token1} \meta{token2} \meta{tokens1}
-% ~~\Arg{tokens2}
+% \cs{exp_args:NNnx} \meta{token1} \meta{token2} \meta{tokens1} \Arg{tokens2}
% \end{syntax}
% These functions absorb four arguments and expand the second, third
% and fourth as detailed by their argument specifier. The first
@@ -425,7 +421,7 @@
%
% \section{Unbraced expansion}
%
-% \begin{function}
+% \begin{function}[EXP]
% {
% \exp_last_unbraced:Nf,
% \exp_last_unbraced:NV,
@@ -434,6 +430,8 @@
% \exp_last_unbraced:NcV,
% \exp_last_unbraced:NNV,
% \exp_last_unbraced:NNo,
+% \exp_last_unbraced:Nno,
+% \exp_last_unbraced:Noo,
% \exp_last_unbraced:Nfo,
% \exp_last_unbraced:NNNV,
% \exp_last_unbraced:NNNo
@@ -445,9 +443,10 @@
% specification, carry out the expansion
% indicated and leave the the results in the input stream, with the
% last argument not surrounded by the usual braces.
-% Of these, \cs{exp_last_unbraced:Nfo} needs special (slower) processing.
+% Of these, the \texttt{:Nno}, \texttt{:Noo}, and \texttt{:Nfo}
+% variants need special (slower) processing.
% \end{function}
-%
+%
% \begin{function}[EXP]{\exp_last_two_unbraced:Noo}
% \begin{syntax}
% \cs{exp_last_two_unbraced:Noo} \meta{token} \meta{tokens1} \Arg{tokens2}
@@ -474,24 +473,29 @@
% appropriate argument specifier variant or the appropriate
% \cs{exp_arg:N} function.
% \begin{texnote}
-% This is the \TeX{} primitive \cs{expandafter} renamed.
+% This is the \TeX{} primitive \tn{expandafter} renamed.
% \end{texnote}
% \end{function}
%
% \section{Preventing expansion}
%
-% \begin{function}{\exp_not:N}
+% 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
+% after the expansion has completed.
+%
+% \begin{function}[EXP]{\exp_not:N}
% \begin{syntax}
% \cs{exp_not:N} \meta{token}
% \end{syntax}
% Prevents expansion of the \meta{token} in a context where it would otherwise
% be expanded, for example an |x|-type argument.
% \begin{texnote}
-% This is the \TeX{} \cs{noexpand} primitive.
+% This is the \TeX{} \tn{noexpand} primitive.
% \end{texnote}
% \end{function}
%
-% \begin{function}{\exp_not:c}
+% \begin{function}[EXP]{\exp_not:c}
% \begin{syntax}
% \cs{exp_not:c} \Arg{tokens}
% \end{syntax}
@@ -500,7 +504,7 @@
% sequence is then inhibited.
% \end{function}
%
-% \begin{function}{\exp_not:n}
+% \begin{function}[EXP]{\exp_not:n}
% \begin{syntax}
% \cs{exp_not:n} \Arg{tokens}
% \end{syntax}
@@ -508,11 +512,11 @@
% otherwise
% be expanded, for example an |x|-type argument.
% \begin{texnote}
-% This is the \eTeX{} \cs{unexpanded} primitive.
+% This is the \eTeX{} \tn{unexpanded} primitive.
% \end{texnote}
% \end{function}
%
-% \begin{function}{\exp_not:V}
+% \begin{function}[EXP]{\exp_not:V}
% \begin{syntax}
% \cs{exp_not:V} \meta{variable}
% \end{syntax}
@@ -521,7 +525,7 @@
% be expanded, for example an |x|-type argument.
% \end{function}
%
-% \begin{function}{\exp_not:v}
+% \begin{function}[EXP]{\exp_not:v}
% \begin{syntax}
% \cs{exp_not:v} \Arg{tokens}
% \end{syntax}
@@ -532,7 +536,7 @@
% be expanded, for example an |x|-type argument.
% \end{function}
%
-% \begin{function}{\exp_not:o}
+% \begin{function}[EXP]{\exp_not:o}
% \begin{syntax}
% \cs{exp_not:o} \Arg{tokens}
% \end{syntax}
@@ -543,7 +547,7 @@
%
% \begin{function}[EXP]{\exp_not:f}
% \begin{syntax}
-% \cs{exp_not:f} \meta{tokens}
+% \cs{exp_not:f} \Arg{tokens}
% \end{syntax}
% Expands \meta{tokens} fully until the first unexpandable token
% is found. Expansion then stops, and the result of the expansion
@@ -551,7 +555,7 @@
% further expansion.
% \end{function}
%
-% \begin{function}[EXP]{\exp_stop_f:}
+% \begin{function}[updated = 2011-06-03, EXP]{\exp_stop_f:}
% \begin{syntax}
% \cs{function:f} \meta{tokens} \cs{exp_stop_f:} \meta{more tokens}
% \end{syntax}
@@ -578,7 +582,7 @@
% \end{syntax}
% These functions evaluates a \meta{variable} as part of a |V| or |v|
% expansion (respectively), preceeded by \cs{c_zero} which stops
-% the expansion of a previous \cs{tex_romannumeral:D}.
+% the expansion of a previous \tn{romannumeral}.
% A \meta{variable} might exist as
% one of two things: a parameter-less non-long, non-protected macro
% or a built-in \TeX{} register such as |\count|.
@@ -726,7 +730,7 @@
% \begin{macro}{\::f}
% \begin{macro}{\exp_stop_f:}
% This function is used to expand a token list until the first
-% unexpandable token is found. The underlying |\tex_romannumeral:D -`0|
+% unexpandable token is found. The underlying \tn{romannumeral} |-`0|
% expands everything in its way to find something terminating the
% number and thereby expands the function in front of it. This
% scanning procedure is terminated once the expansion hits
@@ -735,9 +739,9 @@
% a number, this number also terminates the scanning and is left
% untouched. In the example shown earlier the scanning was stopped
% once \TeX{} had fully expanded |\cs_set_eq:Nc \aaa { b \l_tmpa_tl b }|
-% into |\cs_set_eq:NwN \aaa = \blurb| which then turned out to contain
-% the non-expandable token |\cs_set_eq:NwN|. Since the expansion of
-% |\tex_romannumeral:D -`0| is \meta{null}, we wind up with a fully
+% into |\cs_set_eq:NN \aaa = \blurb| which then turned out to contain
+% the non-expandable token |\cs_set_eq:NN|. Since the expansion of
+% \tn{romannumeral} |-`0| is \meta{null}, we wind up with a fully
% expanded list, only \TeX{} has not tried to execute any of the
% non-expandable tokens. This is what differentiates this function
% from the |x| argument type.
@@ -770,7 +774,7 @@
% |tl|, |num|, |int|, |skip|, |dim| and |muskip|. The |V| version
% 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 primitive \cs{tex_romannumeral:D} sets off an expansion
+% |V|. The primitive \tn{romannumeral} sets off an expansion
% similar to an |f| type expansion, which we will terminate using
% \cs{c_zero}. The argument is returned in braces.
% \begin{macrocode}
@@ -795,9 +799,9 @@
% This function evaluates a register. Now a register might exist as
% one of two things: A parameter-less macro or a built-in \TeX{}
% register such as |\count|. For the \TeX{} registers we have to
-% utilize a |\tex_the:D| whereas for the macros we merely 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
-% |\tex_the:D| and when not to. What we do here is try to find out
+% \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
% |\exp_after:wN|. The technique is to compare the meaning of the
% register in question when it has been prefixed with |\exp_not:N|
@@ -824,7 +828,7 @@
\fi:
% \end{macrocode}
% The next bit requires some explanation. The function must be
-% initiated by the primitive \cs{tex_romannumeral:D} and we want to
+% initiated by the primitive \tn{romannumeral} and we want to
% terminate this expansion chain by inserting the \cs{c_zero} integer
% constant. However, we have to expand the register |#1| before we do
% that. If it is a \TeX{} register, we need to execute the sequence
@@ -866,7 +870,7 @@
%
% One of the most important features of these functions is that they
% are fully expandable and therefore allow to prefix them with
-% |\pref_global:D| for example.
+% |\tex_global:D| for example.
%
% \begin{macro}{\exp_args:No}
% \begin{macro}{\exp_args:NNo}
@@ -1008,7 +1012,7 @@
}
% \end{macrocode}
% \end{macro}
-%
+%
% \subsection{Definitions with the automated technique}
% \label{sec:gendef}
%
@@ -1119,6 +1123,7 @@
% \begin{macro}{\exp_last_unbraced:NcV}
% \begin{macro}{\exp_last_unbraced:NNV}
% \begin{macro}{\exp_last_unbraced:NNo}
+% \begin{macro}{\exp_last_unbraced:Nno}
% \begin{macro}{\exp_last_unbraced:Noo}
% \begin{macro}{\exp_last_unbraced:Nfo}
% \begin{macro}{\exp_last_unbraced:NNNV}
@@ -1147,6 +1152,7 @@
}
\cs_new:Npn \exp_last_unbraced:NNo #1#2#3
{ \exp_after:wN #1 \exp_after:wN #2 #3 }
+\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:Npn \exp_last_unbraced:NNNV #1#2#3#4
@@ -1170,7 +1176,8 @@
% \end{macro}
% \end{macro}
% \end{macro}
-%
+% \end{macro}
+%
% \begin{macro}{\exp_last_two_unbraced:Noo}
% If |#2| is a single token then this can be implemented as
% \begin{verbatim}