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

% \iffalse meta-comment
%
%% File: l3basics.dtx Copyright (C) 1990-2014 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{l3bootstrap}
\GetIdInfo$Id: l3basics.dtx 4642 2014-01-04 17:28:32Z joseph $
  {L3 Basic definitions}
%</driver|package>
%<*driver>
\documentclass[full]{l3doc}
\begin{document}
  \DocInput{\jobname.dtx}
\end{document}
%</driver>
% \fi
%
% \title{^^A
%   The \pkg{l3basics} package\\ Basic definitions^^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}
%
% As the name suggest this package holds some basic definitions which
% are needed by most or all other packages in this set.
%
% Here we describe those functions that are used all over the place. With
% that we mean functions dealing with the construction and testing of
% control sequences. Furthermore the basic parts of conditional
% processing are covered; conditional processing dealing with specific
% data types is described in the modules specific for the respective
% data types.
%
% \section{No operation functions}
%
% \begin{function}[EXP]{\prg_do_nothing:}
%   \begin{syntax}
%     \cs{prg_do_nothing:}
%   \end{syntax}
%   An expandable function which does nothing at all: leaves nothing
%   in the input stream after a single expansion.
% \end{function}
%
% \begin{function}{\scan_stop:}
%   \begin{syntax}
%     \cs{scan_stop:}
%   \end{syntax}
%   A non-expandable function which does nothing. Does not vanish on
%   expansion but produces no typeset output.
% \end{function}
%
% \section{Grouping material}
%
% \begin{function}{\group_begin:, \group_end:}
%   \begin{syntax}
%     \cs{group_begin:}
%     \cs{group_end:}
%   \end{syntax}
%   These functions begin and end a group for definition purposes.
%   Assignments are local to groups unless carried out in a global
%   manner. (A small number of exceptions to this rule will be noted
%   as necessary elsewhere in this document.) Each \cs{group_begin:}
%   must be matched by a \cs{group_end:}, although this does not have
%   to occur within the same function. Indeed, it is often necessary
%   to start a group within one function and finish it within another,
%   for example when seeking to use non-standard category codes.
% \end{function}
%
% \begin{function}{\group_insert_after:N}
%   \begin{syntax}
%     \cs{group_insert_after:N} \meta{token}
%   \end{syntax}
%   Adds \meta{token} to the list of \meta{tokens} to be inserted
%   when the current group level ends. The list of \meta{tokens} to be
%   inserted will be empty at the beginning of a group: multiple
%   applications of \cs{group_insert_after:N} may be used to build
%   the inserted list one \meta{token} at a time. The current group
%   level may be closed by a \cs{group_end:} function or by a token
%   with category code $2$ (close-group). The later will be a ^^A{
%   |}| if standard category codes apply.
% \end{function}
%
% \section{Control sequences and functions}
%
% As \TeX{} is a macro language, creating new functions means
% creating macros. At point of use, a function is replaced by
% the replacement text (\enquote{code}) in which each parameter
% in the code (|#1|, |#2|, \emph{etc.}) is replaced the appropriate
% arguments absorbed by the function. In the following, \meta{code}
% is therefore used as a shorthand for \enquote{replacement text}.
%
% Functions which are not \enquote{protected} will be fully expanded
% inside an \texttt{x} expansion. In contrast, \enquote{protected}
% functions are not expanded within \texttt{x} expansions.
%
% \subsection{Defining functions}
%
% Functions can be created with no requirement that they are declared
% first (in contrast to variables, which must always be declared).
% Declaring a function before setting up the code means that the name
% chosen will be checked and an error raised if it is already in use.
% The name of a function can be checked at the point of definition using
% the \cs{cs_new\ldots} functions: this is recommended for all
% functions which are defined for the first time.
%
% There are three ways to define new functions.
% All classes define a function to expand to the substitution text.
% Within the substitution text the actual parameters are substituted
% for the formal parameters (|#1|, |#2|, \ldots).
% \begin{description}
%   \item[\texttt{new}]
%     Create a new function with the \texttt{new} scope,
%     such as \cs{cs_new:Npn}.  The definition is global and will result in
%     an error if it is already defined.
%   \item[\texttt{set}]
%     Create a new function with the \texttt{set} scope,
%     such as \cs{cs_set:Npn}. The definition is restricted to the current
%     \TeX{} group and will not result in an error if the function is already
%     defined.
%   \item[\texttt{gset}]
%     Create a new function with the \texttt{gset} scope,
%     such as \cs{cs_gset:Npn}. The definition is global and
%     will not result in an error if the function is already defined.
% \end{description}
%
% Within each set of scope there are different ways to define a function.
% The differences depend on restrictions on the actual parameters and
% the expandability of the resulting function.
% \begin{description}
%   \item[\texttt{nopar}]
%      Create a new function with the \texttt{nopar} restriction,
%      such as \cs{cs_set_nopar:Npn}. The parameter may not contain
%      \cs{par} tokens.
%   \item[\texttt{protected}]
%      Create a new function with the \texttt{protected} restriction,
%      such as \cs{cs_set_protected:Npn}. The parameter may contain
%      \cs{par} tokens but the function will not expand within an
%      \texttt{x}-type expansion.
% \end{description}
% 
% Finally, the functions in
% Subsections~\ref{sec:l3basics:defining-new-function-1}~and
% \ref{sec:l3basics:defining-new-function-2} are primarily meant to define
% \emph{base functions} only. Base functions can only have the following
% argument specifiers:
% \begin{description}
%   \item[|N| and |n|] No manipulation.
%   \item[|T| and |F|] Functionally equivalent to |n| (you are actually
%     encouraged to use the family of |\prg_new_conditional:| functions
%     described in Section~\ref{sec:l3prg:new-conditional-functions}).
%   \item[|p| and |w|] These are special cases.
% \end{description}
% 
% The |\cs_new:| functions below (and friends) do not stop you from using
% other argument specifiers in your function names, but they do not handle
% expansion for you. You should define the base function and then use
% \cs{cs_generate_variant:Nn} to generate custom variants as described in
% Section~\ref{sec:l3expan:defining-variants}.
%
% \subsection{Defining new functions using parameter text}
% \label{sec:l3basics:defining-new-function-1}
%
% \begin{function}{\cs_new:Npn, \cs_new:cpn, \cs_new:Npx, \cs_new:cpx}
%   \begin{syntax}
%     \cs{cs_new:Npn} \meta{function} \meta{parameters} \Arg{code}
%   \end{syntax}
%   Creates \meta{function} to expand to \meta{code} as replacement text.
%   Within the \meta{code}, the \meta{parameters} (|#1|, |#2|,
%   \emph{etc.}) will be replaced by those absorbed by the function.
%   The definition is global and an error will result if the
%   \meta{function} is already defined.
% \end{function}
%
% \begin{function}
%   {
%     \cs_new_nopar:Npn, \cs_new_nopar:cpn,
%     \cs_new_nopar:Npx, \cs_new_nopar:cpx
%   }
%   \begin{syntax}
%     \cs{cs_new_nopar:Npn} \meta{function} \meta{parameters} \Arg{code}
%   \end{syntax}
%   Creates \meta{function} to expand to \meta{code} as replacement text.
%   Within the \meta{code}, the \meta{parameters} (|#1|, |#2|,
%   \emph{etc.}) will be replaced by those absorbed by the function.
%   When the \meta{function} is used the \meta{parameters} absorbed
%   cannot contain \cs{par} tokens. The definition is global and
%   an error will result if the \meta{function} is already defined.
% \end{function}
%
% \begin{function}
%   {
%     \cs_new_protected:Npn, \cs_new_protected:cpn,
%     \cs_new_protected:Npx, \cs_new_protected:cpx
%   }
%   \begin{syntax}
%     \cs{cs_new_protected:Npn} \meta{function} \meta{parameters} \Arg{code}
%   \end{syntax}
%   Creates \meta{function} to expand to \meta{code} as replacement text.
%   Within the \meta{code}, the \meta{parameters} (|#1|, |#2|,
%   \emph{etc.}) will be replaced by those absorbed by the function.
%   The \meta{function} will not expand within an \texttt{x}-type
%   argument. The definition is global and an error will result if the
%   \meta{function} is already defined.
% \end{function}
%
% \begin{function}
%   {
%     \cs_new_protected_nopar:Npn, \cs_new_protected_nopar:cpn ,
%     \cs_new_protected_nopar:Npx, \cs_new_protected_nopar:cpx
%   }
%   \begin{syntax}
%     \cs{cs_new_protected_nopar:Npn} \meta{function} \meta{parameters} \Arg{code}
%   \end{syntax}
%   Creates \meta{function} to expand to \meta{code} as replacement text.
%   Within the \meta{code}, the \meta{parameters} (|#1|, |#2|,
%   \emph{etc.}) will be replaced by those absorbed by the function.
%   When the \meta{function} is used the \meta{parameters} absorbed
%   cannot contain \cs{par} tokens. The \meta{function} will not
%   expand within an \texttt{x}-type argument. The definition is global
%   and an error will result if the \meta{function} is already defined.
% \end{function}
%
% \begin{function}{\cs_set:Npn, \cs_set:cpn, \cs_set:Npx, \cs_set:cpx}
%   \begin{syntax}
%     \cs{cs_set:Npn} \meta{function} \meta{parameters} \Arg{code}
%   \end{syntax}
%   Sets \meta{function} to expand to \meta{code} as replacement text.
%   Within the \meta{code}, the \meta{parameters} (|#1|, |#2|,
%   \emph{etc.}) will be replaced by those absorbed by the function.
%   The assignment of a meaning to the \meta{function} is restricted to
%   the current \TeX{} group level.
% \end{function}
%
% \begin{function}
%   {
%     \cs_set_nopar:Npn, \cs_set_nopar:cpn,
%     \cs_set_nopar:Npx, \cs_set_nopar:cpx
%   }
%   \begin{syntax}
%     \cs{cs_set_nopar:Npn} \meta{function} \meta{parameters} \Arg{code}
%   \end{syntax}
%   Sets \meta{function} to expand to \meta{code} as replacement text.
%   Within the \meta{code}, the \meta{parameters} (|#1|, |#2|,
%   \emph{etc.}) will be replaced by those absorbed by the function.
%   When the \meta{function} is used the \meta{parameters} absorbed
%   cannot contain \cs{par} tokens. The assignment of a meaning
%   to the \meta{function} is restricted to the current \TeX{} group
%   level.
% \end{function}
%
% \begin{function}
%   {
%     \cs_set_protected:Npn, \cs_set_protected:cpn,
%     \cs_set_protected:Npx, \cs_set_protected:cpx
%   }
%   \begin{syntax}
%     \cs{cs_set_protected:Npn} \meta{function} \meta{parameters} \Arg{code}
%   \end{syntax}
%   Sets \meta{function} to expand to \meta{code} as replacement text.
%   Within the \meta{code}, the \meta{parameters} (|#1|, |#2|,
%   \emph{etc.}) will be replaced by those absorbed by the function.
%   The assignment of a meaning to the \meta{function} is restricted to
%   the current \TeX{} group level. The \meta{function} will
%   not expand within an \texttt{x}-type argument.
% \end{function}
%
% \begin{function}
%   {
%     \cs_set_protected_nopar:Npn, \cs_set_protected_nopar:cpn ,
%     \cs_set_protected_nopar:Npx, \cs_set_protected_nopar:cpx ,
%   }
%   \begin{syntax}
%     \cs{cs_set_protected_nopar:Npn} \meta{function} \meta{parameters} \Arg{code}
%   \end{syntax}
%   Sets \meta{function} to expand to \meta{code} as replacement text.
%   Within the \meta{code}, the \meta{parameters} (|#1|, |#2|,
%   \emph{etc.}) will be replaced by those absorbed by the function.
%   When the \meta{function} is used the \meta{parameters} absorbed
%   cannot contain \cs{par} tokens. The assignment of a meaning
%   to the \meta{function} is restricted to the current \TeX{} group
%   level. The \meta{function} will not expand within an
%   \texttt{x}-type argument.
% \end{function}
%
% \begin{function}{\cs_gset:Npn, \cs_gset:cpn, \cs_gset:Npx, \cs_gset:cpx}
%   \begin{syntax}
%     \cs{cs_gset:Npn} \meta{function} \meta{parameters} \Arg{code}
%   \end{syntax}
%   Globally sets \meta{function} to expand to \meta{code} as replacement
%   text. Within the \meta{code}, the \meta{parameters} (|#1|, |#2|,
%   \emph{etc.}) will be replaced by those absorbed by the function.
%   The assignment of a meaning to the \meta{function} is \emph{not}
%   restricted to the current \TeX{} group level: the assignment is
%   global.
% \end{function}
%
% \begin{function}
%   {
%     \cs_gset_nopar:Npn, \cs_gset_nopar:cpn,
%     \cs_gset_nopar:Npx, \cs_gset_nopar:cpx
%   }
%   \begin{syntax}
%     \cs{cs_gset_nopar:Npn} \meta{function} \meta{parameters} \Arg{code}
%   \end{syntax}
%   Globally sets \meta{function} to expand to \meta{code} as replacement
%   text. Within the \meta{code}, the \meta{parameters} (|#1|, |#2|,
%   \emph{etc.}) will be replaced by those absorbed by the function.
%   When the \meta{function} is used the \meta{parameters} absorbed
%   cannot contain \cs{par} tokens. The assignment of a meaning to the
%   \meta{function} is \emph{not} restricted to the current \TeX{}
%   group level: the assignment is global.
% \end{function}
%
% \begin{function}
%   {
%     \cs_gset_protected:Npn, \cs_gset_protected:cpn,
%     \cs_gset_protected:Npx, \cs_gset_protected:cpx
%   }
%   \begin{syntax}
%     \cs{cs_gset_protected:Npn} \meta{function} \meta{parameters} \Arg{code}
%   \end{syntax}
%   Globally sets \meta{function} to expand to \meta{code} as replacement
%   text. Within the \meta{code}, the \meta{parameters} (|#1|, |#2|,
%   \emph{etc.}) will be replaced by those absorbed by the function.
%   The assignment of a meaning to the \meta{function} is \emph{not}
%   restricted to the current \TeX{} group level: the assignment is
%   global. The \meta{function} will not expand within an
%   \texttt{x}-type argument.
% \end{function}
%
% \begin{function}
%   {
%     \cs_gset_protected_nopar:Npn, \cs_gset_protected_nopar:cpn,
%     \cs_gset_protected_nopar:Npx, \cs_gset_protected_nopar:cpx
%   }
%   \begin{syntax}
%     \cs{cs_gset_protected_nopar:Npn} \meta{function} \meta{parameters} \Arg{code}
%   \end{syntax}
%   Globally sets \meta{function} to expand to \meta{code} as replacement
%   text. Within the \meta{code}, the \meta{parameters} (|#1|, |#2|,
%   \emph{etc.}) will be replaced by those absorbed by the function.
%   When the \meta{function} is used the \meta{parameters} absorbed
%   cannot contain \cs{par} tokens. The assignment of a meaning to the
%   \meta{function} is \emph{not} restricted to the current \TeX{}
%   group level: the assignment is global. The \meta{function} will
%   not expand within an \texttt{x}-type argument.
% \end{function}
%
% \subsection{Defining new functions using the signature}
% \label{sec:l3basics:defining-new-function-2}
%
% \begin{function}
%   {
%     \cs_new:Nn, \cs_new:cn,
%     \cs_new:Nx, \cs_new:cx
%   }
%   \begin{syntax}
%     \cs{cs_new:Nn} \meta{function} \Arg{code}
%   \end{syntax}
%   Creates \meta{function} to expand to \meta{code} as replacement text.
%   Within the \meta{code}, the number of \meta{parameters} is detected
%   automatically from the function signature. These \meta{parameters}
%   (|#1|, |#2|, \emph{etc.}) will be replaced by those absorbed by the
%   function. The definition is global and
%   an error will result if the \meta{function} is already defined.
% \end{function}
%
% \begin{function}
%   {
%     \cs_new_nopar:Nn, \cs_new_nopar:cn,
%     \cs_new_nopar:Nx, \cs_new_nopar:cx
%   }
%   \begin{syntax}
%     \cs{cs_new_nopar:Nn} \meta{function} \Arg{code}
%   \end{syntax}
%   Creates \meta{function} to expand to \meta{code} as replacement text.
%   Within the \meta{code}, the number of \meta{parameters} is detected
%   automatically from the function signature. These \meta{parameters}
%   (|#1|, |#2|, \emph{etc.}) will be replaced by those absorbed by the
%   function.  When the \meta{function} is used the \meta{parameters}
%   absorbed cannot contain \cs{par} tokens. The definition is global and
%   an error will result if the \meta{function} is already defined.
% \end{function}
%
% \begin{function}
%   {
%     \cs_new_protected:Nn, \cs_new_protected:cn,
%     \cs_new_protected:Nx, \cs_new_protected:cx
%   }
%   \begin{syntax}
%     \cs{cs_new_protected:Nn} \meta{function} \Arg{code}
%   \end{syntax}
%   Creates \meta{function} to expand to \meta{code} as replacement text.
%   Within the \meta{code}, the number of \meta{parameters} is detected
%   automatically from the function signature. These \meta{parameters}
%   (|#1|, |#2|, \emph{etc.}) will be replaced by those absorbed by the
%   function. The \meta{function} will not expand within an \texttt{x}-type
%   argument. The definition is global and
%   an error will result if the \meta{function} is already defined.
% \end{function}
%
% \begin{function}
%   {
%     \cs_new_protected_nopar:Nn, \cs_new_protected_nopar:cn,
%     \cs_new_protected_nopar:Nx, \cs_new_protected_nopar:cx
%   }
%   \begin{syntax}
%     \cs{cs_new_protected_nopar:Nn} \meta{function} \Arg{code}
%   \end{syntax}
%   Creates \meta{function} to expand to \meta{code} as replacement text.
%   Within the \meta{code}, the number of \meta{parameters} is detected
%   automatically from the function signature. These \meta{parameters}
%   (|#1|, |#2|, \emph{etc.}) will be replaced by those absorbed by the
%   function.  When the \meta{function} is used the \meta{parameters}
%   absorbed cannot contain \cs{par} tokens. The \meta{function} will not
%   expand within an \texttt{x}-type argument. The definition is global and
%   an error will result if the \meta{function} is already defined.
% \end{function}
%
% \begin{function}
%   {
%     \cs_set:Nn, \cs_set:cn,
%     \cs_set:Nx, \cs_set:cx
%   }
%   \begin{syntax}
%     \cs{cs_set:Nn} \meta{function} \Arg{code}
%   \end{syntax}
%   Sets \meta{function} to expand to \meta{code} as replacement text.
%   Within the \meta{code}, the number of \meta{parameters} is detected
%   automatically from the function signature. These \meta{parameters}
%   (|#1|, |#2|, \emph{etc.}) will be replaced by those absorbed by the
%   function.
%   The assignment of a meaning to the \meta{function} is restricted to
%   the current \TeX{} group level.
% \end{function}
%
% \begin{function}
%   {
%     \cs_set_nopar:Nn, \cs_set_nopar:cn,
%     \cs_set_nopar:Nx, \cs_set_nopar:cx
%   }
%   \begin{syntax}
%     \cs{cs_set_nopar:Nn} \meta{function} \Arg{code}
%   \end{syntax}
%   Sets \meta{function} to expand to \meta{code} as replacement text.
%   Within the \meta{code}, the number of \meta{parameters} is detected
%   automatically from the function signature. These \meta{parameters}
%   (|#1|, |#2|, \emph{etc.}) will be replaced by those absorbed by the
%   function.  When the \meta{function} is used the \meta{parameters}
%   absorbed cannot contain \cs{par} tokens.
%   The assignment of a meaning to the \meta{function} is restricted to
%   the current \TeX{} group level.
% \end{function}
%
% \begin{function}
%   {
%     \cs_set_protected:Nn, \cs_set_protected:cn,
%     \cs_set_protected:Nx, \cs_set_protected:cx
%   }
%   \begin{syntax}
%     \cs{cs_set_protected:Nn} \meta{function} \Arg{code}
%   \end{syntax}
%   Sets \meta{function} to expand to \meta{code} as replacement text.
%   Within the \meta{code}, the number of \meta{parameters} is detected
%   automatically from the function signature. These \meta{parameters}
%   (|#1|, |#2|, \emph{etc.}) will be replaced by those absorbed by the
%   function. The \meta{function} will not expand within an \texttt{x}-type
%   argument.
%   The assignment of a meaning to the \meta{function} is restricted to
%   the current \TeX{} group level.
% \end{function}
%
% \begin{function}
%   {
%     \cs_set_protected_nopar:Nn, \cs_set_protected_nopar:cn,
%     \cs_set_protected_nopar:Nx, \cs_set_protected_nopar:cx
%   }
%   \begin{syntax}
%     \cs{cs_set_protected_nopar:Nn} \meta{function} \Arg{code}
%   \end{syntax}
%   Sets \meta{function} to expand to \meta{code} as replacement text.
%   Within the \meta{code}, the number of \meta{parameters} is detected
%   automatically from the function signature. These \meta{parameters}
%   (|#1|, |#2|, \emph{etc.}) will be replaced by those absorbed by the
%   function.  When the \meta{function} is used the \meta{parameters}
%   absorbed cannot contain \cs{par} tokens. The \meta{function} will not
%   expand within an \texttt{x}-type argument.
%   The assignment of a meaning to the \meta{function} is restricted to
%   the current \TeX{} group level.
% \end{function}
%
% \begin{function}
%   {
%     \cs_gset:Nn, \cs_gset:cn,
%     \cs_gset:Nx, \cs_gset:cx
%   }
%   \begin{syntax}
%     \cs{cs_gset:Nn} \meta{function} \Arg{code}
%   \end{syntax}
%   Sets \meta{function} to expand to \meta{code} as replacement text.
%   Within the \meta{code}, the number of \meta{parameters} is detected
%   automatically from the function signature. These \meta{parameters}
%   (|#1|, |#2|, \emph{etc.}) will be replaced by those absorbed by the
%   function.
%   The assignment of a meaning to the \meta{function} is  global.
% \end{function}
%
% \begin{function}
%   {
%     \cs_gset_nopar:Nn, \cs_gset_nopar:cn,
%     \cs_gset_nopar:Nx, \cs_gset_nopar:cx
%   }
%   \begin{syntax}
%     \cs{cs_gset_nopar:Nn} \meta{function} \Arg{code}
%   \end{syntax}
%   Sets \meta{function} to expand to \meta{code} as replacement text.
%   Within the \meta{code}, the number of \meta{parameters} is detected
%   automatically from the function signature. These \meta{parameters}
%   (|#1|, |#2|, \emph{etc.}) will be replaced by those absorbed by the
%   function.  When the \meta{function} is used the \meta{parameters}
%   absorbed cannot contain \cs{par} tokens.
%   The assignment of a meaning to the \meta{function} is global.
% \end{function}
%
% \begin{function}
%   {
%     \cs_gset_protected:Nn, \cs_gset_protected:cn,
%     \cs_gset_protected:Nx, \cs_gset_protected:cx
%   }
%   \begin{syntax}
%     \cs{cs_gset_protected:Nn} \meta{function} \Arg{code}
%   \end{syntax}
%   Sets \meta{function} to expand to \meta{code} as replacement text.
%   Within the \meta{code}, the number of \meta{parameters} is detected
%   automatically from the function signature. These \meta{parameters}
%   (|#1|, |#2|, \emph{etc.}) will be replaced by those absorbed by the
%   function. The \meta{function} will not expand within an \texttt{x}-type
%   argument.
%   The assignment of a meaning to the \meta{function} is  global.
% \end{function}
%
% \begin{function}
%   {
%     \cs_gset_protected_nopar:Nn, \cs_gset_protected_nopar:cn,
%     \cs_gset_protected_nopar:Nx, \cs_gset_protected_nopar:cx
%   }
%   \begin{syntax}
%     \cs{cs_gset_protected_nopar:Nn} \meta{function} \Arg{code}
%   \end{syntax}
%   Sets \meta{function} to expand to \meta{code} as replacement text.
%   Within the \meta{code}, the number of \meta{parameters} is detected
%   automatically from the function signature. These \meta{parameters}
%   (|#1|, |#2|, \emph{etc.}) will be replaced by those absorbed by the
%   function.  When the \meta{function} is used the \meta{parameters}
%   absorbed cannot contain \cs{par} tokens. The \meta{function} will not
%   expand within an \texttt{x}-type argument.
%   The assignment of a meaning to the \meta{function} is global.
% \end{function}
%
% \begin{function}[updated = 2012-01-14]
%   {
%     \cs_generate_from_arg_count:NNnn,
%     \cs_generate_from_arg_count:cNnn,
%     \cs_generate_from_arg_count:Ncnn
%   }
%   \begin{syntax}
%     \cs{cs_generate_from_arg_count:NNnn} \meta{function} \meta{creator} \meta{number} \meta{code}
%   \end{syntax}
%   Uses the \meta{creator} function (which should have signature
%   |Npn|, for example \cs{cs_new:Npn}) to define a \meta{function}
%   which takes \meta{number} arguments and has \meta{code} as
%   replacement text. The \meta{number} of arguments is an integer expression,
%   evaluated as detailed for \cs{int_eval:n}.
% \end{function}
%
% \subsection{Copying control sequences}
%
% Control sequences (not just functions as defined above) can
% be set to have the same meaning using the functions described
% here. Making two control sequences equivalent means that the
% second control sequence is a \emph{copy} of the first (rather than
% a pointer to it). Thus the old and new control sequence are not
% tied together: changes to one are not reflected in the other.
%
% In the following text \enquote{cs} is used as an abbreviation for
% \enquote{control sequence}.
%
% \begin{function}
%   {\cs_new_eq:NN, \cs_new_eq:Nc, \cs_new_eq:cN, \cs_new_eq:cc}
%   \begin{syntax}
%     \cs{cs_new_eq:NN} \meta{cs_1} \meta{cs_2}
%     \cs{cs_new_eq:NN} \meta{cs_1} \meta{token}
%   \end{syntax}
%   Globally creates \meta{control sequence_1} and sets it to have the same
%   meaning as \meta{control sequence_2} or <token>.
%   The second control sequence may
%   subsequently be altered without affecting the copy.
% \end{function}
%
% \begin{function}
%   {\cs_set_eq:NN, \cs_set_eq:Nc, \cs_set_eq:cN, \cs_set_eq:cc}
%   \begin{syntax}
%     \cs{cs_set_eq:NN} \meta{cs_1} \meta{cs_2}
%     \cs{cs_set_eq:NN} \meta{cs_1} \meta{token}
%   \end{syntax}
%   Sets \meta{control sequence_1} to have the same meaning as
%   \meta{control sequence_2} (or <token>).
%   The second control sequence may subsequently be
%   altered without affecting the copy. The assignment of a meaning
%   to the \meta{control sequence_1} is restricted to the current
%   \TeX{} group level.
% \end{function}
%
% \begin{function}
%   {\cs_gset_eq:NN, \cs_gset_eq:Nc, \cs_gset_eq:cN, \cs_gset_eq:cc}
%   \begin{syntax}
%     \cs{cs_gset_eq:NN} \meta{cs_1} \meta{cs_2}
%     \cs{cs_gset_eq:NN} \meta{cs_1} \meta{token}
%   \end{syntax}
%   Globally sets \meta{control sequence_1} to have the same meaning as
%   \meta{control sequence_2} (or <token>).
%   The second control sequence may subsequently be
%   altered without affecting the copy. The assignment of a meaning to
%   the \meta{control sequence_1} is \emph{not} restricted to the current
%   \TeX{} group level: the assignment is global.
% \end{function}
%
% \subsection{Deleting control sequences}
%
% There are occasions where control sequences need to be deleted.
% This is handled in a very simple manner.
%
% \begin{function}[updated = 2011-09-15]{\cs_undefine:N, \cs_undefine:c}
%   \begin{syntax}
%     \cs{cs_undefine:N} \meta{control sequence}
%   \end{syntax}
%   Sets \meta{control sequence} to be globally undefined.
% \end{function}
%
% \subsection{Showing control sequences}
%
% \begin{function}[EXP, updated = 2011-12-22]{\cs_meaning:N, \cs_meaning:c}
%   \begin{syntax}
%     \cs{cs_meaning:N} \meta{control sequence}
%   \end{syntax}
%   This function expands to the \emph{meaning} of the \meta{control sequence}
%   control sequence. This will show the \meta{replacement text} for a
%   macro.
%   \begin{texnote}
%     This is \TeX{}'s \tn{meaning} primitive.
%     The \texttt{c} variant correctly reports undefined arguments.
%   \end{texnote}
% \end{function}
%
% \begin{function}[updated = 2012-09-09]{\cs_show:N, \cs_show:c}
%   \begin{syntax}
%     \cs{cs_show:N} \meta{control sequence}
%   \end{syntax}
%   Displays the definition of the \meta{control sequence} on the
%   terminal.
%   \begin{texnote}
%     This is similar to the \TeX{} primitive \tn{show}, wrapped to a
%     fixed number of characters per line.
%   \end{texnote}
% \end{function}
%
% \subsection{Converting to and from control sequences}
%
% \begin{function}[EXP]{\use:c}
%   \begin{syntax}
%     \cs{use:c} \Arg{control sequence name}
%   \end{syntax}
%   Converts the given \meta{control sequence name} into a single
%   control sequence token. This process requires two expansions.
%   The content for \meta{control sequence name} may be literal
%   material or from other expandable functions. The
%   \meta{control sequence name} must, when fully expanded, consist
%   of character tokens which are not active: typically, they will
%   be of category code $10$ (space), $11$ (letter)
%   or $12$ (other), or a mixture of these.
% \end{function}
%
% As an example of the \cs{use:c} function, both
%   \begin{verbatim}
%     \use:c { a b c }
%   \end{verbatim}
%   and
%   \begin{verbatim}
%     \tl_new:N  \l_my_tl
%     \tl_set:Nn \l_my_tl { a b c }
%     \use:c { \tl_use:N \l_my_tl }
%   \end{verbatim}
%   would be equivalent to
%   \begin{verbatim}
%     \abc
%   \end{verbatim}
%   after two expansions of \cs{use:c}.
%   
% \begin{function}[TF, added = 2012-11-10]
%   {\cs_if_exist_use:N,\cs_if_exist_use:c}
%   \begin{syntax}
%     \cs{cs_if_exist_use:N} \meta{control sequence}
%   \end{syntax}
%   Tests whether the \meta{control sequence} is currently defined
%   (whether as a function or another control sequence type), and if it
%   does inserts the  \meta{control sequence} into the input stream.
% \end{function}
%   
% \begin{function}[TF,EXP, added = 2012-11-10]
%   {\cs_if_exist_use:N,\cs_if_exist_use:c}
%   \begin{syntax}
%     \cs{cs_if_exist_use:NTF} \meta{control sequence} \Arg{true code} \Arg{false code}
%   \end{syntax}
%   Tests whether the \meta{control sequence} is currently defined
%   (whether as a function or another control sequence type), and if it
%   does inserts the  \meta{control sequence} into the input stream followed
%   by the \meta{true code}.
% \end{function}
%
% \begin{function}[EXP]{\cs:w, \cs_end:}
%   \begin{syntax}
%     \cs{cs:w} \meta{control sequence name} \cs{cs_end:}
%   \end{syntax}
%   Converts the given \meta{control sequence name} into a single
%   control sequence token. This process requires one expansion.
%   The content for \meta{control sequence name} may be literal
%   material or from other expandable functions. The
%   \meta{control sequence name} must, when fully expanded, consist
%   of character tokens which are not active: typically, they will
%   be of category code $10$ (space), $11$ (letter)
%   or $12$ (other), or a mixture of these.
%   \begin{texnote}
%     These are the \TeX{} primitives \tn{csname} and \tn{endcsname}.
%   \end{texnote}
% \end{function}
%
% As an example of the \cs{cs:w} and \cs{cs_end:} functions, both
%   \begin{verbatim}
%     \cs:w a b c \cs_end:
%   \end{verbatim}
%   and
%   \begin{verbatim}
%     \tl_new:N  \l_my_tl
%     \tl_set:Nn \l_my_tl { a b c }
%     \cs:w \tl_use:N \l_my_tl \cs_end:
%   \end{verbatim}
%   would be equivalent to
%   \begin{verbatim}
%     \abc
%   \end{verbatim}
%   after one expansion of \cs{cs:w}.
%
% \begin{function}[EXP]{\cs_to_str:N}
%   \begin{syntax}
%     \cs{cs_to_str:N} \meta{control sequence}
%   \end{syntax}
%   Converts the given \meta{control sequence} into a series of
%   characters with category code $12$ (other), except spaces,
%   of category code $10$. The sequence will \emph{not} include
%   the current escape token, \emph{cf.}~\cs{token_to_str:N}.
%   Full expansion of this function requires exactly $2$ expansion
%   steps, and so an \texttt{x}-type expansion, or two
%   \texttt{o}-type expansions will be required to
%   convert the \meta{control sequence} to a sequence of characters
%   in the input stream. In most cases, an \texttt{f}-expansion
%   will be correct as well, but this loses a space at the start
%   of the result.
% \end{function}
%
% \section{Using or removing tokens and arguments}
%
% Tokens in the input can be read and used or read and discarded.
% If one or more tokens are wrapped in braces then in absorbing them
% the outer set will be removed. At the same time, the category code
% of each token is set when the token is read by a function (if it
% is read more than once, the category code is determined by the
% the situation in force when first function absorbs the token).
%
% \begin{function}[EXP]{\use:n, \use:nn, \use:nnn, \use:nnnn}
%   \begin{syntax}
%     \cs{use:n}    \Arg{group_1}
%     \cs{use:nn}   \Arg{group_1} \Arg{group_2}
%     \cs{use:nnn}  \Arg{group_1} \Arg{group_2} \Arg{group_3}
%     \cs{use:nnnn} \Arg{group_1} \Arg{group_2} \Arg{group_3} \Arg{group_4}
%   \end{syntax}
%   As illustrated, these functions will absorb between one and four
%   arguments, as indicated by the argument specifier. The braces
%   surrounding each argument will be removed leaving the remaining
%   tokens in the input stream. The category code of these tokens will
%   also be fixed by this process (if it has not already been by some
%   other absorption). All of these functions require only a single
%   expansion to operate, so that one expansion of
%   \begin{verbatim}
%     \use:nn { abc } { { def } }
%   \end{verbatim}
%   will result in the input stream containing
%   \begin{verbatim}
%     abc { def }
%   \end{verbatim}
%   \emph{i.e.} only the outer braces will be removed.
% \end{function}
%
% \begin{function}[EXP]{\use_i:nn, \use_ii:nn}
%    \begin{syntax}
%     \cs{use_i:nn} \Arg{arg_1} \Arg{arg_2}
%   \end{syntax}
%   These functions absorb two arguments from the input stream. The function
%   \cs{use_i:nn} discards the second argument, and leaves the content
%   of the first argument in the input stream. \cs{use_ii:nn} discards
%   the first argument and leaves the content of the second argument in
%   the input stream.
%   The category code
%   of these tokens will also be fixed (if it has not already been by
%   some other absorption). A single expansion is needed for the
%   functions to take effect.
% \end{function}
%
% \begin{function}[EXP]{\use_i:nnn, \use_ii:nnn, \use_iii:nnn}
%   \begin{syntax}
%     \cs{use_i:nnn} \Arg{arg_1} \Arg{arg_2} \Arg{arg_3}
%   \end{syntax}
%   These functions absorb three arguments from the input stream. The
%   function \cs{use_i:nnn} discards the second and third arguments, and
%   leaves the content of the first argument in the input stream.
%   \cs{use_ii:nnn} and \cs{use_iii:nnn} work similarly, leaving the
%   content of second or third arguments in the input stream, respectively.
%   The category code
%   of these tokens will also be fixed (if it has not already been by
%   some other absorption). A single expansion is needed for the
%   functions to take effect.
% \end{function}
%
% \begin{function}[EXP]
%   {\use_i:nnnn, \use_ii:nnnn, \use_iii:nnnn, \use_iv:nnnn}
%   \begin{syntax}
%     \cs{use_i:nnnn} \Arg{arg_1} \Arg{arg_2} \Arg{arg_3} \Arg{arg_4}
%   \end{syntax}
%   These functions absorb four arguments from the input stream. The
%   function \cs{use_i:nnnn} discards the second, third and fourth
%   arguments, and leaves the content of the first argument in the input
%   stream.
%   \cs{use_ii:nnnn}, \cs{use_iii:nnnn} and \cs{use_iv:nnnn} work similarly,
%   leaving the content of second, third or fourth arguments in the input
%   stream, respectively. The category code
%   of these tokens will also be fixed (if it has not already been by
%   some other absorption). A single expansion is needed for the
%   functions to take effect.
% \end{function}
%
% \begin{function}[EXP]{\use_i_ii:nnn}
%   \begin{syntax}
%     \cs{use_i_ii:nnn} \Arg{arg_1} \Arg{arg_2} \Arg{arg_3}
%   \end{syntax}
%   This functions will absorb three arguments and leave the content of the
%   first and second in the input stream. The category code of
%   these tokens will also be fixed (if it has not already been by
%   some other absorption). A single expansion is needed for the
%   functions to take effect. An example:
%   \begin{verbatim}
%     \use_i_ii:nnn { abc } { { def } } { ghi }
%   \end{verbatim}
%   will result in the input stream containing
%   \begin{verbatim}
%     abc { def }
%   \end{verbatim}
%   \emph{i.e.} the outer braces will be removed and the third group
%   will be removed.
% \end{function}
%
% \begin{function}[EXP]
%   {
%     \use_none:n         ,
%     \use_none:nn        ,
%     \use_none:nnn       ,
%     \use_none:nnnn      ,
%     \use_none:nnnnn     ,
%     \use_none:nnnnnn    ,
%     \use_none:nnnnnnn   ,
%     \use_none:nnnnnnnn  ,
%     \use_none:nnnnnnnnn
%   }
%   \begin{syntax}
%     \cs{use_none:n} \Arg{group_1}
%   \end{syntax}
%   These functions absorb between one and nine groups from the
%   input stream, leaving nothing on the resulting input stream.
%   These functions work after a single expansion. One or more of the
%   \texttt{n} arguments may be an unbraced single token
%   (\emph{i.e.}~an \texttt{N} argument).
% \end{function}
%
% \begin{function}[updated = 2011-12-31]{\use:x}
%   \begin{syntax}
%     \cs{use:x} \Arg{expandable tokens}
%   \end{syntax}
%   Fully expands the \meta{expandable tokens} and inserts the
%   result into the input stream at the current location.
%   Any hash characters (|#|) in the argument must be doubled.
% \end{function}
%
% \subsection{Selecting tokens from delimited arguments}
%
% A different kind of function for selecting tokens from the token
% stream are those that use delimited arguments.
%
% \begin{function}[EXP]
%   {
%     \use_none_delimit_by_q_nil:w,
%     \use_none_delimit_by_q_stop:w,
%     \use_none_delimit_by_q_recursion_stop:w
%   }
%   \begin{syntax}
%    \cs{use_none_delimit_by_q_nil:w} \meta{balanced text} \cs{q_nil}
%    \cs{use_none_delimit_by_q_stop:w} \meta{balanced text} \cs{q_stop}
%    \cs{use_none_delimit_by_q_recursion_stop:w} \meta{balanced text} \cs{q_recursion_stop}
%   \end{syntax}
%   Absorb the \meta{balanced text} form the input stream delimited by
%   the marker given in the function name, leaving nothing in the
%   input stream.
% \end{function}
%
% \begin{function}[EXP]
%   {
%     \use_i_delimit_by_q_nil:nw,
%     \use_i_delimit_by_q_stop:nw,
%     \use_i_delimit_by_q_recursion_stop:nw
%   }
%   \begin{syntax}
%    \cs{use_i_delimit_by_q_nil:nw} \Arg{inserted tokens} \meta{balanced text} \cs{q_nil}
%    \cs{use_i_delimit_by_q_stop:nw} \Arg{inserted tokens} \meta{balanced text} \cs{q_stop}
%    \cs{use_i_delimit_by_q_recursion_stop:nw} \Arg{inserted tokens} \meta{balanced text} \cs{q_recursion_stop}
%   \end{syntax}
%   Absorb the \meta{balanced text} form the input stream delimited by
%   the marker given in the function name, leaving \meta{inserted tokens}
%   in the input stream for further processing.
% \end{function}
%
% \section{Predicates and conditionals}
%
% \LaTeX3 has three concepts for conditional flow processing:
% \begin{description}
%   \item[Branching conditionals]
%     Functions that carry out a test and then execute, depending on its
%     result, either the code supplied as the \meta{true code} or the
%     \meta{false code}.
%     These arguments are denoted with |T| and |F|, respectively. An
%     example would be
%     \begin{quote}
%      |\cs_if_free:cTF {abc}| \Arg{true code} \Arg{false code}
%     \end{quote}
%     a function that will turn the first argument into a control sequence
%     (since it's marked as |c|) then checks whether this control sequence
%     is still free and then depending on the result carry out the code in
%     the second argument (true case) or in the third argument (false
%     case).
%
%     These type of functions are known as \enquote{conditionals};
%     whenever a |TF| function is defined it will usually be accompanied by
%     |T| and |F| functions as well. These are provided for convenience when
%     the branch only needs to go a single way. Package writers are free to
%     choose which types to define but the kernel definitions will always
%     provide all three versions.
%
%     Important to note is that these branching conditionals with \meta{true
%     code} and/or \meta{false code} are always defined in a way that the
%     code of the chosen alternative can operate on following tokens in
%     the input stream.
%
%     These conditional functions may or may not be fully expandable, but if
%     they are expandable they will be accompanied by a \enquote{predicate}
%     for the same test as described below.
%
%   \item[Predicates]
%     \enquote{Predicates} are functions that return a special type of
%     boolean value which can be tested by the boolean expression parser.
%     All functions of this type
%     are expandable and have names that end with |_p| in the
%     description part.  For example,
%     \begin{quote}
%       \cs{cs_if_free_p:N}
%     \end{quote}
%     would be a predicate function for the same type of test as the
%     conditional described above. It would return \enquote{true} if its
%     argument (a single token denoted by |N|) is still free for definition.
%     It would be used in constructions like
%     \begin{quote}
%       |\bool_if:nTF {| \\
%       \verb"  \cs_if_free_p:N \l_tmpz_tl || \cs_if_free_p:N \g_tmpz_tl " \\
%       |}|
%       \Arg{true code} \Arg{false code}
%     \end{quote}
%
%     For each predicate defined, a \enquote{branching conditional} will
%     also exist that behaves like a conditional described above.
%
%   \item[Primitive conditionals]
%      There is a third variety of conditional, which is the original
%      concept used in plain \TeX{} and \LaTeXe{}. Their use is discouraged
%      in \pkg{expl3} (although still used in low-level definitions)
%      because they are more fragile and in many cases require more
%      expansion control (hence more code) than the two types of
%      conditionals described above.
% \end{description}
%
% \begin{variable}{\c_true_bool, \c_false_bool}
%   Constants that represent |true| and |false|, respectively. Used to
%   implement predicates.
% \end{variable}
%
% \subsection{Tests on control sequences}
%
% \begin{function}[EXP,pTF]{\cs_if_eq:NN}
%   \begin{syntax}
%     \cs{cs_if_eq_p:NN} \Arg{cs_1} \Arg{cs_2}
%     \cs{cs_if_eq:NNTF} \Arg{cs_1} \Arg{cs_2} \Arg{true code} \Arg{false code}
%   \end{syntax}
%   Compares the definition of two \meta{control sequences} and
%   is logically \texttt{true} the same, \emph{i.e.}~if they have exactly
%   the same definition when examined with \cs{cs_show:N}.
% \end{function}
%
% \begin{function}[EXP,pTF]{\cs_if_exist:N, \cs_if_exist:c}
%   \begin{syntax}
%     \cs{cs_if_exist_p:N} \meta{control sequence}
%     \cs{cs_if_exist:NTF} \meta{control sequence} \Arg{true code} \Arg{false code}
%   \end{syntax}
%   Tests whether the \meta{control sequence} is currently defined
%   (whether as a function or another control sequence type). Any
%   valid definition of \meta{control sequence} will evaluate as
%   \texttt{true}.
% \end{function}
%
% \begin{function}[EXP,pTF]{\cs_if_free:N, \cs_if_free:c}
%   \begin{syntax}
%     \cs{cs_if_free_p:N} \meta{control sequence}
%     \cs{cs_if_free:NTF} \meta{control sequence} \Arg{true code} \Arg{false code}
%   \end{syntax}
%   Tests whether the \meta{control sequence} is currently free to
%   be defined. This test will be \texttt{false} if the
%   \meta{control sequence} currently exists (as defined by
%   \cs{cs_if_exist:N}).
% \end{function}
%
% \subsection{Testing string equality}
%
% \begin{function}[EXP,pTF]
%   {
%     \str_if_eq:nn, \str_if_eq:Vn, \str_if_eq:on, \str_if_eq:no,
%     \str_if_eq:nV, \str_if_eq:VV
%   }
%   \begin{syntax}
%     \cs{str_if_eq_p:nn} \Arg{tl_1} \Arg{tl_2}
%     \cs{str_if_eq:nnTF} \Arg{tl_1} \Arg{tl_2} \Arg{true code} \Arg{false code}
%   \end{syntax}
%   Compares the two \meta{token lists} on a character by character
%   basis, and is \texttt{true} if the two lists contain the same
%   characters in the same order. Thus for example
%   \begin{verbatim}
%     \str_if_eq_p:no { abc } { \tl_to_str:n { abc } }
%   \end{verbatim}
%   is logically \texttt{true}.
% \end{function}
%
% \begin{function}[EXP,pTF, added = 2012-06-05]{\str_if_eq_x:nn}
%   \begin{syntax}
%     \cs{str_if_eq_x_p:nn} \Arg{tl_1} \Arg{tl_2}
%     \cs{str_if_eq_x:nnTF} \Arg{tl_1} \Arg{tl_2} \Arg{true code} \Arg{false code}
%   \end{syntax}
%   Compares the full expansion of two \meta{token lists} on a character by
%   character basis, and is \texttt{true} if the two lists contain the same
%   characters in the same order. Thus for example
%   \begin{verbatim}
%     \str_if_eq_x_p:nn { abc } { \tl_to_str:n { abc } }
%   \end{verbatim}
%   is logically \texttt{true}.
% \end{function}
%
% \begin{function}[added = 2013-07-24, EXP, TF]{\str_case:nn, \str_case:on}
%   \begin{syntax}
%     \cs{str_case:nnTF} \Arg{test string} \\
%     ~~|{| \\
%     ~~~~\Arg{string case_1} \Arg{code case_1} \\
%     ~~~~\Arg{string case_2} \Arg{code case_2} \\
%     ~~~~\ldots \\
%     ~~~~\Arg{string case_n} \Arg{code case_n} \\
%     ~~|}| \\
%     ~~\Arg{true code}
%     ~~\Arg{false code}
%   \end{syntax}
%   This function compares the \meta{test string} in turn with each
%   of the \meta{string cases}. If the two are equal (as described for
%   \cs{str_if_eq:nnTF} then the
%   associated \meta{code} is left in the input stream. If any of the
%   cases are matched, the \meta{true code} is also inserted into the
%   input stream (after the code for the appropriate case), while if none
%   match then the \meta{false code} is inserted. The function
%   \cs{str_case:nn}, which does nothing if there is no match, is also
%   available.
% \end{function}
%
% \begin{function}[added = 2013-07-24, EXP, TF]{\str_case_x:nn}
%   \begin{syntax}
%     \cs{str_case_x:nnn} \Arg{test string} \\
%     ~~|{| \\
%     ~~~~\Arg{string case_1} \Arg{code case_1} \\
%     ~~~~\Arg{string case_2} \Arg{code case_2} \\
%     ~~~~\ldots \\
%     ~~~~\Arg{string case_n} \Arg{code case_n} \\
%     ~~|}| \\
%     ~~\Arg{true code}
%     ~~\Arg{false code}
%   \end{syntax}
%   This function compares the full expansion of the \meta{test string}
%   in turn with the full expansion of the \meta{string cases}. If the two
%   full expansions are equal (as described for \cs{str_if_eq:nnTF} then the
%   associated \meta{code} is left in the input stream.  If any of the
%   cases are matched, the \meta{true code} is also inserted into the
%   input stream (after the code for the appropriate case), while if none
%   match then the \meta{false code} is inserted. The function
%   \cs{str_case_x:nn}, which does nothing if there is no match, is also
%   available.
%   The \meta{test string} is expanded in each comparison, and must
%   always yield the same result: for example, random numbers must
%   not be used within this string.
% \end{function}
%
% \subsection{Engine-specific conditionals}
%
% \begin{function}[updated = 2011-09-06,EXP,pTF]{\luatex_if_engine:}
%   \begin{syntax}
%     \cs{luatex_if_engine:TF} \Arg{true code} \Arg{false code}
%   \end{syntax}
%   Detects is the document is being compiled using \LuaTeX{}.
% \end{function}
%
% \begin{function}[updated = 2011-09-06,EXP,pTF]{\pdftex_if_engine:}
%   \begin{syntax}
%     \cs{pdftex_if_engine:TF} \Arg{true code} \Arg{false code}
%   \end{syntax}
%   Detects is the document is being compiled using \pdfTeX{}.
% \end{function}
%
% \begin{function}[updated = 2011-09-06,EXP,pTF]{\xetex_if_engine:}
%   \begin{syntax}
%     \cs{xetex_if_engine:TF} \Arg{true code} \Arg{false code}
%   \end{syntax}
%   Detects is the document is being compiled using \XeTeX{}.
% \end{function}
%
% \subsection{Primitive conditionals}
%
% The \eTeX{} engine itself provides many different conditionals. Some
% expand whatever comes after them and others don't. Hence the names
% for these underlying functions will often contain a |:w| part but
% higher level functions are often available. See for instance
% \cs{int_compare_p:nNn} which is a wrapper for \cs{if_int_compare:w}.
%
% Certain conditionals deal with specific data types like boxes and
% fonts and are described there. The ones described below are either
% the universal conditionals or deal with control sequences. We will
% prefix primitive conditionals with |\if_|.
%
% \begin{function}[EXP]
%   {\if_true:, \if_false:, \or:, \else:, \fi:, \reverse_if:N}
%   \begin{syntax}
%     "\if_true:" <true code> "\else:" <false code> "\fi:" \\
%     "\if_false:" <true code> "\else:" <false code> "\fi:" \\
%     "\reverse_if:N" <primitive conditional>
%   \end{syntax}
%   "\if_true:" always executes <true code>, while "\if_false:" always
%   executes <false code>. "\reverse_if:N" reverses any two-way primitive
%   conditional. "\else:" and "\fi:" delimit the branches of the
%   conditional. "\or:" is used in case switches, see \pkg{l3int}
%   for more.
%   \begin{texnote}
%     These are equivalent to their corresponding \TeX\ primitive
%     conditionals; \cs{reverse_if:N} is \eTeX's \tn{unless}.
%   \end{texnote}
% \end{function}
%
% \begin{function}[EXP]{\if_meaning:w}
%   \begin{syntax}
%     "\if_meaning:w" <arg_1> <arg_2> <true code> "\else:" <false code> "\fi:"
%   \end{syntax}
%   "\if_meaning:w" executes <true code> when <arg_1> and <arg_2> are the same,
%   otherwise it executes <false code>.
%   <arg_1> and <arg_2> could be functions, variables, tokens; in all cases the
%   \emph{unexpanded} definitions are compared.
%   \begin{texnote}
%     This is \TeX{}'s \tn{ifx}.
%   \end{texnote}
% \end{function}
%
% \begin{function}[EXP]{\if:w, \if_charcode:w,\if_catcode:w}
%   \begin{syntax}
%     "\if:w" <token_1> <token_2> <true code> "\else:" <false code> "\fi:" \\
%     "\if_catcode:w" <token_1> <token_2> <true code> "\else:" <false code> "\fi:"
%   \end{syntax}
%   These conditionals will expand any following tokens until two
%   unexpandable tokens are left. If you wish to prevent this expansion,
%   prefix the token in question with "\exp_not:N". "\if_catcode:w"
%   tests if the category codes of the two tokens are the same whereas
%   "\if:w" tests if the character codes are
%   identical. "\if_charcode:w" is an alternative name for "\if:w".
% \end{function}
%
% \begin{function}[EXP]{\if_cs_exist:N, \if_cs_exist:w}
%   \begin{syntax}
%     "\if_cs_exist:N" <cs> <true code> "\else:" <false code> "\fi:" \\
%     "\if_cs_exist:w" <tokens> "\cs_end:" <true code> "\else:" <false code> "\fi:"
%   \end{syntax}
%   Check if <cs> appears in the hash table or if the control sequence
%   that can be formed from <tokens> appears in the hash table. The
%   latter function does not turn the control sequence in question into
%   "\scan_stop:"! This can be useful when dealing with control
%   sequences which cannot be entered as a single token.
% \end{function}
%
% \begin{function}[EXP]
%   {
%     \if_mode_horizontal:, \if_mode_vertical:,
%     \if_mode_math:, \if_mode_inner:
%   }
%   \begin{syntax}
%     "\if_mode_horizontal:" <true code> "\else:" <false code> "\fi:"
%   \end{syntax}
%   Execute <true code> if currently in horizontal mode, otherwise
%   execute <false code>. Similar for the other functions.
% \end{function}
%
% \section{Internal kernel functions}
%
% \begin{function}{\__chk_if_exist_cs:N, \__chk_if_exist_cs:c}
%   \begin{syntax}
%     \cs{__chk_if_exist_cs:N} \meta{cs}
%   \end{syntax}
%   This function checks that \meta{cs} exists according to the
%   criteria for \cs{cs_if_exist_p:N}, and if not raises a kernel-level
%   error.
% \end{function}
%
% \begin{function}{\__chk_if_free_cs:N, \__chk_if_free_cs:c}
%   \begin{syntax}
%     \cs{__chk_if_free_cs:N} \meta{cs}
%   \end{syntax}
%   This function checks that \meta{cs} is free according to the
%   criteria for \cs{cs_if_free_p:N}, and if not raises a kernel-level
%   error.
% \end{function}
%
% \begin{function}[EXP]{\__cs_count_signature:N, \__cs_count_signature:c}
%   \begin{syntax}
%     \cs{__cs_count_signature:N} \meta{function}
%   \end{syntax}
%   Splits the \meta{function} into the \meta{name} (\emph{i.e.}~the part
%   before the colon) and the \meta{signature} (\emph{i.e.}~after the colon).
%   The \meta{number} of tokens in the \meta{signature} is then left in
%   the input stream. If there was no \meta{signature} then the result is
%   the marker value $-1$.
% \end{function}
%
% \begin{function}[EXP]{\__cs_split_function:NN}
%   \begin{syntax}
%     \cs{__cs_split_function:NN} \meta{function} \meta{processor}
%   \end{syntax}
%   Splits the \meta{function} into the \meta{name} (\emph{i.e.}~the part
%   before the colon) and the \meta{signature} (\emph{i.e.}~after the colon).
%   This information is then placed in the input stream after the
%   \meta{processor} function in three parts: the \meta{name}, the
%   \meta{signature} and a logic token indicating if a colon was found
%   (to differentiate variables from function names). The \meta{name}
%   will not include the escape character, and both the \meta{name} and
%   \meta{signature} are made up of tokens with category code $12$
%   (other). The \meta{processor} should be a function with argument
%   specification \texttt{:nnN} (plus any trailing arguments needed).
% \end{function}
%
% \begin{function}[EXP]{\__cs_get_function_name:N}
%   \begin{syntax}
%     \cs{__cs_get_function_name:N} \meta{function}
%   \end{syntax}
%   Splits the \meta{function} into the \meta{name} (\emph{i.e.}~the part
%   before the colon) and the \meta{signature} (\emph{i.e.}~after the colon).
%   The \meta{name} is then left in the input stream without the escape
%   character present made up of tokens with category code $12$
%   (other).
% \end{function}
%
% \begin{function}[EXP]{\__cs_get_function_signature:N}
%   \begin{syntax}
%     \cs{__cs_get_function_signature:N} \meta{function}
%   \end{syntax}
%   Splits the \meta{function} into the \meta{name} (\emph{i.e.}~the part
%   before the colon) and the \meta{signature} (\emph{i.e.}~after the colon).
%   The \meta{signature} is then left in the input stream made up of
%   tokens with category code $12$ (other).
% \end{function}
%
% \begin{function}{\__cs_tmp:w}
%   Function used for various short-term usages, for instance defining
%   functions whose definition involves tokens which are hard to insert
%   normally (spaces, characters with category other).
% \end{function}
%
% \begin{function}{\__kernel_register_show:N, \__kernel_register_show:c}
%   \begin{syntax}
%     \cs{__kernel_register_show:N} \meta{register}
%   \end{syntax}
%   Used to show the contents of a \TeX{} register at the terminal, formatted
%   such that internal parts of the mechanism are not visible.
% \end{function}
%
% \begin{function}{\__prg_case_end:nw}
%   \begin{syntax}
%     \cs{__prg_case_end:nw} \Arg{code} \meta{tokens} \cs{q_mark} \Arg{true code} \cs{q_mark} \Arg{false code}  \cs{q_stop}
%   \end{syntax}
%   Used to terminate case statements (\cs{int_case:nnTF}, \emph{etc.})
%   by removing trailing \meta{tokens} and the end marker
%   \cs{q_stop}, inserting the \meta{code} for the successful
%   case (if one is found) and either the \texttt{true code} or
%   \texttt{false code} for the over all outcome, as appropriate.
% \end{function}
%
% \begin{function}{\__str_if_eq_x_return:nn}
%   \begin{syntax}
%     \cs{__str_if_eq_x_return:nn} \Arg{tl_1} \Arg{tl_2}
%   \end{syntax}
%   Compares the full expansion of two \meta{token lists} on a character by
%   character basis, and is \texttt{true} if the two lists contain the same
%   characters in the same order. Either \cs{prg_return_true:} or
%   \cs{prg_return_false:} is then left in the input stream. This is a version
%   of \cs{str_if_eq_x:nn(TF)} coded for speed.
% \end{function}
%
% \end{documentation}
%
% \begin{implementation}
%
% \section{\pkg{l3basics} implementation}
%
%    \begin{macrocode}
%<*initex|package>
%    \end{macrocode}
%
%    \begin{macrocode}
%<*package>
\ProvidesExplPackage
  {\ExplFileName}{\ExplFileDate}{\ExplFileVersion}{\ExplFileDescription}
\__expl_package_check:
%</package>
%    \end{macrocode}
%
% \subsection{Renaming some \TeX{} primitives (again)}
%
% Having given all the \TeX{} primitives a consistent name, we need to
% give sensible names to the ones we actually want to use.
% These will be defined as needed in the appropriate modules, but
% do a few now, just to get started.\footnote{This renaming gets expensive
% in terms of csname usage, an alternative scheme would be to just use
% the \cs{tex\ldots:D} name in the cases where no good alternative exists.}
%
% \begin{macro}[EXP]
%   {
%     \if_true:, \if_false:, \or:, \else:, \fi:, \reverse_if:N,
%     \if:w, \if_charcode:w, \if_catcode:w, \if_meaning:w
%   }
%   Then some conditionals.
%    \begin{macrocode}
\tex_let:D \if_true:           \tex_iftrue:D
\tex_let:D \if_false:          \tex_iffalse:D
\tex_let:D \or:                \tex_or:D
\tex_let:D \else:              \tex_else:D
\tex_let:D \fi:                \tex_fi:D
\tex_let:D \reverse_if:N       \etex_unless:D
\tex_let:D \if:w               \tex_if:D
\tex_let:D \if_charcode:w      \tex_if:D
\tex_let:D \if_catcode:w       \tex_ifcat:D
\tex_let:D \if_meaning:w       \tex_ifx:D
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}[EXP]
%   {
%     \if_mode_math:,
%     \if_mode_horizontal:,
%     \if_mode_vertical:,
%     \if_mode_inner:
%   }
%   \TeX{} lets us detect some if its modes.
%    \begin{macrocode}
\tex_let:D \if_mode_math:       \tex_ifmmode:D
\tex_let:D \if_mode_horizontal: \tex_ifhmode:D
\tex_let:D \if_mode_vertical:   \tex_ifvmode:D
\tex_let:D \if_mode_inner:      \tex_ifinner:D
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}[EXP]{\if_cs_exist:N, \if_cs_exist:w, \cs:w, \cs_end:}
%   Building csnames and testing if control sequences exist.
%    \begin{macrocode}
\tex_let:D \if_cs_exist:N      \etex_ifdefined:D
\tex_let:D \if_cs_exist:w      \etex_ifcsname:D
\tex_let:D \cs:w               \tex_csname:D
\tex_let:D \cs_end:            \tex_endcsname:D
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}[EXP]{\exp_after:wN, \exp_not:N, \exp_not:n}
%    The three |\exp_| functions are used in the \textsf{l3expan} module
%    where they are described.
%    \begin{macrocode}
\tex_let:D \exp_after:wN       \tex_expandafter:D
\tex_let:D \exp_not:N          \tex_noexpand:D
\tex_let:D \exp_not:n          \etex_unexpanded:D
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}[EXP]{\token_to_meaning:N, \token_to_str:N, \cs_meaning:N}
%   Examining a control sequence or token.
%    \begin{macrocode}
\tex_let:D \token_to_meaning:N \tex_meaning:D
\tex_let:D \token_to_str:N     \tex_string:D
\tex_let:D \cs_meaning:N       \tex_meaning:D
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\scan_stop:, \group_begin:, \group_end:}
%    The next three are basic functions for which there also exist
%    versions that are safe inside alignments. These safe versions are
%    defined in the \textsf{l3prg} module.
%    \begin{macrocode}
\tex_let:D \scan_stop:         \tex_relax:D
\tex_let:D \group_begin:       \tex_begingroup:D
\tex_let:D \group_end:         \tex_endgroup:D
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}[EXP]{\if_int_compare:w, \__int_to_roman:w}
%   For integers.
%    \begin{macrocode}
\tex_let:D \if_int_compare:w   \tex_ifnum:D
\tex_let:D \__int_to_roman:w     \tex_romannumeral:D
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\group_insert_after:N}
%   Adding material after the end of a group.
%    \begin{macrocode}
\tex_let:D \group_insert_after:N \tex_aftergroup:D
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}[EXP]{\exp_args:Nc, \exp_args:cc}
%   Discussed in \pkg{l3expan}, but needed much earlier.
%    \begin{macrocode}
\tex_long:D \tex_def:D \exp_args:Nc #1#2
  { \exp_after:wN #1 \cs:w #2 \cs_end: }
\tex_long:D \tex_def:D \exp_args:cc #1#2
  { \cs:w #1 \exp_after:wN \cs_end: \cs:w #2 \cs_end: }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}[EXP]{\token_to_meaning:c, \token_to_str:c, \cs_meaning:c}
%   A small number of variants defined by hand.
%   Some of the necessary functions
%   (\cs{use_i:nn}, \cs{use_ii:nn}, and \cs{exp_args:NNc}) are not
%   defined at that point yet, but will be defined before those variants
%   are used.  The \cs{cs_meaning:c} command must check for an undefined
%   control sequence to avoid defining it mistakenly.
%    \begin{macrocode}
\tex_def:D \token_to_str:c { \exp_args:Nc \token_to_str:N }
\tex_long:D \tex_def:D \cs_meaning:c #1
  {
    \if_cs_exist:w #1 \cs_end:
      \exp_after:wN \use_i:nn
    \else:
      \exp_after:wN \use_ii:nn
    \fi:
    { \exp_args:Nc \cs_meaning:N {#1} }
    { \tl_to_str:n {undefined} }
  }
\tex_let:D \token_to_meaning:c = \cs_meaning:c
%    \end{macrocode}
% \end{macro}
%
% \subsection{Defining some constants}
%
% \begin{variable}{\c_minus_one, \c_zero, \c_sixteen}
% \begin{variable}{\c_six, \c_seven, \c_twelve}
%    We need the constants \cs{c_minus_one} and \cs{c_sixteen} now for
%    writing information to the log and the terminal and \cs{c_zero}
%    which is used by some functions in the \textsf{l3alloc} module. The
%    rest are defined in the \textsf{l3int} module -- at least for the
%    ones that can be defined with \cs{tex_chardef:D} or
%    \cs{tex_mathchardef:D}. For other constants the \textsf{l3int} module is
%    required but it can't be used until the allocation has been set
%    up properly! The actual allocation mechanism is in
%    \textsf{l3alloc} and as \TeX{} wants to reserve count registers
%    0--9, the first available one is~10 so we use that for
%    \cs{c_minus_one}.
%    \begin{macrocode}
%<*package>
\tex_let:D \c_minus_one \m@ne
%</package>
%<*initex>
\tex_countdef:D \c_minus_one = 10 ~
\c_minus_one = -1 ~
%</initex>
\tex_chardef:D \c_sixteen = 16 ~
\tex_chardef:D \c_zero    = 0 ~
\tex_chardef:D \c_six     = 6 ~
\tex_chardef:D \c_seven   = 7 ~
\tex_chardef:D \c_twelve  = 12 ~
%    \end{macrocode}
% \end{variable}
% \end{variable}
%
% \begin{variable}{\c_max_register_int}
%   This is here as this particular integer is needed both in package
%   mode and to bootstrap \pkg{l3alloc}, and is documented in \pkg{l3int}.
%    \begin{macrocode}
\etex_ifdefined:D \luatex_luatexversion:D
  \tex_chardef:D \c_max_register_int = 65 535 ~
\tex_else:D
  \tex_mathchardef:D \c_max_register_int = 32 767 ~
\tex_fi:D
%    \end{macrocode}
% \end{variable}
%
% \subsection{Defining functions}
%
% We start by providing functions for the typical definition
% functions. First the local ones.
%
% \begin{macro}
%   {
%     \cs_set_nopar:Npn           , \cs_set_nopar:Npx           ,
%     \cs_set:Npn                 , \cs_set:Npx                 ,
%     \cs_set_protected_nopar:Npn , \cs_set_protected_nopar:Npx ,
%     \cs_set_protected:Npn       , \cs_set_protected:Npx
%   }
%   All assignment functions in \LaTeX3 should be naturally protected;
%   after all, the \TeX{} primitives for assignments are and it can be
%   a cause of problems if others aren't.
%    \begin{macrocode}
\tex_let:D \cs_set_nopar:Npn            \tex_def:D
\tex_let:D \cs_set_nopar:Npx            \tex_edef:D
\etex_protected:D \cs_set_nopar:Npn \cs_set:Npn
  { \tex_long:D \cs_set_nopar:Npn }
\etex_protected:D \cs_set_nopar:Npn \cs_set:Npx
  { \tex_long:D \cs_set_nopar:Npx }
\etex_protected:D \cs_set_nopar:Npn \cs_set_protected_nopar:Npn
  { \etex_protected:D \cs_set_nopar:Npn }
\etex_protected:D \cs_set_nopar:Npn \cs_set_protected_nopar:Npx
  { \etex_protected:D \cs_set_nopar:Npx }
\cs_set_protected_nopar:Npn \cs_set_protected:Npn
  { \etex_protected:D \tex_long:D \cs_set_nopar:Npn }
\cs_set_protected_nopar:Npn \cs_set_protected:Npx
  { \etex_protected:D \tex_long:D \cs_set_nopar:Npx }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}
%   {
%     \cs_gset_nopar:Npn           , \cs_gset_nopar:Npx           ,
%     \cs_gset:Npn                 , \cs_gset:Npx                 ,
%     \cs_gset_protected_nopar:Npn , \cs_gset_protected_nopar:Npx ,
%     \cs_gset_protected:Npn       , \cs_gset_protected:Npx
%   }
%   Global versions of the above functions.
%    \begin{macrocode}
\tex_let:D \cs_gset_nopar:Npn           \tex_gdef:D
\tex_let:D \cs_gset_nopar:Npx           \tex_xdef:D
\cs_set_protected_nopar:Npn \cs_gset:Npn
  { \tex_long:D \cs_gset_nopar:Npn }
\cs_set_protected_nopar:Npn \cs_gset:Npx
  { \tex_long:D \cs_gset_nopar:Npx }
\cs_set_protected_nopar:Npn \cs_gset_protected_nopar:Npn
  { \etex_protected:D \cs_gset_nopar:Npn }
\cs_set_protected_nopar:Npn \cs_gset_protected_nopar:Npx
  { \etex_protected:D \cs_gset_nopar:Npx }
\cs_set_protected_nopar:Npn \cs_gset_protected:Npn
  { \etex_protected:D \tex_long:D \cs_gset_nopar:Npn }
\cs_set_protected_nopar:Npn \cs_gset_protected:Npx
  { \etex_protected:D \tex_long:D \cs_gset_nopar:Npx }
%    \end{macrocode}
% \end{macro}
%
% \subsection{Selecting tokens}
%
% \begin{variable}{\l__exp_internal_tl}
%   Scratch token list variable for \pkg{l3expan}, used by \cs{use:x},
%   used in defining conditionals.  We don't use |tl| methods because
%   \pkg{l3basics} is loaded earlier.
%    \begin{macrocode}
\cs_set_nopar:Npn \l__exp_internal_tl { }
%    \end{macrocode}
% \end{variable}
%
% \begin{macro}[EXP]{\use:c}
%    This macro grabs its argument and returns a csname from it.
%    \begin{macrocode}
\cs_set:Npn \use:c #1 { \cs:w #1 \cs_end: }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\use:x}
%   Fully expands its argument and passes it to the input stream. Uses
%   the reserved \cs{l__exp_internal_tl} which will be set up in \pkg{l3expan}.
%    \begin{macrocode}
\cs_set_protected:Npn \use:x #1
  {
    \cs_set_nopar:Npx \l__exp_internal_tl {#1}
    \l__exp_internal_tl
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}[EXP]{\use:n, \use:nn, \use:nnn, \use:nnnn}
%    These macros grab their arguments and returns them back to the input
%    (with outer braces removed).
%    \begin{macrocode}
\cs_set:Npn \use:n    #1       {#1}
\cs_set:Npn \use:nn   #1#2     {#1#2}
\cs_set:Npn \use:nnn  #1#2#3   {#1#2#3}
\cs_set:Npn \use:nnnn #1#2#3#4 {#1#2#3#4}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}[EXP]{\use_i:nn, \use_ii:nn}
%    The equivalent to \LaTeXe{}'s \tn{@firstoftwo} and \tn{@secondoftwo}.
%    \begin{macrocode}
\cs_set:Npn \use_i:nn  #1#2 {#1}
\cs_set:Npn \use_ii:nn #1#2 {#2}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}[EXP]
%   {
%     \use_i:nnn , \use_ii:nnn , \use_iii:nnn , \use_i_ii:nnn ,
%     \use_i:nnnn, \use_ii:nnnn, \use_iii:nnnn, \use_iv:nnnn
%   }
%   We also need something for picking up arguments from a longer list.
%    \begin{macrocode}
\cs_set:Npn \use_i:nnn    #1#2#3 {#1}
\cs_set:Npn \use_ii:nnn   #1#2#3 {#2}
\cs_set:Npn \use_iii:nnn  #1#2#3 {#3}
\cs_set:Npn \use_i_ii:nnn #1#2#3 {#1#2}
\cs_set:Npn \use_i:nnnn   #1#2#3#4 {#1}
\cs_set:Npn \use_ii:nnnn  #1#2#3#4 {#2}
\cs_set:Npn \use_iii:nnnn #1#2#3#4 {#3}
\cs_set:Npn \use_iv:nnnn  #1#2#3#4 {#4}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}[EXP]
%   {
%     \use_none_delimit_by_q_nil:w  ,
%     \use_none_delimit_by_q_stop:w ,
%     \use_none_delimit_by_q_recursion_stop:w
%   }
%   Functions that gobble everything until they see either \cs{q_nil},
%   \cs{q_stop}, or \cs{q_recursion_stop}, respectively.
%    \begin{macrocode}
\cs_set:Npn \use_none_delimit_by_q_nil:w  #1 \q_nil  { }
\cs_set:Npn \use_none_delimit_by_q_stop:w #1 \q_stop { }
\cs_set:Npn \use_none_delimit_by_q_recursion_stop:w #1 \q_recursion_stop { }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}
%   {
%     \use_i_delimit_by_q_nil:nw  ,
%     \use_i_delimit_by_q_stop:nw ,
%     \use_i_delimit_by_q_recursion_stop:nw
%   }
%   Same as above but execute first argument after gobbling. Very useful
%   when you need to skip the rest of a mapping sequence but want an
%   easy way to control what should be expanded next.
%    \begin{macrocode}
\cs_set:Npn \use_i_delimit_by_q_nil:nw  #1#2 \q_nil  {#1}
\cs_set:Npn \use_i_delimit_by_q_stop:nw #1#2 \q_stop {#1}
\cs_set:Npn \use_i_delimit_by_q_recursion_stop:nw #1#2 \q_recursion_stop {#1}
%    \end{macrocode}
% \end{macro}
%
% \subsection{Gobbling tokens from input}
%
% \begin{macro}[EXP]
%   {
%     \use_none:n,
%     \use_none:nn,
%     \use_none:nnn,
%     \use_none:nnnn,
%     \use_none:nnnnn,
%     \use_none:nnnnnn,
%     \use_none:nnnnnnn,
%     \use_none:nnnnnnnn,
%     \use_none:nnnnnnnnn
%   }
%   To gobble tokens from the input we use a standard naming convention:
%   the number of tokens gobbled is given by the number of |n|'s
%   following the |:| in the name. Although we could define functions to
%   remove ten arguments or more using separate calls of
%   \cs{use_none:nnnnn}, this is very non-intuitive to the programmer
%   who will assume that expanding such a function once will take care
%   of gobbling all the tokens in one go.
%    \begin{macrocode}
\cs_set:Npn \use_none:n         #1                 { }
\cs_set:Npn \use_none:nn        #1#2               { }
\cs_set:Npn \use_none:nnn       #1#2#3             { }
\cs_set:Npn \use_none:nnnn      #1#2#3#4           { }
\cs_set:Npn \use_none:nnnnn     #1#2#3#4#5         { }
\cs_set:Npn \use_none:nnnnnn    #1#2#3#4#5#6       { }
\cs_set:Npn \use_none:nnnnnnn   #1#2#3#4#5#6#7     { }
\cs_set:Npn \use_none:nnnnnnnn  #1#2#3#4#5#6#7#8   { }
\cs_set:Npn \use_none:nnnnnnnnn #1#2#3#4#5#6#7#8#9 { }
%    \end{macrocode}
% \end{macro}
%
% \subsection{Conditional processing and definitions}
%
% Underneath any predicate function (|_p|) or other conditional forms
% (|TF|, etc.) is a built-in logic saying that it after all of the
% testing and processing must return the \meta{state} this leaves
% \TeX{} in. Therefore, a simple user interface could be something like
% \begin{verbatim}
%   \if_meaning:w #1#2
%     \prg_return_true:
%   \else:
%     \if_meaning:w #1#3
%       \prg_return_true:
%     \else:
%       \prg_return_false:
%     \fi:
%   \fi:
% \end{verbatim}
% Usually, a \TeX{} programmer would have to insert a number of
% \cs{exp_after:wN}s to ensure the state value is returned at exactly
% the point where the last conditional is finished.  However, that
% obscures the code and forces the \TeX{} programmer to prove that
% he/she knows the $2^{n}-1$ table.  We therefore provide the simpler
% interface.
%
% \begin{macro}[EXP]{\prg_return_true:, \prg_return_false:}
%   The idea here is that \cs{__int_to_roman:w} will expand fully any
%   \cs{else:} and the \cs{fi:} that are waiting to be discarded,
%   before reaching the \cs{c_zero} which will leave the expansion null.
%   The code can then leave either the first or second argument in the
%   input stream. This means that all of the branching code has to contain
%   at least two tokens: see how the logical tests are actually implemented
%   to see this.
%    \begin{macrocode}
\cs_set_nopar:Npn \prg_return_true:
  { \exp_after:wN \use_i:nn  \__int_to_roman:w }
\cs_set_nopar:Npn \prg_return_false:
  { \exp_after:wN \use_ii:nn \__int_to_roman:w}
%    \end{macrocode}
%   An extended state space could be implemented by including a more
%   elaborate function in place of \cs{use_i:nn}/\cs{use_ii:nn}. Provided
%   two arguments are absorbed then the code will work.
% \end{macro}
%
% \begin{macro}
%   {
%     \prg_set_conditional:Npnn           ,
%     \prg_new_conditional:Npnn           ,
%     \prg_set_protected_conditional:Npnn ,
%     \prg_new_protected_conditional:Npnn ,
%   }
% \begin{macro}[aux]{\__prg_generate_conditional_parm:nnNpnn}
%   The user functions for the types using parameter text from the
%   programmer. The various functions only differ by which function is
%   used for the assignment. For those |Npnn| type functions, we must
%   grab the parameter text, reading everything up to a left brace
%   before continuing. Then split the base function into name and
%   signature, and feed \Arg{name} \Arg{signature} \meta{boolean}
%   \Arg{set~or~new} \Arg{maybe~protected} \Arg{parameters} |{TF,...}|
%   \Arg{code} to the auxiliary function responsible for defining all
%   conditionals.
%    \begin{macrocode}
\cs_set_protected_nopar:Npn \prg_set_conditional:Npnn
  { \__prg_generate_conditional_parm:nnNpnn { set } { } }
\cs_set_protected_nopar:Npn \prg_new_conditional:Npnn
  { \__prg_generate_conditional_parm:nnNpnn { new } { } }
\cs_set_protected_nopar:Npn \prg_set_protected_conditional:Npnn
  { \__prg_generate_conditional_parm:nnNpnn { set } { _protected } }
\cs_set_protected_nopar:Npn \prg_new_protected_conditional:Npnn
  { \__prg_generate_conditional_parm:nnNpnn { new } { _protected } }
\cs_set_protected:Npn \__prg_generate_conditional_parm:nnNpnn #1#2#3#4#
  {
    \__cs_split_function:NN #3 \__prg_generate_conditional:nnNnnnnn
    {#1} {#2} {#4}
  }
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}
%   {
%     \prg_set_conditional:Nnn           ,
%     \prg_new_conditional:Nnn           ,
%     \prg_set_protected_conditional:Nnn ,
%     \prg_new_protected_conditional:Nnn ,
%   }
% \begin{macro}[aux]
%   {
%     \__prg_generate_conditional_count:nnNnn ,
%     \__prg_generate_conditional_count:nnNnnnn
%   }
%   The user functions for the types automatically inserting the correct
%   parameter text based on the signature. The various functions only
%   differ by which function is used for the assignment. Split the base
%   function into name and signature.  The second auxiliary generates
%   the parameter text from the number of letters in the signature.
%   Then feed \Arg{name} \Arg{signature} \meta{boolean} \Arg{set~or~new}
%   \Arg{maybe~protected} \Arg{parameters} |{TF,...}| \Arg{code} to the
%   auxiliary function responsible for defining all conditionals.  If
%   the \meta{signature} has more than $9$ letters, the definition is
%   aborted since \TeX{} macros have at most $9$ arguments.  The
%   erroneous case where the function name contains no colon is captured
%   later.
%    \begin{macrocode}
\cs_set_protected_nopar:Npn \prg_set_conditional:Nnn
  { \__prg_generate_conditional_count:nnNnn { set } { } }
\cs_set_protected_nopar:Npn \prg_new_conditional:Nnn
  { \__prg_generate_conditional_count:nnNnn { new } { } }
\cs_set_protected_nopar:Npn \prg_set_protected_conditional:Nnn
  { \__prg_generate_conditional_count:nnNnn { set } { _protected } }
\cs_set_protected_nopar:Npn \prg_new_protected_conditional:Nnn
  { \__prg_generate_conditional_count:nnNnn { new } { _protected } }
\cs_set_protected:Npn \__prg_generate_conditional_count:nnNnn #1#2#3
  {
    \__cs_split_function:NN #3 \__prg_generate_conditional_count:nnNnnnn
    {#1} {#2}
  }
\cs_set_protected:Npn \__prg_generate_conditional_count:nnNnnnn #1#2#3#4#5
  {
    \__cs_parm_from_arg_count:nnF
      { \__prg_generate_conditional:nnNnnnnn {#1} {#2} #3 {#4} {#5} }
      { \tl_count:n {#2} }
      {
        \__msg_kernel_error:nnxx { kernel } { bad-number-of-arguments }
          { \token_to_str:c { #1 : #2 } }
          { \tl_count:n {#2} }
        \use_none:nn
      }
  }
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}[aux]
%   {
%     \__prg_generate_conditional:nnNnnnnn,
%     \__prg_generate_conditional:nnnnnnw
%   }
%   The workhorse here is going through a list of desired forms, \emph{i.e.},
%   |p|, |TF|, |T| and |F|. The first three arguments come from splitting up
%   the base form of the conditional, which gives the name, signature
%   and a boolean to signal whether or not there was a colon in the
%   name. In the absence of a colon, we throw an error and don't define
%   any conditional. The fourth and fifth arguments build up the
%   defining function.  The sixth is the parameters to use (possibly
%   empty), the seventh is the list of forms to define, the eighth is the
%   replacement text which we will augment when defining the forms.
%   The use of \cs{etex_detokenize:D} makes the later loop more robust.
%    \begin{macrocode}
\cs_set_protected:Npn \__prg_generate_conditional:nnNnnnnn #1#2#3#4#5#6#7#8
  {
    \if_meaning:w \c_false_bool #3
      \__msg_kernel_error:nnx { kernel } { missing-colon }
        { \token_to_str:c {#1} }
      \exp_after:wN \use_none:nn
    \fi:
    \use:x
      {
        \exp_not:N \__prg_generate_conditional:nnnnnnw
        \exp_not:n { {#4} {#5} {#1} {#2} {#6} {#8} }
        \etex_detokenize:D {#7}
        \exp_not:n { , \q_recursion_tail , \q_recursion_stop }
      }
  }
%    \end{macrocode}
%   Looping through the list of desired forms.  First are six arguments
%   and seventh is the form.  Use the form to call the
%   correct type.  If the form does not exist, the \cs{use:c}
%   construction results in \tn{relax}, and the error message is
%   displayed (unless the form is empty, to allow for |{T, , F}|),
%   then \cs{use_none:nnnnnnn} cleans up.  Otherwise, the
%   error message is removed by the variant form.
%    \begin{macrocode}
\cs_set_protected:Npn \__prg_generate_conditional:nnnnnnw #1#2#3#4#5#6#7 ,
  {
    \if_meaning:w \q_recursion_tail #7
      \exp_after:wN \use_none_delimit_by_q_recursion_stop:w
    \fi:
    \use:c { __prg_generate_ #7 _form:wnnnnnn }
        \tl_if_empty:nF {#7}
          {
            \__msg_kernel_error:nnxx
              { kernel } { conditional-form-unknown }
              {#7} { \token_to_str:c { #3 : #4 } }
          }
        \use_none:nnnnnnn
      \q_stop
      {#1} {#2} {#3} {#4} {#5} {#6}
    \__prg_generate_conditional:nnnnnnw {#1} {#2} {#3} {#4} {#5} {#6}
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}[aux]
%   {
%     \__prg_generate_p_form:wnnnnnn,
%     \__prg_generate_TF_form:wnnnnnn,
%     \__prg_generate_T_form:wnnnnnn,
%     \__prg_generate_F_form:wnnnnnn
%   }
%   How to generate the various forms. Those functions take the
%   following arguments: 1: \texttt{set} or \texttt{new}, 2: empty or
%   \texttt{\_protected}, 3: function name 4: signature, 5: parameter
%   text (or empty), 6: replacement. Remember that the logic-returning
%   functions expect two arguments to be present after \cs{c_zero}:
%   notice the construction of the different variants relies on this,
%   and that the |TF| variant will be slightly faster than the |T|
%   version.  The |p| form is only valid for expandable tests, we check
%   for that by making sure that the second argument is empty.
%    \begin{macrocode}
\cs_set_protected:Npn \__prg_generate_p_form:wnnnnnn #1 \q_stop #2#3#4#5#6#7
  {
    \if_meaning:w \scan_stop: #3 \scan_stop:
      \exp_after:wN \use_i:nn
    \else:
      \exp_after:wN \use_ii:nn
    \fi:
      {
        \exp_args:cc { cs_ #2 #3 :Npn } { #4 _p: #5 } #6
          { #7 \c_zero \c_true_bool \c_false_bool }
      }
      {
        \__msg_kernel_error:nnx { kernel } { protected-predicate }
          { \token_to_str:c { #4 _p: #5 } }
      }
  }
\cs_set_protected:Npn \__prg_generate_T_form:wnnnnnn #1 \q_stop #2#3#4#5#6#7
  {
    \exp_args:cc { cs_ #2 #3 :Npn } { #4 : #5 T } #6
      { #7 \c_zero \use:n \use_none:n }
  }
\cs_set_protected:Npn \__prg_generate_F_form:wnnnnnn #1 \q_stop #2#3#4#5#6#7
  {
    \exp_args:cc { cs_ #2 #3 :Npn } { #4 : #5 F } #6
      { #7 \c_zero { } }
  }
\cs_set_protected:Npn \__prg_generate_TF_form:wnnnnnn #1 \q_stop #2#3#4#5#6#7
  {
    \exp_args:cc { cs_ #2 #3 :Npn } { #4 : #5 TF } #6
      { #7 \c_zero }
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\prg_set_eq_conditional:NNn,\prg_new_eq_conditional:NNn}
% \begin{macro}[aux]{\__prg_set_eq_conditional:NNNn}
%   The setting-equal functions.  Split the two functions and feed a
%   first auxiliary \Arg{name_1} \Arg{signature_1} \meta{boolean_1}
%   \Arg{name_2} \Arg{signature_2} \meta{boolean_2}
%   \meta{copying~function} \meta{conditions} |,| \cs{q_recursion_tail}
%   |,| \cs{q_recursion_stop}
%    \begin{macrocode}
\cs_set_protected_nopar:Npn \prg_set_eq_conditional:NNn
  { \__prg_set_eq_conditional:NNNn \cs_set_eq:cc }
\cs_set_protected_nopar:Npn \prg_new_eq_conditional:NNn
  { \__prg_set_eq_conditional:NNNn \cs_new_eq:cc }
\cs_set_protected:Npn \__prg_set_eq_conditional:NNNn #1#2#3#4
  {
    \use:x
      {
        \exp_not:N \__prg_set_eq_conditional:nnNnnNNw
          \__cs_split_function:NN #2 \prg_do_nothing:
          \__cs_split_function:NN #3 \prg_do_nothing:
          \exp_not:N #1
          \etex_detokenize:D {#4}
          \exp_not:n { , \q_recursion_tail , \q_recursion_stop }
      }
  }
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}[aux]
%   {
%     \__prg_set_eq_conditional:nnNnnNNw ,
%     \__prg_set_eq_conditional_loop:nnnnNw
%   }
% \begin{macro}[aux, EXP]
%   {
%     \__prg_set_eq_conditional_p_form:nnn  ,
%     \__prg_set_eq_conditional_TF_form:nnn ,
%     \__prg_set_eq_conditional_T_form:nnn  ,
%     \__prg_set_eq_conditional_F_form:nnn  ,
%   }
%   Split the function to be defined, and setup a manual clist loop over
%   argument |#6| of the first auxiliary.  The second auxiliary receives
%   twice three arguments coming from splitting the function to be
%   defined and the function to copy.  Make sure that both functions
%   contained a colon, otherwise we don't know how to build
%   conditionals, hence abort.  Call the looping macro, with arguments
%   \Arg{name_1} \Arg{signature_1} \Arg{name_2} \Arg{signature_2}
%   \meta{copying~function} and followed by the comma list.  At each
%   step in the loop, make sure that the conditional form we copy is
%   defined, and copy it, otherwise abort.
%    \begin{macrocode}
\cs_set_protected:Npn \__prg_set_eq_conditional:nnNnnNNw #1#2#3#4#5#6
  {
    \if_meaning:w \c_false_bool #3
      \__msg_kernel_error:nnx { kernel } { missing-colon }
        { \token_to_str:c {#1} }
      \exp_after:wN \use_none_delimit_by_q_recursion_stop:w
    \fi:
    \if_meaning:w \c_false_bool #6
      \__msg_kernel_error:nnx { kernel } { missing-colon }
        { \token_to_str:c {#4} }
      \exp_after:wN \use_none_delimit_by_q_recursion_stop:w
    \fi:
    \__prg_set_eq_conditional_loop:nnnnNw {#1} {#2} {#4} {#5}
  }
\cs_set_protected:Npn \__prg_set_eq_conditional_loop:nnnnNw #1#2#3#4#5#6 ,
  {
    \if_meaning:w \q_recursion_tail #6
      \exp_after:wN \use_none_delimit_by_q_recursion_stop:w
    \fi:
    \use:c { __prg_set_eq_conditional_ #6 _form:wNnnnn }
        \tl_if_empty:nF {#6}
          {
            \__msg_kernel_error:nnxx
              { kernel } { conditional-form-unknown }
              {#6} { \token_to_str:c { #1 : #2 } }
          }
        \use_none:nnnnnn
      \q_stop
      #5 {#1} {#2} {#3} {#4}
    \__prg_set_eq_conditional_loop:nnnnNw {#1} {#2} {#3} {#4} #5
  }
\cs_set:Npn \__prg_set_eq_conditional_p_form:wNnnnn #1 \q_stop #2#3#4#5#6
  {
    \__chk_if_exist_cs:c { #5 _p : #6    }
    #2 { #3 _p : #4    } { #5 _p : #6    }
  }
\cs_set:Npn \__prg_set_eq_conditional_TF_form:wNnnnn #1 \q_stop #2#3#4#5#6
  {
    \__chk_if_exist_cs:c { #5    : #6 TF }
    #2 { #3    : #4 TF } { #5    : #6 TF }
  }
\cs_set:Npn \__prg_set_eq_conditional_T_form:wNnnnn #1 \q_stop #2#3#4#5#6
  {
    \__chk_if_exist_cs:c { #5    : #6 T  }
    #2 { #3    : #4 T  } { #5    : #6 T  }
  }
\cs_set:Npn \__prg_set_eq_conditional_F_form:wNnnnn #1 \q_stop #2#3#4#5#6
  {
    \__chk_if_exist_cs:c { #5    : #6  F }
    #2 { #3    : #4  F } { #5    : #6  F }
  }
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% All that is left is to define the canonical boolean true and false.
% I think Michael originated the idea of expandable boolean tests.  At
% first these were supposed to expand into either \texttt{TT} or
% \texttt{TF} to be tested using \cs{if:w} but this was later changed to
% |00| and |01|, so they could be used in logical
% operations. Later again they were changed to being numerical
% constants with values of $1$ for true and $0$ for false. We need
% this from the get-go.
%
% \begin{variable}{\c_true_bool, \c_false_bool}
%    Here are the canonical boolean values.
%    \begin{macrocode}
\tex_chardef:D \c_true_bool  = 1 ~
\tex_chardef:D \c_false_bool = 0 ~
%    \end{macrocode}
% \end{variable}
%
% \subsection{Dissecting a control sequence}
%
% \begin{macro}[EXP]{\cs_to_str:N}
% \begin{macro}[aux, EXP]{\__cs_to_str:N, \__cs_to_str:w}
%   This converts a control sequence into the character string of its
%   name, removing the leading escape character. This turns out to be
%   a non-trivial matter as there a different cases:
%   \begin{itemize}
%     \item The usual case of a printable escape character;
%     \item the case of a non-printable escape characters, e.g., when
%     the value of the \tn{escapechar} is negative;
%     \item when the escape character is a space.
%   \end{itemize}
%   One approach to solve this is to test how many tokens result from
%   |\token_to_str:N \a|. If there are two tokens, then the escape
%   character is printable, while if it is non-printable then only
%   one is present.
%
%   However, there is an additional complication: the control
%   sequence itself may start with a space. Clearly that should \emph{not} be
%   lost in the process of converting to a string. So the approach adopted is
%   a little more intricate still. When the escape character is printable,
%   \verb*|\token_to_str:N \ | yields the escape character itself and a space.
%   The character codes are different, thus the \cs{if:w} test is false,
%   and \TeX{} reads \cs{__cs_to_str:N} after turning the following
%   control sequence into a string; this auxiliary removes the escape
%   character, and stops the expansion of the initial \cs{__int_to_roman:w}.
%   The second case is that the escape character is not printable. Then
%   the \cs{if:w} test is unfinished after reading a the space from
%   \verb*|\token_to_str:N \ |, and the auxiliary \cs{__cs_to_str:w}
%   is expanded, feeding |-| as a second character for the test;
%   the test is false, and \TeX{} skips to \cs{fi:}, then performs
%   \cs{token_to_str:N}, and stops the \cs{__int_to_roman:w} with \cs{c_zero}.
%   The last case is that the escape character is itself a space. In this
%   case, the \cs{if:w} test is true, and the auxiliary \cs{__cs_to_str:w}
%   comes into play, inserting |-\__int_value:w|, which expands \cs{c_zero}
%   to the character |0|. The initial \cs{__int_to_roman:w} then sees
%   |0|, which is not a terminated number, followed by the escape character,
%   a space, which is removed, terminating the argument of
%   \cs{__int_to_roman:w}.
%   In all three cases, \cs{cs_to_str:N} takes two expansion steps
%   to be fully expanded.
%    \begin{macrocode}
\cs_set_nopar:Npn \cs_to_str:N
  {
    \__int_to_roman:w
      \if:w \token_to_str:N \ \__cs_to_str:w \fi:
      \exp_after:wN \__cs_to_str:N \token_to_str:N
  }
\cs_set:Npn \__cs_to_str:N #1 { \c_zero }
\cs_set:Npn \__cs_to_str:w #1 \__cs_to_str:N
  { - \__int_value:w \fi: \exp_after:wN \c_zero }
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}[EXP, int]{\__cs_split_function:NN}
% \begin{macro}[aux, EXP]
%   {\__cs_split_function_auxi:w, \__cs_split_function_auxii:w}
%   This function takes a function name and splits it into name with
%   the escape char removed and argument specification. In addition to
%   this, a third argument, a boolean \meta{true} or \meta{false} is
%   returned with \meta{true} for when there is a colon in the function
%   and \meta{false} if there is not. Lastly, the second argument of
%   \cs{__cs_split_function:NN} is supposed to be a function
%   taking three variables, one for name, one for signature, and one
%   for the boolean.  For example,
%   |\__cs_split_function:NN \foo_bar:cnx \use_i:nnn| as input
%   becomes |\use_i:nnn {foo_bar} {cnx} \c_true_bool|.
%
%   We can't use a literal |:| because it has the wrong catcode here, so
%   it's transformed from |@| with \cs{tex_lowercase:D}.
%
%   First ensure that we actually get a properly evaluated string by
%   expanding \cs{cs_to_str:N} twice.  If the function contained a
%   colon, the auxiliary takes as |#1| the function name, delimited by
%   the first colon, then the signature |#2|, delimited by \cs{q_mark},
%   then \cs{c_true_bool} as |#3|, and |#4| cleans up until \cs{q_stop}.
%   Otherwise, the |#1| contains the function name and \cs{q_mark}
%   \cs{c_true_bool}, |#2| is empty, |#3| is \cs{c_false_bool}, and |#4|
%   cleans up.  In both cases, |#5| is the \meta{processor}.  The second
%   auxiliary trims the trailing \cs{q_mark} from the function name if
%   present (that is, if the original function had no colon).
%    \begin{macrocode}
\group_begin:
\tex_lccode:D  `\@ = `\: \scan_stop:
\tex_catcode:D `\@ = 12 ~
\tex_lowercase:D
  {
    \group_end:
    \cs_set:Npn \__cs_split_function:NN #1
      {
        \exp_after:wN \exp_after:wN
        \exp_after:wN \__cs_split_function_auxi:w
          \cs_to_str:N #1 \q_mark \c_true_bool
          @ \q_mark \c_false_bool
          \q_stop
      }
    \cs_set:Npn \__cs_split_function_auxi:w #1 @ #2 \q_mark #3#4 \q_stop #5
      { \__cs_split_function_auxii:w #5 #1 \q_mark \q_stop {#2} #3 }
    \cs_set:Npn \__cs_split_function_auxii:w #1#2 \q_mark #3 \q_stop
      { #1 {#2} }
  }
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}[EXP, int]
%   {\__cs_get_function_name:N, \__cs_get_function_signature:N}
%   Simple wrappers.
%    \begin{macrocode}
\cs_set:Npn \__cs_get_function_name:N #1
  { \__cs_split_function:NN #1 \use_i:nnn }
\cs_set:Npn \__cs_get_function_signature:N #1
  { \__cs_split_function:NN #1 \use_ii:nnn }
%    \end{macrocode}
% \end{macro}
%
% \subsection{Exist or free}
%
% A control sequence is said to \emph{exist} (to be used) if has an entry in
% the hash table and its meaning is different from the primitive
% \tn{relax} token. A control sequence is said to be \emph{free}
% (to be defined) if it does not already exist.
%
% \begin{macro}[pTF, EXP]{\cs_if_exist:N,\cs_if_exist:c}
%   Two versions for checking existence. For the |N| form we firstly
%   check for \cs{scan_stop:} and then if it is in the hash
%   table. There is no problem when inputting something like \cs{else:}
%   or \cs{fi:} as \TeX{} will only ever skip input in case the token
%   tested against is \cs{scan_stop:}.
%    \begin{macrocode}
\prg_set_conditional:Npnn \cs_if_exist:N #1 { p , T , F , TF }
  {
    \if_meaning:w #1 \scan_stop:
      \prg_return_false:
    \else:
      \if_cs_exist:N #1
        \prg_return_true:
      \else:
        \prg_return_false:
      \fi:
    \fi:
  }
%    \end{macrocode}
%   For the |c| form we firstly check if it is in the hash table and
%   then for \cs{scan_stop:} so that we do not add it to the hash table
%   unless it was already there. Here we have to be careful as the text
%   to be skipped if the first test is false may contain tokens that
%   disturb the scanner. Therefore, we ensure that the second test is
%   performed after the first one has concluded completely.
%    \begin{macrocode}
\prg_set_conditional:Npnn \cs_if_exist:c #1 { p , T , F , TF }
  {
    \if_cs_exist:w #1 \cs_end:
      \exp_after:wN \use_i:nn
    \else:
      \exp_after:wN \use_ii:nn
    \fi:
    {
      \exp_after:wN \if_meaning:w \cs:w #1 \cs_end: \scan_stop:
        \prg_return_false:
      \else:
        \prg_return_true:
      \fi:
    }
    \prg_return_false:
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}[pTF, EXP]{\cs_if_free:N,\cs_if_free:c}
%   The logical reversal of the above.
%    \begin{macrocode}
\prg_set_conditional:Npnn \cs_if_free:N #1 { p , T , F , TF }
  {
    \if_meaning:w #1 \scan_stop:
      \prg_return_true:
    \else:
      \if_cs_exist:N #1
        \prg_return_false:
      \else:
        \prg_return_true:
      \fi:
    \fi:
  }
\prg_set_conditional:Npnn \cs_if_free:c #1 { p , T , F , TF }
  {
    \if_cs_exist:w #1 \cs_end:
      \exp_after:wN \use_i:nn
    \else:
      \exp_after:wN \use_ii:nn
    \fi:
      {
        \exp_after:wN \if_meaning:w \cs:w #1 \cs_end: \scan_stop:
          \prg_return_true:
        \else:
          \prg_return_false:
        \fi:
      }
      { \prg_return_true: }
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}[EXP,TF,added=2011-10-10]
%   {\cs_if_exist_use:N, \cs_if_exist_use:c}
% \begin{macro}[EXP,added=2011-10-10]
%   {\cs_if_exist_use:N, \cs_if_exist_use:c}
%   The \cs{cs_if_exist_use:\ldots{}} functions cannot be implemented
%   as conditionals because the true branch must leave both the control
%   sequence itself and the true code in the input stream.
%   For the \texttt{c} variants, we are careful not to put the control
%   sequence in the hash table if it does not exist.
%    \begin{macrocode}
\cs_set:Npn \cs_if_exist_use:NTF #1#2
  { \cs_if_exist:NTF #1 { #1 #2 } }
\cs_set:Npn \cs_if_exist_use:NF #1
  { \cs_if_exist:NTF #1 { #1 } }
\cs_set:Npn \cs_if_exist_use:NT #1 #2
  { \cs_if_exist:NTF #1 { #1 #2 } { } }
\cs_set:Npn \cs_if_exist_use:N #1
  { \cs_if_exist:NTF #1 { #1 } { } }
\cs_set:Npn \cs_if_exist_use:cTF #1#2
  { \cs_if_exist:cTF {#1} { \use:c {#1} #2 } }
\cs_set:Npn \cs_if_exist_use:cF #1
  { \cs_if_exist:cTF {#1} { \use:c {#1} } }
\cs_set:Npn \cs_if_exist_use:cT #1#2
  { \cs_if_exist:cTF {#1} { \use:c {#1} #2 } { } }
\cs_set:Npn \cs_if_exist_use:c #1
  { \cs_if_exist:cTF {#1} { \use:c {#1} } { } }
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \subsection{Defining and checking (new) functions}
%
%    We provide two kinds of functions that can be used to define
%    control sequences. On the one hand we have functions that check
%    if their argument doesn't already exist, they are called
%    |\..._new|. The second type of defining functions doesn't check
%    if the argument is already defined.
%
%    Before we can define them, we need some auxiliary macros that
%    allow us to generate error messages. The definitions here are
%    only temporary, they will be redefined later on.
%
% \begin{macro}{\iow_log:x, \iow_term:x}
%    We define a routine to write only to the log file. And a
%    similar one for writing to both the log file and the terminal.
%    These will be redefined later by \pkg{l3io}.
%    \begin{macrocode}
\cs_set_protected_nopar:Npn \iow_log:x
  { \tex_immediate:D \tex_write:D \c_minus_one }
\cs_set_protected_nopar:Npn \iow_term:x
  { \tex_immediate:D \tex_write:D \c_sixteen }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}[int]
%   {\__msg_kernel_error:nnxx, \__msg_kernel_error:nnx, \__msg_kernel_error:nn}
%   If an internal error occurs before \LaTeX3 has loaded \pkg{l3msg} then
%   the code should issue a usable if terse error message and halt. This
%   can only happen if a coding error is made by the team, so this is
%   a reasonable response.
%    \begin{macrocode}
\cs_set_protected:Npn \__msg_kernel_error:nnxx #1#2#3#4
  {
    \tex_errmessage:D
      {
        !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!~! ^^J
        Argh,~internal~LaTeX3~error! ^^J ^^J
        Module ~ #1 , ~ message~name~"#2": ^^J
        Arguments~'#3'~and~'#4' ^^J ^^J
        This~is~one~for~The~LaTeX3~Project:~bailing~out
      }
    \tex_end:D
  }
\cs_set_protected:Npn \__msg_kernel_error:nnx #1#2#3
  { \__msg_kernel_error:nnxx {#1} {#2} {#3} { } }
\cs_set_protected:Npn \__msg_kernel_error:nn #1#2
  { \__msg_kernel_error:nnxx {#1} {#2} { } { } }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}[rEXP]{\msg_line_context:}
%   Another one from \pkg{l3msg} which will be altered later.
%    \begin{macrocode}
\cs_set_nopar:Npn \msg_line_context:
  { on~line~ \tex_the:D \tex_inputlineno:D }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}[int]{\__chk_if_free_cs:N, \__chk_if_free_cs:c}
%   This command is called by \cs{cs_new_nopar:Npn} and \cs{cs_new_eq:NN}
%   \emph{etc.}\
%   to make sure that the argument sequence is not already in use. If
%   it is, an error is signalled.  It checks if \meta{csname} is
%   undefined or \cs{scan_stop:}. Otherwise an error message is
%   issued. We have to make sure we don't put the argument into the
%   conditional processing since it may be an |\if...| type function!
%    \begin{macrocode}
\cs_set_protected:Npn \__chk_if_free_cs:N #1
  {
    \cs_if_free:NF #1
      {
        \__msg_kernel_error:nnxx { kernel } { command-already-defined }
          { \token_to_str:N #1 } { \token_to_meaning:N #1 }
      }
}
%<*package>
\tex_ifodd:D \l@expl@log@functions@bool
  \cs_set_protected:Npn \__chk_if_free_cs:N #1
    {
      \cs_if_free:NF #1
        {
          \__msg_kernel_error:nnxx { kernel } { command-already-defined }
            { \token_to_str:N #1 } { \token_to_meaning:N #1 }
        }
      \iow_log:x { Defining~\token_to_str:N #1~ \msg_line_context: }
    }
\fi:
%</package>
\cs_set_protected_nopar:Npn \__chk_if_free_cs:c
  { \exp_args:Nc \__chk_if_free_cs:N }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}[int]{\__chk_if_exist_cs:N, \__chk_if_exist_cs:c}
%    This function issues an error message when the control sequence
%    in its argument does not exist.
%    \begin{macrocode}
\cs_set_protected:Npn \__chk_if_exist_cs:N #1
  {
    \cs_if_exist:NF #1
      {
        \__msg_kernel_error:nnx { kernel } { command-not-defined }
          { \token_to_str:N #1 }
      }
  }
\cs_set_protected_nopar:Npn \__chk_if_exist_cs:c
  { \exp_args:Nc \__chk_if_exist_cs:N }
%    \end{macrocode}
% \end{macro}
%
% \subsection{More new definitions}
%
% \begin{macro}
%   {
%     \cs_new_nopar:Npn           , \cs_new_nopar:Npx           ,
%     \cs_new:Npn                 , \cs_new:Npx                 ,
%     \cs_new_protected_nopar:Npn , \cs_new_protected_nopar:Npx ,
%     \cs_new_protected:Npn       , \cs_new_protected:Npx
%   }
%   Function which check that the control sequence is free before
%   defining it.
%     \begin{macrocode}
\cs_set:Npn \__cs_tmp:w #1#2
  {
    \cs_set_protected:Npn #1 ##1
       {
         \__chk_if_free_cs:N ##1
         #2 ##1
      }
  }
\__cs_tmp:w \cs_new_nopar:Npn           \cs_gset_nopar:Npn
\__cs_tmp:w \cs_new_nopar:Npx           \cs_gset_nopar:Npx
\__cs_tmp:w \cs_new:Npn                 \cs_gset:Npn
\__cs_tmp:w \cs_new:Npx                 \cs_gset:Npx
\__cs_tmp:w \cs_new_protected_nopar:Npn \cs_gset_protected_nopar:Npn
\__cs_tmp:w \cs_new_protected_nopar:Npx \cs_gset_protected_nopar:Npx
\__cs_tmp:w \cs_new_protected:Npn       \cs_gset_protected:Npn
\__cs_tmp:w \cs_new_protected:Npx       \cs_gset_protected:Npx
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}
%   {
%     \cs_set_nopar:cpn  , \cs_set_nopar:cpx  ,
%     \cs_gset_nopar:cpn , \cs_gset_nopar:cpx ,
%     \cs_new_nopar:cpn  , \cs_new_nopar:cpx
%   }
%   Like \cs{cs_set_nopar:Npn} and \cs{cs_new_nopar:Npn}, except that the
%   first argument consists of the sequence of characters that should
%   be used to form the name of the desired control sequence (the |c|
%   stands for csname argument, see the expansion module). Global
%   versions are also provided.
%
%   \cs{cs_set_nopar:cpn}\meta{string}\meta{rep-text} will turn \meta{string}
%   into a csname and then assign \meta{rep-text} to it by using
%   \cs{cs_set_nopar:Npn}.  This means that there might be a parameter
%   string between the two arguments.
%    \begin{macrocode}
\cs_set:Npn \__cs_tmp:w #1#2
  { \cs_new_protected_nopar:Npn #1 { \exp_args:Nc #2 } }
\__cs_tmp:w \cs_set_nopar:cpn  \cs_set_nopar:Npn
\__cs_tmp:w \cs_set_nopar:cpx  \cs_set_nopar:Npx
\__cs_tmp:w \cs_gset_nopar:cpn \cs_gset_nopar:Npn
\__cs_tmp:w \cs_gset_nopar:cpx \cs_gset_nopar:Npx
\__cs_tmp:w \cs_new_nopar:cpn  \cs_new_nopar:Npn
\__cs_tmp:w \cs_new_nopar:cpx  \cs_new_nopar:Npx
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}
%   {
%     \cs_set:cpn  , \cs_set:cpx  ,
%     \cs_gset:cpn , \cs_gset:cpx ,
%     \cs_new:cpn  , \cs_new:cpx
%   }
%   Variants of the \cs{cs_set:Npn} versions which make a csname out
%   of the first arguments. We may also do this globally.
%    \begin{macrocode}
\__cs_tmp:w \cs_set:cpn  \cs_set:Npn
\__cs_tmp:w \cs_set:cpx  \cs_set:Npx
\__cs_tmp:w \cs_gset:cpn \cs_gset:Npn
\__cs_tmp:w \cs_gset:cpx \cs_gset:Npx
\__cs_tmp:w \cs_new:cpn  \cs_new:Npn
\__cs_tmp:w \cs_new:cpx  \cs_new:Npx
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}
%   {
%     \cs_set_protected_nopar:cpn  , \cs_set_protected_nopar:cpx  ,
%     \cs_gset_protected_nopar:cpn , \cs_gset_protected_nopar:cpx ,
%     \cs_new_protected_nopar:cpn  , \cs_new_protected_nopar:cpx
%   }
%   Variants of the \cs{cs_set_protected_nopar:Npn} versions which make
%   a csname out of the first arguments. We may also do this globally.
%    \begin{macrocode}
\__cs_tmp:w \cs_set_protected_nopar:cpn  \cs_set_protected_nopar:Npn
\__cs_tmp:w \cs_set_protected_nopar:cpx  \cs_set_protected_nopar:Npx
\__cs_tmp:w \cs_gset_protected_nopar:cpn \cs_gset_protected_nopar:Npn
\__cs_tmp:w \cs_gset_protected_nopar:cpx \cs_gset_protected_nopar:Npx
\__cs_tmp:w \cs_new_protected_nopar:cpn  \cs_new_protected_nopar:Npn
\__cs_tmp:w \cs_new_protected_nopar:cpx  \cs_new_protected_nopar:Npx
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}
%   {
%     \cs_set_protected:cpn  , \cs_set_protected:cpx  ,
%     \cs_gset_protected:cpn , \cs_gset_protected:cpx ,
%     \cs_new_protected:cpn  , \cs_new_protected:cpx
%   }
%   Variants of the \cs{cs_set_protected:Npn} versions which make a csname
%   out of the first arguments. We may also do this globally.
%    \begin{macrocode}
\__cs_tmp:w \cs_set_protected:cpn  \cs_set_protected:Npn
\__cs_tmp:w \cs_set_protected:cpx  \cs_set_protected:Npx
\__cs_tmp:w \cs_gset_protected:cpn \cs_gset_protected:Npn
\__cs_tmp:w \cs_gset_protected:cpx \cs_gset_protected:Npx
\__cs_tmp:w \cs_new_protected:cpn  \cs_new_protected:Npn
\__cs_tmp:w \cs_new_protected:cpx  \cs_new_protected:Npx
%    \end{macrocode}
% \end{macro}
%
% \subsection{Copying definitions}
%
% \begin{macro}
%   {
%     \cs_set_eq:NN  , \cs_set_eq:cN  , \cs_set_eq:Nc  , \cs_set_eq:cc  ,
%     \cs_gset_eq:NN , \cs_gset_eq:cN , \cs_gset_eq:Nc , \cs_gset_eq:cc ,
%     \cs_new_eq:NN  , \cs_new_eq:cN  , \cs_new_eq:Nc  , \cs_new_eq:cc
%   }
%   These macros allow us to copy the definition of a control sequence
%   to another control sequence.
%
%   The |=| sign allows us to define funny char tokens like |=| itself
%   or \verb*| | with this function. For the definition of
%   |\c_space_char{~}| to work we need the |~| after the |=|.
%
%   \cs{cs_set_eq:NN} is long to avoid problems with a literal argument
%   of \cs{par}.  While \cs{cs_new_eq:NN} will probably never be correct
%   with a first argument of \cs{par}, define it long in order to throw
%   an \enquote{already defined} error rather than
%   \enquote{runaway argument}.
%    \begin{macrocode}
\cs_new_protected:Npn \cs_set_eq:NN #1 { \tex_let:D #1 =~ }
\cs_new_protected_nopar:Npn \cs_set_eq:cN { \exp_args:Nc  \cs_set_eq:NN }
\cs_new_protected_nopar:Npn \cs_set_eq:Nc { \exp_args:NNc \cs_set_eq:NN }
\cs_new_protected_nopar:Npn \cs_set_eq:cc { \exp_args:Ncc \cs_set_eq:NN }
\cs_new_protected_nopar:Npn \cs_gset_eq:NN { \tex_global:D  \cs_set_eq:NN }
\cs_new_protected_nopar:Npn \cs_gset_eq:Nc { \exp_args:NNc  \cs_gset_eq:NN }
\cs_new_protected_nopar:Npn \cs_gset_eq:cN { \exp_args:Nc   \cs_gset_eq:NN }
\cs_new_protected_nopar:Npn \cs_gset_eq:cc { \exp_args:Ncc  \cs_gset_eq:NN }
\cs_new_protected:Npn \cs_new_eq:NN #1
  {
    \__chk_if_free_cs:N #1
    \tex_global:D \cs_set_eq:NN #1
  }
\cs_new_protected_nopar:Npn \cs_new_eq:cN { \exp_args:Nc  \cs_new_eq:NN }
\cs_new_protected_nopar:Npn \cs_new_eq:Nc { \exp_args:NNc \cs_new_eq:NN }
\cs_new_protected_nopar:Npn \cs_new_eq:cc { \exp_args:Ncc \cs_new_eq:NN }
%    \end{macrocode}
% \end{macro}
%
% \subsection{Undefining functions}
%
% \begin{macro}{\cs_undefine:N, \cs_undefine:c}
%   The following function is used to free the main memory from the
%   definition of some function that isn't in use any longer.
%   The \texttt{c} variant is careful not to add the control sequence
%   to the hash table if it isn't there yet, and it also avoids nesting
%   \TeX{} conditionals in case |#1| is unbalanced in this matter.
%    \begin{macrocode}
\cs_new_protected:Npn \cs_undefine:N #1
  { \cs_gset_eq:NN #1 \tex_undefined:D }
\cs_new_protected:Npn \cs_undefine:c #1
  {
    \if_cs_exist:w #1 \cs_end:
      \exp_after:wN \use:n
    \else:
      \exp_after:wN \use_none:n
    \fi:
    { \cs_gset_eq:cN {#1} \tex_undefined:D }
  }
%    \end{macrocode}
% \end{macro}
%
% \subsection{Generating parameter text from argument count}
%
% \begin{macro}[int]{\__cs_parm_from_arg_count:nnF}
% \begin{macro}[aux]{\__cs_parm_from_arg_count_test:nnF}
%   \LaTeX3 provides shorthands to define control sequences and
%   conditionals with a simple parameter text, derived directly from the
%   signature, or more generally from knowing the number of arguments,
%   between~$0$ and~$9$.  This function expands to its first argument,
%   untouched, followed by a brace group containing the parameter text
%   |{#|$1$\ldots{}|#|$n$|}|, where $n$ is the result of evaluating the
%   second argument (as described in \cs{int_eval:n}).  If the second
%   argument gives a result outside the range $[0,9]$, the third
%   argument is returned instead, normally an error message.  Some of
%   the functions use here are not defined yet, but will be defined
%   before this function is called.
%    \begin{macrocode}
\cs_set_protected:Npn \__cs_parm_from_arg_count:nnF #1#2
  {
    \exp_args:Nx \__cs_parm_from_arg_count_test:nnF
      {
        \exp_after:wN \exp_not:n
        \if_case:w \__int_eval:w #2 \__int_eval_end:
             { }
        \or: { ##1 }
        \or: { ##1##2 }
        \or: { ##1##2##3 }
        \or: { ##1##2##3##4 }
        \or: { ##1##2##3##4##5 }
        \or: { ##1##2##3##4##5##6 }
        \or: { ##1##2##3##4##5##6##7 }
        \or: { ##1##2##3##4##5##6##7##8 }
        \or: { ##1##2##3##4##5##6##7##8##9 }
        \else: { \c_false_bool }
        \fi:
      }
      {#1}
  }
\cs_set_protected:Npn \__cs_parm_from_arg_count_test:nnF #1#2
  {
    \if_meaning:w \c_false_bool #1
      \exp_after:wN \use_ii:nn
    \else:
      \exp_after:wN \use_i:nn
    \fi:
    { #2 {#1} }
  }
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \subsection{Defining functions from a given number of arguments}
%
% \begin{macro}[EXP, int]{\__cs_count_signature:N, \__cs_count_signature:c}
% \begin{macro}[aux, EXP]{\__cs_count_signature:nnN}
%   Counting the number of tokens in the signature, \emph{i.e.}, the
%   number of arguments the function should take.  Since this is not
%   used in any time-critical function, we simply use \cs{tl_count:n} if
%   there is a signature, otherwise $-1$ arguments to signal an error.
%   We need a variant form right away.
%    \begin{macrocode}
\cs_new:Npn \__cs_count_signature:N #1
  { \int_eval:n { \__cs_split_function:NN #1 \__cs_count_signature:nnN } }
\cs_new:Npn \__cs_count_signature:nnN #1#2#3
  {
    \if_meaning:w \c_true_bool #3
      \tl_count:n {#2}
    \else:
      \c_minus_one
    \fi:
  }
\cs_new_nopar:Npn \__cs_count_signature:c
  { \exp_args:Nc \__cs_count_signature:N }
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}
%   {
%     \cs_generate_from_arg_count:NNnn,
%     \cs_generate_from_arg_count:cNnn,
%     \cs_generate_from_arg_count:Ncnn
%   }
%   We provide a constructor function for defining functions with a
%   given number of arguments.  For this we need to choose the correct
%   parameter text and then use that when defining.  Since \TeX{}
%   supports from zero to nine arguments, we use a simple switch to
%   choose the correct parameter text, ensuring the result is returned
%   after finishing the conditional.  If it is not between zero and
%   nine, we throw an error.
%
%   1: function to define, 2: with what to define it, 3: the number of
%   args it requires and 4: the replacement text
%    \begin{macrocode}
\cs_new_protected:Npn \cs_generate_from_arg_count:NNnn #1#2#3#4
  {
    \__cs_parm_from_arg_count:nnF { \use:nnn #2 #1 } {#3}
      {
        \__msg_kernel_error:nnxx { kernel } { bad-number-of-arguments }
          { \token_to_str:N #1 } { \int_eval:n {#3} }
      }
      {#4}
  }
%    \end{macrocode}
%   A variant form we need right away, plus one which is used elsewhere but
%   which is most logically created here.
%    \begin{macrocode}
\cs_new_protected_nopar:Npn \cs_generate_from_arg_count:cNnn
  { \exp_args:Nc \cs_generate_from_arg_count:NNnn }
\cs_new_protected_nopar:Npn \cs_generate_from_arg_count:Ncnn
  { \exp_args:NNc \cs_generate_from_arg_count:NNnn }
%    \end{macrocode}
% \end{macro}
%
% \subsection{Using the signature to define functions}
%
% We can now combine some of the tools we have to provide a simple
% interface for defining functions.  We define some simpler functions
% with user interface |\cs_set:Nn \foo_bar:nn {#1,#2}|, \emph{i.e.}, the
% number of arguments is read from the signature.
%
% \begin{macro}
%   {
%     \cs_set:Nn                  , \cs_set:Nx                  ,
%     \cs_set_nopar:Nn            , \cs_set_nopar:Nx            ,
%     \cs_set_protected:Nn        , \cs_set_protected:Nx        ,
%     \cs_set_protected_nopar:Nn  , \cs_set_protected_nopar:Nx  ,
%     \cs_gset:Nn                 , \cs_gset:Nx                 ,
%     \cs_gset_nopar:Nn           , \cs_gset_nopar:Nx           ,
%     \cs_gset_protected:Nn       , \cs_gset_protected:Nx       ,
%     \cs_gset_protected_nopar:Nn , \cs_gset_protected_nopar:Nx ,
%     \cs_new:Nn                  , \cs_new:Nx                  ,
%     \cs_new_nopar:Nn            , \cs_new_nopar:Nx            ,
%     \cs_new_protected:Nn        , \cs_new_protected:Nx        ,
%     \cs_new_protected_nopar:Nn  , \cs_new_protected_nopar:Nx  ,
%   }
%   We want to define \cs{cs_set:Nn} as
%   \begin{verbatim}
%     \cs_set_protected:Npn \cs_set:Nn #1#2
%       {
%         \cs_generate_from_arg_count:NNnn #1 \cs_set:Npn
%           { \__cs_count_signature:N #1 } {#2}
%       }
%   \end{verbatim}
%   In short, to define \cs{cs_set:Nn} we need just use \cs{cs_set:Npn},
%   everything else is the same for each variant.  Therefore, we can
%   make it simpler by temporarily defining a function to do this for
%   us.
%    \begin{macrocode}
\cs_set:Npn \__cs_tmp:w #1#2#3
  {
    \cs_new_protected_nopar:cpx { cs_ #1 : #2 }
      {
        \exp_not:N \__cs_generate_from_signature:NNn
        \exp_after:wN \exp_not:N \cs:w cs_ #1 : #3 \cs_end:
      }
  }
\cs_new_protected:Npn \__cs_generate_from_signature:NNn #1#2
  {
    \__cs_split_function:NN #2 \__cs_generate_from_signature:nnNNNn
    #1 #2
  }
\cs_new_protected:Npn \__cs_generate_from_signature:nnNNNn #1#2#3#4#5#6
  {
    \bool_if:NTF #3
      {
        \cs_generate_from_arg_count:NNnn
          #5 #4 { \tl_count:n {#2} } {#6}
      }
      {
        \__msg_kernel_error:nnx { kernel } { missing-colon }
          { \token_to_str:N #5 }
      }
  }
%    \end{macrocode}
%   Then we define the 24 variants beginning with |N|.
%    \begin{macrocode}
\__cs_tmp:w { set }                  { Nn } { Npn }
\__cs_tmp:w { set }                  { Nx } { Npx }
\__cs_tmp:w { set_nopar }            { Nn } { Npn }
\__cs_tmp:w { set_nopar }            { Nx } { Npx }
\__cs_tmp:w { set_protected }        { Nn } { Npn }
\__cs_tmp:w { set_protected }        { Nx } { Npx }
\__cs_tmp:w { set_protected_nopar }  { Nn } { Npn }
\__cs_tmp:w { set_protected_nopar }  { Nx } { Npx }
\__cs_tmp:w { gset }                 { Nn } { Npn }
\__cs_tmp:w { gset }                 { Nx } { Npx }
\__cs_tmp:w { gset_nopar }           { Nn } { Npn }
\__cs_tmp:w { gset_nopar }           { Nx } { Npx }
\__cs_tmp:w { gset_protected }       { Nn } { Npn }
\__cs_tmp:w { gset_protected }       { Nx } { Npx }
\__cs_tmp:w { gset_protected_nopar } { Nn } { Npn }
\__cs_tmp:w { gset_protected_nopar } { Nx } { Npx }
\__cs_tmp:w { new }                  { Nn } { Npn }
\__cs_tmp:w { new }                  { Nx } { Npx }
\__cs_tmp:w { new_nopar }            { Nn } { Npn }
\__cs_tmp:w { new_nopar }            { Nx } { Npx }
\__cs_tmp:w { new_protected }        { Nn } { Npn }
\__cs_tmp:w { new_protected }        { Nx } { Npx }
\__cs_tmp:w { new_protected_nopar }  { Nn } { Npn }
\__cs_tmp:w { new_protected_nopar }  { Nx } { Npx }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}
%   {
%     \cs_set:cn                  , \cs_set:cx                  ,
%     \cs_set_nopar:cn            , \cs_set_nopar:cx            ,
%     \cs_set_protected:cn        , \cs_set_protected:cx        ,
%     \cs_set_protected_nopar:cn  , \cs_set_protected_nopar:cx  ,
%     \cs_gset:cn                 , \cs_gset:cx                 ,
%     \cs_gset_nopar:cn           , \cs_gset_nopar:cx           ,
%     \cs_gset_protected:cn       , \cs_gset_protected:cx       ,
%     \cs_gset_protected_nopar:cn , \cs_gset_protected_nopar:cx ,
%     \cs_new:cn                  , \cs_new:cx                  ,
%     \cs_new_nopar:cn            , \cs_new_nopar:cx            ,
%     \cs_new_protected:cn        , \cs_new_protected:cx        ,
%     \cs_new_protected_nopar:cn  , \cs_new_protected_nopar:cx  ,
%   }
%   The 24 |c| variants simply use \cs{exp_args:Nc}.
%    \begin{macrocode}
\cs_set:Npn \__cs_tmp:w #1#2
  {
    \cs_new_protected_nopar:cpx { cs_ #1 : c #2 }
      {
        \exp_not:N \exp_args:Nc
        \exp_after:wN \exp_not:N \cs:w cs_ #1 : N #2 \cs_end:
      }
  }
\__cs_tmp:w { set }                  { n }
\__cs_tmp:w { set }                  { x }
\__cs_tmp:w { set_nopar }            { n }
\__cs_tmp:w { set_nopar }            { x }
\__cs_tmp:w { set_protected }        { n }
\__cs_tmp:w { set_protected }        { x }
\__cs_tmp:w { set_protected_nopar }  { n }
\__cs_tmp:w { set_protected_nopar }  { x }
\__cs_tmp:w { gset }                 { n }
\__cs_tmp:w { gset }                 { x }
\__cs_tmp:w { gset_nopar }           { n }
\__cs_tmp:w { gset_nopar }           { x }
\__cs_tmp:w { gset_protected }       { n }
\__cs_tmp:w { gset_protected }       { x }
\__cs_tmp:w { gset_protected_nopar } { n }
\__cs_tmp:w { gset_protected_nopar } { x }
\__cs_tmp:w { new }                  { n }
\__cs_tmp:w { new }                  { x }
\__cs_tmp:w { new_nopar }            { n }
\__cs_tmp:w { new_nopar }            { x }
\__cs_tmp:w { new_protected }        { n }
\__cs_tmp:w { new_protected }        { x }
\__cs_tmp:w { new_protected_nopar }  { n }
\__cs_tmp:w { new_protected_nopar }  { x }
%    \end{macrocode}
% \end{macro}
%
% \subsection{Checking control sequence equality}
%
% \begin{macro}[pTF, EXP]
%   {\cs_if_eq:NN, \cs_if_eq:cN, \cs_if_eq:Nc, \cs_if_eq:cc}
%   Check if two control sequences are identical.
%    \begin{macrocode}
\prg_new_conditional:Npnn \cs_if_eq:NN #1#2 { p , T , F , TF }
  {
    \if_meaning:w #1#2
      \prg_return_true: \else: \prg_return_false: \fi:
  }
\cs_new_nopar:Npn \cs_if_eq_p:cN { \exp_args:Nc  \cs_if_eq_p:NN }
\cs_new_nopar:Npn \cs_if_eq:cNTF { \exp_args:Nc  \cs_if_eq:NNTF }
\cs_new_nopar:Npn \cs_if_eq:cNT  { \exp_args:Nc  \cs_if_eq:NNT }
\cs_new_nopar:Npn \cs_if_eq:cNF  { \exp_args:Nc  \cs_if_eq:NNF }
\cs_new_nopar:Npn \cs_if_eq_p:Nc { \exp_args:NNc \cs_if_eq_p:NN }
\cs_new_nopar:Npn \cs_if_eq:NcTF { \exp_args:NNc \cs_if_eq:NNTF }
\cs_new_nopar:Npn \cs_if_eq:NcT  { \exp_args:NNc \cs_if_eq:NNT }
\cs_new_nopar:Npn \cs_if_eq:NcF  { \exp_args:NNc \cs_if_eq:NNF }
\cs_new_nopar:Npn \cs_if_eq_p:cc { \exp_args:Ncc \cs_if_eq_p:NN }
\cs_new_nopar:Npn \cs_if_eq:ccTF { \exp_args:Ncc \cs_if_eq:NNTF }
\cs_new_nopar:Npn \cs_if_eq:ccT  { \exp_args:Ncc \cs_if_eq:NNT }
\cs_new_nopar:Npn \cs_if_eq:ccF  { \exp_args:Ncc \cs_if_eq:NNF }
%    \end{macrocode}
% \end{macro}
%
% \subsection{Diagnostic functions}
%
% \begin{macro}[int]{\__kernel_register_show:N, \__kernel_register_show:c}
%   Check that the variable exists, then apply the \tn{showthe} primitive to
%   the variable.  The odd-looking \cs{use:n} gives a nicer output.
%    \begin{macrocode}
\cs_new_protected:Npn \__kernel_register_show:N #1
  {
    \cs_if_exist:NTF #1
      { \tex_showthe:D \use:n {#1} }
      {
        \__msg_kernel_error:nnx { kernel } { variable-not-defined }
          { \token_to_str:N #1 }
      }
  }
\cs_new_protected_nopar:Npn \__kernel_register_show:c
  { \exp_args:Nc \__kernel_register_show:N }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\cs_show:N, \cs_show:c}
% \begin{macro}[aux, EXP]{\__cs_show:www}
%   Some control sequences have a very long name or meaning.  Thus,
%   simply using \TeX{}'s primitive \tn{show} could lead to overlong
%   lines.  The output of this primitive is mimicked to some extent: a
%   line-break is added after the first colon in the meaning (this is
%   what \TeX{} does for macros and five |\...mark| primitives).  Then
%   the re-built string is given to \cs{iow_wrap:nnnN} for
%   line-wrapping.  The \cs{cs_show:c} command converts its argument to
%   a control sequence within a group to avoid showing \tn{relax} for
%   undefined control sequences.
%    \begin{macrocode}
\group_begin:
  \tex_lccode:D `? = `: \scan_stop:
  \tex_catcode:D `? = 12 \scan_stop:
\tex_lowercase:D
  {
    \group_end:
    \cs_new_protected:Npn \cs_show:N #1
      {
        \__msg_show_variable:n
          {
            > ~ \token_to_str:N #1 =
            \exp_after:wN \__cs_show:www \cs_meaning:N #1
              \use_none:nn ? \prg_do_nothing:
          }
      }
    \cs_new:Npn \__cs_show:www #1 ? { #1 ? \\ }
  }
\cs_new_protected_nopar:Npn \cs_show:c
  { \group_begin: \exp_args:NNc \group_end: \cs_show:N }
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \subsection{Engine specific definitions}
%
% \begin{macro}[pTF, EXP]
%   {\xetex_if_engine:, \luatex_if_engine:, \pdftex_if_engine:}
%   In some cases it will be useful to know which engine we're running.
%   This can all be hard-coded for speed.
%    \begin{macrocode}
\cs_new_eq:NN \luatex_if_engine:T  \use_none:n
\cs_new_eq:NN \luatex_if_engine:F  \use:n
\cs_new_eq:NN \luatex_if_engine:TF \use_ii:nn
\cs_new_eq:NN \pdftex_if_engine:T  \use:n
\cs_new_eq:NN \pdftex_if_engine:F  \use_none:n
\cs_new_eq:NN \pdftex_if_engine:TF \use_i:nn
\cs_new_eq:NN \xetex_if_engine:T   \use_none:n
\cs_new_eq:NN \xetex_if_engine:F   \use:n
\cs_new_eq:NN \xetex_if_engine:TF  \use_ii:nn
\cs_new_eq:NN \luatex_if_engine_p: \c_false_bool
\cs_new_eq:NN \pdftex_if_engine_p: \c_true_bool
\cs_new_eq:NN \xetex_if_engine_p:  \c_false_bool
\cs_if_exist:NT \xetex_XeTeXversion:D
  {
    \cs_gset_eq:NN \pdftex_if_engine:T  \use_none:n
    \cs_gset_eq:NN \pdftex_if_engine:F  \use:n
    \cs_gset_eq:NN \pdftex_if_engine:TF \use_ii:nn
    \cs_gset_eq:NN \xetex_if_engine:T   \use:n
    \cs_gset_eq:NN \xetex_if_engine:F   \use_none:n
    \cs_gset_eq:NN \xetex_if_engine:TF  \use_i:nn
    \cs_gset_eq:NN \pdftex_if_engine_p: \c_false_bool
    \cs_gset_eq:NN \xetex_if_engine_p:  \c_true_bool
  }
\cs_if_exist:NT \luatex_directlua:D
  {
    \cs_gset_eq:NN \luatex_if_engine:T  \use:n
    \cs_gset_eq:NN \luatex_if_engine:F  \use_none:n
    \cs_gset_eq:NN \luatex_if_engine:TF \use_i:nn
    \cs_gset_eq:NN \pdftex_if_engine:T  \use_none:n
    \cs_gset_eq:NN \pdftex_if_engine:F  \use:n
    \cs_gset_eq:NN \pdftex_if_engine:TF \use_ii:nn
    \cs_gset_eq:NN \luatex_if_engine_p: \c_true_bool
    \cs_gset_eq:NN \pdftex_if_engine_p: \c_false_bool
  }
%    \end{macrocode}
% \end{macro}
%
% \subsection{Doing nothing functions}
%
% \begin{macro}[EXP]{\prg_do_nothing:}
%   This does not fit anywhere else!
%    \begin{macrocode}
\cs_new_nopar:Npn \prg_do_nothing: { }
%    \end{macrocode}
% \end{macro}
%
% \subsection{String comparisons}
%
% \begin{macro}[pTF, EXP]{\str_if_eq:nn, \str_if_eq_x:nn}
%   Modern engines provide a direct way of comparing two token lists,
%   but returning a number. This set of conditionals therefore make life
%   a bit clearer. The \texttt{nn} and \texttt{xx} versions are created
%   directly as this is most efficient. These should eventually
%   move somewhere else.
%    \begin{macrocode}
\prg_new_conditional:Npnn \str_if_eq:nn #1#2 { p , T , F , TF }
  {
    \if_int_compare:w \pdftex_strcmp:D { \exp_not:n {#1} } { \exp_not:n {#2} }
      = \c_zero
      \prg_return_true: \else: \prg_return_false: \fi:
  }
\prg_new_conditional:Npnn \str_if_eq_x:nn #1#2 { p , T , F , TF }
  {
    \if_int_compare:w \pdftex_strcmp:D {#1} {#2} = \c_zero
      \prg_return_true: \else: \prg_return_false: \fi:
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}[int, EXP]{\__str_if_eq_x_return:nn}
%   It turns out that we often need to compare a token list
%   with the result of applying some function to it, and
%   return with \cs{prg_return_true/false:}. This test is
%   similar to \cs{str_if_eq:nnTF}, but hard-coded for speed.
%    \begin{macrocode}
\cs_new:Npn \__str_if_eq_x_return:nn #1 #2
  {
    \if_int_compare:w \pdftex_strcmp:D {#1} {#2} = \c_zero
      \prg_return_true:
    \else:
      \prg_return_false:
    \fi:
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}[EXP]{\str_case:nn, \str_case_x:nn}
% \begin{macro}[EXP, TF]{\str_case:nn, \str_case_x:nn}
% \begin{macro}[EXP, aux]{\__str_case:nnTF, \__str_case_x:nnTF}
% \begin{macro}[int, EXP]{\__prg_case_end:nw}
% \begin{macro}[aux, EXP]
%   {\__str_case:nw, \__str_case_x:nw, \__str_case_end:nw}
%   The aim here is to allow the case statement to be evaluated
%   using a known number of expansion steps (two), and without
%   needing to use an explicit \enquote{end of recursion} marker.
%   That is achieved by using the test input as the final case,
%   as this will always be true. The trick is then to tidy up
%   the output such that the appropriate case code plus either
%   the \texttt{true} or \texttt{false} branch code is inserted.
%    \begin{macrocode}
\cs_new:Npn \str_case:nn #1#2
  {
    \tex_romannumeral:D
    \__str_case:nnTF {#1} {#2} { } { }
  }
\cs_new:Npn \str_case:nnT #1#2#3
  {
    \tex_romannumeral:D
    \__str_case:nnTF {#1} {#2} {#3} { }
  }
\cs_new:Npn \str_case:nnF #1#2
  {
    \tex_romannumeral:D
    \__str_case:nnTF {#1} {#2} { }
  }
\cs_new:Npn \str_case:nnTF #1#2
  {
    \tex_romannumeral:D
    \__str_case:nnTF {#1} {#2}
  }
\cs_new:Npn \__str_case:nnTF #1#2#3#4
  { \__str_case:nw {#1} #2 {#1} { } \q_mark {#3} \q_mark {#4} \q_stop }
\cs_new:Npn \__str_case:nw #1#2#3
  {
    \str_if_eq:nnTF {#1} {#2}
      { \__str_case_end:nw {#3} }
      { \__str_case:nw {#1} }
  }
\cs_new:Npn \str_case_x:nn #1#2
  {
    \tex_romannumeral:D
    \__str_case_x:nnTF {#1} {#2} { } { }
  }
\cs_new:Npn \str_case_x:nnT #1#2#3
  {
    \tex_romannumeral:D
    \__str_case_x:nnTF {#1} {#2} {#3} { }
  }
\cs_new:Npn \str_case_x:nnF #1#2
  {
    \tex_romannumeral:D
    \__str_case_x:nnTF {#1} {#2} { }
  }
\cs_new:Npn \str_case_x:nnTF #1#2
  {
    \tex_romannumeral:D
    \__str_case_x:nnTF {#1} {#2}
  }
\cs_new:Npn \__str_case_x:nnTF #1#2#3#4
  { \__str_case_x:nw {#1} #2 {#1} { } \q_mark {#3} \q_mark {#4} \q_stop }
\cs_new:Npn \__str_case_x:nw #1#2#3
  {
    \str_if_eq_x:nnTF {#1} {#2}
      { \__str_case_end:nw {#3} }
      { \__str_case_x:nw {#1} }
  }
%    \end{macrocode}
%   To tidy up the recursion, there are two outcomes. If there was a hit to
%   one of the cases searched for, then |#1| will be the code to insert,
%   |#2| will be the \emph{next} case to check on and |#3| will be all of
%   the rest of the cases code. That means that |#4| will be the \texttt{true}
%   branch code, and |#5| will be tidy up the spare \cs{q_mark} and the
%   \texttt{false} branch. On the other hand, if none of the cases matched
%   then we arrive here using the \enquote{termination} case of comparing
%   the search with itself. That means that |#1| will be empty, |#2| will be
%   the first \cs{q_mark} and so |#4| will be the \texttt{false} code (the
%   \texttt{true} code is mopped up by |#3|).
%    \begin{macrocode}
\cs_new:Npn \__prg_case_end:nw #1#2#3 \q_mark #4#5 \q_stop
  { \c_zero #1 #4 }
\cs_new_eq:NN \__str_case_end:nw \__prg_case_end:nw
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \subsection{Breaking out of mapping functions}
%
% \begin{macro}[EXP]{\__prg_break_point:Nn, \__prg_map_break:Nn}
%   In inline mappings, the nesting level must be reset
%   at the end of the mapping, even when the user decides
%   to break out. This is done by putting the code that
%   must be performed as an argument of \cs{__prg_break_point:Nn}.
%   The breaking functions are then defined to jump to
%   that point and perform the argument of \cs{__prg_break_point:Nn},
%   before the user's code (if any).  There is a check that we close the
%   correct loop, otherwise we continue breaking.
%    \begin{macrocode}
\cs_new_eq:NN \__prg_break_point:Nn \use_ii:nn
\cs_new:Npn \__prg_map_break:Nn #1#2#3 \__prg_break_point:Nn #4#5
  {
    #5
    \if_meaning:w #1 #4
      \exp_after:wN \use_iii:nnn
    \fi:
    \__prg_map_break:Nn #1 {#2}
  }
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\__prg_break_point:}
% \begin{macro}{\__prg_break:, \__prg_break:n}
%   Very simple analogues of \cs{__prg_break_point:Nn} and
%   \cs{__prg_map_break:Nn}, for use in fast short-term recursions which
%   are not mappings, do not need to support nesting, and in which
%   nothing has to be done at the end of the loop.
%    \begin{macrocode}
\cs_new_eq:NN \__prg_break_point: \prg_do_nothing:
\cs_new:Npn \__prg_break: #1 \__prg_break_point: { }
\cs_new:Npn \__prg_break:n #1#2 \__prg_break_point: {#1}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \subsection{Deprecated functions}
%
% \begin{macro}{\str_case:nnn, \str_case_x:nnn}
%   Deprecated 2013-07-15.
%    \begin{macrocode}
\cs_new_eq:NN \str_case:nnn \str_case:nnF
\cs_new_eq:NN \str_case_x:nnn \str_case_x:nnF
%    \end{macrocode}
% \end{macro}
%
%    \begin{macrocode}
%</initex|package>
%    \end{macrocode}
%
% \end{implementation}
%
% \PrintIndex