diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3basics.dtx')
| -rw-r--r-- | Master/texmf-dist/source/latex/l3kernel/l3basics.dtx | 3208 |
1 files changed, 3208 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3basics.dtx b/Master/texmf-dist/source/latex/l3kernel/l3basics.dtx new file mode 100644 index 00000000000..52cc56c699a --- /dev/null +++ b/Master/texmf-dist/source/latex/l3kernel/l3basics.dtx @@ -0,0 +1,3208 @@ +% \iffalse meta-comment +% +%% File: l3basics.dtx Copyright (C) 1990-2011 The LaTeX3 project +%% +%% It may be distributed and/or modified under the conditions of the +%% LaTeX Project Public License (LPPL), either version 1.3c of this +%% license or (at your option) any later version. The latest version +%% of this license is in the file +%% +%% http://www.latex-project.org/lppl.txt +%% +%% This file is part of the "expl3 bundle" (The Work in LPPL) +%% and all files in that bundle must be distributed together. +%% +%% The released version of this bundle is available from CTAN. +%% +%% ----------------------------------------------------------------------- +%% +%% The development version of the bundle can be found at +%% +%% http://www.latex-project.org/svnroot/experimental/trunk/ +%% +%% for those people who are interested. +%% +%%%%%%%%%%% +%% NOTE: %% +%%%%%%%%%%% +%% +%% Snapshots taken from the repository represent work in progress and may +%% not work or may contain conflicting material! We therefore ask +%% people _not_ to put them into distributions, archives, etc. without +%% prior consultation with the LaTeX3 Project. +%% +%% ----------------------------------------------------------------------- +% +%<*driver|package> +\RequirePackage{l3names} +\GetIdInfo$Id: l3basics.dtx 2493 2011-07-04 09:50:22Z bruno $ + {L3 Experimental basic definitions} +%</driver|package> +%<*driver> +\documentclass[full]{l3doc} +\begin{document} + \DocInput{\jobname.dtx} +\end{document} +%</driver> +% \fi +% +% \title{^^A +% The \pkg{l3basics} package\\ Basic definitions^^A +% \thanks{This file describes v\ExplFileVersion, +% last revised \ExplFileDate.}^^A +% } +% +% \author{^^A +% The \LaTeX3 Project\thanks +% {^^A +% E-mail: +% \href{mailto:latex-team@latex-project.org} +% {latex-team@latex-project.org}^^A +% }^^A +% } +% +% \date{Released \ExplFileDate} +% +% \maketitle +% +% \begin{documentation} +% +% As the name suggest this package holds some basic definitions which +% are needed by most or all other packages in this set. +% +% Here we describe those functions that are used all over the place. With +% that we mean functions dealing with the construction and testing of +% control sequences. Furthermore the basic parts of conditional +% processing are covered; conditional processing dealing with specific +% data types is described in the modules specific for the respective +% data types. +% +% \section{No operation functions} +% +% \begin{function}[EXP]{\prg_do_nothing:} +% \begin{syntax} +% \cs{prg_do_nothing:} +% \end{syntax} +% An expandable function which does nothing at all: leaves nothing +% in the input stream after a single expansion. +% \end{function} +% +% \begin{function}{\scan_stop:} +% \begin{syntax} +% \cs{scan_stop:} +% \end{syntax} +% A non-expandable function which does nothing. Does not vanish on +% expansion but produces no typeset output. +% \end{function} +% +% \section{Grouping material} +% +% \begin{function}{\group_begin:, \group_end:} +% \begin{syntax} +% \cs{group_begin:} +% \cs{group_end:} +% \end{syntax} +% These functions begin and end a group for definition purposes. +% Assignments are local to groups unless carried out in a global +% manner. (A small number of exceptions to this rule will be noted +% as necessary elsewhere in this document.) Each \cs{group_begin:} +% must be matched by a \cs{group_end:}, although this does not have +% to occur within the same function. Indeed, it is often necessary +% to start a group within one function and finish it within another, +% for example when seeking to use non-standard category codes. +% \end{function} +% +% \begin{function}{\group_insert_after:N} +% \begin{syntax} +% \cs{group_insert_after:N} \meta{token} +% \end{syntax} +% Adds \meta{token} to the list of \meta{tokens} to be inserted +% when the current group level ends. The list of \meta{tokens} to be +% inserted will be empty at the beginning of a group: multiple +% applications of \cs{group_insert_after:N} may be used to build +% the inserted list one \meta{token} at a time. The current group +% level may be closed by a \cs{group_end:} function or by a token +% with category code $2$ (close-group). The later will be a ^^A{ +% |}| if standard category codes apply. +% \end{function} +% +% \section{Control sequences and functions} +% +% As \TeX{} is a macro language, creating new functions means +% creating macros. At point of use, a function is replaced by +% the replacement text (\enquote{code}) in which each parameter +% in the code (|#1|, |#2|, \emph{etc.}) is replaced the appropriate +% arguments absorbed by the function. In the following, \meta{code} +% is therefore used as a shorthand for \enquote{replacement text}. +% +% Functions which are not \enquote{protected} will be fully expanded +% inside an \texttt{x} expansion. In contrast, \enquote{protected} +% functions are not expanded within \texttt{x} expansions. +% +% \subsection{Defining functions} +% +% Functions can be created with no requirement that they are declared +% first (in contrast to variables, which must always be declared). +% Declaring a function before setting up the code means that the name +% chosen will be checked and an error raised if it is already in use. +% The name of a function can be checked at the point of definition using +% the \cs{cs_new\ldots} functions: this is recommended for all +% functions which are defined for the first time. +% +% \subsection{Defining new functions using primitive parameter text} +% +% \begin{function}{\cs_new:Npn, \cs_new:cpn, \cs_new:Npx, \cs_new:cpx} +% \begin{syntax} +% \cs{cs_new:Npn} \meta{function} \meta{parameters} \Arg{code} +% \end{syntax} +% Creates \meta{function} to expand to \meta{code} as replacement text. +% Within the \meta{code}, the \meta{parameters} (|#1|, |#2|, +% \emph{etc.}) will be replaced by those absorbed by the function. +% The definition is global and an error will result if the +% \meta{function} is already defined. +% \end{function} +% +% \begin{function} +% { +% \cs_new_nopar:Npn, \cs_new_nopar:cpn, +% \cs_new_nopar:Npx, \cs_new_nopar:cpx +% } +% \begin{syntax} +% \cs{cs_new_nopar:Npn} \meta{function} \meta{parameters} \Arg{code} +% \end{syntax} +% Creates \meta{function} to expand to \meta{code} as replacement text. +% Within the \meta{code}, the \meta{parameters} (|#1|, |#2|, +% \emph{etc.}) will be replaced by those absorbed by the function. +% When the \meta{function} is used the \meta{parameters} absorbed +% cannot contain \cs{par} tokens. The definition is global and +% an error will result if the \meta{function} is already defined. +% \end{function} +% +% \begin{function} +% { +% \cs_new_protected:Npn, \cs_new_protected:cpn, +% \cs_new_protected:Npx, \cs_new_protected:cpx +% } +% \begin{syntax} +% \cs{cs_new_protected:Npn} \meta{function} \meta{parameters} +% ~~\Arg{code} +% \end{syntax} +% Creates \meta{function} to expand to \meta{code} as replacement text. +% Within the \meta{code}, the \meta{parameters} (|#1|, |#2|, +% \emph{etc.}) will be replaced by those absorbed by the function. +% The \meta{function} will not expand within an \texttt{x}-type +% argument. The definition is global and an error will result if the +% \meta{function} is already defined. +% \end{function} +% +% \begin{function} +% { +% \cs_new_protected_nopar:Npn, \cs_new_protected_nopar:cpn , +% \cs_new_protected_nopar:Npx, \cs_new_protected_nopar:cpx +% } +% \begin{syntax} +% \cs{cs_new_protected_nopar:Npn} \meta{function} \meta{parameters} +% ~~\Arg{code} +% \end{syntax} +% Creates \meta{function} to expand to \meta{code} as replacement text. +% Within the \meta{code}, the \meta{parameters} (|#1|, |#2|, +% \emph{etc.}) will be replaced by those absorbed by the function. +% When the \meta{function} is used the \meta{parameters} absorbed +% cannot contain \cs{par} tokens. The \meta{function} will not +% expand within an \texttt{x}-type argument. The definition is global +% and an error will result if the \meta{function} is already defined. +% \end{function} +% +% \begin{function}{\cs_set:Npn, \cs_set:cpn, \cs_set:Npx, \cs_set:cpx} +% \begin{syntax} +% \cs{cs_set:Npn} \meta{function} \meta{parameters} \Arg{code} +% \end{syntax} +% Sets \meta{function} to expand to \meta{code} as replacement text. +% Within the \meta{code}, the \meta{parameters} (|#1|, |#2|, +% \emph{etc.}) will be replaced by those absorbed by the function. +% The assignment of a meaning to \meta{function} is restricted to +% the current \TeX{} group level. +% \end{function} +% +% \begin{function} +% { +% \cs_set_nopar:Npn, \cs_set_nopar:cpn, +% \cs_set_nopar:Npx, \cs_set_nopar:cpx +% } +% \begin{syntax} +% \cs{cs_set_nopar:Npn} \meta{function} \meta{parameters} \Arg{code} +% \end{syntax} +% Sets \meta{function} to expand to \meta{code} as replacement text. +% Within the \meta{code}, the \meta{parameters} (|#1|, |#2|, +% \emph{etc.}) will be replaced by those absorbed by the function. +% When the \meta{function} is used the \meta{parameters} absorbed +% cannot contain \cs{par} tokens. The assignment of a meaning +% to \meta{function} is restricted to the current \TeX{} group +% level. +% \end{function} +% +% \begin{function} +% { +% \cs_set_protected:Npn, \cs_set_protected:cpn, +% \cs_set_protected:Npx, \cs_set_protected:cpx +% } +% \begin{syntax} +% \cs{cs_set_protected:Npn} \meta{function} \meta{parameters} +% ~~\Arg{code} +% \end{syntax} +% Sets \meta{function} to expand to \meta{code} as replacement text. +% Within the \meta{code}, the \meta{parameters} (|#1|, |#2|, +% \emph{etc.}) will be replaced by those absorbed by the function. +% The assignment of a meaning to \meta{function} is restricted to +% the current \TeX{} group level. The \meta{function} will +% not expand within an \texttt{x}-type argument. +% \end{function} +% +% \begin{function} +% { +% \cs_set_protected_nopar:Npn, \cs_set_protected_nopar:cpn , +% \cs_set_protected_nopar:Npx, \cs_set_protected_nopar:cpx , +% } +% \begin{syntax} +% \cs{cs_set_protected_nopar:Npn} \meta{function} +% ~~\meta{parameters} \Arg{code} +% \end{syntax} +% Sets \meta{function} to expand to \meta{code} as replacement text. +% Within the \meta{code}, the \meta{parameters} (|#1|, |#2|, +% \emph{etc.}) will be replaced by those absorbed by the function. +% When the \meta{function} is used the \meta{parameters} absorbed +% cannot contain \cs{par} tokens. The assignment of a meaning +% to \meta{function} is restricted to the current \TeX{} group +% level. The \meta{function} will not expand within an +% \texttt{x}-type argument. +% \end{function} +% +% \begin{function}{\cs_gset:Npn, \cs_gset:cpn, \cs_gset:Npx, \cs_gset:cpx} +% \begin{syntax} +% \cs{cs_gset:Npn} \meta{function} \meta{parameters} \Arg{code} +% \end{syntax} +% Globally sets \meta{function} to expand to \meta{code} as replacement +% text. Within the \meta{code}, the \meta{parameters} (|#1|, |#2|, +% \emph{etc.}) will be replaced by those absorbed by the function. +% The assignment of a meaning to \meta{function} is \emph{not} +% restricted to the current \TeX{} group level: the assignment is +% global. +% \end{function} +% +% \begin{function} +% { +% \cs_gset_nopar:Npn, \cs_gset_nopar:cpn, +% \cs_gset_nopar:Npx , \cs_gset_nopar:cpx +% } +% \begin{syntax} +% \cs{cs_gset_nopar:Npn} \meta{function} \meta{parameters} \Arg{code} +% \end{syntax} +% Globally sets \meta{function} to expand to \meta{code} as replacement +% text. Within the \meta{code}, the \meta{parameters} (|#1|, |#2|, +% \emph{etc.}) will be replaced by those absorbed by the function. +% When the \meta{function} is used the \meta{parameters} absorbed +% cannot contain \cs{par} tokens. The assignment of a meaning to +% \meta{function} is \emph{not} restricted to the current \TeX{} +% group level: the assignment is global. +% \end{function} +% +% \begin{function} +% { +% \cs_gset_protected:Npn, \cs_gset_protected:cpn, +% \cs_gset_protected:Npx, \cs_gset_protected:cpx +% } +% \begin{syntax} +% \cs{cs_gset_protected:Npn} \meta{function} \meta{parameters} +% ~~\Arg{code} +% \end{syntax} +% Globally sets \meta{function} to expand to \meta{code} as replacement +% text. Within the \meta{code}, the \meta{parameters} (|#1|, |#2|, +% \emph{etc.}) will be replaced by those absorbed by the function. +% The assignment of a meaning to \meta{function} is \emph{not} +% restricted to the current \TeX{} group level: the assignment is +% global. The \meta{function} will not expand within an +% \texttt{x}-type argument. +% \end{function} +% +% \begin{function} +% { +% \cs_gset_protected_nopar:Npn, \cs_gset_protected_nopar:cpn, +% \cs_gset_protected_nopar:Npx, \cs_gset_protected_nopar:cpx +% } +% \begin{syntax} +% \cs{cs_gset_protected_nopar:Npn} \meta{function} +% ~~\meta{parameters} \Arg{code} +% \end{syntax} +% Globally sets \meta{function} to expand to \meta{code} as replacement +% text. Within the \meta{code}, the \meta{parameters} (|#1|, |#2|, +% \emph{etc.}) will be replaced by those absorbed by the function. +% When the \meta{function} is used the \meta{parameters} absorbed +% cannot contain \cs{par} tokens. The assignment of a meaning to +% \meta{function} is \emph{not} restricted to the current \TeX{} +% group level: the assignment is global. The \meta{function} will +% not expand within an \texttt{x}-type argument. +% \end{function} +% +% \subsection{Defining new functions using the signature} +% +% \begin{function} +% { +% \cs_new:Nn, \cs_new:cn, +% \cs_new:Nx, \cs_new:cx +% } +% \begin{syntax} +% \cs{cs_new:Nn} \meta{function} \Arg{code} +% \end{syntax} +% Creates \meta{function} to expand to \meta{code} as replacement text. +% Within the \meta{code}, the number of \meta{parameters} is detected +% automatically from the function signature. These \meta{parameters} +% (|#1|, |#2|, \emph{etc.}) will be replaced by those absorbed by the +% function. The definition is global and +% an error will result if the \meta{function} is already defined. +% \end{function} +% +% \begin{function} +% { +% \cs_new_nopar:Nn, \cs_new_nopar:cn, +% \cs_new_nopar:Nx, \cs_new_nopar:cx +% } +% \begin{syntax} +% \cs{cs_new_nopar:Nn} \meta{function} \Arg{code} +% \end{syntax} +% Creates \meta{function} to expand to \meta{code} as replacement text. +% Within the \meta{code}, the number of \meta{parameters} is detected +% automatically from the function signature. These \meta{parameters} +% (|#1|, |#2|, \emph{etc.}) will be replaced by those absorbed by the +% function. When the \meta{function} is used the \meta{parameters} +% absorbed cannot contain \cs{par} tokens. The definition is global and +% an error will result if the \meta{function} is already defined. +% \end{function} +% +% \begin{function} +% { +% \cs_new_protected:Nn, \cs_new_protected:cn, +% \cs_new_protected:Nx, \cs_new_protected:cx +% } +% \begin{syntax} +% \cs{cs_new_protected:Nn} \meta{function} \Arg{code} +% \end{syntax} +% Creates \meta{function} to expand to \meta{code} as replacement text. +% Within the \meta{code}, the number of \meta{parameters} is detected +% automatically from the function signature. These \meta{parameters} +% (|#1|, |#2|, \emph{etc.}) will be replaced by those absorbed by the +% function. The \meta{function} will not expand within an \texttt{x}-type +% argument. The definition is global and +% an error will result if the \meta{function} is already defined. +% \end{function} +% +% \begin{function} +% { +% \cs_new_protected_nopar:Nn, \cs_new_protected_nopar:cn, +% \cs_new_protected_nopar:Nx, \cs_new_protected_nopar:cx +% } +% \begin{syntax} +% \cs{cs_new_protected_nopar:Nn} \meta{function} \Arg{code} +% \end{syntax} +% Creates \meta{function} to expand to \meta{code} as replacement text. +% Within the \meta{code}, the number of \meta{parameters} is detected +% automatically from the function signature. These \meta{parameters} +% (|#1|, |#2|, \emph{etc.}) will be replaced by those absorbed by the +% function. When the \meta{function} is used the \meta{parameters} +% absorbed cannot contain \cs{par} tokens. The \meta{function} will not +% expand within an \texttt{x}-type argument. The definition is global and +% an error will result if the \meta{function} is already defined. +% \end{function} +% +% \begin{function} +% { +% \cs_set:Nn, \cs_set:cn, +% \cs_set:Nx, \cs_set:cx +% } +% \begin{syntax} +% \cs{cs_set:Nn} \meta{function} \Arg{code} +% \end{syntax} +% Sets \meta{function} to expand to \meta{code} as replacement text. +% Within the \meta{code}, the number of \meta{parameters} is detected +% automatically from the function signature. These \meta{parameters} +% (|#1|, |#2|, \emph{etc.}) will be replaced by those absorbed by the +% function. +% The assignment of a meaning to \meta{function} is restricted to +% the current \TeX{} group level. +% \end{function} +% +% \begin{function} +% { +% \cs_set_nopar:Nn, \cs_set_nopar:cn, +% \cs_set_nopar:Nx, \cs_set_nopar:cx +% } +% \begin{syntax} +% \cs{cs_set_nopar:Nn} \meta{function} \Arg{code} +% \end{syntax} +% Sets \meta{function} to expand to \meta{code} as replacement text. +% Within the \meta{code}, the number of \meta{parameters} is detected +% automatically from the function signature. These \meta{parameters} +% (|#1|, |#2|, \emph{etc.}) will be replaced by those absorbed by the +% function. When the \meta{function} is used the \meta{parameters} +% absorbed cannot contain \cs{par} tokens. +% The assignment of a meaning to \meta{function} is restricted to +% the current \TeX{} group level. +% \end{function} +% +% \begin{function} +% { +% \cs_set_protected:Nn, \cs_set_protected:cn, +% \cs_set_protected:Nx, \cs_set_protected:cx +% } +% \begin{syntax} +% \cs{cs_set_protected:Nn} \meta{function} \Arg{code} +% \end{syntax} +% Sets \meta{function} to expand to \meta{code} as replacement text. +% Within the \meta{code}, the number of \meta{parameters} is detected +% automatically from the function signature. These \meta{parameters} +% (|#1|, |#2|, \emph{etc.}) will be replaced by those absorbed by the +% function. The \meta{function} will not expand within an \texttt{x}-type +% argument. +% The assignment of a meaning to \meta{function} is restricted to +% the current \TeX{} group level. +% \end{function} +% +% \begin{function} +% { +% \cs_set_protected_nopar:Nn, \cs_set_protected_nopar:cn, +% \cs_set_protected_nopar:Nx, \cs_set_protected_nopar:cx +% } +% \begin{syntax} +% \cs{cs_set_protected_nopar:Nn} \meta{function} \Arg{code} +% \end{syntax} +% Sets \meta{function} to expand to \meta{code} as replacement text. +% Within the \meta{code}, the number of \meta{parameters} is detected +% automatically from the function signature. These \meta{parameters} +% (|#1|, |#2|, \emph{etc.}) will be replaced by those absorbed by the +% function. When the \meta{function} is used the \meta{parameters} +% absorbed cannot contain \cs{par} tokens. The \meta{function} will not +% expand within an \texttt{x}-type argument. +% The assignment of a meaning to \meta{function} is restricted to +% the current \TeX{} group level. +% \end{function} +% +% \begin{function} +% { +% \cs_gset:Nn, \cs_gset:cn, +% \cs_gset:Nx, \cs_gset:cx +% } +% \begin{syntax} +% \cs{cs_gset:Nn} \meta{function} \Arg{code} +% \end{syntax} +% Sets \meta{function} to expand to \meta{code} as replacement text. +% Within the \meta{code}, the number of \meta{parameters} is detected +% automatically from the function signature. These \meta{parameters} +% (|#1|, |#2|, \emph{etc.}) will be replaced by those absorbed by the +% function. +% The assignment of a meaning to \meta{function} is global. +% \end{function} +% +% \begin{function} +% { +% \cs_gset_nopar:Nn, \cs_gset_nopar:cn, +% \cs_gset_nopar:Nx, \cs_gset_nopar:cx +% } +% \begin{syntax} +% \cs{cs_gset_nopar:Nn} \meta{function} \Arg{code} +% \end{syntax} +% Sets \meta{function} to expand to \meta{code} as replacement text. +% Within the \meta{code}, the number of \meta{parameters} is detected +% automatically from the function signature. These \meta{parameters} +% (|#1|, |#2|, \emph{etc.}) will be replaced by those absorbed by the +% function. When the \meta{function} is used the \meta{parameters} +% absorbed cannot contain \cs{par} tokens. +% The assignment of a meaning to \meta{function} is global. +% \end{function} +% +% \begin{function} +% { +% \cs_gset_protected:Nn, \cs_gset_protected:cn, +% \cs_gset_protected:Nx, \cs_gset_protected:cx +% } +% \begin{syntax} +% \cs{cs_gset_protected:Nn} \meta{function} \Arg{code} +% \end{syntax} +% Sets \meta{function} to expand to \meta{code} as replacement text. +% Within the \meta{code}, the number of \meta{parameters} is detected +% automatically from the function signature. These \meta{parameters} +% (|#1|, |#2|, \emph{etc.}) will be replaced by those absorbed by the +% function. The \meta{function} will not expand within an \texttt{x}-type +% argument. +% The assignment of a meaning to \meta{function} is global. +% \end{function} +% +% \begin{function} +% { +% \cs_gset_protected_nopar:Nn, \cs_gset_protected_nopar:cn, +% \cs_gset_protected_nopar:Nx, \cs_gset_protected_nopar:cx +% } +% \begin{syntax} +% \cs{cs_gset_protected_nopar:Nn} \meta{function} \Arg{code} +% \end{syntax} +% Sets \meta{function} to expand to \meta{code} as replacement text. +% Within the \meta{code}, the number of \meta{parameters} is detected +% automatically from the function signature. These \meta{parameters} +% (|#1|, |#2|, \emph{etc.}) will be replaced by those absorbed by the +% function. When the \meta{function} is used the \meta{parameters} +% absorbed cannot contain \cs{par} tokens. The \meta{function} will not +% expand within an \texttt{x}-type argument. +% The assignment of a meaning to \meta{function} is global. +% \end{function} +% +% \begin{function} +% {\cs_generate_from_arg_count:NNnn, \cs_generate_from_arg_count:cNnn} +% \begin{syntax} +% \cs{cs_generate_from_arg_count:NNnn} \meta{function} +% ~~\meta{creator} \meta{number} \meta{code} +% \end{syntax} +% Uses the \meta{creator} function (which should have signature +% |Npn|, for example \cs{cs_new:Npn}) to define a \meta{function} +% which takes \meta{number} arguments and has \meta{code} as +% replacement text. The \meta{number} of arguments is an integer expression, +% evaluated as detailed for \cs{int_eval:n}. +% \end{function} +% +% \subsection{Copying control sequences} +% +% Control sequences (not just functions as defined above) can +% be set to have the same meaning using the functions described +% here. Making two control sequences equivalent means that the +% second control sequence is a \emph{copy} of the first (rather than +% a pointer to it). Thus the old and new control sequence are not +% tided 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} +% \end{syntax} +% Creates \meta{control sequence 1} and sets it to have the same +% meaning as \meta{control sequence 2} at the point where +% \cs{cs_new_eq:NN} is executed. The two control sequences may +% subsequently be altered without affecting the copy. The assignment +% of a meaning to \meta{control sequence 1} is global. +% \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} +% \end{syntax} +% Sets \meta{control sequence 1} to have the same meaning as +% \meta{control sequence 2} at the point where \cs{cs_set_eq:NN} +% is executed. The two control sequences may subsequently be +% altered without affecting the copy. The assignment of a meaning +% to \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} +% \end{syntax} +% Globally sets \meta{control sequence 1} to have the same meaning as +% \meta{control sequence 2} at the point where \cs{cs_gset_eq:NN} +% is executed. The two control sequences may subsequently be +% altered without affecting the copy. The assignment of a meaning to +% \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}{\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]{\cs_meaning:N, \cs_meaning:c} +% \begin{syntax} +% \cs{cs_meaning:N} \meta{control sequence} +% \end{syntax} +% This function expands to the \emph{meaning} of the \meta{control sequence} +% control sequence. This will show the \meta{replacement text} for a +% macro. +% \begin{texnote} +% This is \TeX{}'s \cs{meaning} primitive. +% \end{texnote} +% \end{function} +% +% \begin{function}{\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 the \TeX{} primitive \cs{show}. +% \end{texnote} +% \end{function} +% + +% \subsection{Converting to and from control sequences} +% +% \begin{function}[EXP]{\use:c} +% \begin{syntax} +% \cs{use:c} \Arg{control sequence name} +% \end{syntax} +% Converts the given \meta{control sequence name} into a single +% control sequence token. This process requires two expansions. +% The content for \meta{control sequence name} may be literal +% material or from other expandable functions. The +% \meta{control sequence name} must, when fully expanded, consist +% of character tokens which are not active: typically, they will +% be of category code $10$ (space), $11$ (letter) +% or $12$ (other), or a mixture of these. As an example, 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}. +% \end{function} +% +% \begin{function}[EXP]{\cs:w, \cs_end:} +% \begin{syntax} +% \cs{cs:w} \meta{control sequence name} \cs{cs_end:} +% \end{syntax} +% Converts the given \meta{control sequence name} into a single +% control sequence token. This process requires one expansion. +% The content for \meta{control sequence name} may be literal +% material or from other expandable functions. The +% \meta{control sequence name} must, when fully expanded, consist +% of character tokens which are not active: typically, they will +% be of category code $10$ (space), $11$ (letter) +% or $12$ (other), or a mixture of these. As an example, 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{texnote} +% These are the \TeX{} primitives \cs{csname} and \cs{endcsname}. +% \end{texnote} +% \end{function} +% +% \begin{function}[EXP]{\cs_to_str:N} +% \begin{syntax} +% \cs{cs_to_str:N} \Arg{control sequence} +% \end{syntax} +% Converts the given \meta{control sequence} into a series of +% characters with category code $12$ (other), except spaces, +% of category code $10$. The sequence will \emph{not} include +% the current escape token, \emph{cf.}~\cs{token_to_str:N}. +% Full expansion of this function requires a variable number +% of expansion steps (either 3 or 4), and so an +% \texttt{f}- or \texttt{x}-type expansion will be required to +% convert the \meta{control sequence} to a sequence of characters +% in the input stream. +% \end{function} +% +% \section{Using or removing tokens and arguments} +% +% Tokens in the input can be read and used or read and discarded. +% If one or more tokens are wrapped in braces then in absorbing them +% the outer set will be removed. At the same time, the category code +% of each token is set when the token is read by a function (if it +% is read more than once, the category code is determined by the +% the situation in force when first function absorbs the token). +% +% \begin{function}[EXP]{\use:n, \use:nn, \use:nnn, \use:nnnn} +% \begin{syntax} +% \cs{use:n} \Arg{group1} +% \cs{use:nn} \Arg{group1} \Arg{group2} +% \cs{use:nnn} \Arg{group1} \Arg{group2} \Arg{group3} +% \cs{use:nnn} \Arg{group1} \Arg{group2} \Arg{group3} \Arg{group4} +% \end{syntax} +% As illustrated, these functions will absorb between one and four +% arguments, as indicated by the argument specifier. The braces +% surrounding each argument will be removed leaving the remaining +% tokens in the input stream. The category code of these tokens will +% also be fixed by this process (if it has not already been by some +% other absorption). All of these functions require only a single +% expansion to operate, so that one expansion of +% \begin{verbatim} +% \use:nn { abc } { { def } } +% \end{verbatim} +% will result in the input stream containing +% \begin{verbatim} +% abc { def } +% \end{verbatim} +% \emph{i.e.} only the outer braces will be removed. +% \end{function} +% +% \begin{function}[EXP]{\use_i:nn, \use_ii:nn} +% \begin{syntax} +% \cs{use_i:nn} \Arg{group1} \Arg{group2} +% \end{syntax} +% These functions will absorb two groups and leave only the +% first or the second in the input stream. The braces surrounding the +% arguments will be removed as part of this process. The category code +% of these tokens will also be fixed (if it has not already been by +% some other absorption). A single expansion is needed for the +% functions to take effect. +% \end{function} +% +% \begin{function}[EXP]{\use_i:nnn, \use_ii:nnn, \use_iii:nnn} +% \begin{syntax} +% \cs{use_i:nnn} \Arg{group1} \Arg{group2} \Arg{group3} +% \end{syntax} +% These functions will absorb three groups and leave only of these +% in the input stream. The braces surrounding the arguments will be +% removed as part of this process. The category code of these tokens +% will also be fixed (if it has not already been by some other +% absorption). A single expansion is needed for the functions to take +% effect. +% \end{function} +% +% \begin{function}[EXP] +% {\use_i:nnnn, \use_ii:nnnn, \use_iii:nnnn , \use_iv:nnnn} +% \begin{syntax} +% \cs{use_i:nnnn} \Arg{group1} \Arg{group2} \Arg{group3} \Arg{group4} +% \end{syntax} +% These functions will absorb four groups and leave only of these +% in the input stream. The braces surrounding the arguments will be +% removed as part of this process. The category code of these tokens +% will also be fixed (if it has not already been by some other +% absorption). A single expansion is needed for the functions to take +% effect. +% \end{function} +% +% \begin{function}[EXP]{\use_i_ii:nnn} +% \begin{syntax} +% \cs{use_i_ii:nnn} \Arg{group1} \Arg{group2} \Arg{group3} +% \end{syntax} +% This functions will absorb three groups and leave the first and +% second in the input stream. The braces surrounding the arguments +% will be removed as part of this process. The category code of +% these tokens will also be fixed (if it has not already been by +% some other absorption). A single expansion is needed for the +% functions to take effect. An example: +% \begin{verbatim} +% \use_i_ii:nnn { abc } { { def } } { ghi } +% \end{verbatim} +% will result in the input stream containing +% \begin{verbatim} +% abc { def } +% \end{verbatim} +% \emph{i.e.} the outer braces will be removed and the third group +% will be removed. +% \end{function} +% +% \begin{function}[EXP] +% { +% \use_none:n , +% \use_none:nn , +% \use_none:nnn , +% \use_none:nnnn , +% \use_none:nnnnn , +% \use_none:nnnnnn , +% \use_none:nnnnnnn , +% \use_none:nnnnnnnn , +% \use_none:nnnnnnnnn +% } +% \begin{syntax} +% \cs{use_none:n} \Arg{group1} +% \end{syntax} +% These functions absorb between one and nine groups from the +% input stream, leaving nothing on the resulting input stream. +% These functions work after a single expansion. One or more of the +% \texttt{n} arguments may be an unbraced single token +% (\emph{i.e.}~an \texttt{N} argument). +% \end{function} +% +% \begin{function}{\use:x} +% \begin{syntax} +% \cs{use:x} \Arg{expandable tokens} +% \end{syntax} +% Fully expands the \meta{expandable tokens} and inserts the +% result into the input stream at the current location. +% \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} +% \end{syntax} +% Absorb the \meta{balanced} text form the input stream delimited by +% the marker given in the function name, leaving nothing in the +% input stream. +% \end{function} +% +% \begin{function}[EXP] +% { +% \use_i_delimit_by_q_nil:nw, +% \use_i_delimit_by_q_stop:nw, +% \use_i_delimit_by_q_recursion_stop:nw +% } +% \begin{syntax} +% \cs{use_i_delimit_by_q_nil:nw} \Arg{inserted tokens} +% ~~\meta{balanced text} \cs{q_nil} +% \end{syntax} +% Absorb the \meta{balanced} text form the input stream delimited by +% the marker given in the function name, leaving \meta{inserted tokens} +% in the input stream for further processing. +% \end{function} +% +% +% \begin{function}[EXP] +% { +% \use_i_after_fi:nw, +% \use_i_after_else:nw, +% \use_i_after_or:nw, +% \use_i_after_orelse:nw +% } +% \begin{syntax} +% \cs{use_i_after_fi:nw} \Arg{inserted tokens} \cs{fi:} +% \cs{use_i_after_else:nw} \Arg{inserted tokens} \cs{else:} +% ~~\meta{balanced text} \cs{fi:} +% \cs{use_i_after_or:nw} \Arg{inserted tokens} \cs{or:} +% ~~\meta{balanced text} \cs{fi:} +% \cs{use_i_after_orelse:nw} \Arg{inserted tokens} \cs{or:} or \cs{else:} +% ~~\meta{balanced text} \cs{fi:} +% \end{syntax} +% Absorb the \meta{balanced text}, if appropriate, delimited by +% the function name given. The \meta{inserted tokens} are then placed +% in the input stream after the delimiter. Thus for example +% \begin{verbatim} +% \use_i_after_fi:nw { some tokens } \fi: +% \end{verbatim} +% will leave +% \begin{verbatim} +% \fi: some tokens +% \end{verbatim} +% in the input stream for further processing. See the discussion of the +% primitive \TeX{} conditionals for more detail on \cs{else:}, \cs{fi:} +% and \cs{or:}. +% \end{function} +% +% \subsection{Decomposing control sequences} +% +% \begin{function}[EXP]{\cs_get_arg_count_from_signature:N} +% \begin{syntax} +% \cs{cs_get_arg_count_from_signature:N} \meta{function} +% \end{syntax} +% Splits the \meta{function} into the name (\emph{i.e.}~the part +% before the colon) and the signature (\emph{i.e.}~after the colon). +% The \meta{number} of tokens in the \meta{signature} is then left in +% the input stream. If there was no \meta{signature} then the result is +% the marker value $-1$. +% \end{function} +% +% \begin{function}[EXP]{\cs_get_function_name:N} +% \begin{syntax} +% \cs{cs_get_function_name:NN} \meta{function} +% \end{syntax} +% Splits the \meta{function} into the name (\emph{i.e.}~the part +% before the colon) and the signature (\emph{i.e.}~after the colon). +% The \meta{name} is then left in the input stream without the escape +% character present made up of tokens with category code $12$ +% (other). +% \end{function} +% +% \begin{function}{[EXP]\cs_get_function_signature:N} +% \begin{syntax} +% \cs{cs_get_function_signature:NN} \meta{function} +% \end{syntax} +% Splits the \meta{function} into the name (\emph{i.e.}~the part +% before the colon) and the signature (\emph{i.e.}~after the colon). +% The \meta{signature} is then left in the input stream made up of +% tokens with category code $12$ (other). +% \end{function} +% +% \begin{function}EXP]{\cs_split_function:NN} +% \begin{syntax} +% \cs{cs_split_function:NN} \meta{function} \meta{processor} +% \end{syntax} +% Splits the \meta{function} into the name (\emph{i.e.}~the part +% before the colon) and the signature (\emph{i.e.}~after the colon). +% This information is then placed in the input stream after the +% \meta{processor} function in three parts: the \meta{name}, the +% \meta{signature} and a logic token indicating if a colon was found +% (to differentiate variables from function names). The \meta{name} +% will not include the escape character, and both the \meta{name} and +% \meta{signature} are made up of tokens with category code $12$ +% (other). The \meta{processor} should be a function with argument +% specification \texttt{:nnN} (plus any trailing arguments needed). +% \end{function} +% +% \begin{function}[EXP]{\cs_to_str:N} +% \begin{syntax} +% \cs{cs_to_str:N} \Arg{control sequence} +% \end{syntax} +% Converts the given \meta{control sequence} into a series of +% characters with category code $12$ (other), except spaces, +% of category code $10$. The sequence will \emph{not} include +% the current escape token, \emph{cf.}~\cs{token_to_str:N}. +% Full expansion of this function requires a variable number +% of expansion steps (either 3 or 4), and so an +% \texttt{f}- or \texttt{x}-type expansion will be required to +% convert the \meta{control sequence} to a sequence of characters +% in the input stream. +% \end{function} +% +% \section{Predicates and conditionals} +% \label{sec:predicates} +% +% \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 in the \meta{true arg} or the +% \meta{false arg}. +% These arguments are denoted with |T| and |F|, respectively. An +% example would be +% \begin{quote} +% |\cs_if_free:cTF{abc}| \Arg{true code} \Arg{false code} +% \end{quote} +% a function that will turn the first argument into a control sequence +% (since it's marked as |c|) then checks whether this control sequence +% is still free and then depending on the result carry out the code in +% the second argument (true case) or in the third argument (false +% case). +% +% These type of functions are known as \enquote{conditionals}; +% whenever a |TF| function is defined it will usually be accompanied by +% |T| and |F| functions as well. These are provided for convenience when +% the branch only needs to go a single way. Package writers are free to +% choose which types to define but the kernel definitions will always +% provide all three versions. +% +% Important to note is that these branching conditionals with \meta{true +% code} and/or \meta{false code} are always defined in a way that the +% code of the chosen alternative can operate on following tokens in +% the input stream. +% +% These conditional functions may or may not be fully expandable, but if +% they are expandable they will be accompanied by a \enquote{predicate} +% for the same test as described below. +% +% \item[Predicates] +% \enquote{Predicates} are functions that return a special type of +% boolean value which can be tested by the function \cs{if_predicate:w} +% or in 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_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} +% |\if_predicate:w \cs_if_free_p:N \l_tmpz_tl| \\ +% | |\meta{true code} \\ +% |else:| \\ +% | |\meta{false code}\\ +% |\fi:| \\ +% \end{quote} +% or in expressions utilizing the boolean logic parser: +% \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} +% +% Like their branching cousins, predicate functions ensure that all +% underlying primitive |\else:| or |\fi:| have been removed before +% returning the boolean true or false values.\footnote{If defined +% using the interface provided.} +% +% For each predicate defined, a \enquote{predicate conditional} will +% also exist that behaves like a conditional described above. +% +% \item[Primitive conditionals] +% There is a third variety of conditional, which is the original +% concept used in plain \TeX{} and \LaTeXe{}. Their use is discouraged +% in \pkg{expl3} (although still used in low-level definitions) +% because they are more fragile and in many cases require more +% expansion control (hence more code) than the two types of +% conditionals described above. +% \end{description} +% +% \begin{variable}{\c_true_bool, \c_false_bool} +% Constants that represent |true| and |false|, respectively. Used to +% implement predicates. +% \end{variable} +% +% \subsection{Tests on control sequences} +% +% \begin{function}[EXP,pTF]{\cs_if_eq:NN} +% \begin{syntax} +% \cs{cs_if_eq_p:NN} \Arg{cs1} \Arg{cs2} +% \cs{cs_if_eq:NNTF} \Arg{cs1} \Arg{cs2} \Arg{true code} +% ~~\Arg{false code} +% \end{syntax} +% Compares the definition of two \meta{control sequences} and +% is logically \texttt{true} if the two are the same. The branching +% versions then leave either \meta{true code} or \meta{false code} +% in the input stream, as appropriate to the truth of the test and the +% variant of the function chosen. The logical truth of the test is left +% in the input stream by the predicate version. +% \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} \meta{true code} +% ~~\meta{false code} +% \end{syntax} +% Tests whether the \meta{control sequence} is currently defined +% (whether as a function or another control sequence type). Any +% valid definition of \meta{control sequence} will evaluate as +% \texttt{true}. The branching versions then leave either +% \meta{true code} or \meta{false code} in the input stream, as +% appropriate to the truth of the test and the variant of the function +% chosen. The logical truth of the test is left in the input stream by +% the predicate version. +% \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} \meta{true code} +% ~~\meta{false code} +% \end{syntax} +% Tests whether the \meta{control sequence} is currently free to +% be defined. This test will be \texttt{false} if the +% \meta{control sequence} currently exists (as defined by +% \cs{cs_if_exist:N}). The branching versions then leave either +% \meta{true code} or \meta{false code} in the input stream, as +% appropriate to the truth of the test and the variant of the function +% chosen. The logical truth of the test is left in the input stream by +% the predicate version. +% \end{function} +% +% \subsection{Testing string equality} +% +% \begin{function}[EXP,pTF] +% { +% \str_if_eq:nn, \str_if_eq:Vn, \str_if_eq:on, \str_if_eq:no, +% \str_if_eq:nV, \str_if_eq:VV, \str_if_eq:xx +% } +% \begin{syntax} +% \cs{str_if_eq_p:nn} \Arg{tl1} \Arg{tl2} +% \cs{str_if_eq:nnTF} \Arg{tl1} \Arg{tl2} \Arg{true code} \Arg{false code} +% \end{syntax} +% Compares the two \meta{token lists} on a character by character +% basis, and is \texttt{true} if the two lists contain the same +% characters in the same order. Thus for example +% \begin{verbatim} +% \str_if_eq_p:xx { abc } { \tl_to_str:n { abc } } +% \end{verbatim} +% is logically \texttt{true}. The branching versions then leave either +% \meta{true code} or \meta{false code} in the input stream, as +% appropriate to the truth of the test and the variant of the function +% chosen. The logical truth of the test is left in the input stream by +% the predicate version. All versions of these functions are fully +% expandable (including those involving an \texttt{x}-type +% expansion). +% \end{function} +% +% \subsection{Engine-specific conditionals} +% +% \begin{function}[EXP,TF]{\luatex_if_engine:} +% \begin{syntax} +% \cs{luatex_if_luatex:TF} \Arg{true code} \Arg{false code} +% \end{syntax} +% Detects is the document is being compiled using \LuaTeX{}. The +% branching versions then leave either \meta{true code} or +% \meta{false code} in the input stream, as appropriate to the truth +% of the test and the variant of the function chosen. +% \end{function} +% +% \begin{function}[EXP,TF]{\pdftex_if_engine:} +% \begin{syntax} +% \cs{pdftex_if_engine:TF} \Arg{true code} \Arg{false code} +% \end{syntax} +% Detects is the document is being compiled using \pdfTeX{}. The +% branching versions then leave either \meta{true code} or +% \meta{false code} in the input stream, as appropriate to the truth +% of the test and the variant of the function chosen. +% \end{function} +% +% \begin{function}[EXP,TF]{\xetex_if_engine:} +% \begin{syntax} +% \cs{xetex_if_engine:TF} \Arg{true code} \Arg{false code} +% \end{syntax} +% Detects is the document is being compiled using \XeTeX{}. The +% branching versions then leave either \meta{true code} or +% \meta{false code} in the input stream, as appropriate to the truth +% of the test and the variant of the function chosen. +% \end{function} +% +% \begin{variable} +% { +% \c_luatex_is_engine_bool, \c_pdftex_is_engine_bool, +% \c_xetex_is_engine_bool +% } +% Boolean versions of the engine conditionals, for use in predicate +% tests. +% \end{variable} +% +% \subsection{Primitive conditionals} +% +% The \eTeX{} engine itself provides many different conditionals. Some +% expand whatever comes after them and others don't. Hence the names +% for these underlying functions will often contain a |:w| part but +% higher level functions are often available. See for instance +% |\int_compare_p:nNn| which is a wrapper for |\if_num:w|. +% +% Certain conditionals deal with specific data types like boxes and +% fonts and are described there. The ones described below are either +% the universal conditionals or deal with control sequences. We will +% prefix primitive conditionals with |\if_|. +% +% \begin{function}[EXP] +% {\if_true:, \if_false:, \or:, \else:, \fi:, \reverse_if:N} +% \begin{syntax} +% "\if_true:" <true code> "\else:" <false code> "\fi:" \\ +% "\if_false:" <true code> "\else:" <false code> "\fi:" \\ +% "\reverse_if:N" <primitive conditional> +% \end{syntax} +% "\if_true:" always executes <true code>, while "\if_false:" always +% executes <false code>. "\reverse_if:N" reverses any two-way primitive +% conditional. "\else:" and "\fi:" delimit the branches of the +% conditional. "\or:" is used in case switches, see \pkg{l3intexpr} +% for more. +% \begin{texnote} +% These are equivalent to their corresponding \TeX\ primitive +% conditionals; |\reverse_if:N| is \eTeX's |\unless|. +% \end{texnote} +% \end{function} +% +% \begin{function}[EXP]{\if_meaning:w} +% \begin{syntax} +% "\if_meaning:w" <arg1> <arg2> <true code> "\else:" <false code> "\fi:" +% \end{syntax} +% "\if_meaning:w" executes <true code> when <arg1> and <arg2> are the same, +% otherwise it executes <false code>. +% <arg1> and <arg2> could be functions, variables, tokens; in all cases the +% \emph{unexpanded} definitions are compared. +% \begin{texnote} +% This is \TeX's |\ifx|. +% \end{texnote} +% \end{function} +% +% \begin{function}[EXP]{\if:w, \if_charcode:w,\if_catcode:w} +% \begin{syntax} +% "\if:w" <token1> <token2> <true code> "\else:" <false code> "\fi:" \\ +% "\if_catcode:w" <token1> <token2> <true code> "\else:" <false +% code> "\fi:" +% \end{syntax} +% These conditionals will expand any following tokens until two +% unexpandable tokens are left. If you wish to prevent this expansion, +% prefix the token in question with "\exp_not:N". "\if_catcode:w" +% tests if the category codes of the two tokens are the same whereas +% "\if:w" tests if the character codes are +% identical. "\if_charcode:w" is an alternative name for "\if:w". +% \end{function} +% +% \begin{function}[EXP]{\if_predicate:w} +% \begin{syntax} +% "\if_predicate:w" <predicate> <true code> "\else:" <false code> "\fi:" +% \end{syntax} +% This function takes a predicate function and +% branches according to the result. (In practice this function would also +% accept a single boolean variable in place of the <predicate> but to make the +% coding clearer this should be done through "\if_bool:N".) +% \end{function} +% +% \begin{function}[EXP]{\if_bool:N} +% \begin{syntax} +% "\if_bool:N" <boolean> <true code> "\else:" <false code> "\fi:" +% \end{syntax} +% This function takes a boolean variable and +% branches according to the result. +% \end{function} +% +% \begin{function}[EXP]{\if_cs_exist:N, \if_cs_exist:w} +% \begin{syntax} +% "\if_cs_exist:N" <cs> <true code> "\else:" <false code> "\fi:" \\ +% "\if_cs_exist:w" <tokens> "\cs_end:" <true code> "\else:" <false +% code> "\fi:" +% \end{syntax} +% Check if <cs> appears in the hash table or if the control sequence +% that can be formed from <tokens> appears in the hash table. The +% latter function does not turn the control sequence in question into +% "\scan_stop:"! This can be useful when dealing with control +% sequences which cannot be entered as a single token. +% \end{function} +% +% \begin{function}[EXP] +% { +% \if_mode_horizontal:, \if_mode_vertical:, +% \if_mode_math:, \if_mode_inner: +% } +% \begin{syntax} +% "\if_mode_horizontal:" <true code> "\else:" <false code> "\fi:" +% \end{syntax} +% Execute <true code> if currently in horizontal mode, otherwise +% execute <false code>. Similar for the other functions. +% \end{function} +% +% \section{Internal kernel functions} +% +% \begin{function}{\chk_if_exist_cs:N, \chk_if_exist_cs:c} +% \begin{syntax} +% \cs{chk_if_exist_cs:N} \meta{cs} +% \end{syntax} +% This function checks that \meta{cs} exists according to the +% criteria for \cs{cs_if_exist_p:N}, and if not raises a kernel-level +% error. +% \end{function} +% +% \begin{function}{\chk_if_free_cs:N, \chk_if_free_cs:c} +% \begin{syntax} +% \cs{chk_if_free_cs:N} \meta{cs} +% \end{syntax} +% This function checks that \meta{cs} is free according to the +% criteria for \cs{cs_if_free_p:N}, and if not raises a kernel-level +% error. +% \end{function} +% +% \begin{function}{\pref_global:D, \pref_long:D, \pref_protected:D} +% \begin{syntax} +% \cs{pref_global:D} \cs{cs_set_nopar:Npn} +% \end{syntax} +% Prefix functions that can be used in front of some definition +% functions (namely \ldots). The result of prefixing a function +% definition with \cs{pref_global:D} makes the definition global, +% \cs{pref_long:D} change the argument scanning mechanism so that it +% allows \cs{par} tokens in the argument of the prefixed function, +% and \cs{pref_protected:D} makes the definition robust inside +% \texttt{x}-type expansions. +% +% None of these internal functions should be used by a programmer since +% the necessary combinations are all available as separate function, +% \emph{e.g.} \cs{cs_set:Npn} is internally implemented as \cs{pref_long:D} +% \c{cs_set_nopar:Npn}. +% \begin{texnote} +% These prefixes are the primitives \tn{global}, \tn{long}, and +% \cs{protected}. +% \end{texnote} +% \end{function} +% +% \end{documentation} +% +% \begin{implementation} +% +% \section{\pkg{l3basics} implementation} +% +% \begin{macrocode} +%<*initex|package> +% \end{macrocode} +% +% \begin{macrocode} +%<*package> +\ProvidesExplPackage + {\ExplFileName}{\ExplFileDate}{\ExplFileVersion}{\ExplFileDescription} +\package_check_loaded_expl: +%</package> +% \end{macrocode} +% +% \subsection{Renaming some \TeX{} primitives (again)} +% +% Having given all the \TeX{} primitives a consistent name, we need to +% give sensible names to the ones we actually want to use. +% These will be defined as needed in the appropriate modules, but +% do a few now, just to get started.\footnote{This renaming gets expensive +% in terms of csname usage, an alternative scheme would be to just use +% the \cs{tex\ldots:D} name in the cases where no good alternative exists.} +% +% \begin{macro}{\cs_set_eq:NwN} +% A pretty basic requirement: \cs{let} one control sequence to another. +% \begin{macrocode}> +\tex_let:D \cs_set_eq:NwN \tex_let:D +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\if_true:} +% \begin{macro}{\if_false:} +% \begin{macro}{\or:} +% \begin{macro}{\else:} +% \begin{macro}{\fi:} +% \begin{macro}{\reverse_if:N} +% \begin{macro}{\if:w} +% \begin{macro}{\if_bool:N} +% \begin{macro}{\if_predicate:w} +% \begin{macro}{\if_charcode:w} +% \begin{macro}{\if_catcode:w} +% Then some conditionals. +% \begin{macrocode} +\cs_set_eq:NwN \if_true: \tex_iftrue:D +\cs_set_eq:NwN \if_false: \tex_iffalse:D +\cs_set_eq:NwN \or: \tex_or:D +\cs_set_eq:NwN \else: \tex_else:D +\cs_set_eq:NwN \fi: \tex_fi:D +\cs_set_eq:NwN \reverse_if:N \etex_unless:D +\cs_set_eq:NwN \if:w \tex_if:D +\cs_set_eq:NwN \if_bool:N \tex_ifodd:D +\cs_set_eq:NwN \if_predicate:w \tex_ifodd:D +\cs_set_eq:NwN \if_charcode:w \tex_if:D +\cs_set_eq:NwN \if_catcode:w \tex_ifcat:D +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\if_meaning:w} +% \begin{macrocode} +\cs_set_eq:NwN \if_meaning:w \tex_ifx:D +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\if_mode_math:} +% \begin{macro}{\if_mode_horizontal:} +% \begin{macro}{\if_mode_vertical:} +% \begin{macro}{\if_mode_inner:} +% \TeX{} lets us detect some if its modes. +% \begin{macrocode} +\cs_set_eq:NwN \if_mode_math: \tex_ifmmode:D +\cs_set_eq:NwN \if_mode_horizontal: \tex_ifhmode:D +\cs_set_eq:NwN \if_mode_vertical: \tex_ifvmode:D +\cs_set_eq:NwN \if_mode_inner: \tex_ifinner:D +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\if_cs_exist:N} +% \begin{macro}{\if_cs_exist:w} +% \begin{macrocode} +\cs_set_eq:NwN \if_cs_exist:N \etex_ifdefined:D +\cs_set_eq:NwN \if_cs_exist:w \etex_ifcsname:D +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\exp_after:wN} +% \begin{macro}{\exp_not:N} +% \begin{macro}{\exp_not:n} +% The three |\exp_| functions are used in the \textsf{l3expan} module +% where they are described. +% \begin{macrocode} +\cs_set_eq:NwN \exp_after:wN \tex_expandafter:D +\cs_set_eq:NwN \exp_not:N \tex_noexpand:D +\cs_set_eq:NwN \exp_not:n \etex_unexpanded:D +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\token_to_meaning:N} +% \begin{macro}{\token_to_str:N} +% \begin{macro}{\cs:w} +% \begin{macro}{\cs_end:} +% \begin{macro}{\cs_meaning:N} +% \begin{macro}{\cs_show:N} +% \begin{macrocode} +\cs_set_eq:NwN \token_to_meaning:N \tex_meaning:D +\cs_set_eq:NwN \token_to_str:N \tex_string:D +\cs_set_eq:NwN \cs:w \tex_csname:D +\cs_set_eq:NwN \cs_end: \tex_endcsname:D +\cs_set_eq:NwN \cs_meaning:N \tex_meaning:D +\cs_set_eq:NwN \cs_show:N \tex_show:D +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\scan_stop:} +% \begin{macro}{\group_begin:} +% \begin{macro}{\group_end:} +% The next three are basic functions for which there also exist +% versions that are safe inside alignments. These safe versions are +% defined in the \textsf{l3prg} module. +% \begin{macrocode} +\cs_set_eq:NwN \scan_stop: \tex_relax:D +\cs_set_eq:NwN \group_begin: \tex_begingroup:D +\cs_set_eq:NwN \group_end: \tex_endgroup:D +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\if_int_compare:w} +% \begin{macro}{\int_to_roman:w} +% \begin{macrocode} +\cs_set_eq:NwN \if_int_compare:w \tex_ifnum:D +\cs_set_eq:NwN \int_to_roman:w \tex_romannumeral:D +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\group_insert_after:N} +% \begin{macrocode} +\cs_set_eq:NwN \group_insert_after:N \tex_aftergroup:D +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\pref_global:D} +% \begin{macro}{\pref_long:D} +% \begin{macro}{\pref_protected:D} +% \begin{macrocode} +\cs_set_eq:NwN \pref_global:D \tex_global:D +\cs_set_eq:NwN \pref_long:D \tex_long:D +\cs_set_eq:NwN \pref_protected:D \etex_protected:D +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\exp_args:Nc} +% Discussed in \pkg{l3expan}, but needed much earlier. +% \begin{macrocode} +\tex_long:D \tex_def:D \exp_args:Nc #1#2 { \exp_after:wN #1 \cs:w #2 \cs_end: } +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\token_to_str:c} +% \begin{macro}{\cs_meaning:c} +% \begin{macro}{\cs_show:c} +%% A small number of variants by hand. +% \begin{macrocode} +\tex_def:D \cs_meaning:c { \exp_args:Nc \cs_meaning:N } +\tex_def:D \token_to_str:c { \exp_args:Nc \token_to_str:N } +\tex_def:D \cs_show:c { \exp_args:Nc \cs_show:N } +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \subsection {Defining functions} +% +% We start by providing functions for the typical definition +% functions. First the local ones. +% +% \begin{macro}{\cs_set_nopar:Npn} +% \begin{macro}{\cs_set_nopar:Npx} +% \begin{macro}{\cs_set:Npn} +% \begin{macro}{\cs_set:Npx} +% \begin{macro}{\cs_set_protected_nopar:Npn} +% \begin{macro}{\cs_set_protected_nopar:Npx} +% \begin{macro}{\cs_set_protected:Npn} +% \begin{macro}{\cs_set_protected:Npx} +% All assignment functions in \LaTeX3 should be naturally robust; +% after all, the \TeX{} primitives for assignments are and it can be +% a cause of problems if others aren't. +% \begin{macrocode} +\cs_set_eq:NwN \cs_set_nopar:Npn \tex_def:D +\cs_set_eq:NwN \cs_set_nopar:Npx \tex_edef:D +\pref_protected:D \cs_set_nopar:Npn \cs_set:Npn + { \pref_long:D \cs_set_nopar:Npn } +\pref_protected:D \cs_set_nopar:Npn \cs_set:Npx + { \pref_long:D \cs_set_nopar:Npx } +\pref_protected:D \cs_set_nopar:Npn \cs_set_protected_nopar:Npn + { \pref_protected:D \cs_set_nopar:Npn } +\pref_protected:D \cs_set_nopar:Npn \cs_set_protected_nopar:Npx + { \pref_protected:D \cs_set_nopar:Npx } +\cs_set_protected_nopar:Npn \cs_set_protected:Npn + { \pref_protected:D \pref_long:D \cs_set_nopar:Npn } +\cs_set_protected_nopar:Npn \cs_set_protected:Npx + { \pref_protected:D \pref_long:D \cs_set_nopar:Npx } +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\cs_gset_nopar:Npn} +% \begin{macro}{\cs_gset_nopar:Npx} +% \begin{macro}{\cs_gset:Npn} +% \begin{macro}{\cs_gset:Npx} +% \begin{macro}{\cs_gset_protected_nopar:Npn} +% \begin{macro}{\cs_gset_protected_nopar:Npx} +% \begin{macro}{\cs_gset_protected:Npn} +% \begin{macro}{\cs_gset_protected:Npx} +% Global versions of the above functions. +% \begin{macrocode} +\cs_set_eq:NwN \cs_gset_nopar:Npn \tex_gdef:D +\cs_set_eq:NwN \cs_gset_nopar:Npx \tex_xdef:D +\cs_set_protected_nopar:Npn \cs_gset:Npn + { \pref_long:D \cs_gset_nopar:Npn } +\cs_set_protected_nopar:Npn \cs_gset:Npx + { \pref_long:D \cs_gset_nopar:Npx } +\cs_set_protected_nopar:Npn \cs_gset_protected_nopar:Npn + { \pref_protected:D \cs_gset_nopar:Npn } +\cs_set_protected_nopar:Npn \cs_gset_protected_nopar:Npx + { \pref_protected:D \cs_gset_nopar:Npx } +\cs_set_protected_nopar:Npn \cs_gset_protected:Npn + { \pref_protected:D \pref_long:D \cs_gset_nopar:Npn } +\cs_set_protected_nopar:Npn \cs_gset_protected:Npx + { \pref_protected:D \pref_long:D \cs_gset_nopar:Npx } +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \subsection{Selecting tokens} +% +% \begin{macro}{\use:c} +% This macro grabs its argument and returns a csname from it. +% \begin{macrocode} +\cs_set:Npn \use:c #1 { \cs:w #1 \cs_end: } +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\use:x} +% \begin{macro}[aux]{\cs_tmp:w} +% Fully expands its argument and passes it to the input stream. +% Uses |\cs_tmp:| as a scratch register but does not affect it. +% \begin{macrocode} +\cs_set_protected:Npn \use:x #1 + { + \group_begin: + \cs_set:Npx \cs_tmp:w {#1} + \exp_after:wN + \group_end: + \cs_tmp:w + } +\cs_set:Npn \cs_tmp:w { } +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\use:n} +% \begin{macro}{\use:nn} +% \begin{macro}{\use:nnn} +% \begin{macro}{\use:nnnn} +% These macro grabs its arguments and returns it back to the input +% (with outer braces removed). +% \begin{macrocode} +\cs_set:Npn \use:n #1 {#1} +\cs_set:Npn \use:nn #1#2 {#1#2} +\cs_set:Npn \use:nnn #1#2#3 {#1#2#3} +\cs_set:Npn \use:nnnn #1#2#3#4 {#1#2#3#4} +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\use_i:nn} +% \begin{macro}{\use_ii:nn} +% The equivalent to \LaTeXe{}'s \cs{@firstoftwo} and \cs{@secondoftwo}. +% \begin{macrocode} +\cs_set:Npn \use_i:nn #1#2 {#1} +\cs_set:Npn \use_ii:nn #1#2 {#2} +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\use_i:nnn} +% \begin{macro}{\use_ii:nnn} +% \begin{macro}{\use_iii:nnn} +% \begin{macro}{\use_i_ii:nnn} +% \begin{macro}{\use_i:nnnn} +% \begin{macro}{\use_ii:nnnn} +% \begin{macro}{\use_iii:nnnn} +% \begin{macro}{\use_iv:nnnn} +% We also need something for picking up arguments from a longer +% list. +% \begin{macrocode} +\cs_set:Npn \use_i:nnn #1#2#3 {#1} +\cs_set:Npn \use_ii:nnn #1#2#3 {#2} +\cs_set:Npn \use_iii:nnn #1#2#3 {#3} +\cs_set:Npn \use_i_ii:nnn #1#2#3 {#1#2} +\cs_set:Npn \use_i:nnnn #1#2#3#4 {#1} +\cs_set:Npn \use_ii:nnnn #1#2#3#4 {#2} +\cs_set:Npn \use_iii:nnnn #1#2#3#4 {#3} +\cs_set:Npn \use_iv:nnnn #1#2#3#4 {#4} +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\use_none_delimit_by_q_nil:w} +% \begin{macro}{\use_none_delimit_by_q_stop:w} +% \begin{macro}{\use_none_delimit_by_q_recursion_stop:w} +% Functions that gobble everything until they see either \cs{q_nil} or +% \cs{q_stop}, respectively. +% \begin{macrocode} +\cs_set:Npn \use_none_delimit_by_q_nil:w #1 \q_nil { } +\cs_set:Npn \use_none_delimit_by_q_stop:w #1 \q_stop { } +\cs_set:Npn \use_none_delimit_by_q_recursion_stop:w #1 \q_recursion_stop { } +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\use_i_delimit_by_q_nil:nw} +% \begin{macro}{\use_i_delimit_by_q_stop:nw} +% \begin{macro}{\use_i_delimit_by_q_recursion_stop:nw} +% Same as above but execute first argument after gobbling. Very +% useful when you need to skip the rest of a mapping sequence but +% want an easy way to control what should be expanded next. +% \begin{macrocode} +\cs_set:Npn \use_i_delimit_by_q_nil:nw #1#2 \q_nil {#1} +\cs_set:Npn \use_i_delimit_by_q_stop:nw #1#2 \q_stop {#1} +\cs_set:Npn \use_i_delimit_by_q_recursion_stop:nw #1#2 \q_recursion_stop {#1} +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\use_i_after_fi:nw} +% \begin{macro}{\use_i_after_else:nw} +% \begin{macro}{\use_i_after_or:nw} +% \begin{macro}{\use_i_after_orelse:nw} +% Returns the first argument after ending the conditional. +% \begin{macrocode} +\cs_set:Npn \use_i_after_fi:nw #1 \fi: { \fi: #1 } +\cs_set:Npn \use_i_after_else:nw #1 \else: #2 \fi: { \fi: #1 } +\cs_set:Npn \use_i_after_or:nw #1 \or: #2 \fi: { \fi: #1 } +\cs_set:Npn \use_i_after_orelse:nw #1#2#3 \fi: { \fi: #1 } +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \subsection{Gobbling tokens from input} +% +% \begin{macro}{\use_none:n} +% \begin{macro}{\use_none:nn} +% \begin{macro}{\use_none:nnn} +% \begin{macro}{\use_none:nnnn} +% \begin{macro}{\use_none:nnnnn} +% \begin{macro}{\use_none:nnnnnn} +% \begin{macro}{\use_none:nnnnnnn} +% \begin{macro}{\use_none:nnnnnnnn} +% \begin{macro}{\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 defining +% |\use_none:nnn| and above as separate calls of |\use_none:n| and +% |\use_none:nn| is slightly faster, this is very non-intuitive to +% the programmer who will assume that expanding such a function once +% will take care of gobbling all the tokens in one go. +% \begin{macrocode} +\cs_set:Npn \use_none:n #1 { } +\cs_set:Npn \use_none:nn #1#2 { } +\cs_set:Npn \use_none:nnn #1#2#3 { } +\cs_set:Npn \use_none:nnnn #1#2#3#4 { } +\cs_set:Npn \use_none:nnnnn #1#2#3#4#5 { } +\cs_set:Npn \use_none:nnnnnn #1#2#3#4#5#6 { } +\cs_set:Npn \use_none:nnnnnnn #1#2#3#4#5#6#7 { } +\cs_set:Npn \use_none:nnnnnnnn #1#2#3#4#5#6#7#8 { } +\cs_set:Npn \use_none:nnnnnnnnn #1#2#3#4#5#6#7#8#9 { } +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \subsection{Conditional processing and definitions} +% +% Underneath any predicate function (|_p|) or other conditional forms +% (|TF|, etc.) is a built-in logic saying that it after all of the +% testing and processing must return the \meta{state} this leaves +% \TeX{} in. Therefore, a simple user interface could be something like +% \begin{verbatim} +% \if_meaning:w #1#2 \prg_return_true: \else: +% \if_meaning:w #1#3 \prg_return_true: \else: +% \prg_return_false: +% \fi: \fi: +% \end{verbatim} +% Usually, a \TeX{} programmer would have to insert a number of +% |\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}{\prg_return_true:} +% \begin{macro}{\prg_return_false:} +% The idea here is that \cs{int_to_roman:w} will expand fully any +% \cs{else:} and the \cs{fi:} that are waiting to be discarded, +% before reaching the \cs{c_zero} which will leave the expansion null. +% The code can then leave either the first or second argument in the +% input stream. This means that all of the branching code has to contain +% at least two tokens: see how the logical tests are actually implemented +% to see this. +% \begin{macrocode} +\cs_set_nopar:Npn \prg_return_true: + { \exp_after:wN \use_i:nn \int_to_roman:w } +\cs_set_nopar:Npn \prg_return_false: + { \exp_after:wN \use_ii:nn \int_to_roman:w} +% \end{macrocode} +% An extended state space could be implemented by including a more +% elaborate function in place of \cs{use_i:nn}/\cs{use_ii:nn}. Provided +% two arguments are absorbed then the code will work. +% \end{macro} +% \end{macro} +% +% \begin{macro}{\prg_set_conditional:Npnn,\prg_new_conditional:Npnn, +% \prg_set_protected_conditional:Npnn,\prg_new_protected_conditional:Npnn} +% The user functions for the types using parameter text from the +% programmer. Call aux function to grab parameters, split the base +% function into name and signature and then use, \emph{e.g.}, |\cs_set:Npn| +% to define it with. +% \begin{macrocode} +\cs_set_protected:Npn \prg_set_conditional:Npnn #1 + { + \prg_get_parm_aux:nw + { + \cs_split_function:NN #1 \prg_generate_conditional_aux:nnNNnnnn + \cs_set:Npn { parm } + } + } +\cs_set_protected:Npn \prg_new_conditional:Npnn #1 + { + \prg_get_parm_aux:nw + { + \cs_split_function:NN #1 \prg_generate_conditional_aux:nnNNnnnn + \cs_new:Npn { parm } + } + } +\cs_set_protected:Npn \prg_set_protected_conditional:Npnn #1 + { + \prg_get_parm_aux:nw{ + \cs_split_function:NN #1 \prg_generate_conditional_aux:nnNNnnnn + \cs_set_protected:Npn { parm } + } + } +\cs_set_protected:Npn \prg_new_protected_conditional:Npnn #1 + { + \prg_get_parm_aux:nw + { + \cs_split_function:NN #1 \prg_generate_conditional_aux:nnNNnnnn + \cs_new_protected:Npn { parm } + } + } +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\prg_set_conditional:Nnn,\prg_new_conditional:Nnn, +% \prg_set_protected_conditional:Nnn,\prg_new_protected_conditional:Nnn} +% The user functions for the types automatically inserting the +% correct parameter text based on the signature. Call aux function +% after calculating number of arguments, split the base function +% into name and signature and then use, \emph{e.g.}, |\cs_set:Npn| to +% define it with. +% \begin{macrocode} +\cs_set_protected:Npn \prg_set_conditional:Nnn #1 + { + \exp_args:Nnf \prg_get_count_aux:nn + { + \cs_split_function:NN #1 \prg_generate_conditional_aux:nnNNnnnn + \cs_set:Npn { count } + } + { \cs_get_arg_count_from_signature:N #1 } + } +\cs_set_protected:Npn \prg_new_conditional:Nnn #1 + { + \exp_args:Nnf \prg_get_count_aux:nn + { + \cs_split_function:NN #1 \prg_generate_conditional_aux:nnNNnnnn + \cs_new:Npn { count} + } + { \cs_get_arg_count_from_signature:N #1 } + } + +\cs_set_protected:Npn \prg_set_protected_conditional:Nnn #1{ + \exp_args:Nnf \prg_get_count_aux:nn{ + \cs_split_function:NN #1 \prg_generate_conditional_aux:nnNNnnnn + \cs_set_protected:Npn {count} + }{\cs_get_arg_count_from_signature:N #1} +} + +\cs_set_protected:Npn \prg_new_protected_conditional:Nnn #1 + { + \exp_args:Nnf \prg_get_count_aux:nn + { + \cs_split_function:NN #1 \prg_generate_conditional_aux:nnNNnnnn + \cs_new_protected:Npn {count} + } + { \cs_get_arg_count_from_signature:N #1 } + } +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\prg_set_eq_conditional:NNn,\prg_new_eq_conditional:NNn} +% The obvious setting-equal functions. +% \begin{macrocode} +\cs_set_protected:Npn \prg_set_eq_conditional:NNn #1#2#3 + { \prg_set_eq_conditional_aux:NNNn \cs_set_eq:cc #1#2 {#3} } +\cs_set_protected:Npn \prg_new_eq_conditional:NNn #1#2#3 + { \prg_set_eq_conditional_aux:NNNn \cs_new_eq:cc #1#2 {#3} } +% \end{macrocode} +% \end{macro} +% +% \begin{macro}[aux]{\prg_get_parm_aux:nw,\prg_get_count_aux:nn} +% For the |Npnn| type we must grab the parameter text before +% continuing. We make this a very generic function that takes one +% argument before reading everything up to a left brace. Something +% similar for the |Nnn| type. +% \begin{macrocode} +\cs_set:Npn \prg_get_count_aux:nn #1#2 { #1 {#2} } +\cs_set:Npn \prg_get_parm_aux:nw #1#2# { #1 {#2} } +% \end{macrocode} +% \end{macro} +% \begin{macro}[aux]{\prg_generate_conditional_parm_aux:nnNNnnnn, +% \prg_generate_conditional_parm_aux: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. For the time being, we do not use this piece of information +% but could well throw an error. The fourth argument is how to +% define this function, the fifth is the text |parm| or |count| for +% which version to use to define the functions, the sixth is the +% parameters to use (possibly empty) or number of arguments, the +% seventh is the list of forms to define, the eight is the +% replacement text which we will augment when defining the forms. +% \begin{macrocode} +\cs_set_protected:Npn \prg_generate_conditional_aux:nnNNnnnn #1#2#3#4#5#6#7#8 + { + \prg_generate_conditional_aux:nnw {#5} + { + #4 {#1} {#2} {#6} {#8} + } + #7 , ? , \q_recursion_stop + } +% \end{macrocode} +% Looping through the list of desired forms. First is the text |parm| +% or |count|, second is five arguments packed together and third is +% the form. Use text and form to call the correct type. +% \begin{macrocode} +\cs_set_protected:Npn \prg_generate_conditional_aux:nnw #1#2#3 , + { + \if:w ?#3 + \exp_after:wN \use_none_delimit_by_q_recursion_stop:w + \fi: + \use:c { prg_generate_#3_form_#1:Nnnnn } #2 + \prg_generate_conditional_aux:nnw {#1} {#2} + } +% \end{macrocode} +% \end{macro} +% +% \begin{macro}[aux] +% { +% \prg_generate_p_form_parm:Nnnnn, +% \prg_generate_TF_form_parm:Nnnnn, +% \prg_generate_T_form_parm:Nnnnn, +% \prg_generate_F_form_parm:Nnnnn +% } +% How to generate the various forms. The |parm| types here takes the +% following arguments: 1: how to define (an N-type), 2: name, 3: +% signature, 4: parameter text (or empty), 5: replacement. Remember that +% the logic-returning functions expect two arguments to be present after +% \cs{c_zero}: notice the construction of the different variants +% relies on this, and that the |TF| variant will be slightly faster +% than the |T| version. +% \begin{macrocode} +\cs_set_protected:Npn \prg_generate_p_form_parm:Nnnnn #1#2#3#4#5 + { + \exp_args:Nc #1 { #2 _p: #3 } #4 + { + #5 \c_zero + \c_true_bool \c_false_bool + } + } +\cs_set_protected:Npn \prg_generate_T_form_parm:Nnnnn #1#2#3#4#5 + { + \exp_args:Nc #1 { #2 : #3 T } #4 + { + #5 \c_zero + \use:n \use_none:n + } + } +\cs_set_protected:Npn \prg_generate_F_form_parm:Nnnnn #1#2#3#4#5 + { + \exp_args:Nc #1 { #2 : #3 F } #4 + { + #5 \c_zero + { } + } + } +\cs_set_protected:Npn \prg_generate_TF_form_parm:Nnnnn #1#2#3#4#5 + { + \exp_args:Nc #1 { #2 : #3 TF } #4 + { #5 \c_zero } + } +% \end{macrocode} +% \end{macro} +% \begin{macro}[aux] +% { +% \prg_generate_p_form_count:Nnnnn, +% \prg_generate_TF_form_count:Nnnnn, +% \prg_generate_T_form_count:Nnnnn, +% \prg_generate_F_form_count:Nnnnn +% } +% The |count| form is similar, but of course requires a number rather +% than a primitive argument specification. +% \begin{macrocode} +\cs_set_protected:Npn \prg_generate_p_form_count:Nnnnn #1#2#3#4#5 + { + \cs_generate_from_arg_count:cNnn { #2 _p: #3 } #1 {#4} + { + #5 \c_zero + \c_true_bool \c_false_bool + } + } +\cs_set_protected:Npn \prg_generate_T_form_count:Nnnnn #1#2#3#4#5 + { + \cs_generate_from_arg_count:cNnn { #2 : #3 T } #1 {#4} + { + #5 \c_zero + \use:n \use_none:n + } + } +\cs_set_protected:Npn \prg_generate_F_form_count:Nnnnn #1#2#3#4#5 + { + \cs_generate_from_arg_count:cNnn { #2 : #3 F } #1 {#4} + { + #5 \c_zero + { } + } + } +\cs_set_protected:Npn \prg_generate_TF_form_count:Nnnnn #1#2#3#4#5 + { + \cs_generate_from_arg_count:cNnn { #2 : #3 TF } #1 {#4} + { #5 \c_zero } + } +% \end{macrocode} +% \end{macro} +% +% \begin{macro}[aux]{\prg_set_eq_conditional_aux:NNNn, +% \prg_set_eq_conditional_aux:NNNw} +% \begin{macrocode} +\cs_set_protected:Npn \prg_set_eq_conditional_aux:NNNn #1#2#3#4 + { \prg_set_eq_conditional_aux:NNNw #1#2#3#4 , ? , \q_recursion_stop } +% \end{macrocode} +% Manual clist loop over argument |#4|. +% \begin{macrocode} +\cs_set_protected:Npn \prg_set_eq_conditional_aux:NNNw #1#2#3#4 , + { + \if:w ? #4 \scan_stop: + \exp_after:wN \use_none_delimit_by_q_recursion_stop:w + \fi: + #1 + { \exp_args:NNc \cs_split_function:NN #2 { prg_conditional_form_#4:nnn } } + { \exp_args:NNc \cs_split_function:NN #3 { prg_conditional_form_#4:nnn } } + \prg_set_eq_conditional_aux:NNNw #1 {#2} {#3} + } +% \end{macrocode} +% \begin{macrocode} +\cs_set:Npn \prg_conditional_form_p:nnn #1#2#3 { #1 _p : #2 } +\cs_set:Npn \prg_conditional_form_TF:nnn #1#2#3 { #1 : #2 TF } +\cs_set:Npn \prg_conditional_form_T:nnn #1#2#3 { #1 : #2 T } +\cs_set:Npn \prg_conditional_form_F:nnn #1#2#3 { #1 : #2 F } +% \end{macrocode} +% \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 |\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{macro}{\c_true_bool} +% \begin{macro}{\c_false_bool} +% Here are the canonical boolean values. +% \begin{macrocode} +\tex_chardef:D \c_true_bool = 1~ +\tex_chardef:D \c_false_bool = 0~ +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \subsection{Dissecting a control sequence} +% +% \begin{macro}{\cs_to_str:N} +% \begin{macro}[aux]{\cs_to_str_aux: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 |\tex_escapechar:D| 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 escape sequence will terminate the expansion started by +% \cs{int_to_roman:w}, which is a negative number and so will not +% gobble the escape character even if it's a number. The \cs{tex_if:D} +% test will then be \texttt{false}, and the na\"ive approach of gobbling +% the first character of the \cs{token_to_str:N} version of the control +% sequence will work, even if the first character is a space. +% The second case is that the escape character is itself a space. In this +% case, the escape character space is consumed terminating the first +% \cs{int_to_roman:w}, and \cs{cs_to_str_aux:w} is expanded. This +% inserts a space, making the \cs{if:w} test \texttt{true}. The +% second \cs{int_to_roman:w} will then execute the \cs{token_to_str:N}, +% with the escape-character space being consumed by the +% \cs{int_to_roman:w}, and thus leaving the control sequence name in the +% input stream. The final case is where the escape character is not +% printable. +% The flow here starts with the \verb*|\token_to_str:N \ | giving just a +% space, which terminates the first \cs{int_to_roman:w} but leaves no +% token for the \cs{if:w} test. This means that the \cs{int_to_roman:w} +% is executed before the test is finished. The result is that the +% \cs{fi:}, expanded before the \cs{tex_if:D} is finished, becomes +% \cs{scan_stop:} \cs{fi:}, and the \cs{scan_stop:} is then used in +% the \cs{if:w} test. +% In this case, \cs{token_to_str:N} is therefore used with no gobbling at +% all, which is exactly what is needed in this case. +% \begin{macrocode} +\cs_set_nopar:Npn \cs_to_str:N + { + \if:w \int_to_roman:w - `0 \token_to_str:N \ % + \cs_to_str_aux:w + \fi: + \exp_after:wN \use_none:n \token_to_str:N + } +\cs_set_nopar:Npn \cs_to_str_aux:w #1 \use_none:n + { ~ \int_to_roman:w - `0 \fi: } +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\cs_split_function:NN} +% \begin{macro}[aux]{\cs_split_function_aux:w} +% \begin{macro}[aux]{\cs_split_function_auxii:w} +% This function takes a function name and splits it into name with +% the escape char removed and argument specification. In addition to +% this, a third argument, a boolean \meta{true} or \meta{false} is +% returned with \meta{true} for when there is a colon in the function +% and \meta{false} if there is not. Lastly, the second argument of +% |\cs_split_function:NN| is supposed to be a function +% taking three variables, one for name, one for signature, and one +% for the boolean. For example, +% |\cs_split_function:NN\foo_bar:cnx\use_i:nnn| as input +% becomes |\use_i:nnn {foo_bar}{cnx}\c_true_bool|. +% +% Can't use a literal |:| because it has the wrong catcode here, so +% it's transformed from |@| with |\tex_lowercase:D|. +% \begin{macrocode} +\group_begin: + \tex_lccode:D `\@ = `\: \scan_stop: + \tex_catcode:D `\@ = 12~ +\tex_lowercase:D + { + \group_end: +% \end{macrocode} +% First ensure that we actually get a properly evaluated str as we +% don't know how many expansions |\cs_to_str:N| requires. Insert +% extra colon to catch the error cases. +% \begin{macrocode} + \cs_set:Npn \cs_split_function:NN #1#2 + { + \exp_after:wN \cs_split_function_aux:w + \int_to_roman:w - `\q \cs_to_str:N #1 @ a \q_stop #2 + } +% \end{macrocode} +% If no colon in the name, |#2| is |a| with catcode 11 and |#3| is +% empty. If colon in the name, then either |#2| is a colon or the +% first letter of the signature. The letters here have catcode 12. +% If a colon was given we need to a) split off the colon and quark at +% the end and b) ensure we return the name, signature and boolean true +% We can't use |\quark_if_no_value:NTF| yet but this is very safe +% anyway as all tokens have catcode~12. +% \begin{macrocode} + \cs_set:Npn \cs_split_function_aux:w #1 @ #2#3 \q_stop #4 + { + \if_meaning:w a #2 + \exp_after:wN \use_i:nn + \else: + \exp_after:wN\use_ii:nn + \fi: + { #4 {#1} { } \c_false_bool } + { \cs_split_function_auxii:w #2#3 \q_stop #4 {#1} } + } + \cs_set:Npn \cs_split_function_auxii:w #1 @a \q_stop #2#3 + { #2{#3}{#1}\c_true_bool } +% \end{macrocode} +% End of lowercase +% \begin{macrocode} + } +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\cs_get_function_name:N, \cs_get_function_signature:N} +% Now returning the name is trivial: just discard the last two +% arguments. Similar for signature. +% \begin{macrocode} +\cs_set:Npn \cs_get_function_name:N #1 + { \cs_split_function:NN #1 \use_i:nnn } +\cs_set:Npn \cs_get_function_signature:N #1 + { \cs_split_function:NN #1 \use_ii:nnn } +% \end{macrocode} +% \end{macro} +% +% \subsection{Exist or free} +% +% A control sequence is said to \emph{exist} (to be used) if has an entry in +% the hash table and its meaning is different from the primitive +% |\tex_relax:D| token. A control sequence is said to be \emph{free} +% (to be defined) if it does not already exist. +% +% \begin{macro}[pTF]{\cs_if_exist:N,\cs_if_exist:c} +% Two versions for checking existence. For the |N| form we firstly +% check for |\scan_stop:| and then if it is in the hash +% table. There is no problem when inputting something like |\else:| +% or |\fi:| as \TeX{} will only ever skip input in case the token +% tested against is |\scan_stop:|. +% \begin{macrocode} +\prg_set_conditional:Npnn \cs_if_exist:N #1 { p , T , F , TF } + { + \if_meaning:w #1 \scan_stop: + \prg_return_false: + \else: + \if_cs_exist:N #1 + \prg_return_true: + \else: + \prg_return_false: + \fi: + \fi: + } +% \end{macrocode} +% For the |c| form we firstly check if it is in the hash table and +% then for |\scan_stop:| so that we do not add it to the hash table +% unless it was already there. Here we have to be careful as the text +% to be skipped if the first test is false may contain tokens that +% disturb the scanner. Therefore, we ensure that the second test is +% performed after the first one has concluded completely. +% \begin{macrocode} +\prg_set_conditional:Npnn \cs_if_exist:c #1 { p , T , F , TF } + { + \if_cs_exist:w #1 \cs_end: + \exp_after:wN \use_i:nn + \else: + \exp_after:wN \use_ii:nn + \fi: + { + \exp_after:wN \if_meaning:w \cs:w #1 \cs_end: \scan_stop: + \prg_return_false: + \else: + \prg_return_true: + \fi: + } + \prg_return_false: + } +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \begin{macro}[pTF]{\cs_if_free:N,\cs_if_free:c} +% The logical reversal of the above. +% \begin{macrocode} +\prg_set_conditional:Npnn \cs_if_free:N #1 { p , T , F , TF } + { + \if_meaning:w #1 \scan_stop: + \prg_return_true: + \else: + \if_cs_exist:N #1 + \prg_return_false: + \else: + \prg_return_true: + \fi: + \fi: + } +\prg_set_conditional:Npnn \cs_if_free:c #1 { p , T , F , TF } + { + \if_cs_exist:w #1 \cs_end: + \exp_after:wN \use_i:nn + \else: + \exp_after:wN \use_ii:nn + \fi: + { + \exp_after:wN \if_meaning:w \cs:w #1 \cs_end: \scan_stop: + \prg_return_true: + \else: + \prg_return_false: + \fi: + } + { \prg_return_true: } + } +% \end{macrocode} +% \end{macro} +% +% \subsection{Defining and checking (new) functions} +% +% \begin{macro}{\c_minus_one, \c_zero, \c_sixteen} +% \begin{macro}{\c_six, \c_seven, \c_twelve} +% We need the constants |\c_minus_one| and |\c_sixteen| now for +% writing information to the log and the terminal and |\c_zero| +% which is used by some functions in the \textsf{l3alloc} module. The +% rest are defined in the \textsf{l3int} module -- at least for the +% ones that can be defined with |\tex_chardef:D| or +% |\tex_mathchardef:D|. For other constants the \textsf{l3int} module is +% required but it can't be used until the allocation has been set +% up properly! The actual allocation mechanism is in +% \textsf{l3alloc} and as \TeX{} wants to reserve count registers +% 0--9, the first available one is~10 so we use that for +% |\c_minus_one|. +% \begin{macrocode} +%<*package> +\cs_set_eq:NwN \c_minus_one \m@ne +%</package> +%<*initex> +\tex_countdef:D \c_minus_one = 10 ~ +\c_minus_one = -1 ~ +%</initex> +\tex_chardef:D \c_sixteen = 16~ +\tex_chardef:D \c_zero = 0~ +\tex_chardef:D \c_six = 6~ +\tex_chardef:D \c_seven = 7~ +\tex_chardef:D \c_twelve = 12~ +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\c_max_register_int} +% This is here as this particular integer is needed both in package +% mode and to bootstrap \pkg{l3alloc} +% \begin{macrocode} +\tex_mathchardef:D \c_max_register_int = 32 767 \scan_stop: +% \end{macrocode} +% \end{macro} +% +% We provide two kinds of functions that can be used to define +% control sequences. On the one hand we have functions that check +% if their argument doesn't already exist, they are called +% |\..._new|. The second type of defining functions doesn't check +% if the argument is already defined. +% +% Before we can define them, we need some auxiliary macros that +% allow us to generate error messages. The definitions here are +% only temporary, they will be redefined later on. +% +% \begin{macro}{\iow_log:x} +% \begin{macro}{\iow_term:x} +% We define a routine to write only to the log file. And a +% similar one for writing to both the log file and the terminal. +% These will be redefined later by \pkg{l3io}. +% \begin{macrocode} +\cs_set_protected_nopar:Npn \iow_log:x + { \tex_immediate:D \tex_write:D \c_minus_one } +\cs_set_protected_nopar:Npn \iow_term:x + { \tex_immediate:D \tex_write:D \c_sixteen } +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\msg_kernel_error:nnxx} +% \begin{macro}{\msg_kernel_error:nnx} +% \begin{macro}{\msg_kernel_error:nn} +% If an internal error occurs before \LaTeX3 has loaded \pkg{l3msg} then +% the code should issue a usable if terse error message and halt. This +% can only happen if a coding error is made by the team, so this is +% a reasonable response. +% \begin{macrocode} +\cs_set_protected_nopar:Npn \msg_kernel_error:nnxx #1#2#3#4 + { + \tex_errmessage:D + { + !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!~! ^^J + Argh,~internal~LaTeX3~error! ^^J ^^J + Module ~ #1 , ~ message~name~"#2": ^^J + Arguments~'#3'~and~'#4' ^^J ^^J + This~is~one~for~The~LaTeX3~Project:~bailing~out + } + \tex_end:D + } +\cs_set_protected_nopar:Npn \msg_kernel_error:nnx #1#2#3 + { \msg_kernel_error:nnxx {#1} {#2} {#3} { } } +\cs_set_protected_nopar:Npn \msg_kernel_error:nn #1#2 + { \msg_kernel_error:nnxx {#1} {#2} { } { } } +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\msg_line_context:} +% Another one from \pkg{l3msg} which will be altered later. +% \begin{macrocode} +\cs_set_nopar:Npn \msg_line_context: + { on~line~\tex_the:D \tex_inputlineno:D } +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\cs_record_meaning:N} +% This macro will be used later on for tracing purposes. But we +% need some more modules to define it, so we just give some dummy +% definition here. +% \begin{macrocode} +\cs_set:Npn \cs_record_meaning:N #1 { } +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\chk_if_free_cs:N, \chk_if_free_cs:c} +% This command is called by |\cs_new_nopar:Npn| and |\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 |\scan_stop:|. Otherwise an error message is +% issued. We have to make sure we don't put the argument into the +% conditional processing since it may be an |\if...| type function! +% \begin {macrocode} +\cs_set_protected_nopar:Npn \chk_if_free_cs:N #1 + { + \cs_if_free:NF #1 + { + \msg_kernel_error:nnxx { kernel } { command-already-defined } + { \token_to_str:N #1 } { \token_to_meaning:N #1 } + } +} +%<*package> +\tex_ifodd:D \@l@expl@log@functions@bool + \cs_set_protected_nopar:Npn \chk_if_free_cs:N #1 + { + \cs_if_free:NF #1 + { + \msg_kernel_error:nnxx { kernel } { command-already-defined } + { \token_to_str:N #1 } { \token_to_meaning:N #1 } + } + \iow_log:x { Defining~\token_to_str:N #1~ \msg_line_context: } + } +\fi: +%</package> +\cs_set_protected_nopar:Npn \chk_if_free_cs:c + { \exp_args:Nc \chk_if_free_cs:N } +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\chk_if_exist_cs:N, \chk_if_exist_cs:c} +% This function issues a warning message when the control sequence +% in its argument does not exist. +% \begin{macrocode} +\cs_set_protected_nopar:Npn \chk_if_exist_cs:N #1 + { + \cs_if_exist:NF #1 + { + \msg_kernel_error:nnxx { kernel } { command-not-defined } + { \token_to_str:N #1 } { \token_to_meaning:N #1 } + } + } +\cs_set_protected_nopar:Npn \chk_if_exist_cs:c + { \exp_args:Nc \chk_if_exist_cs:N } +% \end{macrocode} +% \end{macro} +% +% \subsection{More new definitions} +% +% \begin{macro}{\cs_new_nopar:Npn} +% \begin{macro}{\cs_new_nopar:Npx} +% \begin{macro}{\cs_new:Npn} +% \begin{macro}{\cs_new:Npx} +% \begin{macro}{\cs_new_protected_nopar:Npn} +% \begin{macro}{\cs_new_protected_nopar:Npx} +% \begin{macro}{\cs_new_protected:Npn} +% \begin{macro}{\cs_new_protected:Npx} +% Global versions of the above functions. +% \begin {macrocode} +\cs_set:Npn \cs_tmp:w #1#2 + { + \cs_set_protected_nopar:Npn #1 ##1 + { + \chk_if_free_cs:N ##1 + #2 ##1 + } + } +\cs_tmp:w \cs_new_nopar:Npn \cs_gset_nopar:Npn +\cs_tmp:w \cs_new_nopar:Npx \cs_gset_nopar:Npx +\cs_tmp:w \cs_new:Npn \cs_gset:Npn +\cs_tmp:w \cs_new:Npx \cs_gset:Npx +\cs_tmp:w \cs_new_protected_nopar:Npn \cs_gset_protected_nopar:Npn +\cs_tmp:w \cs_new_protected_nopar:Npx \cs_gset_protected_nopar:Npx +\cs_tmp:w \cs_new_protected:Npn \cs_gset_protected:Npn +\cs_tmp:w \cs_new_protected:Npx \cs_gset_protected:Npx +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\cs_set_nopar:cpn} +% \begin{macro}{\cs_set_nopar:cpx} +% \begin{macro}{\cs_gset_nopar:cpn} +% \begin{macro}{\cs_gset_nopar:cpx} +% \begin{macro}{\cs_new_nopar:cpn} +% \begin{macro}{\cs_new_nopar:cpx} +% Like |\cs_set_nopar:Npn| and |\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_set_nopar:cpn|\meta{string}\meta{rep-text} will turn \meta{string} +% into a csname and then assign \m {rep-text} to it by using +% |\cs_set_nopar:Npn|. This means that there might be a parameter +% string between the two arguments. +% \begin{macrocode} +\cs_set:Npn \cs_tmp:w #1#2 + { \cs_new_protected_nopar:Npn #1 { \exp_args:Nc #2 } } +\cs_tmp:w \cs_set_nopar:cpn \cs_set_nopar:Npn +\cs_tmp:w \cs_set_nopar:cpx \cs_set_nopar:Npx +\cs_tmp:w \cs_gset_nopar:cpn \cs_gset_nopar:Npn +\cs_tmp:w \cs_gset_nopar:cpx \cs_gset_nopar:Npx +\cs_tmp:w \cs_new_nopar:cpn \cs_new_nopar:Npn +\cs_tmp:w \cs_new_nopar:cpx \cs_new_nopar:Npx +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\cs_set:cpn} +% \begin{macro}{\cs_set:cpx} +% \begin{macro}{\cs_gset:cpn} +% \begin{macro}{\cs_gset:cpx} +% \begin{macro}{\cs_new:cpn} +% \begin{macro}{\cs_new:cpx} +% Variants of the |\cs_set:Npn| versions which make a csname out +% of the first arguments. We may also do this globally. +% \begin{macrocode} +\cs_tmp:w \cs_set:cpn \cs_set:Npn +\cs_tmp:w \cs_set:cpx \cs_set:Npx +\cs_tmp:w \cs_gset:cpn \cs_gset:Npn +\cs_tmp:w \cs_gset:cpx \cs_gset:Npx +\cs_tmp:w \cs_new:cpn \cs_new:Npn +\cs_tmp:w \cs_new:cpx \cs_new:Npx +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\cs_set_protected_nopar:cpn} +% \begin{macro}{\cs_set_protected_nopar:cpx} +% \begin{macro}{\cs_gset_protected_nopar:cpn} +% \begin{macro}{\cs_gset_protected_nopar:cpx} +% \begin{macro}{\cs_new_protected_nopar:cpn} +% \begin{macro}{\cs_new_protected_nopar:cpx} +% Variants of the |\cs_set_protected_nopar:Npn| versions which make a csname +% out of the first arguments. We may also do this globally. +% \begin{macrocode} +\cs_tmp:w \cs_set_protected_nopar:cpn \cs_set_protected_nopar:Npn +\cs_tmp:w \cs_set_protected_nopar:cpx \cs_set_protected_nopar:Npx +\cs_tmp:w \cs_gset_protected_nopar:cpn \cs_gset_protected_nopar:Npn +\cs_tmp:w \cs_gset_protected_nopar:cpx \cs_gset_protected_nopar:Npx +\cs_tmp:w \cs_new_protected_nopar:cpn \cs_new_protected_nopar:Npn +\cs_tmp:w \cs_new_protected_nopar:cpx \cs_new_protected_nopar:Npx +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\cs_set_protected:cpn} +% \begin{macro}{\cs_set_protected:cpx} +% \begin{macro}{\cs_gset_protected:cpn} +% \begin{macro}{\cs_gset_protected:cpx} +% \begin{macro}{\cs_new_protected:cpn} +% \begin{macro}{\cs_new_protected:cpx} +% Variants of the |\cs_set_protected:Npn| versions which make a csname +% out of the first arguments. We may also do this globally. +% \begin{macrocode} +\cs_tmp:w \cs_set_protected:cpn \cs_set_protected:Npn +\cs_tmp:w \cs_set_protected:cpx \cs_set_protected:Npx +\cs_tmp:w \cs_gset_protected:cpn \cs_gset_protected:Npn +\cs_tmp:w \cs_gset_protected:cpx \cs_gset_protected:Npx +\cs_tmp:w \cs_new_protected:cpn \cs_new_protected:Npn +\cs_tmp:w \cs_new_protected:cpx \cs_new_protected:Npx +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}[aux]{\use_0_parameter:} +% \begin{macro}[aux]{\use_1_parameter:} +% \begin{macro}[aux]{\use_2_parameter:} +% \begin{macro}[aux]{\use_3_parameter:} +% \begin{macro}[aux]{\use_4_parameter:} +% \begin{macro}[aux]{\use_5_parameter:} +% \begin{macro}[aux]{\use_6_parameter:} +% \begin{macro}[aux]{\use_7_parameter:} +% \begin{macro}[aux]{\use_8_parameter:} +% \begin{macro}[aux]{\use_9_parameter:} +% For using parameters, \emph{i.e.}, when you need to define a function to +% process three parameters. See \textsf{xparse} for an application. +% \begin{macrocode} +\cs_new_nopar:cpn { use_0_parameter: } { } +\cs_new_nopar:cpn { use_1_parameter: } { {##1} } +\cs_new_nopar:cpn { use_2_parameter: } { {##1} {##2} } +\cs_new_nopar:cpn { use_3_parameter: } { {##1} {##2} {##3} } +\cs_new_nopar:cpn { use_4_parameter: } { {##1} {##2} {##3} {##4} } +\cs_new_nopar:cpn { use_5_parameter: } { {##1} {##2} {##3} {##4} {##5} } +\cs_new_nopar:cpn { use_6_parameter: } { {##1} {##2} {##3} {##4} {##5} {##6} } +\cs_new_nopar:cpn { use_7_parameter: } + { {##1} {##2} {##3} {##4} {##5}{##6} {##7} } +\cs_new_nopar:cpn { use_8_parameter: } + { {##1} {##2} {##3} {##4} {##5} {##6} {##7} {##8} } +\cs_new_nopar:cpn{ use_9_parameter: } + { {##1} {##2} {##3} {##4} {##5} {##6} {##7} {##8} {##9} } +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \subsection{Copying definitions} +% +% \begin{macro}{\cs_set_eq:NN} +% \begin{macro}{\cs_set_eq:cN} +% \begin{macro}{\cs_set_eq:Nc} +% \begin{macro}{\cs_set_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_set_eq:NN| is long to avoid problems with a literal argument +% of |\par|. While |\cs_new_eq:NN| will probably never be correct +% with a first argument of |\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 { \cs_set_eq:NwN #1 =~ } +\cs_new_protected_nopar:Npn \cs_set_eq:cN { \exp_args:Nc \cs_set_eq:NN } +\cs_new_protected_nopar:Npn \cs_set_eq:Nc { \exp_args:NNc \cs_set_eq:NN } +\cs_new_protected_nopar:Npn \cs_set_eq:cc { \exp_args:Ncc \cs_set_eq:NN } +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\cs_new_eq:NN} +% \begin{macro}{\cs_new_eq:cN} +% \begin{macro}{\cs_new_eq:Nc} +% \begin{macro}{\cs_new_eq:cc} +% \begin{macrocode} +\cs_new_protected:Npn \cs_new_eq:NN #1 + { + \chk_if_free_cs:N #1 + \pref_global:D \cs_set_eq:NN #1 + } +\cs_new_protected_nopar:Npn \cs_new_eq:cN { \exp_args:Nc \cs_new_eq:NN } +\cs_new_protected_nopar:Npn \cs_new_eq:Nc { \exp_args:NNc \cs_new_eq:NN } +\cs_new_protected_nopar:Npn \cs_new_eq:cc { \exp_args:Ncc \cs_new_eq:NN } +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\cs_gset_eq:NN} +% \begin{macro}{\cs_gset_eq:cN} +% \begin{macro}{\cs_gset_eq:Nc} +% \begin{macro}{\cs_gset_eq:cc} +% \begin{macrocode} +\cs_new_protected_nopar:Npn \cs_gset_eq:NN { \pref_global:D \cs_set_eq:NN } +\cs_new_protected_nopar:Npn \cs_gset_eq:Nc { \exp_args:NNc \cs_gset_eq:NN } +\cs_new_protected_nopar:Npn \cs_gset_eq:cN { \exp_args:Nc \cs_gset_eq:NN } +\cs_new_protected_nopar:Npn \cs_gset_eq:cc { \exp_args:Ncc \cs_gset_eq:NN } +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \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. +% \begin{macrocode} +\cs_new_protected_nopar:Npn \cs_undefine:N #1 + { \cs_gset_eq:NN #1 \c_undefined:D } +\cs_new_protected_nopar:Npn \cs_undefine:c #1 + { \cs_gset_eq:cN {#1} \c_undefined:D } +% \end{macrocode} +% \end{macro} +% +% \subsection{Defining functions from a given number of arguments} +% +% \begin{macro}{\cs_get_arg_count_from_signature:N} +% \begin{macro}[aux]{\cs_get_arg_count_from_signature_aux:nnN} +% \begin{macro}[aux]{\cs_get_arg_count_from_signature_auxii:w} +% Counting the number of tokens in the signature, i.e., the number +% of arguments the function should take. If there is no signature, +% we return that there is $-1$ arguments to signal an error. +% Otherwise we insert the string |9876543210| after the signature. +% If the signature is empty, the number we want is $0$ so we remove +% the first nine tokens and return the tenth. Similarly, if the +% signature is |nnn| we want to remove the nine tokens |nnn987654| +% and return $3$. Therefore, we simply remove the first nine tokens +% and then return the tenth. +% \begin{macrocode} +\cs_new:Npn \cs_get_arg_count_from_signature:N #1 + { \cs_split_function:NN #1 \cs_get_arg_count_from_signature_aux:nnN } +\cs_new:Npn \cs_get_arg_count_from_signature_aux:nnN #1#2#3 + { + \if_predicate:w #3 + \exp_after:wN \use_i:nn + \else: + \exp_after:wN\use_ii:nn + \fi: + { + \exp_after:wN \cs_get_arg_count_from_signature_auxii:w + \use_none:nnnnnnnnn #2 9876543210 \q_stop + } + { -1 } +} +\cs_new:Npn \cs_get_arg_count_from_signature_auxii:w #1#2 \q_stop {#1} +% \end{macrocode} +% A variant form we need right away. +% \begin{macrocode} +\cs_new_nopar:Npn \cs_get_arg_count_from_signature:c + { \exp_args:Nc \cs_get_arg_count_from_signature:N } +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}[aux]{\cs_generate_from_arg_count:NNnn} +% \begin{macro}[aux]{\cs_generate_from_arg_count_error_msg:Nn} +% 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 + { + \if_case:w \int_eval:w #3 \int_eval_end: + \use_i_after_orelse:nw {#2#1} + \or: + \use_i_after_orelse:nw {#2#1 ##1} + \or: + \use_i_after_orelse:nw {#2#1 ##1##2} + \or: + \use_i_after_orelse:nw {#2#1 ##1##2##3} + \or: + \use_i_after_orelse:nw {#2#1 ##1##2##3##4} + \or: + \use_i_after_orelse:nw {#2#1 ##1##2##3##4##5} + \or: + \use_i_after_orelse:nw {#2#1 ##1##2##3##4##5##6} + \or: + \use_i_after_orelse:nw {#2#1 ##1##2##3##4##5##6##7} + \or: + \use_i_after_orelse:nw {#2#1 ##1##2##3##4##5##6##7##8} + \or: + \use_i_after_orelse:nw {#2#1 ##1##2##3##4##5##6##7##8##9} + \else: + \use_i_after_fi:nw + { + \cs_generate_from_arg_count_error_msg:Nn #1 {#3} + \use_none:n + } + \fi: + {#4} + } +% \end{macrocode} +% A variant form we need right away. +% \begin{macrocode} +\cs_new_nopar:Npn \cs_generate_from_arg_count:cNnn + { \exp_args:Nc \cs_generate_from_arg_count:NNnn } +% \end{macrocode} +% The error message. Elsewhere we use the value of $-1$ to signal a +% missing colon in a function, so provide a hint for help on this. +% \begin{macrocode} +\cs_new:Npn \cs_generate_from_arg_count_error_msg:Nn #1#2 + { + \msg_kernel_error:nnxx { kernel } { bad-number-of-arguments } + { \token_to_str:N #1 } { \int_eval:n {#2} } + } +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \subsection{Using the signature to define functions} +% +% We can now combine some of the tools we have to provide a simple +% interface for defining functions. We define some simpler functions +% with user interface |\cs_set:Nn \foo_bar:nn {#1,#2}|, \emph{i.e.}, the +% number of arguments is read from the signature. +% +% +% \begin{macro}{\cs_set:Nn} +% \begin{macro}{\cs_set:Nx} +% \begin{macro}{\cs_set_nopar:Nn} +% \begin{macro}{\cs_set_nopar:Nx} +% \begin{macro}{\cs_set_protected:Nn} +% \begin{macro}{\cs_set_protected:Nx} +% \begin{macro}{\cs_set_protected_nopar:Nn} +% \begin{macro}{\cs_set_protected_nopar:Nx} +% \begin{macro}{\cs_gset:Nn} +% \begin{macro}{\cs_gset:Nx} +% \begin{macro}{\cs_gset_nopar:Nn} +% \begin{macro}{\cs_gset_nopar:Nx} +% \begin{macro}{\cs_gset_protected:Nn} +% \begin{macro}{\cs_gset_protected:Nx} +% \begin{macro}{\cs_gset_protected_nopar:Nn} +% \begin{macro}{\cs_gset_protected_nopar:Nx} +% We want to define |\cs_set:Nn| as +% \begin{verbatim} +% \cs_set_protected:Npn \cs_set:Nn #1#2 +% { +% \cs_generate_from_arg_count:NNnn #1 \cs_set:Npn +% { \cs_get_arg_count_from_signature:N #1 } {#2} +% } +% \end{verbatim} +% In short, to define |\cs_set:Nn| we need just use |\cs_set:Npn|, +% everything else is the same for each variant. Therefore, we can +% make it simpler by temporarily defining a function to do this for +% us. +% \begin{macrocode} +\cs_set:Npn \cs_tmp:w #1#2#3 + { + \cs_set_protected:cpx { cs_ #1 : #2 } ##1##2 + { + \exp_not:N \cs_generate_from_arg_count:NNnn ##1 + \exp_after:wN \exp_not:N \cs:w cs_#1 : #3 \cs_end: + { \exp_not:N\cs_get_arg_count_from_signature:N ##1 }{##2} + } + } +% \end{macrocode} +% Then we define the 32 variants beginning with |N|. +% \begin{macrocode} +\cs_tmp:w { set } { Nn } { Npn } +\cs_tmp:w { set } { Nx } { Npx } +\cs_tmp:w { set_nopar } { Nn } { Npn } +\cs_tmp:w { set_nopar } { Nx } { Npx } +\cs_tmp:w { set_protected } { Nn } { Npn } +\cs_tmp:w { set_protected } { Nx } { Npx } +\cs_tmp:w { set_protected_nopar } { Nn } { Npn } +\cs_tmp:w { set_protected_nopar } { Nx } { Npx } +\cs_tmp:w { gset } { Nn } { Npn } +\cs_tmp:w { gset } { Nx } { Npx } +\cs_tmp:w { gset_nopar } { Nn } { Npn } +\cs_tmp:w { gset_nopar } { Nx } { Npx } +\cs_tmp:w { gset_protected } { Nn } { Npn } +\cs_tmp:w { gset_protected } { Nx } { Npx } +\cs_tmp:w { gset_protected_nopar } { Nn } { Npn } +\cs_tmp:w { gset_protected_nopar } { Nx } { Npx } +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\cs_new:Nn} +% \begin{macro}{\cs_new:Nx} +% \begin{macro}{\cs_new_nopar:Nn} +% \begin{macro}{\cs_new_nopar:Nx} +% \begin{macro}{\cs_new_protected:Nn} +% \begin{macro}{\cs_new_protected:Nx} +% \begin{macro}{\cs_new_protected_nopar:Nn} +% \begin{macro}{\cs_new_protected_nopar:Nx} +% \begin{macrocode} +\cs_tmp:w { new } { Nn } { Npn } +\cs_tmp:w { new } { Nx } { Npx } +\cs_tmp:w { new_nopar } { Nn } { Npn } +\cs_tmp:w { new_nopar } { Nx } { Npx } +\cs_tmp:w { new_protected } { Nn } { Npn } +\cs_tmp:w { new_protected } { Nx } { Npx } +\cs_tmp:w { new_protected_nopar } { Nn } { Npn } +\cs_tmp:w { new_protected_nopar } { Nx } { Npx } +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% Then something similar for the |c| variants. +% \begin{verbatim} +% \cs_set_protected:Npn \cs_set:cn #1#2 +% { +% \cs_generate_from_arg_count:cNnn {#1} \cs_set:Npn +% { \cs_get_arg_count_from_signature:c {#1} } {#2} +% } +% \end{verbatim} +% \begin{macrocode} +\cs_set:Npn \cs_tmp:w #1#2#3 + { + \cs_set_protected:cpx {cs_#1:#2}##1##2{ + \exp_not:N\cs_generate_from_arg_count:cNnn {##1} + \exp_after:wN \exp_not:N \cs:w cs_#1:#3 \cs_end: + { \exp_not:N \cs_get_arg_count_from_signature:c {##1} } {##2} + } + } +% \end{macrocode} +% \begin{macro}{\cs_set:cn} +% \begin{macro}{\cs_set:cx} +% \begin{macro}{\cs_set_nopar:cn} +% \begin{macro}{\cs_set_nopar:cx} +% \begin{macro}{\cs_set_protected:cn} +% \begin{macro}{\cs_set_protected:cx} +% \begin{macro}{\cs_set_protected_nopar:cn} +% \begin{macro}{\cs_set_protected_nopar:cx} +% \begin{macro}{\cs_gset:cn} +% \begin{macro}{\cs_gset:cx} +% \begin{macro}{\cs_gset_nopar:cn} +% \begin{macro}{\cs_gset_nopar:cx} +% \begin{macro}{\cs_gset_protected:cn} +% \begin{macro}{\cs_gset_protected:cx} +% \begin{macro}{\cs_gset_protected_nopar:cn} +% \begin{macro}{\cs_gset_protected_nopar:cx} +% The 32 |c| variants. +% \begin{macrocode} +\cs_tmp:w { set } { cn } { Npn } +\cs_tmp:w { set } { cx } { Npx } +\cs_tmp:w { set_nopar } { cn } { Npn } +\cs_tmp:w { set_nopar } { cx } { Npx } +\cs_tmp:w { set_protected } { cn } { Npn } +\cs_tmp:w { set_protected } { cx } { Npx } +\cs_tmp:w { set_protected_nopar } { cn } { Npn } +\cs_tmp:w { set_protected_nopar } { cx } { Npx } +\cs_tmp:w { gset } { cn } { Npn } +\cs_tmp:w { gset } { cx } { Npx } +\cs_tmp:w { gset_nopar } { cn } { Npn } +\cs_tmp:w { gset_nopar } { cx } { Npx } +\cs_tmp:w { gset_protected } { cn } { Npn } +\cs_tmp:w { gset_protected } { cx } { Npx } +\cs_tmp:w { gset_protected_nopar } { cn } { Npn } +\cs_tmp:w { gset_protected_nopar } { cx } { Npx } +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\cs_new:cn} +% \begin{macro}{\cs_new:cx} +% \begin{macro}{\cs_new_nopar:cn} +% \begin{macro}{\cs_new_nopar:cx} +% \begin{macro}{\cs_new_protected:cn} +% \begin{macro}{\cs_new_protected:cx} +% \begin{macro}{\cs_new_protected_nopar:cn} +% \begin{macro}{\cs_new_protected_nopar:cx} +% \begin{macrocode} +\cs_tmp:w { new } { cn } { Npn } +\cs_tmp:w { new } { cx } { Npx } +\cs_tmp:w { new_nopar } { cn } { Npn } +\cs_tmp:w { new_nopar } { cx } { Npx } +\cs_tmp:w { new_protected } { cn } { Npn } +\cs_tmp:w { new_protected } { cx } { Npx } +\cs_tmp:w { new_protected_nopar } { cn } { Npn } +\cs_tmp:w { new_protected_nopar } { cx } { Npx } +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \subsection{Checking control sequence equality} +% +% \begin{macro}[pTF]{\cs_if_eq:NN,\cs_if_eq:cN,\cs_if_eq:Nc,\cs_if_eq:cc} +% Check if two control sequences are identical. +% \begin{macrocode} +\prg_new_conditional:Npnn \cs_if_eq:NN #1#2 { p , T , F , TF } + { + \if_meaning:w #1#2 + \prg_return_true: \else: \prg_return_false: \fi: + } +\cs_new_nopar:Npn \cs_if_eq_p:cN { \exp_args:Nc \cs_if_eq_p:NN } +\cs_new_nopar:Npn \cs_if_eq:cNTF { \exp_args:Nc \cs_if_eq:NNTF } +\cs_new_nopar:Npn \cs_if_eq:cNT { \exp_args:Nc \cs_if_eq:NNT } +\cs_new_nopar:Npn \cs_if_eq:cNF { \exp_args:Nc \cs_if_eq:NNF } +\cs_new_nopar:Npn \cs_if_eq_p:Nc { \exp_args:NNc \cs_if_eq_p:NN } +\cs_new_nopar:Npn \cs_if_eq:NcTF { \exp_args:NNc \cs_if_eq:NNTF } +\cs_new_nopar:Npn \cs_if_eq:NcT { \exp_args:NNc \cs_if_eq:NNT } +\cs_new_nopar:Npn \cs_if_eq:NcF { \exp_args:NNc \cs_if_eq:NNF } +\cs_new_nopar:Npn \cs_if_eq_p:cc { \exp_args:Ncc \cs_if_eq_p:NN } +\cs_new_nopar:Npn \cs_if_eq:ccTF { \exp_args:Ncc \cs_if_eq:NNTF } +\cs_new_nopar:Npn \cs_if_eq:ccT { \exp_args:Ncc \cs_if_eq:NNT } +\cs_new_nopar:Npn \cs_if_eq:ccF { \exp_args:Ncc \cs_if_eq:NNF } +% \end{macrocode} +% \end{macro} +% +% \subsection{Diagnostic wrapper functions} +% +% \begin{macro}{\kernel_register_show:N, \kernel_register_show:c} +% \begin{macrocode} +\cs_new_nopar:Npn \kernel_register_show:N #1 + { + \cs_if_exist:NTF #1 + { \tex_showthe:D #1 } + { + \msg_kernel_error:nnx { kernel } { variable-not-defined } + { \token_to_str:N #1 } + } + } +\cs_new_nopar:Npn \kernel_register_show:c { \exp_args:Nc \int_show:N } +% \end{macrocode} +% \end{macro} +% +% \subsection{Engine specific definitions} +% +% \begin{macro} +% { +% \c_pdftex_is_engine_bool, \c_luatex_is_engine_bool, +% \c_xetex_is_engine_bool +% } +% \begin{macro}[TF]{\xetex_if_engine:, \luatex_if_engine:, \pdftex_if_engine:} +% In some cases it will be useful to know which engine we're running. +% Don't provide a |_p| predicate because the |_bool| is used for the +% same thing. This can all be hard-coded for speed. +% \begin{macrocode} +\cs_new_eq:NN \luatex_if_engine:T \use_none:n +\cs_new_eq:NN \luatex_if_engine:F \use:n +\cs_new_eq:NN \luatex_if_engine:TF \use_ii:nn +\cs_new_eq:NN \pdftex_if_engine:T \use:n +\cs_new_eq:NN \pdftex_if_engine:F \use_none:n +\cs_new_eq:NN \pdftex_if_engine:TF \use_i:nn +\cs_new_eq:NN \xetex_if_engine:T \use_none:n +\cs_new_eq:NN \xetex_if_engine:F \use:n +\cs_new_eq:NN \xetex_if_engine:TF \use_ii:nn +\cs_new_eq:NN \c_luatex_is_engine_bool \c_false_bool +\cs_new_eq:NN \c_pdftex_is_engine_bool \c_true_bool +\cs_new_eq:NN \c_xetex_is_engine_bool \c_false_bool +\cs_if_exist:NT \xetex_XeTeXversion:D + { + \cs_set_eq:NN \pdftex_if_engine:T \use_none:n + \cs_set_eq:NN \pdftex_if_engine:F \use:n + \cs_set_eq:NN \pdftex_if_engine:TF \use_ii:nn + \cs_set_eq:NN \xetex_if_engine:T \use:n + \cs_set_eq:NN \xetex_if_engine:F \use_none:n + \cs_set_eq:NN \xetex_if_engine:TF \use_i:nn + \cs_set_eq:NN \c_pdftex_is_engine_bool \c_false_bool + \cs_set_eq:NN \c_xetex_is_engine_bool \c_true_bool + } +\cs_if_exist:NT \luatex_directlua:D + { + \cs_set_eq:NN \luatex_if_engine:T \use:n + \cs_set_eq:NN \luatex_if_engine:F \use_none:n + \cs_set_eq:NN \luatex_if_engine:TF \use_i:nn + \cs_set_eq:NN \pdftex_if_engine:T \use_none:n + \cs_set_eq:NN \pdftex_if_engine:F \use:n + \cs_set_eq:NN \pdftex_if_engine:TF \use_ii:nn + \cs_set_eq:NN \c_luatex_is_engine_bool \c_true_bool + \cs_set_eq:NN \c_pdftex_is_engine_bool \c_false_bool + } +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \subsection{Doing nothing functions} +% +% \begin{macro}{\prg_do_nothing:} +% This does not fit anywhere else! +% \begin{macrocode} +\cs_new_nopar:Npn \prg_do_nothing: { } +% \end{macrocode} +% \end{macro} +% +% \subsection{String comparisons} +% +% \begin{macro}[pTF]{\str_if_eq:nn} +% \begin{macro}[pTF]{\str_if_eq:xx} +% Modern engines provide a direct way of comparing two token lists, +% but returning a number. This set of conditionals therefore make life +% a bit clearer. The \texttt{nn} and \texttt{xx} versions are created +% directly as this is most efficient. These should eventually +% move somewhere else. +% \begin{macrocode} +\prg_new_conditional:Npnn \str_if_eq:nn #1#2 { p , T , F , TF } + { + \if_int_compare:w \pdftex_strcmp:D { \exp_not:n {#1} } { \exp_not:n {#2} } + = \c_zero + \prg_return_true: \else: \prg_return_false: \fi: + } +\prg_new_conditional:Npnn \str_if_eq:xx #1#2 { p , T , F , TF } + { + \if_int_compare:w \pdftex_strcmp:D {#1} {#2} = \c_zero + \prg_return_true: \else: \prg_return_false: \fi: + } +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \subsection{Deprecated functions} +% +% Deprecated on 2011-05-27, for removal by 2011-08-31. +% +% \begin{macrocode} +\cs_new_eq:NN \cs_gnew_nopar:Npn \cs_new_nopar:Npn +\cs_new_eq:NN \cs_gnew:Npn \cs_new:Npn +\cs_new_eq:NN \cs_gnew_protected_nopar:Npn \cs_new_protected_nopar:Npn +\cs_new_eq:NN \cs_gnew_protected:Npn \cs_new_protected:Npn +\cs_new_eq:NN \cs_gnew_nopar:Npx \cs_new_nopar:Npx +\cs_new_eq:NN \cs_gnew:Npx \cs_new:Npx +\cs_new_eq:NN \cs_gnew_protected_nopar:Npx \cs_new_protected_nopar:Npx +\cs_new_eq:NN \cs_gnew_protected:Npx \cs_new_protected:Npx +\cs_new_eq:NN \cs_gnew_nopar:cpn \cs_new_nopar:cpn +\cs_new_eq:NN \cs_gnew:cpn \cs_new:cpn +\cs_new_eq:NN \cs_gnew_protected_nopar:cpn \cs_new_protected_nopar:cpn +\cs_new_eq:NN \cs_gnew_protected:cpn \cs_new_protected:cpn +\cs_new_eq:NN \cs_gnew_nopar:cpx \cs_new_nopar:cpx +\cs_new_eq:NN \cs_gnew:cpx \cs_new:cpx +\cs_new_eq:NN \cs_gnew_protected_nopar:cpx \cs_new_protected_nopar:cpx +\cs_new_eq:NN \cs_gnew_protected:cpx \cs_new_protected:cpx +% \end{macrocode} +% +% \begin{macrocode} +\cs_new_eq:NN \cs_gnew_eq:NN \cs_new_eq:NN +\cs_new_eq:NN \cs_gnew_eq:cN \cs_new_eq:cN +\cs_new_eq:NN \cs_gnew_eq:Nc \cs_new_eq:Nc +\cs_new_eq:NN \cs_gnew_eq:cc \cs_new_eq:cc +% \end{macrocode} +% +% \begin{macrocode} +\cs_new_eq:NN \cs_gundefine:N \cs_undefine:N +\cs_new_eq:NN \cs_gundefine:c \cs_undefine:c +% \end{macrocode} +% +% \begin{macrocode} +\cs_new_eq:NN \group_execute_after:N \group_insert_after:N +% \end{macrocode} +% +% \begin{macrocode} +%</initex|package> +% \end{macrocode} +% +% \end{implementation} +% +% \PrintIndex |