summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/expl3/l3expan.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/expl3/l3expan.dtx')
-rw-r--r--Master/texmf-dist/source/latex/expl3/l3expan.dtx171
1 files changed, 98 insertions, 73 deletions
diff --git a/Master/texmf-dist/source/latex/expl3/l3expan.dtx b/Master/texmf-dist/source/latex/expl3/l3expan.dtx
index 617e3f27572..1a77ea97d71 100644
--- a/Master/texmf-dist/source/latex/expl3/l3expan.dtx
+++ b/Master/texmf-dist/source/latex/expl3/l3expan.dtx
@@ -36,7 +36,7 @@
\RequirePackage{l3names}
%</driver|package>
%\fi
-\GetIdInfo$Id: l3expan.dtx 1673 2009-11-02 05:40:42Z will $
+\GetIdInfo$Id: l3expan.dtx 1873 2010-03-24 08:32:54Z joseph $
{L3 Experimental Argument Expansion module}
%\iffalse
%<*driver>
@@ -112,26 +112,36 @@
%
% \subsection{Methods for defining variants}
%
-% \begin{function}{\cs_generate_variant:Nn}
-% \begin{syntax}
-% "\cs_generate_variant:Nn" <function> <variant argument>
-% "\cs_generate_variant:Nn " "\foo:Nn" "{c}"
-% "\cs_generate_variant:Nn" "\foo:Nn" "{c,Nx,cx}"
-% \end{syntax}
-% This function greatly simplify the task of defining
-% variantions on a base function with differing expansion control.
-% The first example is equivalent to writing
-% \begin{verbatim}
-% \cs_set_nopar:Npn \foo:cn { \exp_args:Nc \foo:Nn }
-% \end{verbatim}
-% If used with a comma-separated list of variants, it does so for each
-% variant form, i.e., the second example is equivalent to
-% \begin{verbatim}
-% \cs_set_nopar:Npn \foo:cn { \exp_args:Nc \foo:Nn }
-% \cs_set_nopar:Npn \foo:Nx { \exp_args:NNx \foo:Nn }
-% \cs_set_nopar:Npn \foo:cx { \exp_args:Ncx \foo:Nn }
-% \end{verbatim}
-% \end{function}
+%
+%\begin{function}{ \cs_generate_variant:Nn }
+% \begin{syntax}
+% \cs{cs_generate_variant:Nn} \meta{parent control sequence}
+% ~~\Arg{variant argument specifier}
+% \end{syntax}
+% The \meta{parent control sequence} is first separated into the
+% \meta{base name} and \meta{original} argument specifier. The
+% \meta{variant} is then used to modify this by replacing the beginning
+% of the \meta{original} with the \meta{variant}. Thus the \meta{variant}
+% must be no longer than the \meta{original} argument specifier. This
+% new specifier is used to create a modified function which will expand
+% its arguments as required. 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 \cs{foo:cn} which will expand its first
+% argument into a control sequence name and pass the result to
+% \cs{foo:Nn}. Similarly
+% \begin{verbatim}
+% \cs_generate_variant:Nn \foo:Nn { NV }
+% \cs_generate_variant:Nn \foo:Nn { cV }
+% \end{verbatim}
+% would generate the functions \cs{foo:NV} and \cs{foo:cV} in the
+% same way. \cs{cs_generate_variant:Nn} 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.
+%\end{function}
%
% \paragraph{Internal functions} \mbox{}
%
@@ -210,22 +220,6 @@
% try to finish any "\if... \fi:" itself!
%
%
-% \begin{function}{\exp_arg:x}
-% \begin{syntax}
-% "\exp_arg:x" \Arg{arg}
-% \end{syntax}
-% <arg> is expanded fully using an "x" expansion.
-%
-% When pdf\TeX\ 1.50 arrives, it will contain a primitive for
-% performing the equivalent of an "x" expansion after only one
-% expansion and most importantly: as an expandable operation.
-%
-% However, we will not be using the expandable command "\expanded"
-% until it is broadly available; note that as of \TeX~Live~2009,
-% only Lua\TeX\ supports this primitive. Until further notice,
-% "\exp_arg:x" will remain \emph{unexpandable}.
-% \end{function}
-%
%
%
% \section{Manipulating the first argument}
@@ -396,14 +390,14 @@
% \end{function}
%
% \begin{function}{\exp_not:o |
-% \exp_not:d |
% \exp_not:f }
% \begin{syntax}
% "\exp_not:o" \Arg{token list}
% \end{syntax}
% Same as "\exp_not:n" except <token list> is expanded once for the
-% "o" type and twice for the "d" type and the result of this expansion
-% is then prohibited from being expanded further.
+% "o" type and for the "f" type the token list is expanded until an
+% unexpandable token is found, and the result of these expansions is then
+% prohibited from being expanded further.
% \end{function}
%
% \begin{function}{\exp_not:V |
@@ -677,24 +671,15 @@
% \end{macro}
% \end{macro}
%
-% \begin{macro}{\::x,\exp_arg:x}
+% \begin{macro}{\::x}
% This function is used to expand an argument fully.
% We could use the new expandable primitive "\expanded" here, but we
% don't want to create incompatibilities between engines.
% \begin{macrocode}
-%%\cs_new_eq:NN \exp_arg:x \expanded % Move eventually.
-%%\cs_if_free:NTF\exp_arg:x{
- \cs_new:Npn \::x #1 \::: #2#3 {
+ \cs_new_protected:Npn \::x #1 \::: #2#3 {
\cs_set_nopar:Npx \l_exp_tl {{#3}}
\exp_after:wN \exp_arg_next:nnn \l_exp_tl {#1}{#2}
}
-%%}
-%%{
-%% \cs_new:Npn\::x#1\:::#2#3{
-%% \exp_after:wN\exp_arg_next:nnn
-%% \exp_after:wN{\exp_arg:x{#3}}{#1}{#2}
-%% }
-%%}
% \end{macrocode}
% \end{macro}
%
@@ -857,7 +842,7 @@
\cs_set_nopar:Npn \exp_args:Nf {\::f\:::}
\cs_set_nopar:Npn \exp_args:Nv {\::v\:::}
\cs_set_nopar:Npn \exp_args:NV {\::V\:::}
-\cs_set_nopar:Npn \exp_args:Nx {\::x\:::}
+\cs_set_protected_nopar:Npn \exp_args:Nx {\::x\:::}
% \end{macrocode}
% \end{macro}
%
@@ -875,25 +860,25 @@
\cs_set_nopar:Npn \exp_args:NNf {\::N\::f\:::}
\cs_set_nopar:Npn \exp_args:NNv {\::N\::v\:::}
\cs_set_nopar:Npn \exp_args:NNV {\::N\::V\:::}
-\cs_set_nopar:Npn \exp_args:NNx {\::N\::x\:::}
+\cs_set_protected_nopar:Npn \exp_args:NNx {\::N\::x\:::}
-\cs_set_nopar:Npn \exp_args:Ncx {\::c\::x\:::}
+\cs_set_protected_nopar:Npn \exp_args:Ncx {\::c\::x\:::}
\cs_set_nopar:Npn \exp_args:Nfo {\::f\::o\:::}
\cs_set_nopar:Npn \exp_args:Nff {\::f\::f\:::}
\cs_set_nopar:Npn \exp_args:Ncf {\::c\::f\:::}
\cs_set_nopar:Npn \exp_args:Nnf {\::n\::f\:::}
\cs_set_nopar:Npn \exp_args:Nno {\::n\::o\:::}
\cs_set_nopar:Npn \exp_args:NnV {\::n\::V\:::}
-\cs_set_nopar:Npn \exp_args:Nnx {\::n\::x\:::}
+\cs_set_protected_nopar:Npn \exp_args:Nnx {\::n\::x\:::}
\cs_set_nopar:Npn \exp_args:Noc {\::o\::c\:::}
\cs_set_nopar:Npn \exp_args:Noo {\::o\::o\:::}
-\cs_set_nopar:Npn \exp_args:Nox {\::o\::x\:::}
+\cs_set_protected_nopar:Npn \exp_args:Nox {\::o\::x\:::}
\cs_set_nopar:Npn \exp_args:NVV {\::V\::V\:::}
-\cs_set_nopar:Npn \exp_args:Nxo {\::x\::o\:::}
-\cs_set_nopar:Npn \exp_args:Nxx {\::x\::x\:::}
+\cs_set_protected_nopar:Npn \exp_args:Nxo {\::x\::o\:::}
+\cs_set_protected_nopar:Npn \exp_args:Nxx {\::x\::x\:::}
% \end{macrocode}
% \end{macro}
%
@@ -917,23 +902,23 @@
\cs_set_nopar:Npn \exp_args:NNNV {\::N\::N\::V\:::}
\cs_set_nopar:Npn \exp_args:NNno {\::N\::n\::o\:::}
-\cs_set_nopar:Npn \exp_args:NNnx {\::N\::n\::x\:::}
+\cs_set_protected_nopar:Npn \exp_args:NNnx {\::N\::n\::x\:::}
\cs_set_nopar:Npn \exp_args:NNoo {\::N\::o\::o\:::}
-\cs_set_nopar:Npn \exp_args:NNox {\::N\::o\::x\:::}
+\cs_set_protected_nopar:Npn \exp_args:NNox {\::N\::o\::x\:::}
\cs_set_nopar:Npn \exp_args:Nnnc {\::n\::n\::c\:::}
\cs_set_nopar:Npn \exp_args:Nnno {\::n\::n\::o\:::}
-\cs_set_nopar:Npn \exp_args:Nnnx {\::n\::n\::x\:::}
-\cs_set_nopar:Npn \exp_args:Nnox {\::n\::o\::x\:::}
+\cs_set_protected_nopar:Npn \exp_args:Nnnx {\::n\::n\::x\:::}
+\cs_set_protected_nopar:Npn \exp_args:Nnox {\::n\::o\::x\:::}
\cs_set_nopar:Npn \exp_args:NcNc {\::c\::N\::c\:::}
\cs_set_nopar:Npn \exp_args:NcNo {\::c\::N\::o\:::}
\cs_set_nopar:Npn \exp_args:Ncco {\::c\::c\::o\:::}
\cs_set_nopar:Npn \exp_args:Ncco {\::c\::c\::o\:::}
-\cs_set_nopar:Npn \exp_args:Nccx {\::c\::c\::x\:::}
-\cs_set_nopar:Npn \exp_args:Ncnx {\::c\::n\::x\:::}
+\cs_set_protected_nopar:Npn \exp_args:Nccx {\::c\::c\::x\:::}
+\cs_set_protected_nopar:Npn \exp_args:Ncnx {\::c\::n\::x\:::}
-\cs_set_nopar:Npn \exp_args:Noox {\::o\::o\::x\:::}
+\cs_set_protected_nopar:Npn \exp_args:Noox {\::o\::o\::x\:::}
\cs_set_nopar:Npn \exp_args:Nooo {\::o\::o\::o\:::}
% \end{macrocode}
% \end{macro}
@@ -943,15 +928,11 @@
%
%
% \begin{macro}{\exp_not:o}
-% \begin{macro}{\exp_not:d}
% \begin{macro}{\exp_not:f}
% \begin{macro}{\exp_not:v}
% \begin{macro}{\exp_not:V}
% \begin{macrocode}
\cs_new:Npn\exp_not:o#1{\exp_not:n\exp_after:wN{#1}}
-\cs_new:Npn\exp_not:d#1{
- \exp_not:n\exp_after:wN\exp_after:wN\exp_after:wN{#1}
-}
\cs_new:Npn\exp_not:f#1{
\exp_not:n\exp_after:wN{\tex_romannumeral:D -`0 #1}
}
@@ -966,7 +947,6 @@
% \end{macro}
% \end{macro}
% \end{macro}
-% \end{macro}
%
% \begin{macro}{\exp_not:c}
% A helper function.
@@ -995,7 +975,7 @@
% signature. For example, for a base function "\tl_set:Nn" which
% needs a "c" variant form, we want the new signature to be "cn".
% \begin{macrocode}
-\cs_new:Npn \cs_generate_variant:Nn #1 {
+\cs_new_protected:Npn \cs_generate_variant:Nn #1 {
\chk_if_exist_cs:N #1
\cs_split_function:NN #1 \cs_generate_variant_aux:nnNn
}
@@ -1033,7 +1013,8 @@
% If not, then define it and then additionally check if
% the |\exp_args:N| form needed is defined.
% \begin{macrocode}
- \cs_new_nopar:cpx {
+ \_cs_generate_variant_aux:ccpx { #1 : #2 }
+ {
#1:#3 \use:c{use_none:\cs_generate_variant_aux:N #3 ?}#2
}
{
@@ -1069,6 +1050,50 @@
% \end{macro}
% \end{macro}
% \end{macro}
+%
+%\begin{macro}[aux]{\_cs_generate_variant_aux:Ncpx}
+%\begin{macro}[aux]{\_cs_generate_variant_aux:ccpx}
+%\begin{macro}[aux]{\_cs_generate_variant_aux:w}
+% The idea here is to pick up protected parent functions, using the
+% nature of the meaning string that they generate. The test here is
+% almost the same as \cs{tl_if_empty:nTF}, but has to be hard-coded as
+% that function is not yet available and because it has to match both
+% long and short macros.
+% \begin{macrocode}
+\group_begin:
+ \tex_lccode:D `\Z = `\d \scan_stop:
+ \tex_lccode:D `\? =`\\ \scan_stop:
+ \tex_catcode:D `\P = 12 \scan_stop:
+ \tex_catcode:D `\R = 12 \scan_stop:
+ \tex_catcode:D `\O = 12 \scan_stop:
+ \tex_catcode:D `\T = 12 \scan_stop:
+ \tex_catcode:D `\E = 12 \scan_stop:
+ \tex_catcode:D `\C = 12 \scan_stop:
+ \tex_catcode:D `\Z = 12 \scan_stop:
+\tex_lowercase:D {
+ \group_end:
+ \cs_new_nopar:Npn \_cs_generate_variant_aux:Ncpx #1
+ {
+ \exp_after:wN \_cs_generate_variant_aux:w
+ \tex_meaning:D #1 ? PROTECTEZ \q_nil
+ }
+ \cs_new_nopar:Npn \_cs_generate_variant_aux:ccpx
+ { \exp_args:Nc \_cs_generate_variant_aux:Ncpx}
+ \cs_new:Npn \_cs_generate_variant_aux:w
+ #1 ? PROTECTEZ #2 \q_nil
+ {
+ \exp_after:wN \tex_ifx:D \exp_after:wN
+ \q_nil \etex_detokenize:D {#1} \q_nil
+ \exp_after:wN \cs_new_protected_nopar:cpx
+ \tex_else:D
+ \exp_after:wN \cs_new_nopar:cpx
+ \tex_fi:D
+ }
+}
+% \end{macrocode}
+%\end{macro}
+%\end{macro}
+%\end{macro}
%
%
% \begin{macro}{\cs_generate_internal_variant:n}
@@ -1076,7 +1101,7 @@
% and if not define it via the
% |\::| commands using the chars in |#1|
% \begin{macrocode}
-\cs_new:Npn \cs_generate_internal_variant:n #1 {
+\cs_new_protected:Npn \cs_generate_internal_variant:n #1 {
\cs_if_free:cT { exp_args:N #1 }{
% \end{macrocode}
% We use "new" to log the definition if we have to make one.