% \iffalse meta-comment % %% File: l3expan.dtx Copyright (C) 1990-2011 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 %% license or (at your option) any later version. The latest version %% of this license is in the file %% %% http://www.latex-project.org/lppl.txt %% %% 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. %% %% ----------------------------------------------------------------------- %% %% The development version of the bundle can be found at %% %% http://www.latex-project.org/svnroot/experimental/trunk/ %% %% for those people who are interested. %% %%%%%%%%%%% %% NOTE: %% %%%%%%%%%%% %% %% Snapshots taken from the repository represent work in progress and may %% not work or may contain conflicting material! We therefore ask %% people _not_ to put them into distributions, archives, etc. without %% prior consultation with the LaTeX3 Project. %% %% ----------------------------------------------------------------------- % %<*driver|package> \RequirePackage{l3names} \GetIdInfo$Id: l3expan.dtx 3086 2011-12-22 17:55:46Z bruno $ {L3 Experimental argument expansion} % %<*driver> \documentclass[full]{l3doc} \begin{document} \DocInput{\jobname.dtx} \end{document} % % \fi % % \title{^^A % The \pkg{l3expan} package\\ Argument expansion^^A % \thanks{This file describes v\ExplFileVersion, % last revised \ExplFileDate.}^^A % } % % \author{^^A % The \LaTeX3 Project\thanks % {^^A % E-mail: % \href{mailto:latex-team@latex-project.org} % {latex-team@latex-project.org}^^A % }^^A % } % % \date{Released \ExplFileDate} % % \maketitle % % \begin{documentation} % % This module provides generic methods for expanding \TeX{} arguments in a % systematic manner. The functions in this module all have prefix |exp|. % % Not all possible variations are implemented for every base % function. Instead only those that are used within the \LaTeX3 kernel % or otherwise seem to be of general interest are implemented. % Consult the module description to find out which functions are % actually defined. The next section explains how to define missing % variants. % % \section{Defining new variants} % % The definition of variant forms for base functions may be necessary % when writing new functions or when applying a kernel function in a % situation that we haven't thought of before. % % Internally preprocessing of arguments is done with functions from the % |\exp_| module. They all look alike, an example would be % |\exp_args:NNo|. This function has three arguments, the first and the % second are a single tokens the third argument gets % expanded once. If |\seq_gpush:No| was not defined the example % above could be coded in the following way: % \begin{verbatim} % \exp_args:NNo \seq_gpush:Nn % \g_file_name_stack % \l_tmpa_tl % \end{verbatim} % In other words, the first argument to |\exp_args:NNo| is the base % function and the other arguments are preprocessed and then passed to % this base function. In the example the first argument to the base % function should be a single token which is left unchanged while the % second argument is expanded once. From this example we can also see % 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}| % \end{quote} % Providing variants in this way in style files is uncritical as the % |\cs_new_nopar:Npn| function will silently accept definitions whenever the % new definition is identical to an already given one. Therefore adding % such definition to later releases of the kernel will not make such % style files obsolete. % % The steps above may be automated by using the function % |\cs_generate_variant:Nn|, described next. % % \section{Methods for defining variants} % % \begin{function}[updated = 2011-09-15]{\cs_generate_variant:Nn} % \begin{syntax} % \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 % \meta{parent control sequence} is first separated into the % \meta{base name} and \meta{original argument specifier}. The % comma-separated list of \meta{variant argument specifiers} is % 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 % 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 \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 , cV } % \end{verbatim} % would generate the functions \cs{foo:NV} and \cs{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. % \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 % best to follow the following guidelines when defining new functions % that are supposed to come with variant forms: % \begin{itemize} % \item % Arguments that might need expansion should come first in the list of % arguments to make processing faster. % \item % Arguments that should consist of single tokens should come first. % \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 itself subject to |x| % expansion. % \item % In general, unless in the last position, multi-token arguments % |n|, |f|, and |o| will need special processing which 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 % position, |o|, |f|, with possible trailing |N| or |n|, which are % not expanded. % \end{itemize} % % The |V| type returns the value of a register, which can be one of % |tl|, |num|, |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. % % In general, the programmer should not need to be concerned with % expansion control. When simply using the content of a variable, % functions with a |V| specifier should be used. For those referred to by % (cs)name, the |v| specifier is available for the same purpose. Only when % specific expansion steps are needed, such as when using delimited % arguments, should the lower-level functions with |o| specifiers be employed. % % The |f| type is so special that it deserves an example. % Let's pretend we want to set |\aaa| equal to the control sequence % stemming from turning |b \l_tmpa_tl b| into a control % sequence. Furthermore we want to store the execution of it in a % \meta{tl~var}. In this example we assume |\l_tmpa_tl| contains % the text string |lur|. The straightforward approach is % \begin{quote} % |\tl_set:No \l_tmpb_tl {\cs_set_eq:Nc \aaa { b \l_tmpa_tl b } }| % \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: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} % |\tl_set:Nf \l_tmpb_tl {\cs_set_eq:Nc \aaa { b \l_tmpa_tl b } }| % \end{quote} % which puts the desired result in |\l_tmpb_tl|. It requires % |\toks_set:Nf| to be defined as % \begin{quote} % |\cs_set_nopar:Npn \tl_set:Nf { \exp_args:NNf \tl_set:Nn }| % \end{quote} % If you use this type of expansion in conditional processing then % you should stick to using |TF| type functions only as it does not % try to finish any |\if... \fi:| itself! % % \section{Manipulating the first argument} % % These functions are described in detail: expansion of multiple tokens follows % the same rules but is described in a shorter fashion. % % \begin{function}[EXP]{\exp_args:No} % \begin{syntax} % \cs{exp_args:No} \meta{function} \Arg{tokens} \Arg{tokens2} ... % \end{syntax} % This function absorbs two arguments (the \meta{function} name and % 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. % \end{function} % % \begin{function}[EXP]{\exp_args:Nc, \exp_args:cc} % \begin{syntax} % \cs{exp_args:Nc} \meta{function} \Arg{tokens} \Arg{tokens2} ... % \end{syntax} % 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 % 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. % % The |:cc| variant constructs the \meta{function} name in the same % manner as described for the \meta{tokens}. % \end{function} % % \begin{function}[EXP]{\exp_args:NV} % \begin{syntax} % \cs{exp_args:NV} \meta{function} \meta{variable} \Arg{tokens2} ... % \end{syntax} % This function absorbs two arguments (the names of the \meta{function} and % the 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. % \end{function} % % \begin{function}[EXP]{\exp_args:Nv} % \begin{syntax} % \cs{exp_args:Nv} \meta{function} \Arg{tokens} \Arg{tokens2} ... % \end{syntax} % 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 % 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. % \end{function} % % \begin{function}[EXP]{\exp_args:Nf} % \begin{syntax} % \cs{exp_args:Nf} \meta{function} \Arg{tokens} \Arg{tokens2} ... % \end{syntax} % This function absorbs two arguments (the \meta{function} name and % the \meta{tokens}). The \meta{tokens} are fully expanded until the % 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. % \end{function} % % \begin{function}{\exp_args:Nx} % \begin{syntax} % \cs{exp_args:Nx} \meta{function} \Arg{tokens} \Arg{tokens2} ... % \end{syntax} % This function absorbs two arguments (the \meta{function} name and % the \meta{tokens}) and exhaustively expands the \meta{tokens} % 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. % \end{function} % % \section{Manipulating two arguments} % % \begin{function}[EXP] % { % \exp_args:NNo, % \exp_args:NNc, % \exp_args:NNv, % \exp_args:NNV, % \exp_args:NNf, % \exp_args:Nco, % \exp_args:Ncf, % \exp_args:Ncc, % \exp_args:NVV % } % \begin{syntax} % \cs{exp_args:NNc} \meta{token1} \meta{token2} \Arg{tokens} % \end{syntax} % These optimized functions absorb three arguments and expand the second and % third as detailed by their argument specifier. The first argument % of the function is then the next item on the input stream, followed % by the expansion of the second and third arguments. % \end{function} % % \begin{function}[EXP] % { % \exp_args:Nno, % \exp_args:NnV, % \exp_args:Nnf, % \exp_args:Noo, % \exp_args:Noc, % \exp_args:Nff, % \exp_args:Nfo, % \exp_args:Nnc % } % \begin{syntax} % \cs{exp_args:Noo} \meta{token} \Arg{tokens1} \Arg{tokens2} % \end{syntax} % These functions absorb three arguments and expand the second and % third as detailed by their argument specifier. The first argument % of the function is then the next item on the input stream, followed % by the expansion of the second and third arguments. % These functions need special (slower) processing. % \end{function} % % \begin{function} % { % \exp_args:NNx, % \exp_args:Nnx, % \exp_args:Ncx, % \exp_args:Nox, % \exp_args:Nxo, % \exp_args:Nxx % } % \begin{syntax} % \cs{exp_args:NNx} \meta{token1} \meta{token2} \Arg{tokens} % \end{syntax} % These functions absorb three arguments and expand the second and % third as detailed by their argument specifier. The first argument % of the function is then the next item on the input stream, followed % by the expansion of the second and third arguments. These functions % are not expandable. % \end{function} % % \section{Manipulating three arguments} % % \begin{function}[EXP] % { % \exp_args:NNNo, % \exp_args:NNNV, % \exp_args:Nccc, % \exp_args:NcNc, % \exp_args:NcNo, % \exp_args:Ncco % } % \begin{syntax} % \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 % argument of the function is then the next item on the input stream, % followed by the expansion of the second argument, \emph{etc}. % \end{function} % % \begin{function}[EXP] % { % \exp_args:NNoo, % \exp_args:NNno, % \exp_args:Nnno, % \exp_args:Nnnc, % \exp_args:Nooo, % } % \begin{syntax} % \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 % argument of the function is then the next item on the input stream, % followed by the expansion of the second argument, \emph{etc}. % These functions need special (slower) processing. % \end{function} % % \begin{function} % { % \exp_args:NNnx, % \exp_args:NNox, % \exp_args:Nnnx, % \exp_args:Nnox, % \exp_args:Noox, % \exp_args:Ncnx, % \exp_args:Nccx % } % \begin{syntax} % \cs{exp_args:NNnx} \meta{token1} \meta{token2} \Arg{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 % argument of the function is then the next item on the input stream, % followed by the expansion of the second argument, \emph{etc.} % \end{function} % % \section{Unbraced expansion} % % \begin{function}[EXP] % { % \exp_last_unbraced:Nf, % \exp_last_unbraced:NV, % \exp_last_unbraced:No, % \exp_last_unbraced:Nv, % \exp_last_unbraced:Nco, % \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 % } % \begin{syntax} % \cs{exp_last_unbraced:Nno} \meta{token} \meta{tokens1} \meta{tokens2} % \end{syntax} % These functions absorb the number of arguments given by their % 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, the \texttt{:Nno}, \texttt{:Noo}, and \texttt{:Nfo} % variants need special (slower) processing. % \begin{texnote} % As an optimization, the last argument is unbraced by some % of those functions before expansion. This can cause problems % if the argument is empty: for instance, % \cs{exp_last_unbraced:Nf} \cs{mypkg_foo:w} |{ }| \cs{q_stop} % leads to an infinite loop, as the quark is \texttt{f}-expanded. % \end{texnote} % \end{function} % % \begin{function}{\exp_last_unbraced:Nx} % \begin{syntax} % \cs{exp_last_unbraced:Nx} \meta{function} \Arg{tokens} % \end{syntax} % This functions fully expands the \meta{tokens} and leaves % the result in the input stream after reinsertion of \meta{function}. % This function is not expandable. % \end{function} % % \begin{function}[EXP]{\exp_last_two_unbraced:Noo} % \begin{syntax} % \cs{exp_last_two_unbraced:Noo} \meta{token} \meta{tokens1} \Arg{tokens2} % \end{syntax} % This function absorbs three arguments and expand the second and third % once. The first argument of the function is then the next item on the % input stream, followed by the expansion of the second and third arguments, % which are not wrapped in braces. % This function needs special (slower) processing. % \end{function} % % \begin{function}[EXP]{\exp_after:wN} % \begin{syntax} % \cs{exp_after:wN} \meta{token1} \meta{token2} % \end{syntax} % Carries out a single expansion of \meta{token2} prior to expansion % of \meta{token1}. If \meta{token2} is a \TeX{} primitive, it will % be executed rather than expanded, while if \meta{token2} has not % expansion (for example, if it is a character) then it will be left % unchanged. It is important to notice that \meta{token1} may be % \emph{any} single token, including group-opening and -closing % tokens (|{| or |}"| assuming normal \TeX{} category codes). Unless % specifically required, expansion should be carried out using an % appropriate argument specifier variant or the appropriate % \cs{exp_arg:N} function. % \begin{texnote} % This is the \TeX{} primitive \tn{expandafter} renamed. % \end{texnote} % \end{function} % % \section{Preventing expansion} % % 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{} \tn{noexpand} primitive. % \end{texnote} % \end{function} % % \begin{function}[EXP]{\exp_not:c} % \begin{syntax} % \cs{exp_not:c} \Arg{tokens} % \end{syntax} % Expands the \meta{tokens} until only unexpandable content remains, and then % converts this into a control sequence. Further expansion of this control % sequence is then inhibited. % \end{function} % % \begin{function}[EXP]{\exp_not:n} % \begin{syntax} % \cs{exp_not:n} \Arg{tokens} % \end{syntax} % Prevents expansion of the \meta{tokens} in a context where they would % otherwise % be expanded, for example an |x|-type argument. % \begin{texnote} % This is the \eTeX{} \tn{unexpanded} primitive. % \end{texnote} % \end{function} % % \begin{function}[EXP]{\exp_not:V} % \begin{syntax} % \cs{exp_not:V} \meta{variable} % \end{syntax} % Recovers the content of the \meta{variable}, then prevents expansion % of the this material in a context where it would otherwise % be expanded, for example an |x|-type argument. % \end{function} % % \begin{function}[EXP]{\exp_not:v} % \begin{syntax} % \cs{exp_not:v} \Arg{tokens} % \end{syntax} % Expands the \meta{tokens} until only unexpandable content remains, and then % converts this into a control sequence (which should be a \meta{variable} % name). The content of the \meta{variable} is recovered, and further % expansion is prevented in a context where it would otherwise % be expanded, for example an |x|-type argument. % \end{function} % % \begin{function}[EXP]{\exp_not:o} % \begin{syntax} % \cs{exp_not:o} \Arg{tokens} % \end{syntax} % Expands the \meta{tokens} once, then prevents any further expansion in a % context where they would otherwise % be expanded, for example an |x|-type argument. % \end{function} % % \begin{function}[EXP]{\exp_not:f} % \begin{syntax} % \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 % (including any tokens which were not expanded) is protected from % further expansion. % \end{function} % % \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} % This function terminates an \texttt{f}-type expansion. Thus if % a function \cs{function: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} % are also expandable. The function itself is an implicit space % token. Inside an \texttt{x}-type expansion, it will retain its % form, but when typeset it produces the underlying space (\verb*| |). % \end{function} % % \section{Internal functions and variables} % % \begin{variable}{\l_exp_tl} % The |\exp_| module has its private variables to temporarily store % results of the argument expansion. This is done to avoid interference % with other functions using temporary variables. % \end{variable} % % \begin{function}[EXP]{\exp_eval_register:N, \exp_eval_register:c} % \begin{syntax} % \cs{exp_eval_register:N} \meta{variable} % \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 \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|. % \end{function} % % \begin{function}{\::n, \::N, \::c, \::o, \::f, \::x, \::v, \::V, \:::} % \begin{syntax} % |\cs_set_nopar: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 % visible in the log and so forth. % \end{function} % % \begin{function}{\cs_generate_internal_variant:n} % \begin{syntax} % \cs{cs_generate_internal_variant:n} \meta{arg~spec} % \end{syntax} % Tests if the function |\exp_args:N|\meta{arg~spec} exists, and defines it % if it does not. The \meta{arg~spec} should be a series of one or more % of the letters |N|, |c|, |n|, |o|, |V|, |v|, |f| and |x|. % \end{function} % % \end{documentation} % % \begin{implementation} % % \section{\pkg{l3expan} implementation} % % \begin{macrocode} %<*initex|package> % \end{macrocode} % % We start by ensuring that the required packages are loaded. % \begin{macrocode} %<*package> \ProvidesExplPackage {\ExplFileName}{\ExplFileDate}{\ExplFileVersion}{\ExplFileDescription} \package_check_loaded_expl: % % \end{macrocode} % % \begin{macro}{\exp_after:wN} % \begin{macro}{\exp_not:N} % \begin{macro}{\exp_not:n} % These are defined in \pkg{l3basics}. % \end{macro} % \end{macro} % \end{macro} % % \subsection{General expansion} % % 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_set_nopar:Npx| at some point, and % so is never going to be expandable.\footnote{However, some % primitives have certain characteristics that means that their % arguments undergo an \texttt{x} type expansion but the primitive % is in fact still expandable. We shall make it very clear when such % a function is expandable.}) % % The definition of expansion functions with this technique happens % in section~\ref{sec:gendef}. % In section~\ref{sec:handtune} some common cases are coded by a more direct % method for efficiency, typically using calls to |\exp_after:wN|. % % \begin{variable}{\l_exp_tl} % We need a scratch token list variable. % We don't use |tl| methods so that \pkg{l3expan} can be loaded earlier. % \begin{macrocode} \cs_new_nopar:Npn \l_exp_tl { } % \end{macrocode} % \end{variable} % % This code uses internal functions with names that start with |\::| % to perform the expansions. All macros are |long| as this turned out % to be desirable since the tokens undergoing expansion may be % arbitrary user input. % % An argument manipulator |\::|\meta{Z} always has signature |#1\:::#2#3| % where |#1| holds the remaining argument manipulations to be performed, % |\:::| serves as an end marker for the list of manipulations, |#2| % is the carried over result of the previous expansion steps and |#3| is % the argument about to be processed. % % \begin{macro}[aux]{\exp_arg_next:nnn} % \begin{macro}[aux]{\exp_arg_next_nobrace:nnn} % |#1| is the result of an expansion step, |#2| is the remaining % 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 % 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 % require a set of braces. % \begin{macrocode} \cs_new:Npn \exp_arg_next:nnn #1#2#3 { #2 \::: { #3 {#1} } } \cs_new:Npn \exp_arg_next_nobrace:nnn #1#2#3 { #2 \::: { #3 #1 } } % \end{macrocode} % \end{macro} % \end{macro} % % \begin{macro}[int]{\:::} % The end marker is just another name for the identity function. % \begin{macrocode} \cs_new:Npn \::: #1 {#1} % \end{macrocode} % \end{macro} % % \begin{macro}[int]{\::n} % This function is used to skip an argument that doesn't need to % be expanded. % \begin{macrocode} \cs_new:Npn \::n #1 \::: #2#3 { #1 \::: { #2 {#3} } } % \end{macrocode} % \end{macro} % % \begin{macro}[int]{\::N} % This function is used to skip an argument that consists of a % single token and doesn't need to be expanded. % \begin{macrocode} \cs_new:Npn \::N #1 \::: #2#3 { #1 \::: {#2#3} } % \end{macrocode} % \end{macro} % % \begin{macro}[int]{\::c} % This function is used to skip an argument that is turned into % as control sequence without expansion. % \begin{macrocode} \cs_new:Npn \::c #1 \::: #2#3 { \exp_after:wN \exp_arg_next_nobrace:nnn \cs:w #3 \cs_end: {#1} {#2} } % \end{macrocode} % \end{macro} % % \begin{macro}[int]{\::o} % This function is used to expand an argument once. % \begin{macrocode} \cs_new:Npn \::o #1 \::: #2#3 { \exp_after:wN \exp_arg_next:nnn \exp_after:wN {#3} {#1} {#2} } % \end{macrocode} % \end{macro} % % \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 \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 % something non-expandable or a space. We introduce |\exp_stop_f:| % to mark such an end of expansion marker; in case the scanner hits % 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: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. % \begin{macrocode} \cs_new:Npn \::f #1 \::: #2#3 { \exp_after:wN \exp_arg_next:nnn \exp_after:wN { \tex_romannumeral:D -`0 #3 } {#1} {#2} } \use:nn { \cs_new_eq:NN \exp_stop_f: } { ~ } % \end{macrocode} % \end{macro} % \end{macro} % % \begin{macro}[int]{\::x} % This function is used to expand an argument fully. % \begin{macrocode} \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} } % \end{macrocode} % \end{macro} % % \begin{macro}[int]{\::v} % \begin{macro}[int]{\::V} % These functions return the value of a register, i.e., one of % |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 \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} \cs_new:Npn \::V #1 \::: #2#3 { \exp_after:wN \exp_arg_next:nnn \exp_after:wN { \tex_romannumeral:D \exp_eval_register:N #3 } {#1} {#2} } \cs_new:Npn \::v # 1\::: #2#3 { \exp_after:wN \exp_arg_next:nnn \exp_after:wN { \tex_romannumeral:D \exp_eval_register:c {#3} } {#1} {#2} } % \end{macrocode} % \end{macro} % \end{macro} % % \begin{macro}[int]{\exp_eval_register:N, \exp_eval_register:c} % \begin{macro}[aux]{\exp_eval_error_msg:w} % 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 \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 % |\exp_after:wN|. The technique is to compare the meaning of the % register in question when it has been prefixed with |\exp_not:N| % and the register itself. If it is a macro, the prefixed % |\exp_not:N| will temporarily turn it into the primitive % |\scan_stop:|. % \begin{macrocode} \cs_new:Npn \exp_eval_register:N #1 { \exp_after:wN \if_meaning:w \exp_not:N #1 #1 % \end{macrocode} % If the token was not a macro it may be a malformed variable from a % |c| expansion in which case it is equal to the primitive % |\scan_stop:|. In that case we throw an error. We could let \TeX{} % do it for us but that would result in the rather obscure % \begin{quote} % |! You can't use `\relax' after \the.| % \end{quote} % which while quite true doesn't give many hints as to what actually % went wrong. We provide something more sensible. % \begin{macrocode} \if_meaning:w \scan_stop: #1 \exp_eval_error_msg:w \fi: % \end{macrocode} % The next bit requires some explanation. The function must be % 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 % |\exp_after:wN \c_zero \tex_the:D #1| and if it is a macro we % need to execute |\exp_after:wN \c_zero #1|. We therefore issue % the longer of the two sequences and if the register is a macro, we % remove the |\tex_the:D|. % \begin{macrocode} \else: \exp_after:wN \use_i_ii:nnn \fi: \exp_after:wN \c_zero \tex_the:D #1 } \cs_new:Npn \exp_eval_register:c #1 { \exp_after:wN \exp_eval_register:N \cs:w #1 \cs_end: } % \end{macrocode} % Clean up nicely, then call the undefined control sequence. The % result is an error message looking like this: % \begin{verbatim} % ! Undefined control sequence. % \LaTeX3 error: % Erroneous variable used! % l.55 \tl_set:Nv \l_tmpa_tl {undefined_tl} % \end{verbatim} % \begin{macrocode} \cs_new:Npn \exp_eval_error_msg:w #1 \tex_the:D #2 { \fi: \fi: \msg_expandable_kernel_error:nnn { kernel } { bad-var } {#2} \c_zero } % \end{macrocode} % \end{macro} % \end{macro} % % \subsection{Hand-tuned definitions} % \label{sec:handtune} % % One of the most important features of these functions is that they % are fully expandable and therefore allow to prefix them with % |\tex_global:D| for example. % % \begin{macro}{\exp_args:No} % \begin{macro}{\exp_args:NNo} % \begin{macro}{\exp_args:NNNo} % Those lovely runs of expansion! % \begin{macrocode} \cs_new:Npn \exp_args:No #1#2 { \exp_after:wN #1 \exp_after:wN {#2} } \cs_new:Npn \exp_args:NNo #1#2#3 { \exp_after:wN #1 \exp_after:wN #2 \exp_after:wN {#3} } \cs_new:Npn \exp_args:NNNo #1#2#3#4 { \exp_after:wN #1 \exp_after:wN#2 \exp_after:wN #3 \exp_after:wN {#4} } % \end{macrocode} % \end{macro} % \end{macro} % \end{macro} % % \begin{macro}{\exp_args:Nc} % In \pkg{l3basics} %\end{macro} % % \begin{macro}{\exp_args:cc, \exp_args:NNc, \exp_args:Ncc, \exp_args:Nccc} % Here are the functions that turn their argument into csnames but % are expandable. % \begin{macrocode} \cs_new:Npn \exp_args:cc #1#2 { \cs:w #1 \exp_after:wN \cs_end: \cs:w #2 \cs_end: } \cs_new:Npn \exp_args:NNc #1#2#3 { \exp_after:wN #1 \exp_after:wN #2 \cs:w # 3\cs_end: } \cs_new:Npn \exp_args:Ncc #1#2#3 { \exp_after:wN #1 \cs:w #2 \exp_after:wN \cs_end: \cs:w #3 \cs_end: } \cs_new:Npn \exp_args:Nccc #1#2#3#4 { \exp_after:wN #1 \cs:w #2 \exp_after:wN \cs_end: \cs:w #3 \exp_after:wN \cs_end: \cs:w #4 \cs_end: } % \end{macrocode} % \end{macro} % % \begin{macro}{\exp_args:Nf, \exp_args:NV, \exp_args:Nv, \exp_args:Nx} % \begin{macrocode} \cs_new:Npn \exp_args:Nf #1#2 { \exp_after:wN #1 \exp_after:wN { \tex_romannumeral:D -`0 #2 } } \cs_new:Npn \exp_args:Nv #1#2 { \exp_after:wN #1 \exp_after:wN { \tex_romannumeral:D \exp_eval_register:c {#2} } } \cs_new:Npn \exp_args:NV #1#2 { \exp_after:wN #1 \exp_after:wN { \tex_romannumeral:D \exp_eval_register:N #2 } } % \end{macrocode} % \end{macro} % % \begin{macro}{\exp_args:NNV,\exp_args:NNv,\exp_args:NNf, % \exp_args:NVV, % \exp_args:Ncf,\exp_args:Nco} % Some more hand-tuned function with three arguments. % If we force that an |o| argument always has braces, % we could implement \cs{exp_args:Nco} with less tokens % and only two arguments. % \begin{macrocode} \cs_new:Npn \exp_args:NNf #1#2#3 { \exp_after:wN #1 \exp_after:wN #2 \exp_after:wN { \tex_romannumeral:D -`0 #3 } } \cs_new:Npn \exp_args:NNv #1#2#3 { \exp_after:wN #1 \exp_after:wN #2 \exp_after:wN { \tex_romannumeral:D \exp_eval_register:c {#3} } } \cs_new:Npn \exp_args:NNV #1#2#3 { \exp_after:wN #1 \exp_after:wN #2 \exp_after:wN { \tex_romannumeral:D \exp_eval_register:N #3 } } \cs_new:Npn \exp_args:Nco #1#2#3 { \exp_after:wN #1 \cs:w #2 \exp_after:wN \cs_end: \exp_after:wN {#3} } \cs_new:Npn \exp_args:Ncf #1#2#3 { \exp_after:wN #1 \cs:w #2 \exp_after:wN \cs_end: \exp_after:wN { \tex_romannumeral:D -`0 #3 } } \cs_new:Npn \exp_args:NVV #1#2#3 { \exp_after:wN #1 \exp_after:wN { \tex_romannumeral:D \exp_after:wN \exp_eval_register:N \exp_after:wN #2 \exp_after:wN } \exp_after:wN { \tex_romannumeral:D \exp_eval_register:N #3 } } % \end{macrocode} % \end{macro} % % \begin{macro}{\exp_args:Ncco, % \exp_args:NcNc, % \exp_args:NcNo, % \exp_args:NNNV} % A few more that we can hand-tune. % \begin{macrocode} \cs_new:Npn \exp_args:NNNV #1#2#3#4 { \exp_after:wN #1 \exp_after:wN #2 \exp_after:wN #3 \exp_after:wN { \tex_romannumeral:D \exp_eval_register:N #4 } } \cs_new:Npn \exp_args:NcNc #1#2#3#4 { \exp_after:wN #1 \cs:w #2 \exp_after:wN \cs_end: \exp_after:wN #3 \cs:w #4 \cs_end: } \cs_new:Npn \exp_args:NcNo #1#2#3#4 { \exp_after:wN #1 \cs:w #2 \exp_after:wN \cs_end: \exp_after:wN #3 \exp_after:wN {#4} } \cs_new:Npn \exp_args:Ncco #1#2#3#4 { \exp_after:wN #1 \cs:w #2 \exp_after:wN \cs_end: \cs:w #3 \exp_after:wN \cs_end: \exp_after:wN {#4} } % \end{macrocode} % \end{macro} % % \subsection{Definitions with the automated technique} % \label{sec:gendef} % % Some of these could be done more efficiently, but the complexity of % coding then becomes an issue. Notice that the auto-generated functions % are all not long: they don't actually take any arguments themselves. % % \begin{macro}{\exp_args:Nx} % \begin{macrocode} \cs_new_protected_nopar:Npn \exp_args:Nx { \::x \::: } % \end{macrocode} % \end{macro} % % \begin{macro}{\exp_args:NNx, % \exp_args:Nnc, % \exp_args:Ncx, % \exp_args:Nfo,\exp_args:Nff, % \exp_args:Nnf,\exp_args:Nno,\exp_args:NnV,\exp_args:Nnx, % \exp_args:Noo,\exp_args:Noc,\exp_args:Nox, % \exp_args:Nxo,\exp_args:Nxx} % 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:Noc { \::o \::c \::: } \cs_new_nopar:Npn \exp_args:Noo { \::o \::o \::: } \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 \::: } % \end{macrocode} % \end{macro} % % \begin{macro}{\exp_args:Nccx, % \exp_args:Ncnx, % \exp_args:NNno, % \exp_args:Nnno, % \exp_args:Nnnx, % \exp_args:Nnox, % \exp_args:Nooo, % \exp_args:Noox, % \exp_args:Nnnc, % \exp_args:NNnx, % \exp_args:NNoo, % \exp_args:NNox} % \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: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 \::: } % \end{macrocode} % \end{macro} % % \subsection{Last-unbraced versions} % % \begin{macro}[aux]{\exp_arg_last_unbraced:nn} % \begin{macro}[aux]{\::f_unbraced} % \begin{macro}[aux]{\::o_unbraced} % \begin{macro}[aux]{\::V_unbraced} % \begin{macro}[aux]{\::v_unbraced} % \begin{macro}[aux]{\::x_unbraced} % There are a few places where the last argument needs to be available % unbraced. First some helper macros. % \begin{macrocode} \cs_new:Npn \exp_arg_last_unbraced:nn #1#2 { #2#1 } \cs_new:Npn \::f_unbraced \::: #1#2 { \exp_after:wN \exp_arg_last_unbraced:nn \exp_after:wN { \tex_romannumeral:D -`0 #2 } {#1} } \cs_new:Npn \::o_unbraced \::: #1#2 { \exp_after:wN \exp_arg_last_unbraced:nn \exp_after:wN {#2} {#1} } \cs_new:Npn \::V_unbraced \::: #1#2 { \exp_after:wN \exp_arg_last_unbraced:nn \exp_after:wN { \tex_romannumeral:D \exp_eval_register:N #2 } {#1} } \cs_new:Npn \::v_unbraced \::: #1#2 { \exp_after:wN \exp_arg_last_unbraced:nn \exp_after:wN { \tex_romannumeral:D \exp_eval_register:c {#2} } {#1} } \cs_new_protected:Npn \::x_unbraced \::: #1#2 { \cs_set_nopar:Npx \l_exp_tl { \exp_not:n {#1} #2 } \l_exp_tl } % \end{macrocode} % \end{macro} % \end{macro} % \end{macro} % \end{macro} % \end{macro} % \end{macro} % % \begin{macro}{\exp_last_unbraced:NV} % \begin{macro}{\exp_last_unbraced:Nv} % \begin{macro}{\exp_last_unbraced:Nf} % \begin{macro}{\exp_last_unbraced:No} % \begin{macro}{\exp_last_unbraced:Nco} % \begin{macro}{\exp_last_unbraced:NcV} % \begin{macro}{\exp_last_unbraced:NNV} % \begin{macro}{\exp_last_unbraced:NNo} % \begin{macro}{\exp_last_unbraced:NNNV} % \begin{macro}{\exp_last_unbraced:NNNo} % \begin{macro}{\exp_last_unbraced:Nno} % \begin{macro}{\exp_last_unbraced:Noo} % \begin{macro}{\exp_last_unbraced:Nfo} % \begin{macro}{\exp_last_unbraced:Nx} % Now the business end: most of these are hand-tuned for speed, but the % general system is in place. % \begin{macrocode} \cs_new:Npn \exp_last_unbraced:NV #1#2 { \exp_after:wN #1 \tex_romannumeral:D \exp_eval_register:N #2 } \cs_new:Npn \exp_last_unbraced:Nv #1#2 { \exp_after:wN #1 \tex_romannumeral:D \exp_eval_register:c {#2} } \cs_new:Npn \exp_last_unbraced:No #1#2 { \exp_after:wN #1 #2 } \cs_new:Npn \exp_last_unbraced:Nf #1#2 { \exp_after:wN #1 \tex_romannumeral:D -`0 #2 } \cs_new:Npn \exp_last_unbraced:Nco #1#2#3 { \exp_after:wN #1 \cs:w #2 \exp_after:wN \cs_end: #3 } \cs_new:Npn \exp_last_unbraced:NcV #1#2#3 { \exp_after:wN #1 \cs:w #2 \exp_after:wN \cs_end: \tex_romannumeral:D \exp_eval_register:N #3 } \cs_new:Npn \exp_last_unbraced:NNV #1#2#3 { \exp_after:wN #1 \exp_after:wN #2 \tex_romannumeral:D \exp_eval_register:N #3 } \cs_new:Npn \exp_last_unbraced:NNo #1#2#3 { \exp_after:wN #1 \exp_after:wN #2 #3 } \cs_new:Npn \exp_last_unbraced:NNNV #1#2#3#4 { \exp_after:wN #1 \exp_after:wN #2 \exp_after:wN #3 \tex_romannumeral:D \exp_eval_register:N #4 } \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_protected_nopar:Npn \exp_last_unbraced:Nx { \::x_unbraced \::: } % \end{macrocode} % \end{macro} % \end{macro} % \end{macro} % \end{macro} % \end{macro} % \end{macro} % \end{macro} % \end{macro} % \end{macro} % \end{macro} % \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} % \cs_new:Npn \exp_last_two_unbraced:Noo #1 #2 #3 % { \exp_after:wN \exp_after:wN \exp_after:wN #1 \exp_after:wN #2 #3 } % \end{verbatim} % However, for robustness this is not suitable. Instead, a bit of a % shuffle is used to ensure that |#2| can be multiple tokens. % \begin{macrocode} \cs_new:Npn \exp_last_two_unbraced:Noo #1#2#3 { \exp_after:wN \exp_last_two_unbraced_aux:noN \exp_after:wN {#3} {#2} #1 } \cs_new:Npn \exp_last_two_unbraced_aux:noN #1#2#3 { \exp_after:wN #3 #2 #1 } % \end{macrocode} % \end{macro} % % \subsection{Preventing expansion} % % \begin{macro}{\exp_not:o} % \begin{macro}{\exp_not:f} % \begin{macro}{\exp_not:V} % \begin{macro}{\exp_not:v} % \begin{macrocode} \cs_new:Npn \exp_not:o #1 { \etex_unexpanded:D \exp_after:wN {#1} } \cs_new:Npn \exp_not:f #1 { \etex_unexpanded:D \exp_after:wN { \tex_romannumeral:D -`0 #1 } } \cs_new:Npn \exp_not:V #1 { \etex_unexpanded:D \exp_after:wN { \tex_romannumeral:D \exp_eval_register:N #1 } } \cs_new:Npn \exp_not:v #1 { \etex_unexpanded:D \exp_after:wN { \tex_romannumeral:D \exp_eval_register:c {#1} } } % \end{macrocode} % \end{macro} % \end{macro} % \end{macro} % \end{macro} % % \begin{macro}{\exp_not:c} % A helper function. % \begin{macrocode} \cs_new:Npn \exp_not:c #1 { \exp_after:wN \exp_not:N \cs:w #1 \cs_end: } % \end{macrocode} % \end{macro} % % \subsection{Defining function variants} % % \begin{macro}{\cs_generate_variant:Nn} % \begin{macro}[aux]{\cs_generate_variant_aux:nnNNn} % \begin{macro}[aux]{\cs_generate_variant_aux:Nnnw} % \begin{macro}[aux]{\cs_generate_variant_aux:NNn} % \begin{arguments} % \item Base form of a function; \emph{e.g.},~|\tl_set:Nn| % \item One or more variant argument specifiers; e.g., |{Nx,c,cx}| % \end{arguments} % Test whether the base function is protected or not % and define \cs{cs_tmp:w} as either \cs{cs_new_nopar:Npx} or % \cs{cs_new_protected_nopar:Npx}, then used to define all the % variants. % Split up the original base function to grab its name and signature % consisting of $k$ letters. Then we wish to iterate through the list % of variant argument specifiers, and for each one construct a new % function name using the original base name, the variant signature % consisting of $l$ letters and the last $k-l$ letters of the base % 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_protected:Npn \cs_generate_variant:Nn #1 { \chk_if_exist_cs:N #1 \cs_generate_variant_aux:N #1 \cs_split_function:NN #1 \cs_generate_variant_aux:nnNNn #1 } % \end{macrocode} % We discard the boolean |#3| and then set off a loop through the desired % variant forms. The original function is retained as |#4| for efficiency. % \begin{macrocode} \cs_new:Npn \cs_generate_variant_aux:nnNNn #1#2#3#4#5 { \cs_generate_variant_aux:Nnnw #4 {#1}{#2} #5 , ? , \q_recursion_stop } % \end{macrocode} % Next is the real work to be done. We now have 1: original function, % 2: base name, 3: base signature, 4: beginning of variant signature. % To construct the new % csname and the |\exp_args:Ncc| form, we need the variant signature. % In our example, we wanted to discard the first two letters of the % base signature because the variant form started with |cc|. This is % the same as putting first |cc| in the signature and then % |\use_none:nn| followed by the base signature |NNn|. Depending on % the number of characters in |#4|, the relevant \cs{use_none:n\ldots{}n} % is called. % % Firstly though, we check whether to terminate the loop. % Then build the variant function once, to avoid repeating this % relatively expensive operation. Then recurse. % \begin{macrocode} \cs_new:Npn \cs_generate_variant_aux:Nnnw #1#2#3#4 , { \if:w ? #4 \exp_after:wN \use_none_delimit_by_q_recursion_stop:w \fi: \exp_args:NNc \cs_generate_variant_aux:NNn #1 { #2 : #4 \exp_after:wN \use_i_delimit_by_q_stop:nw \use_none:nnnnnnnnn #4 \use_none:nnnnnnnnn \use_none:nnnnnnnn \use_none:nnnnnnn \use_none:nnnnnn \use_none:nnnnn \use_none:nnnn \use_none:nnn \use_none:nn \use_none:n { } \q_stop #3 } {#4} \cs_generate_variant_aux:Nnnw #1 {#2} {#3} } % \end{macrocode} % Check if the variant form has already been defined. % If not, then define it and then additionally check if % the |\exp_args:N| form needed is defined. % Otherwise tell that it was already defined. % \begin{macrocode} \cs_new:Npn \cs_generate_variant_aux:NNn #1 #2 #3 { \cs_if_free:NTF #2 { \cs_tmp:w #2 { \exp_not:c { exp_args:N #3 } \exp_not:N #1 } \cs_generate_internal_variant:n {#3} } { \iow_log:x { Variant~\token_to_str:N #2~% already~defined;~ not~ changing~ it~on~line~% \tex_the:D \tex_inputlineno:D } } } % \end{macrocode} % \end{macro} % \end{macro} % \end{macro} % \end{macro} % % \begin{macro}[aux]{\cs_generate_variant_aux:N} % \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:Npn \cs_generate_variant_aux:N #1 { \exp_after:wN \cs_generate_variant_aux:w \token_to_meaning:N #1 \q_mark \cs_new_protected_nopar:Npx ? PROTECTEZ \q_mark \cs_new_nopar:Npx \q_stop } \cs_new:Npn \cs_generate_variant_aux:w #1 ? PROTECTEZ #2 \q_mark #3 #4 \q_stop { \cs_set_eq:NN \cs_tmp:w #3 } } % \end{macrocode} % \end{macro} % \end{macro} % % \begin{macro}[int]{\cs_generate_internal_variant:n} % \begin{macro}[aux]{\cs_generate_internal_variant_aux:N} % Test if |exp_args:N #1| is already defined % and if not define it via the % |\::| commands using the chars in |#1| % \begin{macrocode} \cs_new_protected:Npn \cs_generate_internal_variant:n #1 { \cs_if_free:cT { exp_args:N #1 } { \cs_new:cpx { exp_args:N #1 } { \cs_generate_internal_variant_aux:N #1 : } } } % \end{macrocode} % This command grabs char by char outputting |\::#1| (not expanded % further) until we see a |:|. That colon is in fact also turned into % |\:::| so that the required structure for |\exp_args...| commands % is correctly terminated. % \begin{macrocode} \cs_new:Npn \cs_generate_internal_variant_aux:N #1 { \exp_not:c { :: #1 } \if_meaning:w : #1 \exp_after:wN \use_none:n \fi: \cs_generate_internal_variant_aux:N } % \end{macrocode} % \end{macro} % \end{macro} % %\subsection{Variants which cannot be created earlier} % % \begin{macro}[pTF] % {\str_if_eq:Vn, \str_if_eq:on, \str_if_eq:nV, \str_if_eq:no, \str_if_eq:VV} % These cannot come earlier as they need \cs{cs_generate_variant:Nn}. % \begin{macrocode} \cs_generate_variant:Nn \str_if_eq_p:nn { V , o } \cs_generate_variant:Nn \str_if_eq_p:nn { nV , no , VV } \cs_generate_variant:Nn \str_if_eq:nnT { V , o } \cs_generate_variant:Nn \str_if_eq:nnT { nV , no , VV } \cs_generate_variant:Nn \str_if_eq:nnF { V , o } \cs_generate_variant:Nn \str_if_eq:nnF { nV , no , VV } \cs_generate_variant:Nn \str_if_eq:nnTF { V , o } \cs_generate_variant:Nn \str_if_eq:nnTF { nV , no , VV } % \end{macrocode} % \end{macro} % % \begin{macrocode} % % \end{macrocode} % % \end{implementation} % % \PrintIndex