summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/l3kernel/l3basics.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/l3kernel/l3basics.dtx')
-rw-r--r--macros/latex/contrib/l3kernel/l3basics.dtx3507
1 files changed, 0 insertions, 3507 deletions
diff --git a/macros/latex/contrib/l3kernel/l3basics.dtx b/macros/latex/contrib/l3kernel/l3basics.dtx
deleted file mode 100644
index 66e999fe62..0000000000
--- a/macros/latex/contrib/l3kernel/l3basics.dtx
+++ /dev/null
@@ -1,3507 +0,0 @@
-% \iffalse meta-comment
-%
-%% File: l3basics.dtx
-%
-% Copyright (C) 1990-2024 The LaTeX 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
-%
-% https://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 development version of the bundle can be found at
-%
-% https://github.com/latex3/latex3
-%
-% for those people who are interested.
-%
-%<*driver>
-\documentclass[full,kernel]{l3doc}
-\begin{document}
- \DocInput{\jobname.dtx}
-\end{document}
-%</driver>
-% \fi
-%
-% \title{^^A
-% The \pkg{l3basics} module\\ Basic definitions^^A
-% }
-%
-% \author{^^A
-% The \LaTeX{} Project\thanks
-% {^^A
-% E-mail:
-% \href{mailto:latex-team@latex-project.org}
-% {latex-team@latex-project.org}^^A
-% }^^A
-% }
-%
-% \date{Released 2024-03-14}
-%
-% \maketitle
-%
-% \begin{documentation}
-%
-% As the name suggests, this module holds some basic definitions which
-% are needed by most or all other modules in this set.
-%
-% Here we describe those functions that are used all over the place.
-% By 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.
-% \begin{texnote}
-% These are the \TeX{} primitives \tn{begingroup} and \tn{endgroup}.
-% \end{texnote}
-% \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 is 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), namely a ^^A{
-% |}| if standard category codes apply.
-% \begin{texnote}
-% This is the \TeX{} primitive \tn{aftergroup}.
-% \end{texnote}
-% \end{function}
-%
-% \begin{function}[added = 2021-05-11]{\group_show_list:, \group_log_list:}
-% \begin{syntax}
-% \cs{group_show_list:}
-% \cs{group_log_list:}
-% \end{syntax}
-% Display (to the terminal or log file) a list of the groups that are
-% currently opened. This is intended for tracking down problems.
-% \begin{texnote}
-% This is a wrapper around the \eTeX{} primitive \tn{showgroups}.
-% \end{texnote}
-% \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} are fully expanded
-% inside an \texttt{e}-type or \texttt{x}-type expansion.
-% In contrast, \enquote{protected} functions are not expanded within
-% \texttt{e} and \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 is 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[no-index]{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 results 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 does 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
-% does 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{e}-type or \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:variants-method}.
-%
-% \subsection{Defining new functions using parameter text}
-% \label{sec:l3basics:defining-new-function-1}
-%
-% \begin{function}
-% {
-% \cs_new:Npn, \cs_new:cpn,
-% \cs_new:Npe, \cs_new:cpe,
-% \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 results if the
-% \meta{function} is already defined.
-% \end{function}
-%
-% \begin{function}
-% {
-% \cs_new_nopar:Npn, \cs_new_nopar:cpn,
-% \cs_new_nopar:Npe, \cs_new_nopar:cpe,
-% \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 results if the \meta{function} is already defined.
-% \end{function}
-%
-% \begin{function}
-% {
-% \cs_new_protected:Npn, \cs_new_protected:cpn,
-% \cs_new_protected:Npe, \cs_new_protected:cpe,
-% \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{e}-type or
-% or \texttt{x}-type
-% argument. The definition is global and an error results 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:Npe, \cs_new_protected_nopar:cpe ,
-% \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{e}-type or \texttt{x}-type argument. The definition is global
-% and an error results if the \meta{function} is already defined.
-% \end{function}
-%
-% \begin{function}
-% {
-% \cs_set:Npn, \cs_set:cpn,
-% \cs_set:Npe, \cs_set:cpe,
-% \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:Npe, \cs_set_nopar:cpe,
-% \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:Npe, \cs_set_protected:cpe,
-% \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{e}-type or \texttt{x}-type argument.
-% \end{function}
-%
-% \begin{function}
-% {
-% \cs_set_protected_nopar:Npn, \cs_set_protected_nopar:cpn ,
-% \cs_set_protected_nopar:Npe, \cs_set_protected_nopar:cpe ,
-% \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{e}-type or \texttt{x}-type argument.
-% \end{function}
-%
-% \begin{function}
-% {
-% \cs_gset:Npn, \cs_gset:cpn,
-% \cs_gset:Npe, \cs_gset:cpe,
-% \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:Npe, \cs_gset_nopar:cpe,
-% \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:Npe, \cs_gset_protected:cpe,
-% \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{e}-type or \texttt{x}-type argument.
-% \end{function}
-%
-% \begin{function}
-% {
-% \cs_gset_protected_nopar:Npn, \cs_gset_protected_nopar:cpn,
-% \cs_gset_protected_nopar:Npe, \cs_gset_protected_nopar:cpe,
-% \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{e}-type or \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:Ne, \cs_new:ce
-% }
-% \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 results if the \meta{function} is already defined.
-% \end{function}
-%
-% \begin{function}
-% {
-% \cs_new_nopar:Nn, \cs_new_nopar:cn,
-% \cs_new_nopar:Ne, \cs_new_nopar:ce
-% }
-% \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 results if the \meta{function} is already defined.
-% \end{function}
-%
-% \begin{function}
-% {
-% \cs_new_protected:Nn, \cs_new_protected:cn,
-% \cs_new_protected:Ne, \cs_new_protected:ce
-% }
-% \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{e}-type
-% or \texttt{x}-type argument. The definition is global and
-% an error results 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:Ne, \cs_new_protected_nopar:ce
-% }
-% \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{e}-type or \texttt{x}-type argument. The definition is global and
-% an error results if the \meta{function} is already defined.
-% \end{function}
-%
-% \begin{function}
-% {
-% \cs_set:Nn, \cs_set:cn,
-% \cs_set:Ne, \cs_set:ce
-% }
-% \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:Ne, \cs_set_nopar:ce
-% }
-% \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:Ne, \cs_set_protected:ce
-% }
-% \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{e}-type
-% or \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:Ne, \cs_set_protected_nopar:ce
-% }
-% \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{e}-type or \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:Ne, \cs_gset:ce
-% }
-% \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:Ne, \cs_gset_nopar:ce
-% }
-% \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:Ne, \cs_gset_protected:ce
-% }
-% \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{e}-type
-% or \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:Ne, \cs_gset_protected_nopar:ce
-% }
-% \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{e}-type or \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:NNno,
-% \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} \Arg{number} \Arg{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. For a macro, this includes the \meta{replacement text}.
-% \begin{texnote}
-% This is the \TeX{} primitive \tn{meaning}.
-% For tokens that are not control sequences, it is more logical to
-% use \cs{token_to_meaning:N}.
-% The \texttt{c} variant correctly reports undefined arguments.
-% \end{texnote}
-% \end{function}
-%
-% \begin{function}[updated = 2017-02-14]{\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}
-%
-% \begin{function}[added = 2014-08-22, updated = 2017-02-14]{\cs_log:N, \cs_log:c}
-% \begin{syntax}
-% \cs{cs_log:N} \meta{control sequence}
-% \end{syntax}
-% Writes the definition of the \meta{control sequence} in the log
-% file. See also \cs{cs_show:N} which displays the result in the
-% terminal.
-% \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}
-% Expands the \meta{control sequence name} until only characters
-% remain, and then converts this into a control sequence. This process
-% requires two expansions. As in other \texttt{c}-type arguments the
-% \meta{control sequence name} must, when fully expanded, consist of
-% character tokens, typically a mixture of category code $10$ (space),
-% $11$ (letter) and $12$ (other).
-% \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}[noTF, EXP, 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}
-% \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
-% according to the conditional \cs{cs_if_exist:NTF}
-% (whether as a function or another control sequence type), and if it
-% is inserts the \meta{control sequence} into the input stream followed
-% by the \meta{true code}. Otherwise the \meta{false code} is used.
-% \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
-% 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 result does \emph{not} include
-% the current escape token, contrarily to \cs{token_to_str:N}.
-% Full expansion of this function requires exactly $2$ expansion
-% steps, and so an \texttt{e}-type or \texttt{x}-type expansion, or two
-% \texttt{o}-type expansions are required to
-% convert the \meta{control sequence} to a sequence of characters
-% in the input stream. In most cases, an \texttt{f}-expansion
-% is correct as well, but this loses a space at the start
-% of the result.
-% \end{function}
-%
-% \section{Analysing control sequences}
-%
-% \begin{function}[EXP, added = 2018-04-06]{\cs_split_function:N}
-% \begin{syntax}
-% \cs{cs_split_function: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).
-% This information is then placed in the input stream
-% 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}
-% does not include the escape character, and both the \meta{name} and
-% \meta{signature} are made up of tokens with category code $12$
-% (other).
-% \end{function}
-%
-% The next three functions decompose \TeX{} macros into their
-% constituent parts: if the \meta{token} passed is not a macro then no
-% decomposition can occur. In the latter case, all three functions leave
-% \cs{scan_stop:} in the input stream.
-%
-% \begin{function}[EXP, added = 2019-02-27]{\cs_prefix_spec:N}
-% \begin{syntax}
-% \cs{cs_prefix_spec:N} \meta{token}
-% \end{syntax}
-% If the \meta{token} is a macro, this function leaves the applicable
-% \TeX{} prefixes in input stream as a string of tokens of category
-% code $12$ (with spaces having category code $10$). Thus for example
-% \begin{verbatim}
-% \cs_set:Npn \next:nn #1#2 { x #1~y #2 }
-% \cs_prefix_spec:N \next:nn
-% \end{verbatim}
-% leaves |\long| in the input stream. If the \meta{token} is
-% not a macro then \cs{scan_stop:} is left in the input stream.
-% \begin{texnote}
-% The prefix can be empty, |\long|, |\protected| or
-% |\protected\long| with backslash replaced by the current escape
-% character.
-% \end{texnote}
-% \end{function}
-%
-% \begin{function}[EXP, added = 2022-06-24]{\cs_parameter_spec:N}
-% \begin{syntax}
-% \cs{cs_parameter_spec:N} \meta{token}
-% \end{syntax}
-% If the \meta{token} is a macro, this function leaves the primitive
-% \TeX{} parameter specification in input stream as a string of
-% character tokens of category code $12$ (with spaces having category
-% code $10$). Thus for example
-% \begin{verbatim}
-% \cs_set:Npn \next:nn #1#2 { x #1 y #2 }
-% \cs_parameter_spec:N \next:nn
-% \end{verbatim}
-% leaves |#1#2| in the input stream. If the \meta{token} is
-% not a macro then \cs{scan_stop:} is left in the input stream.
-% \begin{texnote}
-% If the parameter specification contains the string |->|, then the
-% function produces incorrect results.
-% \end{texnote}
-% \end{function}
-%
-% \begin{function}[EXP, added = 2019-02-27]{\cs_replacement_spec:N, \cs_replacement_spec:c}
-% \begin{syntax}
-% \cs{cs_replacement_spec:N} \meta{token}
-% \end{syntax}
-% If the \meta{token} is a macro, this function leaves the replacement
-% text in input stream as a string of character tokens of category
-% code $12$ (with spaces having category code $10$). Thus for example
-% \begin{verbatim}
-% \cs_set:Npn \next:nn #1#2 { x #1~y #2 }
-% \cs_replacement_spec:N \next:nn
-% \end{verbatim}
-% leaves \verb*|x#1 y#2| in the input stream. If the \meta{token} is
-% not a macro then \cs{scan_stop:} is left in the input stream.
-% \begin{texnote}
-% If the parameter specification contains the string |->|, then the
-% function produces incorrect results.
-% \end{texnote}
-% \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 when absorbing them
-% the outer set is 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 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 absorb between one and four
-% arguments, as indicated by the argument specifier. The braces
-% surrounding each argument are removed and the remaining tokens are
-% left in the input stream. The category code of these tokens is
-% also 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}
-% results in the input stream containing
-% \begin{verbatim}
-% abc { def }
-% \end{verbatim}
-% \emph{i.e.} only the outer braces are removed.
-% \begin{texnote}
-% The \cs{use:n} function is equivalent to \LaTeXe{}'s \tn{@firstofone}.
-% \end{texnote}
-% \end{function}
-%
-% \begin{function}[EXP]
-% {
-% \use_i:nn, \use_ii:nn ,
-% \use_i:nnn , \use_ii:nnn , \use_iii:nnn ,
-% \use_i:nnnn, \use_ii:nnnn, \use_iii:nnnn, \use_iv:nnnn ,
-% \use_i:nnnnn, \use_ii:nnnnn, \use_iii:nnnnn, \use_iv:nnnnn ,
-% \use_v:nnnnn ,
-% \use_i:nnnnnn, \use_ii:nnnnnn, \use_iii:nnnnnn, \use_iv:nnnnnn ,
-% \use_v:nnnnnn , \use_vi:nnnnnn ,
-% \use_i:nnnnnnn, \use_ii:nnnnnnn, \use_iii:nnnnnnn, \use_iv:nnnnnnn ,
-% \use_v:nnnnnnn , \use_vi:nnnnnnn , \use_vii:nnnnnnn ,
-% \use_i:nnnnnnnn, \use_ii:nnnnnnnn, \use_iii:nnnnnnnn, \use_iv:nnnnnnnn ,
-% \use_v:nnnnnnnn , \use_vi:nnnnnnnn , \use_vii:nnnnnnnn , \use_viii:nnnnnnnn ,
-% \use_i:nnnnnnnnn, \use_ii:nnnnnnnnn, \use_iii:nnnnnnnnn, \use_iv:nnnnnnnnn ,
-% \use_v:nnnnnnnnn , \use_vi:nnnnnnnnn , \use_vii:nnnnnnnnn , \use_viii:nnnnnnnnn ,
-% \use_ix:nnnnnnnnn
-% }
-% \begin{syntax}
-% \cs{use_i:nn} \Arg{arg_1} \Arg{arg_2}
-% \cs{use_i:nnn} \Arg{arg_1} \Arg{arg_2} \Arg{arg_3}
-% \cs{use_i:nnnn} \Arg{arg_1} \Arg{arg_2} \Arg{arg_3} \Arg{arg_4}
-% \cs{use_i:nnnnn} \Arg{arg_1} \Arg{arg_2} \Arg{arg_3} \Arg{arg_4} \Arg{arg_5}
-% \cs{use_i:nnnnnn} \Arg{arg_1} \Arg{arg_2} \Arg{arg_3} \Arg{arg_4} \Arg{arg_5} \Arg{arg_6}
-% \cs{use_i:nnnnnnn} \Arg{arg_1} \Arg{arg_2} \Arg{arg_3} \Arg{arg_4} \Arg{arg_5} \Arg{arg_6} \Arg{arg_7}
-% \cs{use_i:nnnnnnnn} \Arg{arg_1} \Arg{arg_2} \Arg{arg_3} \Arg{arg_4} \Arg{arg_5} \Arg{arg_6} \Arg{arg_7} \Arg{arg_8}
-% \cs{use_i:nnnnnnnnn} \Arg{arg_1} \Arg{arg_2} \Arg{arg_3} \Arg{arg_4} \Arg{arg_5} \Arg{arg_6} \Arg{arg_7} \Arg{arg_8} \Arg{arg_9}
-% \end{syntax}
-% These functions absorb a number ($n$) arguments from the input stream.
-% They then discard all arguments other than that indicated by the roman
-% numeral, which is left in the input stream. For example, \cs{use_i:nn}
-% discards the second argument, and leaves the content of the first
-% argument in the input stream.
-% The category code
-% of these tokens is also 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 function absorbs three arguments and leaves the content of the
-% first and second in the input stream. The category code of
-% these tokens is also fixed (if it has not already been by
-% some other absorption). A single expansion is needed for the
-% function to take effect. An example:
-% \begin{verbatim}
-% \use_i_ii:nnn { abc } { { def } } { ghi }
-% \end{verbatim}
-% results in the input stream containing
-% \begin{verbatim}
-% abc { def }
-% \end{verbatim}
-% \emph{i.e.} the outer braces are removed and the third group
-% is removed.
-% \end{function}
-%
-% \begin{function}[EXP, added = 2019-06-02]{\use_ii_i:nn}
-% \begin{syntax}
-% \cs{use_ii_i:nn} \Arg{arg_1} \Arg{arg_2}
-% \end{syntax}
-% This function absorbs two arguments and leaves the content of the
-% second and first in the input stream. The category code of
-% these tokens is also fixed (if it has not already been by
-% some other absorption). A single expansion is needed for the
-% function to take effect.
-% \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).
-% \begin{texnote}
-% These are equivalent to \LaTeXe{}'s \tn{@gobble}, \tn{@gobbletwo},
-% \emph{etc.}
-% \end{texnote}
-% \end{function}
-%
-% \begin{function}[EXP, added = 2018-06-18, updated = 2023-07-05]{\use:e}
-% \begin{syntax}
-% \cs{use:e} \Arg{expandable tokens}
-% \end{syntax}
-% Fully expands the \meta{token list} in an \texttt{e}-type manner,
-% in which parameter character (usually~|#|) need not be doubled, \emph{and}
-% the function remains fully expandable.
-% \begin{texnote}
-% \cs{use:e} is a wrapper around the primitive \tn{expanded}.
-% It requires two expansions to complete its action.
-% \end{texnote}
-% \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} from 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} from 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 turns 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 carries 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 is usually 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 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 are 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}
-% also exists 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}
-%
-% \subsection{Tests on control sequences}
-%
-% \begin{function}[EXP,pTF]{\cs_if_eq:NN}
-% \begin{syntax}
-% \cs{cs_if_eq_p:NN} \meta{cs_1} \meta{cs_2}
-% \cs{cs_if_eq:NNTF} \meta{cs_1} \meta{cs_2} \Arg{true code} \Arg{false code}
-% \end{syntax}
-% Compares the definition of two \meta{control sequences} and
-% is logically \texttt{true} if they are 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
-% definition of \meta{control sequence} other than \tn{relax}
-% evaluates 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 is \texttt{false} if the
-% \meta{control sequence} currently exists (as defined by
-% \cs{cs_if_exist:NTF}).
-% \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 often contains 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
-% prefix primitive conditionals with |\if_|, except for \cs{if:w}.
-%
-% \begin{function}[EXP]
-% {\if_true:, \if_false:, \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. The function "\or:" is documented in \pkg{l3int} and
-% used in case switches.
-% \begin{texnote}
-% \cs{if_true:} and \cs{if_false:} are equivalent to their corresponding
-% \TeX{} primitive conditionals \tn{iftrue} and \tn{iffalse};
-% \cs{else:} and \cs{fi:} are the \TeX{} primitives \tn{else} and \tn{fi};
-% \cs{reverse_if:N} is the \eTeX{} primitive \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 the \TeX{} primitive \tn{ifx}.
-% \end{texnote}
-% \end{function}
-%
-% \begin{function}[EXP]{\if:w, \if_charcode:w, \if_catcode:w}
-% \begin{syntax}
-% "\if:w" <token(s)> <true code> "\else:" <false code> "\fi:" \\
-% "\if_catcode:w" <token(s)> <true code> "\else:" <false code> "\fi:"
-% \end{syntax}
-% "\if_charcode:w" is an alternative name for "\if:w".
-% These conditionals expand \meta{token(s)} until two
-% unexpandable tokens \meta{token_1} and \meta{token_2} are found;
-% any further tokens up to the next unbalanced "\else:" are the true branch,
-% ending with \meta{true code}. It is executed if the condition is fulfilled,
-% otherwise \meta{false code} is executed.
-% You can omit "\else:" when just in front of "\fi:" and
-% you can nest "\if...\else:...\fi:" constructs inside the true branch or the
-% \meta{false code}.
-% With "\exp_not:N", you can prevent the expansion of a token.
-%
-% "\if_catcode:w"
-% tests if \meta{token_1} and \meta{token_2} have the same category code whereas
-% "\if:w" and \cs{if_charcode:w} test if they have the same character code.
-% \begin{texnote}
-% \cs{if:w} and \cs{if_charcode:w} are both the \TeX{} primitive \tn{if}.
-% \cs{if_catcode:w} is the \TeX{} primitive \tn{ifcat}.
-% \end{texnote}
-% \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.
-% \begin{texnote}
-% These are the \TeX{} primitives \tn{ifdefined} and \tn{ifcsname}.
-% \end{texnote}
-% \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.
-% \begin{texnote}
-% These are the \TeX{} primitives \tn{ifhmode}, \tn{ifvmode}, \tn{ifmmode},
-% and~\tn{ifinner}.
-% \end{texnote}
-% \end{function}
-%
-% \section{Starting a paragraph}
-%
-% \begin{function}[added = 2017-07-04]{\mode_leave_vertical:}
-% \begin{syntax}
-% \cs{mode_leave_vertical:}
-% \end{syntax}
-% Ensures that \TeX{} is not in vertical (inter-paragraph) mode. In
-% horizontal or math mode this command has no effect, in vertical mode it
-% switches to horizontal mode, and inserts a box of width
-% \tn{parindent}, followed by the \tn{everypar} token list.
-% \begin{texnote}
-% This results in the contents of the \tn{everypar} token register being
-% inserted, after \cs{mode_leave_vertical:} is complete. Notice that in
-% contrast to the \LaTeXe{} \tn{leavevmode} approach, no box is used
-% by the method implemented here.
-% \end{texnote}
-% \end{function}
-%
-% \section{Debugging support}
-%
-% \begin{function}[added = 2017-07-16, updated = 2023-05-23]{\debug_on:n, \debug_off:n}
-% \begin{syntax}
-% \cs{debug_on:n} |{| \meta{comma-separated list} |}|
-% \cs{debug_off:n} |{| \meta{comma-separated list} |}|
-% \end{syntax}
-% Turn on and off within a group various debugging code, some of which
-% is also available as \pkg{expl3} load-time options. The items that
-% can be used in the \meta{list} are
-% \begin{itemize}
-% \item \texttt{check-declarations} that checks all \pkg{expl3}
-% variables used were previously declared and that local/global
-% variables (based on their name or on their first assignment) are
-% only locally/globally assigned;
-% \item \texttt{check-expressions} that checks integer, dimension,
-% skip, and muskip expressions are not terminated prematurely;
-% \item \texttt{deprecation} that makes soon-to-be-deprecated commands produce errors;
-% \item \texttt{log-functions} that logs function definitions;
-% \item \texttt{all} that does all of the above.
-% \end{itemize}
-% Providing these as switches rather than options allows testing code
-% even if it relies on other packages: load all other packages, call
-% \cs{debug_on:n}, and load the code that one is interested in
-% testing.
-% \end{function}
-%
-% \begin{function}[added = 2017-11-28]{\debug_suspend:, \debug_resume:}
-% \begin{syntax}
-% \cs{debug_suspend:} \ldots{} \cs{debug_resume:}
-% \end{syntax}
-% Suppress (locally) errors and logging from \texttt{debug} commands,
-% except for the \texttt{deprecation} errors or warnings. These pairs
-% of commands can be nested. This can be used around pieces of code
-% that are known to fail checks, if such failures should be ignored.
-% See for instance \pkg{l3coffins}.
-% \end{function}
-%
-% \end{documentation}
-%
-% \begin{implementation}
-%
-% \section{\pkg{l3basics} implementation}
-%
-% \begin{macrocode}
-%<*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 we
-% 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[no-index]{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_global:D \tex_let:D \if_true: \tex_iftrue:D
-\tex_global:D \tex_let:D \if_false: \tex_iffalse:D
-\tex_global:D \tex_let:D \or: \tex_or:D
-\tex_global:D \tex_let:D \else: \tex_else:D
-\tex_global:D \tex_let:D \fi: \tex_fi:D
-\tex_global:D \tex_let:D \reverse_if:N \tex_unless:D
-\tex_global:D \tex_let:D \if:w \tex_if:D
-\tex_global:D \tex_let:D \if_charcode:w \tex_if:D
-\tex_global:D \tex_let:D \if_catcode:w \tex_ifcat:D
-\tex_global:D \tex_let:D \if_meaning:w \tex_ifx:D
-\tex_global:D \tex_let:D \if_bool:N \tex_ifodd: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_global:D \tex_let:D \if_mode_math: \tex_ifmmode:D
-\tex_global:D \tex_let:D \if_mode_horizontal: \tex_ifhmode:D
-\tex_global:D \tex_let:D \if_mode_vertical: \tex_ifvmode:D
-\tex_global: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_global:D \tex_let:D \if_cs_exist:N \tex_ifdefined:D
-\tex_global:D \tex_let:D \if_cs_exist:w \tex_ifcsname:D
-\tex_global:D \tex_let:D \cs:w \tex_csname:D
-\tex_global: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 five |\exp_| functions are used in the \pkg{l3expan} module
-% where they are described.
-% \begin{macrocode}
-\tex_global:D \tex_let:D \exp_after:wN \tex_expandafter:D
-\tex_global:D \tex_let:D \exp_not:N \tex_noexpand:D
-\tex_global:D \tex_let:D \exp_not:n \tex_unexpanded:D
-\tex_global:D \tex_let:D \exp:w \tex_romannumeral:D
-\tex_global:D \tex_chardef:D \exp_end: = 0 ~
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}[EXP]{\token_to_meaning:N, \cs_meaning:N}
-% Examining a control sequence or token.
-% \begin{macrocode}
-\tex_global:D \tex_let:D \token_to_meaning:N \tex_meaning:D
-\tex_global:D \tex_let:D \cs_meaning:N \tex_meaning:D
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}[EXP]{\tl_to_str:n, \token_to_str:N, \__kernel_tl_to_str:w}
-% Making strings.
-% \begin{macrocode}
-\tex_global:D \tex_let:D \tl_to_str:n \tex_detokenize:D
-\tex_global:D \tex_let:D \token_to_str:N \tex_string:D
-\tex_global:D \tex_let:D \__kernel_tl_to_str:w \tex_detokenize: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 \pkg{l3prg} module.
-% \begin{macrocode}
-\tex_global:D \tex_let:D \scan_stop: \tex_relax:D
-\tex_global:D \tex_let:D \group_begin: \tex_begingroup:D
-\tex_global:D \tex_let:D \group_end: \tex_endgroup:D
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macrocode}
-%<@@=int>
-% \end{macrocode}
-%
-% \begin{macro}[EXP]{\if_int_compare:w, \@@_to_roman:w}
-% For integers.
-% \begin{macrocode}
-\tex_global:D \tex_let:D \if_int_compare:w \tex_ifnum:D
-\tex_global:D \tex_let:D \@@_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_global:D \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_gdef:D \exp_args:Nc #1#2
- { \exp_after:wN #1 \cs:w #2 \cs_end: }
-\tex_long:D \tex_gdef: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, documented-as=\token_to_meaning:N]
-% {\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_gdef:D \token_to_str:c { \exp_args:Nc \token_to_str:N }
-\tex_long:D \tex_gdef: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_global:D \tex_let:D \token_to_meaning:c = \cs_meaning:c
-% \end{macrocode}
-% \end{macro}
-%
-% \subsection{Defining some constants}
-%
-% \begin{variable}{\c_zero_int}
-% We need the constant \cs{c_zero_int}
-% which is used by some functions in current module. The
-% rest are defined in the \pkg{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 \pkg{l3int} module is
-% required but it can't be used until the allocation has been set
-% up properly!
-% \begin{macrocode}
-\tex_global:D \tex_chardef:D \c_zero_int = 0 ~
-% \end{macrocode}
-% \end{variable}
-%
-% \begin{variable}{\c_max_register_int}
-% This is here as this particular integer is needed in modules
-% loaded before \pkg{l3int}, and is documented in \pkg{l3int}.
-% \LuaTeX{} and those which contain parts of the Omega extensions have
-% more registers available than \eTeX{}.
-% \begin{macrocode}
-\tex_ifdefined:D \tex_luatexversion:D
- \tex_global:D \tex_chardef:D \c_max_register_int = 65 535 ~
-\tex_else:D
- \tex_ifdefined:D \tex_omathchardef:D
- \tex_global:D \tex_omathchardef:D \c_max_register_int = 65535 ~
- \tex_else:D
- \tex_global:D \tex_mathchardef:D \c_max_register_int = 32767 ~
- \tex_fi:D
-\tex_fi:D
-% \end{macrocode}
-% \end{variable}
-%
-% \subsection{Defining functions}
-%
-% We start by providing functions for the typical definition
-% functions. First the global ones.
-%
-% \begin{macro}
-% {
-% \cs_gset_nopar:Npn , \cs_gset_nopar:Npe , \cs_gset_nopar:Npx ,
-% \cs_gset:Npn , \cs_gset:Npe , \cs_gset:Npx ,
-% \cs_gset_protected_nopar:Npn , \cs_gset_protected_nopar:Npe , \cs_gset_protected_nopar:Npx ,
-% \cs_gset_protected:Npn , \cs_gset_protected:Npe , \cs_gset_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_global:D \tex_let:D \cs_gset_nopar:Npn \tex_gdef:D
-\tex_global:D \tex_let:D \cs_gset_nopar:Npe \tex_xdef:D
-\tex_global:D \tex_let:D \cs_gset_nopar:Npx \tex_xdef:D
-\tex_protected:D \tex_long:D \tex_gdef:D \cs_gset:Npn
- { \tex_long:D \tex_gdef:D }
-\tex_protected:D \tex_long:D \tex_gdef:D \cs_gset:Npe
- { \tex_long:D \tex_xdef:D }
-\tex_global:D \tex_let:D \cs_gset:Npx \cs_gset:Npe
-\tex_protected:D \tex_long:D \tex_gdef:D \cs_gset_protected_nopar:Npn
- { \tex_protected:D \tex_gdef:D }
-\tex_protected:D \tex_long:D \tex_gdef:D \cs_gset_protected_nopar:Npe
- { \tex_protected:D \tex_xdef:D }
-\tex_global:D \tex_let:D \cs_gset_protected_nopar:Npx \cs_gset_protected_nopar:Npe
-\tex_protected:D \tex_long:D \tex_gdef:D \cs_gset_protected:Npn
- { \tex_protected:D \tex_long:D \tex_gdef:D }
-\tex_protected:D \tex_long:D \tex_gdef:D \cs_gset_protected:Npe
- { \tex_protected:D \tex_long:D \tex_xdef:D }
-\tex_global:D \tex_let:D \cs_gset_protected:Npx \cs_gset_protected:Npe
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}
-% {
-% \cs_set_nopar:Npn , \cs_set_nopar:Npe , \cs_set_nopar:Npx ,
-% \cs_set:Npn , \cs_set:Npe , \cs_set:Npx ,
-% \cs_set_protected_nopar:Npn , \cs_set_protected_nopar:Npe , \cs_set_protected_nopar:Npx ,
-% \cs_set_protected:Npn , \cs_set_protected:Npe , \cs_set_protected:Npx
-% }
-% Local versions of the above functions.
-% \begin{macrocode}
-\tex_global:D \tex_let:D \cs_set_nopar:Npn \tex_def:D
-\tex_global:D \tex_let:D \cs_set_nopar:Npe \tex_edef:D
-\tex_global:D \tex_let:D \cs_set_nopar:Npx \tex_edef:D
-\cs_gset_protected:Npn \cs_set:Npn
- { \tex_long:D \tex_def:D }
-\cs_gset_protected:Npn \cs_set:Npe
- { \tex_long:D \tex_edef:D }
-\tex_global:D \tex_let:D \cs_set:Npx \cs_set:Npe
-\cs_gset_protected:Npn \cs_set_protected_nopar:Npn
- { \tex_protected:D \tex_def:D }
-\cs_gset_protected:Npn \cs_set_protected_nopar:Npe
- { \tex_protected:D \tex_edef:D }
-\tex_global:D \tex_let:D \cs_set_protected_nopar:Npx \cs_set_protected_nopar:Npe
-\cs_gset_protected:Npn \cs_set_protected:Npn
- { \tex_protected:D \tex_long:D \tex_def:D }
-\cs_gset_protected:Npn \cs_set_protected:Npe
- { \tex_protected:D \tex_long:D \tex_edef:D }
-\tex_global:D \tex_let:D \cs_set_protected:Npx \cs_set_protected:Npe
-% \end{macrocode}
-% \end{macro}
-%
-% \subsection{Selecting tokens}
-%
-% \begin{macrocode}
-%<@@=exp>
-% \end{macrocode}
-%
-% \begin{variable}{\l_@@_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_gset_nopar:Npn \l_@@_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_gset:Npn \use:c #1 { \cs:w #1 \cs_end: }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}[deprecated]{\use:x}
-% Fully expands its argument and passes it to the input stream. Uses
-% the reserved \cs{l_@@_internal_tl} which we've set up above.
-% \begin{macrocode}
-\cs_gset_protected:Npn \use:x #1
- {
- \cs_set_nopar:Npx \l_@@_internal_tl {#1}
- \l_@@_internal_tl
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macrocode}
-%<@@=use>
-% \end{macrocode}
-%
-% \begin{macro}[EXP]{\use:e}
-% \begin{macrocode}
-\cs_gset:Npn \use:e #1 { \tex_expanded:D {#1} }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macrocode}
-%<@@=exp>
-% \end{macrocode}
-%
-% \begin{macro}[EXP]{\use:n, \use:nn, \use:nnn, \use:nnnn}
-% These macros grab their arguments and return them back to the input
-% (with outer braces removed).
-% \begin{macrocode}
-\cs_gset:Npn \use:n #1 {#1}
-\cs_gset:Npn \use:nn #1#2 {#1#2}
-\cs_gset:Npn \use:nnn #1#2#3 {#1#2#3}
-\cs_gset: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_gset:Npn \use_i:nn #1#2 {#1}
-\cs_gset: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:nnnn, \use_ii:nnnn, \use_iii:nnnn, \use_iv:nnnn ,
-% \use_i:nnnnn, \use_ii:nnnnn, \use_iii:nnnnn, \use_iv:nnnnn ,
-% \use_v:nnnnn ,
-% \use_i:nnnnnn, \use_ii:nnnnnn, \use_iii:nnnnnn, \use_iv:nnnnnn ,
-% \use_v:nnnnnn , \use_vi:nnnnnn ,
-% \use_i:nnnnnnn, \use_ii:nnnnnnn, \use_iii:nnnnnnn, \use_iv:nnnnnnn ,
-% \use_v:nnnnnnn , \use_vi:nnnnnnn , \use_vii:nnnnnnn ,
-% \use_i:nnnnnnnn, \use_ii:nnnnnnnn, \use_iii:nnnnnnnn, \use_iv:nnnnnnnn ,
-% \use_v:nnnnnnnn , \use_vi:nnnnnnnn , \use_vii:nnnnnnnn , \use_viii:nnnnnnnn ,
-% \use_i:nnnnnnnnn, \use_ii:nnnnnnnnn, \use_iii:nnnnnnnnn, \use_iv:nnnnnnnnn ,
-% \use_v:nnnnnnnnn , \use_vi:nnnnnnnnn , \use_vii:nnnnnnnnn , \use_viii:nnnnnnnnn ,
-% \use_ix:nnnnnnnnn
-% }
-% We also need something for picking up arguments from a longer list.
-% \begin{macrocode}
-\cs_gset:Npn \use_i:nnn #1#2#3 {#1}
-\cs_gset:Npn \use_ii:nnn #1#2#3 {#2}
-\cs_gset:Npn \use_iii:nnn #1#2#3 {#3}
-\cs_gset:Npn \use_i:nnnn #1#2#3#4 {#1}
-\cs_gset:Npn \use_ii:nnnn #1#2#3#4 {#2}
-\cs_gset:Npn \use_iii:nnnn #1#2#3#4 {#3}
-\cs_gset:Npn \use_iv:nnnn #1#2#3#4 {#4}
-\cs_gset:Npn \use_i:nnnnn #1#2#3#4#5 {#1}
-\cs_gset:Npn \use_ii:nnnnn #1#2#3#4#5 {#2}
-\cs_gset:Npn \use_iii:nnnnn #1#2#3#4#5 {#3}
-\cs_gset:Npn \use_iv:nnnnn #1#2#3#4#5 {#4}
-\cs_gset:Npn \use_v:nnnnn #1#2#3#4#5 {#5}
-\cs_gset:Npn \use_i:nnnnnn #1#2#3#4#5#6 {#1}
-\cs_gset:Npn \use_ii:nnnnnn #1#2#3#4#5#6 {#2}
-\cs_gset:Npn \use_iii:nnnnnn #1#2#3#4#5#6 {#3}
-\cs_gset:Npn \use_iv:nnnnnn #1#2#3#4#5#6 {#4}
-\cs_gset:Npn \use_v:nnnnnn #1#2#3#4#5#6 {#5}
-\cs_gset:Npn \use_vi:nnnnnn #1#2#3#4#5#6 {#6}
-\cs_gset:Npn \use_i:nnnnnnn #1#2#3#4#5#6#7 {#1}
-\cs_gset:Npn \use_ii:nnnnnnn #1#2#3#4#5#6#7 {#2}
-\cs_gset:Npn \use_iii:nnnnnnn #1#2#3#4#5#6#7 {#3}
-\cs_gset:Npn \use_iv:nnnnnnn #1#2#3#4#5#6#7 {#4}
-\cs_gset:Npn \use_v:nnnnnnn #1#2#3#4#5#6#7 {#5}
-\cs_gset:Npn \use_vi:nnnnnnn #1#2#3#4#5#6#7 {#6}
-\cs_gset:Npn \use_vii:nnnnnnn #1#2#3#4#5#6#7 {#7}
-\cs_gset:Npn \use_i:nnnnnnnn #1#2#3#4#5#6#7#8 {#1}
-\cs_gset:Npn \use_ii:nnnnnnnn #1#2#3#4#5#6#7#8 {#2}
-\cs_gset:Npn \use_iii:nnnnnnnn #1#2#3#4#5#6#7#8 {#3}
-\cs_gset:Npn \use_iv:nnnnnnnn #1#2#3#4#5#6#7#8 {#4}
-\cs_gset:Npn \use_v:nnnnnnnn #1#2#3#4#5#6#7#8 {#5}
-\cs_gset:Npn \use_vi:nnnnnnnn #1#2#3#4#5#6#7#8 {#6}
-\cs_gset:Npn \use_vii:nnnnnnnn #1#2#3#4#5#6#7#8 {#7}
-\cs_gset:Npn \use_viii:nnnnnnnn #1#2#3#4#5#6#7#8 {#8}
-\cs_gset:Npn \use_i:nnnnnnnnn #1#2#3#4#5#6#7#8#9 {#1}
-\cs_gset:Npn \use_ii:nnnnnnnnn #1#2#3#4#5#6#7#8#9 {#2}
-\cs_gset:Npn \use_iii:nnnnnnnnn #1#2#3#4#5#6#7#8#9 {#3}
-\cs_gset:Npn \use_iv:nnnnnnnnn #1#2#3#4#5#6#7#8#9 {#4}
-\cs_gset:Npn \use_v:nnnnnnnnn #1#2#3#4#5#6#7#8#9 {#5}
-\cs_gset:Npn \use_vi:nnnnnnnnn #1#2#3#4#5#6#7#8#9 {#6}
-\cs_gset:Npn \use_vii:nnnnnnnnn #1#2#3#4#5#6#7#8#9 {#7}
-\cs_gset:Npn \use_viii:nnnnnnnnn #1#2#3#4#5#6#7#8#9 {#8}
-\cs_gset:Npn \use_ix:nnnnnnnnn #1#2#3#4#5#6#7#8#9 {#9}
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}[EXP]{\use_i_ii:nnn}
-% \begin{macrocode}
-\cs_gset:Npn \use_i_ii:nnn #1#2#3 {#1#2}
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}[EXP]{\use_ii_i:nn}
-% \begin{macrocode}
-\cs_gset:Npn \use_ii_i:nn #1#2 { #2 #1 }
-% \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_gset:Npn \use_none_delimit_by_q_nil:w #1 \q_nil { }
-\cs_gset:Npn \use_none_delimit_by_q_stop:w #1 \q_stop { }
-\cs_gset:Npn \use_none_delimit_by_q_recursion_stop:w #1 \q_recursion_stop { }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}[EXP]
-% {
-% \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_gset:Npn \use_i_delimit_by_q_nil:nw #1#2 \q_nil {#1}
-\cs_gset:Npn \use_i_delimit_by_q_stop:nw #1#2 \q_stop {#1}
-\cs_gset: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 takes care
-% of gobbling all the tokens in one go.
-% \begin{macrocode}
-\cs_gset:Npn \use_none:n #1 { }
-\cs_gset:Npn \use_none:nn #1#2 { }
-\cs_gset:Npn \use_none:nnn #1#2#3 { }
-\cs_gset:Npn \use_none:nnnn #1#2#3#4 { }
-\cs_gset:Npn \use_none:nnnnn #1#2#3#4#5 { }
-\cs_gset:Npn \use_none:nnnnnn #1#2#3#4#5#6 { }
-\cs_gset:Npn \use_none:nnnnnnn #1#2#3#4#5#6#7 { }
-\cs_gset:Npn \use_none:nnnnnnnn #1#2#3#4#5#6#7#8 { }
-\cs_gset:Npn \use_none:nnnnnnnnn #1#2#3#4#5#6#7#8#9 { }
-% \end{macrocode}
-% \end{macro}
-%
-% \subsection{Debugging and patching later definitions}
-%
-% \begin{macrocode}
-%<@@=debug>
-% \end{macrocode}
-%
-% \begin{macro}{\__kernel_if_debug:TF}
-% A more meaningful test of whether debugging is enabled than messing
-% up with guards. We can also more easily change the logic in one
-% place then. This is needed primarily for deprecations.
-% \begin{macrocode}
-\cs_gset_protected:Npn \__kernel_if_debug:TF #1#2 {#2}
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\debug_on:n, \debug_off:n}
-% Stubs.
-% \begin{macrocode}
-\cs_gset_protected:Npn \debug_on:n #1
- {
- \sys_load_debug:
- \cs_if_exist:NT \@@_all_on:
- { \debug_on:n {#1} }
- }
-\cs_gset_protected:Npn \debug_off:n #1
- {
- \sys_load_debug:
- \cs_if_exist:NT \@@_all_on:
- { \debug_off:n {#1} }
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\debug_suspend:, \debug_resume:}
-% \begin{macrocode}
-\cs_gset_protected:Npn \debug_suspend: { }
-\cs_gset_protected:Npn \debug_resume: { }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\__kernel_deprecation_code:nn}
-% \begin{variable}{\g_@@_deprecation_on_tl, \g_@@_deprecation_off_tl}
-% Some commands were more recently deprecated and not yet removed;
-% only make these into errors if the user requests it. This relies on
-% two token lists, filled up in \pkg{l3deprecation}.
-% \begin{macrocode}
-\cs_gset_nopar:Npn \g_@@_deprecation_on_tl { }
-\cs_gset_nopar:Npn \g_@@_deprecation_off_tl { }
-\cs_gset_protected:Npn \__kernel_deprecation_code:nn #1#2
- {
- \tl_gput_right:Nn \g_@@_deprecation_on_tl {#1}
- \tl_gput_right:Nn \g_@@_deprecation_off_tl {#2}
- }
-% \end{macrocode}
-% \end{variable}
-% \end{macro}
-%
-% \subsection{Conditional processing and definitions}
-%
-% \begin{macrocode}
-%<@@=prg>
-% \end{macrocode}
-%
-% 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{exp:w} expands fully any
-% \cs{else:} and \cs{fi:} that are waiting to be discarded,
-% before reaching the \cs{exp_end:} which leaves an empty expansion.
-% 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_gset:Npn \prg_return_true:
- { \exp_after:wN \use_i:nn \exp:w }
-\cs_gset:Npn \prg_return_false:
- { \exp_after:wN \use_ii:nn \exp: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 would work.
-% \end{macro}
-%
-% \begin{macro}[EXP]{\@@_use_none_delimit_by_q_recursion_stop:w}
-% Private version of \cs{use_none_delimit_by_q_recursion_stop:w}.
-% \begin{macrocode}
-\cs_gset:Npn \@@_use_none_delimit_by_q_recursion_stop:w
- #1 \q_@@_recursion_stop { }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}
-% {
-% \prg_set_conditional:Npnn ,
-% \prg_gset_conditional:Npnn ,
-% \prg_new_conditional:Npnn ,
-% \prg_set_protected_conditional:Npnn ,
-% \prg_gset_protected_conditional:Npnn,
-% \prg_new_protected_conditional:Npnn
-% }
-% \begin{macro}{\@@_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.
-% Note that |e| stands for expandable and |p| for protected.
-% \begin{macrocode}
-\cs_gset_protected:Npn \prg_set_conditional:Npnn
- { \@@_generate_conditional_parm:NNNpnn \cs_set:Npn e }
-\cs_gset_protected:Npn \prg_gset_conditional:Npnn
- { \@@_generate_conditional_parm:NNNpnn \cs_gset:Npn e }
-\cs_gset_protected:Npn \prg_new_conditional:Npnn
- { \@@_generate_conditional_parm:NNNpnn \cs_new:Npn e }
-\cs_gset_protected:Npn \prg_set_protected_conditional:Npnn
- { \@@_generate_conditional_parm:NNNpnn \cs_set_protected:Npn p }
-\cs_gset_protected:Npn \prg_gset_protected_conditional:Npnn
- { \@@_generate_conditional_parm:NNNpnn \cs_gset_protected:Npn p }
-\cs_gset_protected:Npn \prg_new_protected_conditional:Npnn
- { \@@_generate_conditional_parm:NNNpnn \cs_new_protected:Npn p }
-\cs_gset_protected:Npn \@@_generate_conditional_parm:NNNpnn #1#2#3#4#
- {
- \use:e
- {
- \@@_generate_conditional:nnNNNnnn
- \cs_split_function:N #3
- }
- #1 #2 {#4}
- }
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
-%
-% \begin{macro}
-% {
-% \prg_set_conditional:Nnn ,
-% \prg_gset_conditional:Nnn ,
-% \prg_new_conditional:Nnn ,
-% \prg_set_protected_conditional:Nnn ,
-% \prg_gset_protected_conditional:Nnn,
-% \prg_new_protected_conditional:Nnn
-% }
-% \begin{macro}
-% {
-% \@@_generate_conditional_count:NNNnn ,
-% \@@_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_gset_protected:Npn \prg_set_conditional:Nnn
- { \@@_generate_conditional_count:NNNnn \cs_set:Npn e }
-\cs_gset_protected:Npn \prg_gset_conditional:Nnn
- { \@@_generate_conditional_count:NNNnn \cs_set:Npn e }
-\cs_gset_protected:Npn \prg_new_conditional:Nnn
- { \@@_generate_conditional_count:NNNnn \cs_new:Npn e }
-\cs_gset_protected:Npn \prg_set_protected_conditional:Nnn
- { \@@_generate_conditional_count:NNNnn \cs_set_protected:Npn p }
-\cs_gset_protected:Npn \prg_gset_protected_conditional:Nnn
- { \@@_generate_conditional_count:NNNnn \cs_gset_protected:Npn p }
-\cs_gset_protected:Npn \prg_new_protected_conditional:Nnn
- { \@@_generate_conditional_count:NNNnn \cs_new_protected:Npn p }
-\cs_gset_protected:Npn \@@_generate_conditional_count:NNNnn #1#2#3
- {
- \use:e
- {
- \@@_generate_conditional_count:nnNNNnn
- \cs_split_function:N #3
- }
- #1 #2
- }
-\cs_gset_protected:Npn \@@_generate_conditional_count:nnNNNnn #1#2#3#4#5
- {
- \__kernel_cs_parm_from_arg_count:nnF
- { \@@_generate_conditional:nnNNNnnn {#1} {#2} #3 #4 #5 }
- { \tl_count:n {#2} }
- {
- \msg_error:nnee { 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}
-% {
-% \@@_generate_conditional:nnNNNnnn,
-% \@@_generate_conditional:NNnnnnNw,
-% \@@_generate_conditional_test:w,
-% \@@_generate_conditional_fast:nw,
-% }
-% 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{tl_to_str:n} makes the later loop more robust.
-%
-% A large number of our low-level conditionals look like \meta{code}
-% \cs{prg_return_true:} \cs{else:} \cs{prg_return_false:} \cs{fi:} so
-% we optimize this special case by calling
-% \cs{@@_generate_conditional_fast:nw} \Arg{code}. This passes
-% \cs{use_i:nn} instead of \cs{use_i_ii:nnn} to functions such as
-% \cs{@@_generate_p_form:wNNnnnnN}.
-% \begin{macrocode}
-\cs_gset_protected:Npn \@@_generate_conditional:nnNNNnnn #1#2#3#4#5#6#7#8
- {
- \if_meaning:w \c_false_bool #3
- \msg_error:nne { kernel } { missing-colon }
- { \token_to_str:c {#1} }
- \exp_after:wN \use_none:nn
- \fi:
- \use:e
- {
- \exp_not:N \@@_generate_conditional:NNnnnnNw
- \exp_not:n { #4 #5 {#1} {#2} {#6} }
- \@@_generate_conditional_test:w
- #8 \s_@@_mark
- \@@_generate_conditional_fast:nw
- \prg_return_true: \else: \prg_return_false: \fi: \s_@@_mark
- \use_none:n
- \exp_not:n { {#8} \use_i_ii:nnn }
- \tl_to_str:n {#7}
- \exp_not:n { , \q_@@_recursion_tail , \q_@@_recursion_stop }
- }
- }
-\cs_gset:Npn \@@_generate_conditional_test:w
- #1 \prg_return_true: \else: \prg_return_false: \fi: \s_@@_mark #2
- { #2 {#1} }
-\cs_gset:Npn \@@_generate_conditional_fast:nw #1#2 \exp_not:n #3
- { \exp_not:n { {#1} \use_i:nn } }
-% \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:nnnnnnnn} cleans up. Otherwise, the
-% error message is removed by the variant form.
-% \begin{macrocode}
-\cs_gset_protected:Npn \@@_generate_conditional:NNnnnnNw #1#2#3#4#5#6#7#8 ,
- {
- \if_meaning:w \q_@@_recursion_tail #8
- \exp_after:wN \@@_use_none_delimit_by_q_recursion_stop:w
- \fi:
- \use:c { @@_generate_ #8 _form:wNNnnnnN }
- \tl_if_empty:nF {#8}
- {
- \msg_error:nnee
- { kernel } { conditional-form-unknown }
- {#8} { \token_to_str:c { #3 : #4 } }
- }
- \use_none:nnnnnnnn
- \s_@@_stop
- #1 #2 {#3} {#4} {#5} {#6} #7
- \@@_generate_conditional:NNnnnnNw #1 #2 {#3} {#4} {#5} {#6} #7
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}
-% {
-% \@@_generate_p_form:wNNnnnnN,
-% \@@_generate_TF_form:wNNnnnnN,
-% \@@_generate_T_form:wNNnnnnN,
-% \@@_generate_F_form:wNNnnnnN
-% }
-% \begin{macro}[EXP]{\@@_p_true:w, \@@_T_true:w, \@@_F_true:w, \@@_TF_true:w}
-% How to generate the various forms. Those functions take the
-% following arguments: 1: junk, 2: \cs{cs_set:Npn} or similar, 3: |p|
-% (for protected conditionals) or |e|, 4: function name, 5: signature,
-% 6: parameter text, 7: replacement (possibly trimmed by
-% \cs{@@_generate_conditional_fast:nw}), 8: \cs{use_i_ii:nnn} or
-% \cs{use_i:nn} (for \enquote{fast} conditionals). Remember that the
-% logic-returning functions expect two arguments to be present after
-% \cs{exp_end:}: notice the construction of the different variants
-% relies on this, and that the |TF| and |F| variants 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. For \enquote{fast} conditionals, |#7| has an
-% extra \cs[no-index]{if_\ldots{}}. To optimize a bit further we
-% don't use \cs{exp_after:wN} \cs{use_ii:nnn} and similar but instead use
-% \cs{@@_TF_true:w} and similar to swap out the macro after \cs{fi:}. It would
-% be a tiny bit faster if we directly grabbed the |T| and |F| arguments there,
-% but if those are actually missing, the recovery from the runaway argument
-% would not insert \cs{fi:} back, messing up nesting of conditionals.
-% \begin{macrocode}
-\cs_gset_protected:Npn \@@_generate_p_form:wNNnnnnN
- #1 \s_@@_stop #2#3#4#5#6#7#8
- {
- \if_meaning:w e #3
- \exp_after:wN \use_i:nn
- \else:
- \exp_after:wN \use_ii:nn
- \fi:
- {
- #8
- { \exp_args:Nc #2 { #4 _p: #5 } #6 }
- { { #7 \exp_end: \c_true_bool \c_false_bool } }
- { #7 \@@_p_true:w \fi: \c_false_bool }
- }
- {
- \msg_error:nne { kernel } { protected-predicate }
- { \token_to_str:c { #4 _p: #5 } }
- }
- }
-\cs_gset_protected:Npn \@@_generate_T_form:wNNnnnnN
- #1 \s_@@_stop #2#3#4#5#6#7#8
- {
- #8
- { \exp_args:Nc #2 { #4 : #5 T } #6 }
- { { #7 \exp_end: \use:n \use_none:n } }
- { #7 \@@_T_true:w \fi: \use_none:n }
- }
-\cs_gset_protected:Npn \@@_generate_F_form:wNNnnnnN
- #1 \s_@@_stop #2#3#4#5#6#7#8
- {
- #8
- { \exp_args:Nc #2 { #4 : #5 F } #6 }
- { { #7 \exp_end: { } } }
- { #7 \@@_F_true:w \fi: \use:n }
- }
-\cs_gset_protected:Npn \@@_generate_TF_form:wNNnnnnN
- #1 \s_@@_stop #2#3#4#5#6#7#8
- {
- #8
- { \exp_args:Nc #2 { #4 : #5 TF } #6 }
- { { #7 \exp_end: } }
- { #7 \@@_TF_true:w \fi: \use_ii:nn }
- }
-\cs_gset:Npn \@@_p_true:w \fi: \c_false_bool { \fi: \c_true_bool }
-\cs_gset:Npn \@@_T_true:w \fi: \use_none:n { \fi: \use:n }
-\cs_gset:Npn \@@_F_true:w \fi: \use:n { \fi: \use_none:n }
-\cs_gset:Npn \@@_TF_true:w \fi: \use_ii:nn { \fi: \use_i:nn }
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
-%
-% \begin{macro}
-% {
-% \prg_set_eq_conditional:NNn ,
-% \prg_gset_eq_conditional:NNn,
-% \prg_new_eq_conditional:NNn
-% }
-% \begin{macro}{\@@_set_eq_conditional:NNNn}
-% The setting-equal functions. Split both functions and feed
-% \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}
-% to a first auxiliary.
-% \begin{macrocode}
-\cs_gset_protected:Npn \prg_set_eq_conditional:NNn
- { \@@_set_eq_conditional:NNNn \cs_set_eq:cc }
-\cs_gset_protected:Npn \prg_gset_eq_conditional:NNn
- { \@@_set_eq_conditional:NNNn \cs_gset_eq:cc }
-\cs_gset_protected:Npn \prg_new_eq_conditional:NNn
- { \@@_set_eq_conditional:NNNn \cs_new_eq:cc }
-\cs_gset_protected:Npn \@@_set_eq_conditional:NNNn #1#2#3#4
- {
- \use:e
- {
- \exp_not:N \@@_set_eq_conditional:nnNnnNNw
- \cs_split_function:N #2
- \cs_split_function:N #3
- \exp_not:N #1
- \tl_to_str:n {#4}
- \exp_not:n { , \q_@@_recursion_tail , \q_@@_recursion_stop }
- }
- }
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
-%
-% \begin{macro}
-% {
-% \@@_set_eq_conditional:nnNnnNNw ,
-% \@@_set_eq_conditional_loop:nnnnNw
-% }
-% \begin{macro}[EXP]
-% {
-% \@@_set_eq_conditional_p_form:nnn ,
-% \@@_set_eq_conditional_TF_form:nnn ,
-% \@@_set_eq_conditional_T_form:nnn ,
-% \@@_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_gset_protected:Npn \@@_set_eq_conditional:nnNnnNNw #1#2#3#4#5#6
- {
- \if_meaning:w \c_false_bool #3
- \msg_error:nne { 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_error:nne { kernel } { missing-colon }
- { \token_to_str:c {#4} }
- \exp_after:wN \@@_use_none_delimit_by_q_recursion_stop:w
- \fi:
- \@@_set_eq_conditional_loop:nnnnNw {#1} {#2} {#4} {#5}
- }
-\cs_gset_protected:Npn \@@_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 { @@_set_eq_conditional_ #6 _form:wNnnnn }
- \tl_if_empty:nF {#6}
- {
- \msg_error:nnee
- { kernel } { conditional-form-unknown }
- {#6} { \token_to_str:c { #1 : #2 } }
- }
- \use_none:nnnnnn
- \s_@@_stop
- #5 {#1} {#2} {#3} {#4}
- \@@_set_eq_conditional_loop:nnnnNw {#1} {#2} {#3} {#4} #5
- }
-\cs_gset:Npn \@@_set_eq_conditional_p_form:wNnnnn #1 \s_@@_stop #2#3#4#5#6
- { #2 { #3 _p : #4 } { #5 _p : #6 } }
-\cs_gset:Npn \@@_set_eq_conditional_TF_form:wNnnnn #1 \s_@@_stop #2#3#4#5#6
- { #2 { #3 : #4 TF } { #5 : #6 TF } }
-\cs_gset:Npn \@@_set_eq_conditional_T_form:wNnnnn #1 \s_@@_stop #2#3#4#5#6
- { #2 { #3 : #4 T } { #5 : #6 T } }
-\cs_gset:Npn \@@_set_eq_conditional_F_form:wNnnnn #1 \s_@@_stop #2#3#4#5#6
- { #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_global:D \tex_chardef:D \c_true_bool = 1 ~
-\tex_global:D \tex_chardef:D \c_false_bool = 0 ~
-% \end{macrocode}
-% \end{variable}
-%
-% \subsection{Dissecting a control sequence}
-%
-% \begin{macrocode}
-%<@@=cs>
-% \end{macrocode}
-%
-% \begin{function}[EXP]{\@@_count_signature:N}
-% \begin{syntax}
-% \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}{\@@_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{macro}[EXP]{\cs_to_str:N}
-% \begin{macro}[EXP]{\@@_to_str:N, \@@_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{@@_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{tex_romannumeral:D}.
-% 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{@@_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{tex_romannumeral:D} with \cs{c_zero_int}.
-% 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{@@_to_str:w}
-% comes into play, inserting |-\int_value:w|, which expands \cs{c_zero_int}
-% to the character |0|. The initial \cs{tex_romannumeral:D} then sees
-% |0|, which is not a terminated number, followed by the escape character,
-% a space, which is removed, terminating the expansion of
-% \cs{tex_romannumeral:D}.
-% In all three cases, \cs{cs_to_str:N} takes two expansion steps
-% to be fully expanded.
-% \begin{macrocode}
-\cs_gset:Npn \cs_to_str:N
- {
-% \end{macrocode}
-% We implement the expansion scheme using \cs{tex_romannumeral:D}
-% terminating it with \cs{c_zero_int} rather than using \cs{exp:w} and
-% \cs{exp_end:} as we normally do. The reason is that the code
-% heavily depends on terminating the expansion with \cs{c_zero_int} so
-% we make this dependency explicit.
-% \begin{macrocode}
- \tex_romannumeral:D
- \if:w \token_to_str:N \ \@@_to_str:w \fi:
- \exp_after:wN \@@_to_str:N \token_to_str:N
- }
-\cs_gset:Npn \@@_to_str:N #1 { \c_zero_int }
-\cs_gset:Npn \@@_to_str:w #1 \@@_to_str:N
- { - \int_value:w \fi: \exp_after:wN \c_zero_int }
-% \end{macrocode}
-% If speed is a concern we could use \tn{csstring} in \LuaTeX{}. For
-% the empty csname that primitive gives an empty result while the
-% current \cs{cs_to_str:N} gives incorrect results in all engines
-% (this is impossible to fix without huge performance hit).
-% \end{macro}
-% \end{macro}
-%
-% \begin{macro}[EXP]{\cs_split_function:N}
-% \begin{macro}[EXP]
-% {\@@_split_function_auxi:w, \@@_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.
-%
-% 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{s_@@_mark},
-% then \cs{c_true_bool} as |#3|, and |#4| cleans up until \cs{s_@@_stop}.
-% Otherwise, the |#1| contains the function name and \cs{s_@@_mark}
-% \cs{c_true_bool}, |#2| is empty, |#3| is \cs{c_false_bool}, and |#4|
-% cleans up. The second
-% auxiliary trims the trailing \cs{s_@@_mark} from the function name if
-% present (that is, if the original function had no colon).
-% \begin{macrocode}
-\cs_gset_protected:Npn \@@_tmp:w #1
- {
- \cs_gset:Npn \cs_split_function:N ##1
- {
- \exp_after:wN \exp_after:wN \exp_after:wN
- \@@_split_function_auxi:w
- \cs_to_str:N ##1 \s_@@_mark \c_true_bool
- #1 \s_@@_mark \c_false_bool \s_@@_stop
- }
- \cs_gset:Npn \@@_split_function_auxi:w
- ##1 #1 ##2 \s_@@_mark ##3##4 \s_@@_stop
- { \@@_split_function_auxii:w ##1 \s_@@_mark \s_@@_stop {##2} ##3 }
- \cs_gset:Npn \@@_split_function_auxii:w ##1 \s_@@_mark ##2 \s_@@_stop
- { {##1} }
- }
-\exp_after:wN \@@_tmp:w \token_to_str:N :
-% \end{macrocode}
-% \end{macro}
-% \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}
-% \begin{macro}{\@@_if_exist_c_aux:,\@@_if_exist_c_aux:w}
-% 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:}.
-%
-% In both the |N| and |c| form we use the way \cs{prg_set_conditional:Npnn}
-% optimizes the conditionals to negate the tests using \cs{else:} (the
-% \cs{else:} in the top level functions will be removed by the optimization,
-% and this usage of \cs{else:} will be fine).
-% \begin{macrocode}
-\prg_gset_conditional:Npnn \cs_if_exist:N #1 { p , T , F , TF }
- {
- \if_meaning:w #1 \scan_stop:
- \use_i:nnnn
- \else:
- \fi:
- \if_cs_exist:N #1
- \prg_return_true:
- \else:
- \prg_return_false:
- \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}
-\cs_if_exist:NTF \tex_lastnamedcs:D
- {
- \prg_gset_conditional:Npnn \cs_if_exist:c #1 { p , T , F , TF }
- {
- \if_cs_exist:w #1 \cs_end:
- \@@_if_exist_c_aux:
- \prg_return_true:
- \else:
- \prg_return_false:
- \fi:
- }
- \cs_gset:Npn \@@_if_exist_c_aux:
- { \fi: \exp_after:wN \if_meaning:w \tex_lastnamedcs:D \scan_stop: \else: }
- }
- {
- \prg_gset_conditional:Npnn \cs_if_exist:c #1 { p , T , F , TF }
- {
- \if_cs_exist:w #1 \cs_end:
- \@@_if_exist_c_aux:w
- \fi:
- \use_none:n {#1}
- \if_false:
- \prg_return_true:
- \else:
- \prg_return_false:
- \fi:
- }
- \cs_gset:Npn \@@_if_exist_c_aux:w \fi: \use_none:n #1 \if_false:
- { \fi: \exp_after:wN \if_meaning:w \cs:w #1 \cs_end: \scan_stop: \else: }
- }
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
-%
-% \begin{macro}[pTF, EXP]{\cs_if_free:N, \cs_if_free:c}
-% The logical reversal of the above.
-% \begin{macrocode}
-\prg_gset_conditional:Npnn \cs_if_free:N #1 { p , T , F , TF }
- {
- \if_cs_exist:N #1
- \else:
- \use_none:nnnn
- \fi:
- \if_meaning:w #1 \scan_stop:
- \prg_return_true:
- \else:
- \prg_return_false:
- \fi:
- }
-\cs_if_exist:NTF \tex_lastnamedcs:D
- {
- \prg_gset_conditional:Npnn \cs_if_free:c #1 { p , T , F , TF }
- {
- \if_cs_exist:w #1 \cs_end:
- \@@_if_free_c_aux:w
- \fi:
- \if_true:
- \prg_return_true:
- \else:
- \prg_return_false:
- \fi:
- }
- \cs_gset:Npn \@@_if_free_c_aux:w \fi: \if_true:
- { \fi: \exp_after:wN \if_meaning:w \tex_lastnamedcs:D \scan_stop: }
- }
- {
- \prg_gset_conditional:Npnn \cs_if_free:c #1 { p , T , F , TF }
- {
- \if_cs_exist:w #1 \cs_end:
- \@@_if_free_c_aux:w
- \fi:
- \use_none:n {#1}
- \if_true:
- \prg_return_true:
- \else:
- \prg_return_false:
- \fi:
- }
- \cs_gset:Npn \@@_if_free_c_aux:w \fi: \use_none:n #1 \if_true:
- { \fi: \exp_after:wN \if_meaning:w \cs:w #1 \cs_end: \scan_stop: }
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}[EXP,noTF,added=2011-10-10]
-% {\cs_if_exist_use:N, \cs_if_exist_use:c}
-% \begin{macro}{\@@_if_exist_use_aux:w, \@@_if_exist_use_aux:Nnn}
-% The \cs[index=cs_if_exist_use:N]{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.
-% If available we use the \tn{lastnamedcs} primitive.
-% \begin{macrocode}
-\cs_gset:Npn \cs_if_exist_use:NTF #1#2
- { \cs_if_exist:NTF #1 { #1 #2 } }
-\cs_gset:Npn \cs_if_exist_use:NF #1
- { \cs_if_exist:NTF #1 #1 }
-\cs_gset:Npn \cs_if_exist_use:NT #1 #2
- { \cs_if_exist:NT #1 { #1 #2 } }
-\cs_gset:Npn \cs_if_exist_use:N #1
- { \cs_if_exist:NT #1 #1 }
-\cs_if_exist:NTF \tex_lastnamedcs:D
- {
- \cs_gset:Npn \cs_if_exist_use:cTF #1
- {
- \if_cs_exist:w #1 \cs_end:
- \@@_if_exist_use_aux:w
- \fi:
- \use_ii:nn
- }
- \cs_gset:Npn \@@_if_exist_use_aux:w \fi: \use_ii:nn
- { \fi: \exp_after:wN \@@_if_exist_use_aux:Nnn \tex_lastnamedcs:D }
- }
- {
- \cs_gset:Npn \cs_if_exist_use:cTF #1
- {
- \if_cs_exist:w #1 \cs_end:
- \@@_if_exist_use_aux:w
- \fi:
- \use_iii:nnn {#1}
- }
- \cs_gset:Npn \@@_if_exist_use_aux:w \fi: \use_iii:nnn #1
- { \fi: \exp_after:wN \@@_if_exist_use_aux:Nnn \cs:w #1 \cs_end: }
- }
-\cs_gset:Npn \@@_if_exist_use_aux:Nnn #1#2
- {
- \if_meaning:w #1 \scan_stop:
- \exp_after:wN \use_iii:nnn
- \fi:
- \use_i:nn { #1 #2 }
- }
-\cs_gset:Npn \cs_if_exist_use:cF #1
- { \cs_if_exist_use:cTF {#1} {} }
-\cs_gset:Npn \cs_if_exist_use:cT #1#2
- { \cs_if_exist_use:cTF {#1} {#2} {} }
-\cs_gset:Npn \cs_if_exist_use:c #1
- { \cs_if_exist_use:cTF {#1} {} {} }
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
-%
-% \subsection{Preliminaries for 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 next few definitions here are
-% only temporary, they will be redefined later on.
-%
-% \begin{macro}[documented-as = \msg_error:nnnn]
-% {\msg_error:nnee, \msg_error:nne, \msg_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. Setting the \tn{newlinechar} is needed, to
-% turn |^^J| into a proper line break in plain \TeX{}.
-% \begin{macrocode}
-\cs_gset_protected:Npn \msg_error:nnee #1#2#3#4
- {
- \tex_newlinechar:D = `\^^J \scan_stop:
- \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_gset_protected:Npn \msg_error:nne #1#2#3
- { \msg_error:nnee {#1} {#2} {#3} { } }
-\cs_gset_protected:Npn \msg_error:nn #1#2
- { \msg_error:nnee {#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_gset:Npn \msg_line_context:
- { on~line~ \tex_the:D \tex_inputlineno:D }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}[documented-as=\iow_log:n]{\iow_log:e, \iow_term:e}
-% 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{l3file}.
-% \begin{macrocode}
-\cs_gset_protected:Npn \iow_log:e
- { \tex_immediate:D \tex_write:D -1 }
-\cs_gset_protected:Npn \iow_term:e
- { \tex_immediate:D \tex_write:D 16 }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\__kernel_chk_if_free_cs:N, \__kernel_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_gset_protected:Npn \__kernel_chk_if_free_cs:N #1
- {
- \cs_if_free:NF #1
- {
- \msg_error:nnee { kernel } { command-already-defined }
- { \token_to_str:N #1 } { \token_to_meaning:N #1 }
- }
- }
-\cs_gset_protected:Npn \__kernel_chk_if_free_cs:c
- { \exp_args:Nc \__kernel_chk_if_free_cs:N }
-% \end{macrocode}
-% \end{macro}
-%
-% \subsection{Defining new functions}
-%
-% \begin{macrocode}
-%<@@=cs>
-% \end{macrocode}
-%
-% \begin{macro}
-% {
-% \cs_new_nopar:Npn , \cs_new_nopar:Npe , \cs_new_nopar:Npx ,
-% \cs_new:Npn , \cs_new:Npe , \cs_new:Npx ,
-% \cs_new_protected_nopar:Npn , \cs_new_protected_nopar:Npe , \cs_new_protected_nopar:Npx ,
-% \cs_new_protected:Npn , \cs_new_protected:Npe , \cs_new_protected:Npx
-% }
-% \begin{macro}{\@@_tmp:w}
-% Function which check that the control sequence is free before
-% defining it.
-% \begin{macrocode}
-\cs_set:Npn \@@_tmp:w #1#2
- {
- \cs_gset_protected:Npn #1 ##1
- {
- \__kernel_chk_if_free_cs:N ##1
- #2 ##1
- }
- }
-\@@_tmp:w \cs_new_nopar:Npn \cs_gset_nopar:Npn
-\@@_tmp:w \cs_new_nopar:Npe \cs_gset_nopar:Npe
-\@@_tmp:w \cs_new_nopar:Npx \cs_gset_nopar:Npx
-\@@_tmp:w \cs_new:Npn \cs_gset:Npn
-\@@_tmp:w \cs_new:Npe \cs_gset:Npe
-\@@_tmp:w \cs_new:Npx \cs_gset:Npx
-\@@_tmp:w \cs_new_protected_nopar:Npn \cs_gset_protected_nopar:Npn
-\@@_tmp:w \cs_new_protected_nopar:Npe \cs_gset_protected_nopar:Npe
-\@@_tmp:w \cs_new_protected_nopar:Npx \cs_gset_protected_nopar:Npx
-\@@_tmp:w \cs_new_protected:Npn \cs_gset_protected:Npn
-\@@_tmp:w \cs_new_protected:Npe \cs_gset_protected:Npe
-\@@_tmp:w \cs_new_protected:Npx \cs_gset_protected:Npx
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
-%
-% \begin{macro}[documented-as=\cs_set_nopar:Npn]
-% {
-% \cs_set_nopar:cpn , \cs_set_nopar:cpe , \cs_set_nopar:cpx ,
-% \cs_gset_nopar:cpn , \cs_gset_nopar:cpe , \cs_gset_nopar:cpx ,
-% \cs_new_nopar:cpn , \cs_new_nopar:cpe , \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} turns \meta{string}
-% into a csname and then assigns \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 \@@_tmp:w #1#2
- { \cs_new_protected_nopar:Npn #1 { \exp_args:Nc #2 } }
-\@@_tmp:w \cs_set_nopar:cpn \cs_set_nopar:Npn
-\@@_tmp:w \cs_set_nopar:cpe \cs_set_nopar:Npe
-\@@_tmp:w \cs_set_nopar:cpx \cs_set_nopar:Npx
-\@@_tmp:w \cs_gset_nopar:cpn \cs_gset_nopar:Npn
-\@@_tmp:w \cs_gset_nopar:cpe \cs_gset_nopar:Npe
-\@@_tmp:w \cs_gset_nopar:cpx \cs_gset_nopar:Npx
-\@@_tmp:w \cs_new_nopar:cpn \cs_new_nopar:Npn
-\@@_tmp:w \cs_new_nopar:cpe \cs_new_nopar:Npe
-\@@_tmp:w \cs_new_nopar:cpx \cs_new_nopar:Npx
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}[documented-as=\cs_set:Npn]
-% {
-% \cs_set:cpn , \cs_set:cpe , \cs_set:cpx ,
-% \cs_gset:cpn , \cs_gset:cpe , \cs_gset:cpx ,
-% \cs_new:cpn , \cs_new:cpe , \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}
-\@@_tmp:w \cs_set:cpn \cs_set:Npn
-\@@_tmp:w \cs_set:cpe \cs_set:Npe
-\@@_tmp:w \cs_set:cpx \cs_set:Npx
-\@@_tmp:w \cs_gset:cpn \cs_gset:Npn
-\@@_tmp:w \cs_gset:cpe \cs_gset:Npe
-\@@_tmp:w \cs_gset:cpx \cs_gset:Npx
-\@@_tmp:w \cs_new:cpn \cs_new:Npn
-\@@_tmp:w \cs_new:cpe \cs_new:Npe
-\@@_tmp:w \cs_new:cpx \cs_new:Npx
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}[documented-as=\cs_set_protected_nopar:Npn]
-% {
-% \cs_set_protected_nopar:cpn , \cs_set_protected_nopar:cpe , \cs_set_protected_nopar:cpx ,
-% \cs_gset_protected_nopar:cpn , \cs_gset_protected_nopar:cpe , \cs_gset_protected_nopar:cpx ,
-% \cs_new_protected_nopar:cpn , \cs_new_protected_nopar:cpe , \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}
-\@@_tmp:w \cs_set_protected_nopar:cpn \cs_set_protected_nopar:Npn
-\@@_tmp:w \cs_set_protected_nopar:cpe \cs_set_protected_nopar:Npe
-\@@_tmp:w \cs_set_protected_nopar:cpx \cs_set_protected_nopar:Npx
-\@@_tmp:w \cs_gset_protected_nopar:cpn \cs_gset_protected_nopar:Npn
-\@@_tmp:w \cs_gset_protected_nopar:cpe \cs_gset_protected_nopar:Npe
-\@@_tmp:w \cs_gset_protected_nopar:cpx \cs_gset_protected_nopar:Npx
-\@@_tmp:w \cs_new_protected_nopar:cpn \cs_new_protected_nopar:Npn
-\@@_tmp:w \cs_new_protected_nopar:cpe \cs_new_protected_nopar:Npe
-\@@_tmp:w \cs_new_protected_nopar:cpx \cs_new_protected_nopar:Npx
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}[documented-as=\cs_set_protected:Npn]
-% {
-% \cs_set_protected:cpn , \cs_set_protected:cpe , \cs_set_protected:cpx ,
-% \cs_gset_protected:cpn , \cs_gset_protected:cpe , \cs_gset_protected:cpx ,
-% \cs_new_protected:cpn , \cs_new_protected:cpe , \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}
-\@@_tmp:w \cs_set_protected:cpn \cs_set_protected:Npn
-\@@_tmp:w \cs_set_protected:cpe \cs_set_protected:Npe
-\@@_tmp:w \cs_set_protected:cpx \cs_set_protected:Npx
-\@@_tmp:w \cs_gset_protected:cpn \cs_gset_protected:Npn
-\@@_tmp:w \cs_gset_protected:cpe \cs_gset_protected:Npe
-\@@_tmp:w \cs_gset_protected:cpx \cs_gset_protected:Npx
-\@@_tmp:w \cs_new_protected:cpn \cs_new_protected:Npn
-\@@_tmp:w \cs_new_protected:cpe \cs_new_protected:Npe
-\@@_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:Npn \cs_set_eq:cN { \exp_args:Nc \cs_set_eq:NN }
-\cs_new_protected:Npn \cs_set_eq:Nc { \exp_args:NNc \cs_set_eq:NN }
-\cs_new_protected:Npn \cs_set_eq:cc { \exp_args:Ncc \cs_set_eq:NN }
-\cs_new_protected:Npn \cs_gset_eq:NN { \tex_global:D \cs_set_eq:NN }
-\cs_new_protected:Npn \cs_gset_eq:Nc { \exp_args:NNc \cs_gset_eq:NN }
-\cs_new_protected:Npn \cs_gset_eq:cN { \exp_args:Nc \cs_gset_eq:NN }
-\cs_new_protected:Npn \cs_gset_eq:cc { \exp_args:Ncc \cs_gset_eq:NN }
-\cs_new_protected:Npn \cs_new_eq:NN #1
- {
- \__kernel_chk_if_free_cs:N #1
- \tex_global:D \cs_set_eq:NN #1
- }
-\cs_new_protected:Npn \cs_new_eq:cN { \exp_args:Nc \cs_new_eq:NN }
-\cs_new_protected:Npn \cs_new_eq:Nc { \exp_args:NNc \cs_new_eq:NN }
-\cs_new_protected: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.
-% We optimize the case where the command exists by reducing as much as
-% possible the tokens in the conditional.
-% \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:
- \else:
- \use_i:nnnn
- \fi:
- \exp_args:Nc \cs_undefine:N {#1}
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \subsection{Generating parameter text from argument count}
-%
-% \begin{macrocode}
-%<@@=cs>
-% \end{macrocode}
-%
-% \begin{macro}{\__kernel_cs_parm_from_arg_count:nnF}
-% \begin{macro}{\@@_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_new_protected:Npn \__kernel_cs_parm_from_arg_count:nnF #1#2
- {
- \exp_args:Ne \@@_parm_from_arg_count_test:nnF
- {
- \exp_after:wN \exp_not:n
- \if_case:w \int_eval:n {#2}
- { }
- \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_new_protected:Npn \@@_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{macrocode}
-%<@@=cs>
-% \end{macrocode}
-%
-% \begin{macro}[EXP]{\@@_count_signature:N, \@@_count_signature:c}
-% \begin{macro}[EXP]{\@@_count_signature:n}
-% \begin{macro}[EXP]{\@@_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 \@@_count_signature:N #1
- { \exp_args:Nf \@@_count_signature:n { \cs_split_function:N #1 } }
-\cs_new:Npn \@@_count_signature:n #1
- { \int_eval:n { \@@_count_signature:nnN #1 } }
-\cs_new:Npn \@@_count_signature:nnN #1#2#3
- {
- \if_meaning:w \c_true_bool #3
- \tl_count:n {#2}
- \else:
- -1
- \fi:
- }
-\cs_new:Npn \@@_count_signature:c
- { \exp_args:Nc \@@_count_signature:N }
-% \end{macrocode}
-% \end{macro}
-% \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
- {
- \__kernel_cs_parm_from_arg_count:nnF { \use:nnn #2 #1 } {#3}
- {
- \msg_error:nnee { kernel } { bad-number-of-arguments }
- { \token_to_str:N #1 } { \int_eval:n {#3} }
- \use_none:n
- }
- {#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:Npn \cs_generate_from_arg_count:cNnn
- { \exp_args:Nc \cs_generate_from_arg_count:NNnn }
-\cs_new_protected: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}
-%
-% \begin{macrocode}
-%<@@=cs>
-% \end{macrocode}
-%
-% We can now combine some of the tools we have to provide a simple
-% interface for defining functions, where the number of arguments is
-% read from the signature. For instance,
-% |\cs_set:Nn \foo_bar:nn {#1,#2}|.
-%
-% \begin{macro}
-% {
-% \cs_set:Nn , \cs_set:Ne , \cs_set:Nx ,
-% \cs_set_nopar:Nn , \cs_set_nopar:Ne , \cs_set_nopar:Nx ,
-% \cs_set_protected:Nn , \cs_set_protected:Ne , \cs_set_protected:Nx ,
-% \cs_set_protected_nopar:Nn , \cs_set_protected_nopar:Ne , \cs_set_protected_nopar:Nx ,
-% \cs_gset:Nn , \cs_gset:Ne , \cs_gset:Nx ,
-% \cs_gset_nopar:Nn , \cs_gset_nopar:Ne , \cs_gset_nopar:Nx ,
-% \cs_gset_protected:Nn , \cs_gset_protected:Ne , \cs_gset_protected:Nx ,
-% \cs_gset_protected_nopar:Nn , \cs_gset_protected_nopar:Ne , \cs_gset_protected_nopar:Nx ,
-% \cs_new:Nn , \cs_new:Ne , \cs_new:Nx ,
-% \cs_new_nopar:Nn , \cs_new_nopar:Ne , \cs_new_nopar:Nx ,
-% \cs_new_protected:Nn , \cs_new_protected:Ne , \cs_new_protected:Nx ,
-% \cs_new_protected_nopar:Nn , \cs_new_protected_nopar:Ne , \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
-% { \@@_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 \@@_tmp:w #1#2#3
- {
- \cs_new_protected:cpx { cs_ #1 : #2 }
- {
- \exp_not:N \@@_generate_from_signature:NNn
- \exp_after:wN \exp_not:N \cs:w cs_ #1 : #3 \cs_end:
- }
- }
-\cs_new_protected:Npn \@@_generate_from_signature:NNn #1#2
- {
- \use:e
- {
- \@@_generate_from_signature:nnNNNn
- \cs_split_function:N #2
- }
- #1 #2
- }
-\cs_new_protected:Npn \@@_generate_from_signature:nnNNNn #1#2#3#4#5#6
- {
- \bool_if:NTF #3
- {
- \cs_set_nopar:Npx \@@_tmp:w
- { \tl_map_function:nN {#2} \@@_generate_from_signature:n }
- \tl_if_empty:oF \@@_tmp:w
- {
- \msg_error:nneee { kernel } { non-base-function }
- { \token_to_str:N #5 } {#2} { \@@_tmp:w }
- }
- \cs_generate_from_arg_count:NNnn
- #5 #4 { \tl_count:n {#2} } {#6}
- }
- {
- \msg_error:nne { kernel } { missing-colon }
- { \token_to_str:N #5 }
- }
- }
-\cs_new:Npn \@@_generate_from_signature:n #1
- {
- \if:w n #1 \else: \if:w N #1 \else:
- \if:w T #1 \else: \if:w F #1 \else: #1 \fi: \fi: \fi: \fi:
- }
-% \end{macrocode}
-% Then we define the 24 variants beginning with |N|.
-% \begin{macrocode}
-\@@_tmp:w { set } { Nn } { Npn }
-\@@_tmp:w { set } { Ne } { Npe }
-\@@_tmp:w { set } { Nx } { Npx }
-\@@_tmp:w { set_nopar } { Nn } { Npn }
-\@@_tmp:w { set_nopar } { Ne } { Npe }
-\@@_tmp:w { set_nopar } { Nx } { Npx }
-\@@_tmp:w { set_protected } { Nn } { Npn }
-\@@_tmp:w { set_protected } { Ne } { Npe }
-\@@_tmp:w { set_protected } { Nx } { Npx }
-\@@_tmp:w { set_protected_nopar } { Nn } { Npn }
-\@@_tmp:w { set_protected_nopar } { Ne } { Npe }
-\@@_tmp:w { set_protected_nopar } { Nx } { Npx }
-\@@_tmp:w { gset } { Nn } { Npn }
-\@@_tmp:w { gset } { Ne } { Npe }
-\@@_tmp:w { gset } { Nx } { Npx }
-\@@_tmp:w { gset_nopar } { Nn } { Npn }
-\@@_tmp:w { gset_nopar } { Ne } { Npe }
-\@@_tmp:w { gset_nopar } { Nx } { Npx }
-\@@_tmp:w { gset_protected } { Nn } { Npn }
-\@@_tmp:w { gset_protected } { Ne } { Npe }
-\@@_tmp:w { gset_protected } { Nx } { Npx }
-\@@_tmp:w { gset_protected_nopar } { Nn } { Npn }
-\@@_tmp:w { gset_protected_nopar } { Ne } { Npe }
-\@@_tmp:w { gset_protected_nopar } { Nx } { Npx }
-\@@_tmp:w { new } { Nn } { Npn }
-\@@_tmp:w { new } { Ne } { Npe }
-\@@_tmp:w { new } { Nx } { Npx }
-\@@_tmp:w { new_nopar } { Nn } { Npn }
-\@@_tmp:w { new_nopar } { Ne } { Npe }
-\@@_tmp:w { new_nopar } { Nx } { Npx }
-\@@_tmp:w { new_protected } { Nn } { Npn }
-\@@_tmp:w { new_protected } { Ne } { Npe }
-\@@_tmp:w { new_protected } { Nx } { Npx }
-\@@_tmp:w { new_protected_nopar } { Nn } { Npn }
-\@@_tmp:w { new_protected_nopar } { Ne } { Npe }
-\@@_tmp:w { new_protected_nopar } { Nx } { Npx }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}[documented-as=\cs_set:Nn]
-% {
-% \cs_set:cn , \cs_set:ce , \cs_set:cx ,
-% \cs_set_nopar:cn , \cs_set_nopar:ce , \cs_set_nopar:cx ,
-% \cs_set_protected:cn , \cs_set_protected:ce , \cs_set_protected:cx ,
-% \cs_set_protected_nopar:cn , \cs_set_protected_nopar:ce , \cs_set_protected_nopar:cx ,
-% \cs_gset:cn , \cs_gset:ce , \cs_gset:cx ,
-% \cs_gset_nopar:cn , \cs_gset_nopar:ce , \cs_gset_nopar:cx ,
-% \cs_gset_protected:cn , \cs_gset_protected:ce , \cs_gset_protected:cx ,
-% \cs_gset_protected_nopar:cn , \cs_gset_protected_nopar:ce , \cs_gset_protected_nopar:cx ,
-% \cs_new:cn , \cs_new:ce , \cs_new:cx ,
-% \cs_new_nopar:cn , \cs_new_nopar:ce , \cs_new_nopar:cx ,
-% \cs_new_protected:cn , \cs_new_protected:ce , \cs_new_protected:cx ,
-% \cs_new_protected_nopar:cn , \cs_new_protected_nopar:ce , \cs_new_protected_nopar:cx ,
-% }
-% The 24 |c| variants simply use \cs{exp_args:Nc}.
-% \begin{macrocode}
-\cs_set:Npn \@@_tmp:w #1#2
- {
- \cs_new_protected: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:
- }
- }
-\@@_tmp:w { set } { n }
-\@@_tmp:w { set } { e }
-\@@_tmp:w { set } { x }
-\@@_tmp:w { set_nopar } { n }
-\@@_tmp:w { set_nopar } { e }
-\@@_tmp:w { set_nopar } { x }
-\@@_tmp:w { set_protected } { n }
-\@@_tmp:w { set_protected } { e }
-\@@_tmp:w { set_protected } { x }
-\@@_tmp:w { set_protected_nopar } { n }
-\@@_tmp:w { set_protected_nopar } { e }
-\@@_tmp:w { set_protected_nopar } { x }
-\@@_tmp:w { gset } { n }
-\@@_tmp:w { gset } { e }
-\@@_tmp:w { gset } { x }
-\@@_tmp:w { gset_nopar } { n }
-\@@_tmp:w { gset_nopar } { e }
-\@@_tmp:w { gset_nopar } { x }
-\@@_tmp:w { gset_protected } { n }
-\@@_tmp:w { gset_protected } { e }
-\@@_tmp:w { gset_protected } { x }
-\@@_tmp:w { gset_protected_nopar } { n }
-\@@_tmp:w { gset_protected_nopar } { e }
-\@@_tmp:w { gset_protected_nopar } { x }
-\@@_tmp:w { new } { n }
-\@@_tmp:w { new } { e }
-\@@_tmp:w { new } { x }
-\@@_tmp:w { new_nopar } { n }
-\@@_tmp:w { new_nopar } { e }
-\@@_tmp:w { new_nopar } { x }
-\@@_tmp:w { new_protected } { n }
-\@@_tmp:w { new_protected } { e }
-\@@_tmp:w { new_protected } { x }
-\@@_tmp:w { new_protected_nopar } { n }
-\@@_tmp:w { new_protected_nopar } { e }
-\@@_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:Npn \cs_if_eq_p:cN { \exp_args:Nc \cs_if_eq_p:NN }
-\cs_new:Npn \cs_if_eq:cNTF { \exp_args:Nc \cs_if_eq:NNTF }
-\cs_new:Npn \cs_if_eq:cNT { \exp_args:Nc \cs_if_eq:NNT }
-\cs_new:Npn \cs_if_eq:cNF { \exp_args:Nc \cs_if_eq:NNF }
-\cs_new:Npn \cs_if_eq_p:Nc { \exp_args:NNc \cs_if_eq_p:NN }
-\cs_new:Npn \cs_if_eq:NcTF { \exp_args:NNc \cs_if_eq:NNTF }
-\cs_new:Npn \cs_if_eq:NcT { \exp_args:NNc \cs_if_eq:NNT }
-\cs_new:Npn \cs_if_eq:NcF { \exp_args:NNc \cs_if_eq:NNF }
-\cs_new:Npn \cs_if_eq_p:cc { \exp_args:Ncc \cs_if_eq_p:NN }
-\cs_new:Npn \cs_if_eq:ccTF { \exp_args:Ncc \cs_if_eq:NNTF }
-\cs_new:Npn \cs_if_eq:ccT { \exp_args:Ncc \cs_if_eq:NNT }
-\cs_new:Npn \cs_if_eq:ccF { \exp_args:Ncc \cs_if_eq:NNF }
-% \end{macrocode}
-% \end{macro}
-%
-% \subsection{Diagnostic functions}
-%
-% \begin{macrocode}
-%<@@=kernel>
-% \end{macrocode}
-%
-% \begin{macro}{\@@_chk_defined:NT}
-% Error if the variable |#1| is not defined.
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_chk_defined:NT #1#2
- {
- \cs_if_exist:NTF #1
- {#2}
- {
- \msg_error:nne { kernel } { variable-not-defined }
- { \token_to_str:N #1 }
- }
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}
-% {\@@_register_show:N, \@@_register_show:c, \@@_register_log:N, \@@_register_log:c}
-% \begin{macro}{\@@_register_show_aux:NN, \@@_register_show_aux:nNN}
-% Simply using the \tn{showthe} primitive does not allow for
-% line-wrapping, so instead use \cs{tl_show:n} and \cs{tl_log:n} (defined
-% in \pkg{l3tl} and that performs line-wrapping). This displays
-% |>~|\meta{variable}|=|\meta{value}. We expand the value before-hand
-% as otherwise some integers (such as \tn{currentgrouplevel} or
-% \tn{currentgrouptype}) altered by the line-wrapping code would show
-% wrong values.
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_register_show:N
- { \@@_register_show_aux:NN \tl_show:n }
-\cs_new_protected:Npn \@@_register_show:c
- { \exp_args:Nc \@@_register_show:N }
-\cs_new_protected:Npn \@@_register_log:N
- { \@@_register_show_aux:NN \tl_log:n }
-\cs_new_protected:Npn \@@_register_log:c
- { \exp_args:Nc \@@_register_log:N }
-\cs_new_protected:Npn \@@_register_show_aux:NN #1#2
- {
- \@@_chk_defined:NT #2
- {
- \exp_args:No \@@_register_show_aux:nNN
- { \tex_the:D #2 } #2 #1
- }
- }
-\cs_new_protected:Npn \@@_register_show_aux:nNN #1#2#3
- { \exp_args:No #3 { \token_to_str:N #2 = #1 } }
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
-%
-% \begin{macro}{\cs_show:N, \cs_show:c, \cs_log:N, \cs_log:c, \@@_show:NN}
-% 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,
-% then the re-built string is given to \cs{tl_show:n} or \cs{tl_log:n} for
-% line-wrapping. We must expand the meaning before passing it to the
-% wrapping code as otherwise we would wrongly see the definitions that
-% are in place there. To get correct escape characters, set the
-% \tn{escapechar} in a group; this also localizes the assignment
-% performed by \texttt{e}-expansion. The \cs{cs_show:c} and \cs{cs_log:c} commands
-% convert their argument to a control sequence within a group to avoid
-% showing \tn{relax} for undefined control sequences.
-% \begin{macrocode}
-\cs_new_protected:Npn \cs_show:N { \@@_show:NN \tl_show:n }
-\cs_new_protected:Npn \cs_show:c
- { \group_begin: \exp_args:NNc \group_end: \cs_show:N }
-\cs_new_protected:Npn \cs_log:N { \@@_show:NN \tl_log:n }
-\cs_new_protected:Npn \cs_log:c
- { \group_begin: \exp_args:NNc \group_end: \cs_log:N }
-\cs_new_protected:Npn \@@_show:NN #1#2
- {
- \group_begin:
- \int_set:Nn \tex_escapechar:D { `\\ }
- \exp_args:NNe
- \group_end:
- #1 { \token_to_str:N #2 = \cs_meaning:N #2 }
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\group_show_list:, \group_log_list:, \@@_group_show:NN}
-% Wrapper around \tn{showgroups}. Getting \TeX{} to write to the log
-% without interruption the run is done by altering the interaction
-% mode.
-% \begin{macrocode}
-\cs_new_protected:Npn \group_show_list:
- { \@@_group_show:NN \use_none:n 1 }
-\cs_new_protected:Npn \group_log_list:
- { \@@_group_show:NN \int_gzero:N 0 }
-\cs_new_protected:Npn \@@_group_show:NN #1#2
- {
- \use:e
- {
- #1 \tex_interactionmode:D
- \int_set:Nn \tex_tracingonline:D {#2}
- \int_set:Nn \tex_errorcontextlines:D { -1 }
- \exp_not:N \exp_after:wN \scan_stop:
- \tex_showgroups:D
- \int_gset:Nn \tex_interactionmode:D
- { \int_use:N \tex_interactionmode:D }
- \int_set:Nn \tex_tracingonline:D
- { \int_use:N \tex_tracingonline:D }
- \int_set:Nn \tex_errorcontextlines:D
- { \int_use:N \tex_errorcontextlines:D }
- }
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \subsection{Decomposing a macro definition}
-%
-% \begin{macro}{\cs_prefix_spec:N}
-% \begin{macro}{\cs_parameter_spec:N}
-% \begin{macro}{\cs_replacement_spec:N}
-% \begin{macro}{\@@_prefix_arg_replacement:wN}
-% We sometimes want to test if a control sequence can be expanded to
-% reveal a hidden value. However, we cannot just expand the macro
-% blindly as it may have arguments and none might be
-% present. Therefore we define these functions to pick either the
-% prefix(es), the parameter specification, or the replacement text from
-% a macro. All of this information is returned as characters with
-% catcode~$12$. If the token in question isn't a macro, the token
-% \cs{scan_stop:} is returned instead.
-% \begin{macrocode}
-\use:e
- {
- \exp_not:n { \cs_new:Npn \@@_prefix_arg_replacement:wN #1 }
- \tl_to_str:n { macro : } \exp_not:n { #2 -> #3 \s_@@_stop #4 }
- }
- { #4 {#1} {#2} {#3} }
-\cs_new:Npn \cs_prefix_spec:N #1
- {
- \token_if_macro:NTF #1
- {
- \exp_after:wN \@@_prefix_arg_replacement:wN
- \token_to_meaning:N #1 \s_@@_stop \use_i:nnn
- }
- { \scan_stop: }
- }
-\cs_new:Npn \cs_parameter_spec:N #1
- {
- \token_if_macro:NTF #1
- {
- \exp_after:wN \@@_prefix_arg_replacement:wN
- \token_to_meaning:N #1 \s_@@_stop \use_ii:nnn
- }
- { \scan_stop: }
- }
-\cs_new:Npn \cs_replacement_spec:N #1
- {
- \token_if_macro:NTF #1
- {
- \exp_after:wN \@@_prefix_arg_replacement:wN
- \token_to_meaning:N #1 \s_@@_stop \use_iii:nnn
- }
- { \scan_stop: }
- }
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-%
-% \subsection{Doing nothing functions}
-%
-% \begin{macro}[EXP]{\prg_do_nothing:}
-% This does not fit anywhere else!
-% \begin{macrocode}
-\cs_new:Npn \prg_do_nothing: { }
-% \end{macrocode}
-% \end{macro}
-%
-% \subsection{Breaking out of mapping functions}
-%
-% \begin{macrocode}
-%<@@=prg>
-% \end{macrocode}
-%
-% \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{@@_break_point:Nn}.
-% The breaking functions are then defined to jump to
-% that point and perform the argument of \cs{@@_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{Starting a paragraph}
-%
-% \begin{macro}{\mode_leave_vertical:}
-% The approach here is different to that used by \LaTeXe{} or plain \TeX{},
-% which unbox a void box to force horizontal mode. That inserts the
-% \tn{everypar} tokens \emph{before} the re-inserted unboxing tokens. The
-% approach here uses a protected macro, equivalent to the \tn{quitvmode}
-% primitive. In vertical mode, the \tn{indent} primitive is inserted:
-% this will switch to horizontal mode and insert \tn{everypar} tokens and
-% nothing else. Unlike the \LaTeXe{} version, the availability of \eTeX{}
-% means using a mode test can be done at for example the start of an
-% \tn{halign}.
-% \begin{macrocode}
-\cs_new_protected:Npn \mode_leave_vertical:
- {
- \if_mode_vertical:
- \exp_after:wN \tex_indent:D
- \fi:
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macrocode}
-%</package>
-% \end{macrocode}
-%
-% \end{implementation}
-%
-% \PrintIndex