Debian Codegraph @

texmf-dist/doc/latex/l3kernel/source3body.tex

raw
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