| 1 |
\iffalse meta-comment |
| 2 |
|
| 3 |
File: source3body.tex |
| 4 |
|
| 5 |
Copyright (C) 1990-2012,2014-2025 The LaTeX Project |
| 6 |
|
| 7 |
It may be distributed and/or modified under the conditions of the |
| 8 |
LaTeX Project Public License (LPPL), either version 1.3c of this |
| 9 |
license or (at your option) any later version. The latest version |
| 10 |
of this license is in the file |
| 11 |
|
| 12 |
https://www.latex-project.org/lppl.txt |
| 13 |
|
| 14 |
This file is part of the "l3kernel bundle" (The Work in LPPL) |
| 15 |
and all files in that bundle must be distributed together. |
| 16 |
|
| 17 |
The released version of this bundle is available from CTAN. |
| 18 |
|
| 19 |
----------------------------------------------------------------------- |
| 20 |
|
| 21 |
The development version of the bundle can be found at |
| 22 |
|
| 23 |
https://github.com/latex3/latex3 |
| 24 |
|
| 25 |
for those people who are interested. |
| 26 |
|
| 27 |
\fi |
| 28 |
|
| 29 |
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
| 30 |
% |
| 31 |
% This file is used by |
| 32 |
% |
| 33 |
% source3.tex % documentation including implementation |
| 34 |
% |
| 35 |
% interface3.tex % only interface documentation |
| 36 |
% |
| 37 |
% |
| 38 |
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
| 39 |
|
| 40 |
|
| 41 |
\begin{abstract} |
| 42 |
|
| 43 |
\setlength\parindent{0pt} |
| 44 |
\setlength\parskip{\baselineskip} |
| 45 |
|
| 46 |
\noindent |
| 47 |
\ifinterface |
| 48 |
This is the reference documentation for the \pkg{expl3} |
| 49 |
programming environment; see the matching \pkg{source3} PDF |
| 50 |
for the typeset sources. |
| 51 |
\else |
| 52 |
This is the typset sources for the \pkg{expl3} |
| 53 |
programming environment; see the matching \pkg{interface3} PDF |
| 54 |
for the API reference manual. |
| 55 |
\fi |
| 56 |
The \pkg{expl3} modules set up a |
| 57 |
naming scheme for \LaTeX{} commands, which allow the \LaTeX{} programmer |
| 58 |
to systematically name functions and variables, and specify the argument |
| 59 |
types of functions. |
| 60 |
|
| 61 |
The \TeX{} and \eTeX{} primitives are all given a new name according to |
| 62 |
these conventions. However, in the main direct use of the primitives is |
| 63 |
not required or encouraged: the \pkg{expl3} modules define an |
| 64 |
independent low-level \LaTeX3 programming language. |
| 65 |
|
| 66 |
The \pkg{expl3} modules are designed to be loaded on top of |
| 67 |
\LaTeXe{}. With an up-to-date \LaTeXe{} kernel, this material is loaded |
| 68 |
as part of the format. The fundamental programming code can also be loaded |
| 69 |
with other \TeX{} formats, subject to restrictions on the full range of |
| 70 |
functionality. |
| 71 |
|
| 72 |
\end{abstract} |
| 73 |
|
| 74 |
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
| 75 |
% |
| 76 |
% Each of the following \DocInput lines includes a file with extension |
| 77 |
% .dtx. Each of these files may be typeset separately. For instance |
| 78 |
% pdflatex l3box.dtx |
| 79 |
% will typeset the source of the LaTeX3 box commands. If you use the |
| 80 |
% Makefile, the index will be generated automatically; e.g., |
| 81 |
% make doc F=l3box |
| 82 |
% |
| 83 |
% If this file is processed, each of these separate dtx files will be |
| 84 |
% contained as a part of a single document. |
| 85 |
% |
| 86 |
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
| 87 |
|
| 88 |
\makeatletter |
| 89 |
% l3doc is based on article, but for these very large documents we need |
| 90 |
% chapters; the code is based on the standard classes but somewhat simplified |
| 91 |
\renewcommand\part{% |
| 92 |
\clearpage |
| 93 |
\thispagestyle{plain}% |
| 94 |
\@tempswafalse |
| 95 |
\null\vfil |
| 96 |
\secdef\@part\@spart} |
| 97 |
\newcounter {chapter} |
| 98 |
\numberwithin{section}{chapter} |
| 99 |
\renewcommand \thechapter {\@arabic\c@chapter} |
| 100 |
\renewcommand \thesection {\thechapter.\@arabic\c@section} |
| 101 |
\newcommand*\chaptermark[1]{} |
| 102 |
\setcounter{secnumdepth}{2} |
| 103 |
\newcommand\@chapapp{\chaptername} |
| 104 |
\newcommand\chaptername{Chapter} |
| 105 |
\def\ps@headings{% |
| 106 |
\let\@oddfoot\@empty |
| 107 |
\def\@oddhead{{\slshape\rightmark}\hfil\thepage}% |
| 108 |
\let\@mkboth\markboth |
| 109 |
\def\chaptermark##1{% |
| 110 |
\markright {\MakeUppercase{% |
| 111 |
\ifnum \c@secnumdepth >\m@ne |
| 112 |
\@chapapp\ \thechapter. \ % |
| 113 |
\fi |
| 114 |
##1}}}} |
| 115 |
\newcommand\chapter{\clearpage |
| 116 |
\thispagestyle{plain}% |
| 117 |
\global\@topnum\z@ |
| 118 |
\@afterindentfalse |
| 119 |
\secdef\@chapter\@schapter} |
| 120 |
\def\@chapter[#1]#2{\refstepcounter{chapter}% |
| 121 |
\typeout{\@chapapp\space\thechapter.}% |
| 122 |
\addcontentsline{toc}{chapter}% |
| 123 |
{\protect\numberline{\thechapter}#1}% |
| 124 |
\chaptermark{#1}% |
| 125 |
\addtocontents{lof}{\protect\addvspace{10\p@}}% |
| 126 |
\addtocontents{lot}{\protect\addvspace{10\p@}}% |
| 127 |
\@makechapterhead{#2}% |
| 128 |
\@afterheading} |
| 129 |
\def\@makechapterhead#1{% |
| 130 |
\vspace*{50\p@}% |
| 131 |
{\parindent \z@ \raggedright \normalfont |
| 132 |
\huge\bfseries \@chapapp\space \thechapter |
| 133 |
\par\nobreak |
| 134 |
\vskip 20\p@ |
| 135 |
\interlinepenalty\@M |
| 136 |
\Huge \bfseries #1\par\nobreak |
| 137 |
\vskip 40\p@ |
| 138 |
}} |
| 139 |
\newcommand*\l@chapter[2]{% |
| 140 |
\ifnum \c@tocdepth >\m@ne |
| 141 |
\addpenalty{-\@highpenalty}% |
| 142 |
\vskip 1.0em \@plus\p@ |
| 143 |
\setlength\@tempdima{1.5em}% |
| 144 |
\begingroup |
| 145 |
\parindent \z@ \rightskip \@pnumwidth |
| 146 |
\parfillskip -\@pnumwidth |
| 147 |
\leavevmode \bfseries |
| 148 |
\advance\leftskip\@tempdima |
| 149 |
\hskip -\leftskip |
| 150 |
#1\nobreak\hfil |
| 151 |
\nobreak\hb@xt@\@pnumwidth{\hss #2% |
| 152 |
\kern-\p@\kern\p@}\par |
| 153 |
\penalty\@highpenalty |
| 154 |
\endgroup |
| 155 |
\fi} |
| 156 |
\renewcommand*\l@section{\@dottedtocline{1}{1.5em}{2.8em}} |
| 157 |
\renewcommand*\l@subsection{\@dottedtocline{2}{3.8em}{3.2em}} |
| 158 |
\renewcommand*\l@subsubsection{\@dottedtocline{3}{7.0em}{4.1em}} |
| 159 |
\def\partname{Part} |
| 160 |
\def\toclevel@part{-1} |
| 161 |
\def\maketitle{\chapter{\@title}} |
| 162 |
\let\thanks\@gobble |
| 163 |
\let\DelayPrintIndex\PrintIndex |
| 164 |
\let\PrintIndex\@empty |
| 165 |
\providecommand*{\hexnum}[1]{\text{\texttt{\char`\"}#1}} |
| 166 |
\makeatother |
| 167 |
|
| 168 |
\clearpage |
| 169 |
|
| 170 |
{% |
| 171 |
\def\\{:}% fix "newlines" in the ToC |
| 172 |
\tableofcontents |
| 173 |
} |
| 174 |
|
| 175 |
\clearpage |
| 176 |
\pagenumbering{arabic} |
| 177 |
|
| 178 |
\part{Introduction} |
| 179 |
|
| 180 |
\chapter{Introduction to \pkg{expl3} and this document} |
| 181 |
|
| 182 |
This document is intended to act as a comprehensive reference manual |
| 183 |
for the \pkg{expl3} language. A general guide to the \LaTeX3 |
| 184 |
programming language is found in \href{expl3.pdf}{expl3.pdf}. |
| 185 |
|
| 186 |
\section{Naming functions and variables} |
| 187 |
|
| 188 |
\LaTeX3 does not use \texttt{@} as a \enquote{letter} for defining |
| 189 |
internal macros. Instead, the symbols |_| and \texttt{:} |
| 190 |
are used in internal macro names to provide structure. The name of |
| 191 |
each \emph{function} is divided into logical units using \texttt{_}, |
| 192 |
while \texttt{:} separates the \emph{name} of the function from the |
| 193 |
\emph{argument specifier} (\enquote{arg-spec}). This describes the arguments |
| 194 |
expected by the function. In most cases, each argument is represented |
| 195 |
by a single letter. The complete list of arg-spec letters for a function |
| 196 |
is referred to as the \emph{signature} of the function. |
| 197 |
|
| 198 |
Each function name starts with the \emph{module} to which it belongs. |
| 199 |
Thus apart from a small number of very basic functions, all \pkg{expl3} |
| 200 |
function names contain at least one underscore to divide the module |
| 201 |
name from the descriptive name of the function. For example, all |
| 202 |
functions concerned with comma lists are in module \texttt{clist} and |
| 203 |
begin |\clist_|. |
| 204 |
|
| 205 |
Every function must include an argument specifier. For functions which |
| 206 |
take no arguments, this will be blank and the function name will end |
| 207 |
\texttt{:}. Most functions take one or more arguments, and use the |
| 208 |
following argument specifiers: |
| 209 |
\begin{description} |
| 210 |
\item[\texttt{N} and \texttt{n}] These mean \emph{no manipulation}, |
| 211 |
of a single token for \texttt{N} and of a set of tokens given in |
| 212 |
braces for \texttt{n}. Both pass the argument through exactly as |
| 213 |
given. Usually, if you use a single token for an \texttt{n} argument, |
| 214 |
all will be well. |
| 215 |
\item[\texttt{c}] This means \emph{csname}, and indicates that the |
| 216 |
argument will be turned into a csname before being used. So |
| 217 |
|\foo:c| |{ArgumentOne}| will act in the same way as |\foo:N| |
| 218 |
|\ArgumentOne|. All macros that appear in the argument are expanded. |
| 219 |
An internal error will occur if the result of expansion inside |
| 220 |
a \texttt{c}-type argument is not a series of character tokens. |
| 221 |
\item[\texttt{V} and \texttt{v}] These mean \emph{value |
| 222 |
of variable}. The \texttt{V} and \texttt{v} specifiers are used to |
| 223 |
get the content of a variable without needing to worry about the |
| 224 |
underlying \TeX{} structure containing the data. A \texttt{V} |
| 225 |
argument will be a single token (similar to \texttt{N}), for example |
| 226 |
|\foo:V| \cs[no-index]{l_my_\meta{type}}; on the other hand, using |
| 227 |
\texttt{v} a csname is constructed first, and then the value is |
| 228 |
recovered, for example |\foo:v { l_my_|\meta{type} |}|. |
| 229 |
Can be applied to variables which have a \cs{\meta{type}_use:N} |
| 230 |
function (other than boxes and floating points). |
| 231 |
\item[\texttt{o}] This means \emph{expansion once}. In general, the |
| 232 |
\texttt{V} and \texttt{v} specifiers are favored over \texttt{o} |
| 233 |
for recovering stored information. However, \texttt{o} is useful |
| 234 |
for correctly processing information with delimited arguments. |
| 235 |
\item[\texttt{x}] The \texttt{x} specifier stands for \emph{exhaustive |
| 236 |
expansion}: every token in the argument is fully expanded until only |
| 237 |
unexpandable ones remain. The \TeX{} \tn{edef} primitive carries out |
| 238 |
this type of expansion. Functions which feature an \texttt{x}-type |
| 239 |
argument are \emph{not} expandable. |
| 240 |
\item[\texttt{e}] The \texttt{e} specifier is in many respects |
| 241 |
identical to \texttt{x}, but uses \tn{expanded} primitive. |
| 242 |
Parameter character (usually~|#|) in the argument need not be doubled. |
| 243 |
Functions which feature an \texttt{e}-type argument may be |
| 244 |
expandable. |
| 245 |
\item[\texttt{f}] The \texttt{f} specifier stands for \emph{full |
| 246 |
expansion}, and in contrast to \texttt{x} stops at the first |
| 247 |
non-expandable token (reading the argument from left to right) without |
| 248 |
trying to expand it. If this token is a \meta{space token}, it is gobbled, |
| 249 |
and thus won't be part of the resulting argument. For example, when |
| 250 |
setting a token list variable (a macro used for storage), the sequence |
| 251 |
\begin{verbatim} |
| 252 |
\tl_set:Nn \l_mya_tl { A } |
| 253 |
\tl_set:Nn \l_myb_tl { B } |
| 254 |
\tl_set:Nf \l_mya_tl { \l_mya_tl \l_myb_tl } |
| 255 |
\end{verbatim} |
| 256 |
will leave |\l_mya_tl| with the content |A\l_myb_tl|, as |A| cannot |
| 257 |
be expanded and so terminates expansion before |\l_myb_tl| is considered. |
| 258 |
\item[\texttt{T} and \texttt{F}] For logic tests, there are the branch |
| 259 |
specifiers \texttt{T} (\emph{true}) and \texttt{F} (\emph{false}). |
| 260 |
Both specifiers treat the input in the same way as \texttt{n} (no |
| 261 |
change), but make the logic much easier to see. |
| 262 |
\item[\texttt{p}] The letter \texttt{p} indicates \TeX{} |
| 263 |
\emph{parameters}. Normally this will be used for delimited |
| 264 |
functions as \pkg{expl3} provides better methods for creating simple |
| 265 |
sequential arguments. |
| 266 |
\item[\texttt{w}] Finally, there is the \texttt{w} specifier for |
| 267 |
\emph{weird} arguments. This covers everything else, but mainly |
| 268 |
applies to delimited values (where the argument must be terminated |
| 269 |
by some specified string). |
| 270 |
\item[\texttt{D}] The \texttt{D} stands for \textbf{Do not use}. |
| 271 |
All of the \TeX{} primitives are initially \cs[no-index]{let} to a \texttt{D} |
| 272 |
name, and some are then given a second name. |
| 273 |
These functions have no standardized syntax, they are engine |
| 274 |
dependent and their name can change without warning, thus their |
| 275 |
use is \emph{strongly discouraged} in package code: programmers |
| 276 |
should instead use the interfaces documented in |
| 277 |
\ifinterface |
| 278 |
this documentation. |
| 279 |
\else |
| 280 |
\href{interface3.pdf}{interface3.pdf}. |
| 281 |
\fi |
| 282 |
\end{description} |
| 283 |
Notice that the argument specifier describes how the argument is |
| 284 |
processed prior to being passed to the underlying function. For example, |
| 285 |
|\foo:c| will take its argument, convert it to a control sequence and |
| 286 |
pass it to |\foo:N|. |
| 287 |
|
| 288 |
Variables are named in a similar manner to functions, but begin with |
| 289 |
a single letter to define the type of variable: |
| 290 |
\begin{description}[leftmargin=2\parindent, labelindent*=-\parindent] |
| 291 |
\item[\texttt{c}] Constant: global parameters whose value should not |
| 292 |
be changed. |
| 293 |
\item[\texttt{g}] Parameters whose value should only be set globally. |
| 294 |
\item[\texttt{l}] Parameters whose value should only be set locally. |
| 295 |
\end{description} |
| 296 |
Each variable name is then build up in a similar way to that of a |
| 297 |
function, typically starting with the module\footnote{The module names are |
| 298 |
not used in case of generic scratch registers defined in the data |
| 299 |
type modules, e.g., the |
| 300 |
\texttt{int} module contains some scratch variables called \cs{l_tmpa_int}, |
| 301 |
\cs{l_tmpb_int}, and so on. In such a case adding the module name up front |
| 302 |
to denote the module |
| 303 |
and in the back to indicate the type, as in |
| 304 |
\texttt{\string\l_int_tmpa_int} would be very unreadable.} name |
| 305 |
and then a descriptive part. |
| 306 |
Variables end with a short identifier to show the variable type: |
| 307 |
\begin{description}[leftmargin=2\parindent, labelindent*=-\parindent] |
| 308 |
\item[\texttt{bitset}] a set of bits (a string made up of a series of \texttt{0} |
| 309 |
and \texttt{1} tokens that are accessed by position). |
| 310 |
\item[\texttt{clist}] Comma separated list. |
| 311 |
\item[\texttt{dim}] \enquote{Rigid} lengths. |
| 312 |
\item[\texttt{fp}] Floating-point values; |
| 313 |
\item[\texttt{int}] Integer-valued count register. |
| 314 |
\item[\texttt{muskip}] \enquote{Rubber} lengths for use in |
| 315 |
mathematics. |
| 316 |
\item[\texttt{skip}] \enquote{Rubber} lengths. |
| 317 |
\item[\texttt{str}] String variables: contain character data. |
| 318 |
\item[\texttt{tl}] Token list variables: placeholder for a token list. |
| 319 |
\end{description} |
| 320 |
Applying \texttt{V}-type or \texttt{v}-type expansion to variables of |
| 321 |
one of the above types is supported, while it is not supported for the |
| 322 |
following variable types: |
| 323 |
\begin{description}[leftmargin=2\parindent, labelindent*=-\parindent] |
| 324 |
\item[\texttt{bool}] Either true or false. |
| 325 |
\item[\texttt{box}] Box register. |
| 326 |
\item[\texttt{coffin}] A \enquote{box with handles} --- a higher-level |
| 327 |
data type for carrying out \texttt{box} alignment operations. |
| 328 |
\item[\texttt{flag}] Non-negative integer that can be incremented expandably. |
| 329 |
\item[\texttt{fparray}] Fixed-size array of floating point values. |
| 330 |
\item[\texttt{intarray}] Fixed-size array of integers. |
| 331 |
\item[\texttt{ior}/\texttt{iow}] An input or output stream, for |
| 332 |
reading from or writing to, respectively. |
| 333 |
\item[\texttt{prop}] Property list: analogue of dictionary or |
| 334 |
associative arrays in other languages. |
| 335 |
\item[\texttt{regex}] Regular expression. |
| 336 |
\item[\texttt{seq}] \enquote{Sequence}: a data type used to implement |
| 337 |
lists (with access at both ends) and stacks. |
| 338 |
\end{description} |
| 339 |
|
| 340 |
\subsection{Behavior of \texttt{c}-type arguments when the \texttt{N}-type token |
| 341 |
resulting from expansion is undefined} |
| 342 |
|
| 343 |
When \texttt{c}-type expansion is applied, it will produce an \texttt{N}-type |
| 344 |
token to be consumed by the underlying function. If the result of this process |
| 345 |
is a token which is undefined, \TeX{}'s behavior is to make it equal to |
| 346 |
|\scan_stop:| (|\relax|). |
| 347 |
|
| 348 |
This will likely lead to low-level errors if it occurs in contexts where |
| 349 |
\pkg{expl3} expects a \enquote{variable}, e.g.~a \texttt{prop}, \texttt{seq}, |
| 350 |
etc. Therefore, the programmer should ensure that \texttt{c}-type expansion is |
| 351 |
only applied when the resulting \texttt{N}-type token will definitely exist, |
| 352 |
i.e., when it is either defined prior to the application of the \texttt{c}-type |
| 353 |
expansion or will be by the underlying \texttt{N}-type function. |
| 354 |
|
| 355 |
\subsection{Scratch variables} |
| 356 |
|
| 357 |
Modules focussed on variable usage typically provide four scratch variables, |
| 358 |
two local and two global, with names of the form |
| 359 |
\cs[no-index]{\meta{scope}_tmpa_\meta{type}}/\cs[no-index]{\meta{scope}_tmpb_\meta{type}}. These |
| 360 |
are never used by the core code. The nature of \TeX{} grouping means that as |
| 361 |
with any other scratch variable, these should only be set and used with no |
| 362 |
intervening third-party code. |
| 363 |
|
| 364 |
There are two more special types of constants: |
| 365 |
\begin{description}[leftmargin=2\parindent, labelindent*=-\parindent] |
| 366 |
\item[\texttt{q}] Quark constants. |
| 367 |
\item[\texttt{s}] Scan mark constants. |
| 368 |
\end{description} |
| 369 |
Similarly, each quark or scan mark name starts with the module name, |
| 370 |
but doesn't end with a variable type, because the type is already |
| 371 |
marked by the prefix \texttt{q} or \texttt{s}. |
| 372 |
Some general quarks and scan marks provided by \LaTeX3 don't start |
| 373 |
with a module name, for example \cs{s_stop}. |
| 374 |
See documentation of quarks and scan marks in Chapter~\ref{sec:l3quarks} |
| 375 |
for more info. |
| 376 |
|
| 377 |
\subsection{Terminological inexactitude} |
| 378 |
|
| 379 |
A word of warning. In this document, and others referring to the \pkg{expl3} |
| 380 |
programming modules, we often refer to \enquote{variables} and |
| 381 |
\enquote{functions} as if they |
| 382 |
were actual constructs from a real programming language. In truth, \TeX{} |
| 383 |
is a macro processor, and functions are simply macros that may or may not take |
| 384 |
arguments and expand to their replacement text. Many of the common variables |
| 385 |
are \emph{also} macros, and if placed into the input stream will simply expand |
| 386 |
to their definition as well~--- a \enquote{function} with no arguments and a |
| 387 |
\enquote{token list variable} are almost the same.\footnote{\TeX{}nically, |
| 388 |
functions with no arguments are \tn{long} while token list variables are not.} |
| 389 |
On the other |
| 390 |
hand, some \enquote{variables} are actually registers that must be |
| 391 |
initialized and their values set and retrieved with specific functions. |
| 392 |
|
| 393 |
The conventions of the \pkg{expl3} code are designed to clearly separate the |
| 394 |
ideas of \enquote{macros that contain data} and |
| 395 |
\enquote{macros that contain code}, and a |
| 396 |
consistent wrapper is applied to all forms of \enquote{data} whether they be |
| 397 |
macros or |
| 398 |
actually registers. This means that sometimes we will use phrases like |
| 399 |
\enquote{the function returns a value}, when actually we just mean |
| 400 |
\enquote{the macro expands to something}. Similarly, the term |
| 401 |
\enquote{execute} might be used in place of \enquote{expand} |
| 402 |
or it might refer to the more specific case of |
| 403 |
\enquote{processing in \TeX's stomach} |
| 404 |
(if you are familiar with the \TeX{}book parlance). |
| 405 |
|
| 406 |
If in doubt, please ask; chances are we've been hasty in writing certain |
| 407 |
definitions and need to be told to tighten up our terminology. |
| 408 |
|
| 409 |
\section{Documentation conventions} |
| 410 |
|
| 411 |
This document is typeset with the experimental \pkg{l3doc} class; |
| 412 |
several conventions are used to help describe the features of the code. |
| 413 |
A number of conventions are used here to make the documentation clearer. |
| 414 |
|
| 415 |
Each group of related functions is given in a box. For a function with |
| 416 |
a \enquote{user} name, this might read: |
| 417 |
\begin{function}[label = ]{\ExplSyntaxOn, \ExplSyntaxOff} |
| 418 |
\begin{syntax} |
| 419 |
|\ExplSyntaxOn| \dots{} |\ExplSyntaxOff| |
| 420 |
\end{syntax} |
| 421 |
The textual description of how the function works would appear here. The |
| 422 |
syntax of the function is shown in mono-spaced text to the right of |
| 423 |
the box. In this example, the function takes no arguments and so the |
| 424 |
name of the function is simply reprinted. |
| 425 |
\end{function} |
| 426 |
|
| 427 |
For programming functions, which use \texttt{_} and \texttt{:} in their name |
| 428 |
there are a few additional conventions: If two related functions are given |
| 429 |
with identical names but different argument specifiers, these are termed |
| 430 |
\emph{variants} of each other, and the latter functions are printed in grey to |
| 431 |
show this more clearly. They will carry out the same function but will take |
| 432 |
different types of argument: |
| 433 |
\begin{function}[label = ]{\seq_new:N, \seq_new:c} |
| 434 |
\begin{syntax} |
| 435 |
|\seq_new:N| \meta{seq var} |
| 436 |
\end{syntax} |
| 437 |
When a number of variants are described, the arguments are usually |
| 438 |
illustrated only for the base function. Here, \meta{seq var} indicates |
| 439 |
that |\seq_new:N| expects a sequence variable. From the argument |
| 440 |
specifier, |\seq_new:c| also expects a sequence variable, but as a |
| 441 |
name rather than as a control sequence. Each argument given in the |
| 442 |
illustration should be described in the following text. |
| 443 |
\end{function} |
| 444 |
|
| 445 |
\paragraph{Fully expandable functions} |
| 446 |
\hypertarget{expstar}{Some functions are fully expandable}, |
| 447 |
which allows them to be used within |
| 448 |
an \texttt{x}-type or \texttt{e}-type argument (in plain \TeX{} terms, inside an \tn{edef} or \tn{expanded}), |
| 449 |
as well as within an \texttt{f}-type argument. |
| 450 |
These fully expandable functions are indicated in the documentation by |
| 451 |
a star: |
| 452 |
\begin{function}[EXP, label = ]{\cs_to_str:N} |
| 453 |
\begin{syntax} |
| 454 |
|\cs_to_str:N| \meta{cs} |
| 455 |
\end{syntax} |
| 456 |
As with other functions, some text should follow which explains how |
| 457 |
the function works. Usually, only the star will indicate that the |
| 458 |
function is expandable. In this case, the function expects a \meta{cs}, |
| 459 |
shorthand for a \meta{control sequence}. |
| 460 |
\end{function} |
| 461 |
|
| 462 |
\paragraph{Restricted expandable functions} |
| 463 |
\hypertarget{rexpstar}{A few functions are fully expandable} but cannot be fully expanded within |
| 464 |
an \texttt{f}-type argument. In this case a hollow star is used to indicate |
| 465 |
this: |
| 466 |
\begin{function}[rEXP, label = ]{\seq_map_function:NN} |
| 467 |
\begin{syntax} |
| 468 |
|\seq_map_function:NN| \meta{seq var} \meta{function} |
| 469 |
\end{syntax} |
| 470 |
\end{function} |
| 471 |
|
| 472 |
\paragraph{Conditional functions} |
| 473 |
\hypertarget{explTF}{Conditional (\texttt{if}) functions} |
| 474 |
are normally defined in three variants, with |
| 475 |
\texttt{T}, \texttt{F} and \texttt{TF} argument specifiers. This allows |
| 476 |
them to be used for different \enquote{true}/\enquote{false} branches, |
| 477 |
depending on |
| 478 |
which outcome the conditional is being used to test. To indicate this |
| 479 |
without repetition, this information is given in a shortened form: |
| 480 |
\begin{function}[EXP,TF, label = ]{\sys_if_engine_xetex:} |
| 481 |
\begin{syntax} |
| 482 |
|\sys_if_engine_xetex:TF| \Arg{true code} \Arg{false code} |
| 483 |
\end{syntax} |
| 484 |
The underlining and italic of \texttt{TF} indicates that three functions |
| 485 |
are available: |
| 486 |
\begin{itemize} |
| 487 |
\item |\sys_if_engine_xetex:T| |
| 488 |
\item |\sys_if_engine_xetex:F| |
| 489 |
\item |\sys_if_engine_xetex:TF| |
| 490 |
\end{itemize} |
| 491 |
Usually, the illustration |
| 492 |
will use the \texttt{TF} variant, and so both \meta{true code} |
| 493 |
and \meta{false code} will be shown. The two variant forms \texttt{T} and |
| 494 |
\texttt{F} take only \meta{true code} and \meta{false code}, respectively. |
| 495 |
Here, the star also shows that this function is expandable. |
| 496 |
With some minor exceptions, \emph{all} conditional functions in the |
| 497 |
\pkg{expl3} modules should be defined in this way. |
| 498 |
\end{function} |
| 499 |
|
| 500 |
Variables, constants and so on are described in a similar manner: |
| 501 |
\begin{variable}[label = ]{\l_tmpa_tl} |
| 502 |
A short piece of text will describe the variable: there is no |
| 503 |
syntax illustration in this case. |
| 504 |
\end{variable} |
| 505 |
|
| 506 |
In some cases, the function is similar to one in \LaTeXe{} or plain \TeX{}. |
| 507 |
In these cases, the text will include an extra \enquote{\textbf{\TeX{}hackers |
| 508 |
note}} section: |
| 509 |
\begin{function}[EXP, label = ]{\token_to_str:N} |
| 510 |
\begin{syntax} |
| 511 |
|\token_to_str:N| \meta{token} |
| 512 |
\end{syntax} |
| 513 |
The normal description text. |
| 514 |
\begin{texnote} |
| 515 |
Detail for the experienced \TeX{} or \LaTeXe\ programmer. In this |
| 516 |
case, it would point out that this function is the \TeX{} primitive |
| 517 |
|\string|. |
| 518 |
\end{texnote} |
| 519 |
\end{function} |
| 520 |
|
| 521 |
\paragraph{Addition dates} |
| 522 |
|
| 523 |
For functions added to \pkg{expl3} after 2020-02-02 (the point at which is was |
| 524 |
integrated into the \LaTeX{} kernel), the date of addition is included in the |
| 525 |
documentation as \enquote{New}. |
| 526 |
|
| 527 |
\paragraph{Changes to behavior} |
| 528 |
|
| 529 |
Where the documented behavior of a function |
| 530 |
changes after it is first introduced, the date of the update will also be |
| 531 |
given. This means that the programmer can be sure that any release of |
| 532 |
\pkg{expl3} after the date given will contain the function of interest with |
| 533 |
expected behavior as described. Note that changes to code internals, including |
| 534 |
bug fixes, are not recorded in this way \emph{unless} they impact on the |
| 535 |
expected behavior. |
| 536 |
|
| 537 |
\section{Formal language conventions which apply generally} |
| 538 |
|
| 539 |
As this is a formal reference guide for \LaTeX3 programming, the descriptions |
| 540 |
of functions are intended to be reasonably \enquote{complete}. However, there |
| 541 |
is also a need to avoid repetition. Formal ideas which apply to general |
| 542 |
classes of function are therefore summarized here. |
| 543 |
|
| 544 |
For tests which have a \texttt{TF} argument specification, the test if |
| 545 |
evaluated to give a logically \texttt{TRUE} or \texttt{FALSE} result. |
| 546 |
Depending on this result, either the \meta{true code} or the \meta{false code} |
| 547 |
will be left in the input stream. In the case where the test is expandable, |
| 548 |
and a predicate (|_p|) variant is available, the logical value determined by |
| 549 |
the test is left in the input stream: this will typically be part of a larger |
| 550 |
logical construct. |
| 551 |
|
| 552 |
\section{\TeX{} concepts not supported by \LaTeX3{}} |
| 553 |
|
| 554 |
The \TeX{} concept of an \enquote{\tn{outer}} macro is \emph{not supported} |
| 555 |
at all by \LaTeX3{}. As such, the functions provided here may break when |
| 556 |
used on top of \LaTeXe{} if \tn{outer} tokens are used in the arguments. |
| 557 |
|
| 558 |
\DisableImplementation |
| 559 |
|
| 560 |
\part{Bootstrapping} |
| 561 |
|
| 562 |
\DocInput{l3bootstrap.dtx} |
| 563 |
\DocInput{l3names.dtx} |
| 564 |
\ExplSyntaxOn |
| 565 |
\clist_gput_right:Nn \g_docinput_clist { l3kernel-functions.dtx } |
| 566 |
\ExplSyntaxOff |
| 567 |
|
| 568 |
\part{Programming Flow} |
| 569 |
|
| 570 |
\DocInput{l3basics.dtx} |
| 571 |
\DocInput{l3expan.dtx} |
| 572 |
\DocInput{l3sort.dtx} |
| 573 |
\DocInput{l3tl-analysis.dtx} |
| 574 |
\DocInput{l3regex.dtx} |
| 575 |
\DocInput{l3prg.dtx} |
| 576 |
\DocInput{l3sys.dtx} |
| 577 |
\DocInput{l3msg.dtx} |
| 578 |
\DocInput{l3file.dtx} |
| 579 |
|
| 580 |
\DocInput{l3luatex.dtx} |
| 581 |
|
| 582 |
\DocInput{l3legacy.dtx} |
| 583 |
|
| 584 |
|
| 585 |
\part{Data types} |
| 586 |
|
| 587 |
\DocInput{l3tl.dtx} |
| 588 |
\DocInput{l3tl-build.dtx} |
| 589 |
\DocInput{l3str.dtx} |
| 590 |
\DocInput{l3str-convert.dtx} |
| 591 |
\DocInput{l3str-format.dtx} |
| 592 |
\DocInput{l3quark.dtx} |
| 593 |
\DocInput{l3seq.dtx} |
| 594 |
\DocInput{l3int.dtx} |
| 595 |
\DocInput{l3flag.dtx} |
| 596 |
\DocInput{l3clist.dtx} |
| 597 |
\DocInput{l3token.dtx} |
| 598 |
\DocInput{l3prop.dtx} |
| 599 |
\DocInput{l3skip.dtx} |
| 600 |
\DocInput{l3keys.dtx} |
| 601 |
\DocInput{l3intarray.dtx} |
| 602 |
\DocInput{l3fp.dtx} |
| 603 |
% To get the various submodules of l3fp to appear in the implementation |
| 604 |
% part only, they have to be added to the documentation list after typesetting |
| 605 |
% the 'user' part just for the main module. |
| 606 |
\ExplSyntaxOn |
| 607 |
\clist_gput_right:Nn \g_docinput_clist |
| 608 |
{ |
| 609 |
l3fp-aux.dtx , |
| 610 |
l3fp-traps.dtx , |
| 611 |
l3fp-round.dtx , |
| 612 |
l3fp-parse.dtx , |
| 613 |
l3fp-assign.dtx , |
| 614 |
l3fp-logic.dtx , |
| 615 |
l3fp-basics.dtx , |
| 616 |
l3fp-extended.dtx , |
| 617 |
l3fp-expo.dtx , |
| 618 |
l3fp-trig.dtx , |
| 619 |
l3fp-convert.dtx , |
| 620 |
l3fp-random.dtx , |
| 621 |
l3fp-types.dtx , |
| 622 |
l3fp-symbolic.dtx , |
| 623 |
l3fp-functions.dtx |
| 624 |
} |
| 625 |
\ExplSyntaxOff |
| 626 |
|
| 627 |
\DocInput{l3fparray.dtx} |
| 628 |
\DocInput{l3bitset.dtx} |
| 629 |
\DocInput{l3cctab.dtx} |
| 630 |
|
| 631 |
\part{Text manipulation} |
| 632 |
|
| 633 |
\DocInput{l3unicode.dtx} |
| 634 |
\DocInput{l3text.dtx} |
| 635 |
\ExplSyntaxOn |
| 636 |
\clist_gput_right:Nn \g_docinput_clist |
| 637 |
{ |
| 638 |
l3text-case.dtx , |
| 639 |
l3text-map.dtx , |
| 640 |
l3text-purify.dtx , |
| 641 |
l3text-utils.dtx |
| 642 |
} |
| 643 |
\ExplSyntaxOff |
| 644 |
|
| 645 |
\part{Typesetting} |
| 646 |
|
| 647 |
\DocInput{l3box.dtx} |
| 648 |
\DocInput{l3coffins.dtx} |
| 649 |
\DocInput{l3color.dtx} |
| 650 |
\DocInput{l3graphics.dtx} |
| 651 |
\DocInput{l3opacity.dtx} |
| 652 |
\DocInput{l3pdf.dtx} |
| 653 |
|
| 654 |
\part{Utilities} |
| 655 |
|
| 656 |
\DocInput{l3benchmark.dtx} |
| 657 |
|
| 658 |
% implementation part only |
| 659 |
\ExplSyntaxOn |
| 660 |
\clist_gput_right:Nn \g_docinput_clist { l3deprecation.dtx } |
| 661 |
\clist_gput_right:Nn \g_docinput_clist { l3debug.dtx } |
| 662 |
\ExplSyntaxOff |
| 663 |
|
| 664 |
\endinput |