path: root/Master/texmf-dist/source/latex/l3kernel/l3expan.dtx

% \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 2812 2011-09-12 09:19:26Z bruno $
  {L3 Experimental argument expansion}
%</driver|package>
%<*driver>
\documentclass[full]{l3doc}
\begin{document}
  \DocInput{\jobname.dtx}
\end{document}
%</driver>
% \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}{\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} \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
%   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: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.
% \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:
%</package>
%    \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_nopar: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_nopar: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.
%     <argument> \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_error:n { Erroneous ~ variable ~ #2 used! }
    \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_nopar: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}
%   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}
  }
%    \end{macrocode}
%\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: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}
% \begin{macro}{\exp_last_unbraced:NNNo}
%   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: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_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
  {
    \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 }
%    \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}
%
% \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:nnN \exp_after:wN {#3} {#2} #1 }
\cs_new:Npn \exp_last_two_unbraced_aux:nnN #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{macro}[aux]{\cs_generate_variant_aux:N}
%   \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}
%   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_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|. We therefore
%   call a small loop that outputs an |n| for each letter in the variant
%   signature and use this to call the correct |\use_none:| variant.
%
%   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 \use:c { use_none: \cs_generate_variant_aux:N #4 ? } #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_generate_variant_aux:NNpx #1 #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}
%   The small loop for defining the required number of |n|s. Break when
%   seeing a |?|.
%    \begin{macrocode}
\cs_new:Npn \cs_generate_variant_aux:N #1
  {
    \if:w ? #1
      \exp_after:wN \use_none:nn
    \fi:
    n
    \cs_generate_variant_aux:N
  }
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}[aux]{\cs_generate_variant_aux:NNpx}
% \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:NNpx #1
      {
        \exp_after:wN \cs_generate_variant_aux:w
          \token_to_meaning:N #1 ? PROTECTEZ \q_stop
      }
    \cs_new:Npn \cs_generate_variant_aux:w #1 ? PROTECTEZ #2 \q_stop
      {
        \if_catcode:w a \etex_detokenize:D \exp_after:wN {#1} a
          \exp_after:wN \cs_new_protected_nopar:Npx
        \else:
          \exp_after:wN \cs_new_nopar:Npx
        \fi:
      }
  }
%    \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}
%</initex|package>
%    \end{macrocode}
%
% \end{implementation}
%
% \PrintIndex