The L A TEX3 Interfaces
The L
ATEX Project
∗Released 2022-10-26
Abstract
This is the reference documentation for theexpl3programming environment. The expl3modules set up an experimental naming scheme for LATEX commands, which allow the LATEX programmer to systematically name functions and variables, and specify the argument types of functions.
The TEX and ε-TEX primitives are all given a new name according to these con- ventions. However, in the main direct use of the primitives is not required or en- couraged: theexpl3modules define an independent low-level LATEX3 programming language.
The expl3modules are designed to be loaded on top of LATEX 2ε. With an up-to- date LATEX 2εkernel, this material is loaded as part of the format. The fundamental programming code can also be loaded with other TEX formats, subject to restrictions on the full range of functionality.
∗E-mail: [email protected]
Contents
I Introduction 1
1 Introduction toexpl3and this document 2
1.1 Naming functions and variables . . . 2
1.1.1 Scratch variables . . . 5
1.1.2 Terminological inexactitude . . . 5
1.2 Documentation conventions . . . 5
1.3 Formal language conventions which apply generally . . . 7
1.4 TEX concepts not supported by LATEX3 . . . 7
II Bootstrapping 8
2 The l3bootstrappackage: Bootstrap code 9 2.1 Using the LATEX3 modules . . . 93 The l3names package: Namespace for primitives 11 3.1 Setting up the LATEX3 programming language . . . 11
III Programming Flow 12
4 The l3basicspackage: Basic definitions 13 4.1 No operation functions . . . 134.2 Grouping material. . . 13
4.3 Control sequences and functions . . . 14
4.3.1 Defining functions . . . 14
4.3.2 Defining new functions using parameter text . . . 15
4.3.3 Defining new functions using the signature . . . 17
4.3.4 Copying control sequences . . . 19
4.3.5 Deleting control sequences. . . 20
4.3.6 Showing control sequences . . . 20
4.3.7 Converting to and from control sequences . . . 20
4.4 Analysing control sequences . . . 22
5 The l3expanpackage: Argument expansion 30
5.1 Defining new variants . . . 30
5.2 Methods for defining variants . . . 31
5.3 Introducing the variants . . . 32
5.4 Manipulating the first argument . . . 34
5.5 Manipulating two arguments . . . 36
5.6 Manipulating three arguments . . . 36
5.7 Unbraced expansion. . . 37
5.8 Preventing expansion . . . 38
5.9 Controlled expansion . . . 39
5.10 Internal functions . . . 42
6 The l3sortpackage: Sorting functions 43 6.1 Controlling sorting . . . 43
7 The l3tl-analysis package: Analysing token lists 45 8 The l3regexpackage: Regular expressions in TEX 46 8.1 Syntax of regular expressions. . . 47
8.1.1 Regular expression examples . . . 47
8.1.2 Characters in regular expressions . . . 48
8.1.3 Characters classes . . . 48
8.1.4 Structure: alternatives, groups, repetitions . . . 49
8.1.5 Matching exact tokens . . . 50
8.1.6 Miscellaneous . . . 52
8.2 Syntax of the replacement text. . . 52
8.3 Pre-compiling regular expressions . . . 54
8.4 Matching . . . 55
8.5 Submatch extraction . . . 56
8.6 Replacement . . . 57
8.7 Scratch regular expressions . . . 59
8.8 Bugs, misfeatures, future work, and other possibilities. . . 59
9 The l3prgpackage: Control structures 62 9.1 Defining a set of conditional functions. . . 62
9.2 The boolean data type . . . 64
9.2.1 Scratch booleans . . . 66
9.3 Boolean expressions . . . 66
9.4 Logical loops . . . 68
9.5 Producing multiple copies . . . 69
9.6 Detecting TEX’s mode . . . 70
9.7 Primitive conditionals. . . 70
9.8 Nestable recursions and mappings . . . 70
9.8.1 Simple mappings . . . 71
9.9 Internal programming functions . . . 71
10 The l3syspackage: System/runtime functions 72
10.1 The name of the job . . . 72
10.2 Date and time . . . 72
10.3 Engine . . . 73
10.4 Output format. . . 73
10.5 Platform . . . 74
10.6 Random numbers . . . 74
10.7 Access to the shell. . . 74
10.8 Loading configuration data . . . 75
10.8.1 Final settings . . . 76
11 The l3msgpackage: Messages 77 11.1 Creating new messages . . . 77
11.2 Customizable information for message modules . . . 78
11.3 Contextual information for messages . . . 78
11.4 Issuing messages. . . 80
11.4.1 Messages for showing material . . . 83
11.4.2 Expandable error messages . . . 83
11.5 Redirecting messages . . . 83
12 The l3file package: File and I/O operations 85 12.1 Input–output stream management. . . 85
12.1.1 Reading from files . . . 87
12.1.2 Writing to files . . . 90
12.1.3 Wrapping lines in output . . . 92
12.1.4 Constant input–output streams, and variables. . . 93
12.1.5 Primitive conditionals . . . 93
12.2 File operation functions. . . 93
13 The l3luatex package: LuaTEX-specific functions 98 13.1 Breaking out to Lua. . . 98
13.2 Lua interfaces . . . 99 14 The l3legacy package: Interfaces to legacy concepts 101
IV Data types 102
15.5.3 Items and ranges in token lists . . . 115
15.5.4 Sorting token lists . . . 117
15.6 Manipulating tokens in token lists . . . 117
15.6.1 Replacing tokens . . . 117
15.6.2 Reassigning category codes . . . 118
15.7 Constant token lists. . . 119
15.8 Scratch token lists. . . 119
16 The l3strpackage: Strings 121 16.1 Creating and initialising string variables . . . 122
16.2 Adding data to string variables . . . 123
16.3 String conditionals . . . 123
16.4 Mapping over strings . . . 125
16.5 Working with the content of strings . . . 127
16.6 Modifying string variables . . . 130
16.7 String manipulation. . . 131
16.8 Viewing strings . . . 132
16.9 Constant strings. . . 133
16.10 Scratch strings. . . 133
17 The l3str-convertpackage: string encoding conversions 134 17.1 Encoding and escaping schemes . . . 134
17.2 Conversion functions . . . 136
17.3 Conversion by expansion (for PDF contexts) . . . 136
17.4 Possibilities, and things to do . . . 136
18 The l3quarkpackage: Quarks 138 18.1 Quarks . . . 138
18.2 Defining quarks . . . 139
18.3 Quark tests . . . 139
18.4 Recursion . . . 140
18.4.1 An example of recursion with quarks . . . 141
18.5 Scan marks . . . 142
19 The l3seq package: Sequences and stacks 143 19.1 Creating and initialising sequences . . . 143
19.2 Appending data to sequences . . . 145
19.3 Recovering items from sequences. . . 145
19.4 Recovering values from sequences with branching . . . 146
19.5 Modifying sequences . . . 148
19.6 Sequence conditionals . . . 148
19.7 Mapping over sequences . . . 149
19.8 Using the content of sequences directly . . . 151
19.9 Sequences as stacks . . . 152
19.10 Sequences as sets . . . 153
19.11 Constant and scratch sequences . . . 154
19.12 Viewing sequences. . . 155
20 The l3int package: Integers 156
20.1 Integer expressions . . . 156
20.2 Creating and initialising integers. . . 158
20.3 Setting and incrementing integers . . . 159
20.4 Using integers . . . 159
20.5 Integer expression conditionals. . . 160
20.6 Integer expression loops. . . 161
20.7 Integer step functions . . . 163
20.8 Formatting integers . . . 164
20.9 Converting from other formats to integers . . . 165
20.10 Random integers . . . 166
20.11 Viewing integers. . . 167
20.12 Constant integers . . . 167
20.13 Scratch integers . . . 167
20.14 Direct number expansion . . . 168
20.15 Primitive conditionals. . . 168
21 The l3flagpackage: Expandable flags 170 21.1 Setting up flags . . . 170
21.2 Expandable flag commands. . . 171
22 The l3clist package: Comma separated lists 172 22.1 Creating and initialising comma lists . . . 173
22.2 Adding data to comma lists . . . 174
22.3 Modifying comma lists . . . 175
22.4 Comma list conditionals . . . 176
22.5 Mapping over comma lists . . . 176
22.6 Using the content of comma lists directly . . . 178
22.7 Comma lists as stacks. . . 179
22.8 Using a single item . . . 180
22.9 Viewing comma lists . . . 181
22.10 Constant and scratch comma lists . . . 181
23 The l3tokenpackage: Token manipulation 182 23.1 Creating character tokens . . . 183
23.2 Manipulating and interrogating character tokens. . . 184
23.3 Generic tokens . . . 187
24 The l3proppackage: Property lists 199
24.1 Creating and initialising property lists . . . 199
24.2 Adding and updating property list entries . . . 200
24.3 Recovering values from property lists . . . 201
24.4 Modifying property lists . . . 202
24.5 Property list conditionals. . . 202
24.6 Recovering values from property lists with branching . . . 203
24.7 Mapping over property lists . . . 204
24.8 Viewing property lists. . . 205
24.9 Scratch property lists . . . 206
24.10 Constants . . . 206
25 The l3skip package: Dimensions and skips 207 25.1 Creating and initialisingdimvariables. . . 207
25.2 Settingdimvariables . . . 208
25.3 Utilities for dimension calculations . . . 208
25.4 Dimension expression conditionals. . . 209
25.5 Dimension expression loops. . . 211
25.6 Dimension step functions . . . 212
25.7 Usingdimexpressions and variables . . . 213
25.8 Viewingdimvariables. . . 214
25.9 Constant dimensions . . . 215
25.10 Scratch dimensions . . . 215
25.11 Creating and initialisingskip variables . . . 215
25.12 Settingskipvariables . . . 216
25.13 Skip expression conditionals . . . 217
25.14 Usingskipexpressions and variables . . . 217
25.15 Viewingskip variables . . . 217
25.16 Constant skips . . . 218
25.17 Scratch skips. . . 218
25.18 Inserting skips into the output . . . 218
25.19 Creating and initialisingmuskipvariables . . . 219
25.20 Settingmuskipvariables . . . 219
25.21 Usingmuskipexpressions and variables . . . 220
25.22 Viewingmuskipvariables. . . 220
25.23 Constant muskips . . . 221
25.24 Scratch muskips . . . 221
25.25 Primitive conditional . . . 221
26 The l3keyspackage: Key–value interfaces 222 26.1 Creating keys . . . 223
26.2 Sub-dividing keys . . . 228
26.3 Choice and multiple choice keys . . . 228
26.4 Key usage scope . . . 231
26.5 Setting keys . . . 231
26.6 Handling of unknown keys . . . 232
26.7 Selective key setting. . . 232
26.8 Digesting keys . . . 233
26.9 Utility functions for keys . . . 234
26.10 Low-level interface for parsing key–val lists . . . 234
27 The l3intarraypackage: fast global integer arrays 237
27.1 l3intarray documentation . . . 237
27.1.1 Implementation notes . . . 238
28 The l3fp package: Floating points 239 28.1 Creating and initialising floating point variables . . . 241
28.2 Setting floating point variables. . . 241
28.3 Using floating points . . . 242
28.4 Floating point conditionals . . . 243
28.5 Floating point expression loops . . . 245
28.6 Some useful constants, and scratch variables . . . 247
28.7 Floating point exceptions. . . 248
28.8 Viewing floating points . . . 249
28.9 Floating point expressions . . . 250
28.9.1 Input of floating point numbers . . . 250
28.9.2 Precedence of operators . . . 251
28.9.3 Operations . . . 251
28.10 Disclaimer and roadmap . . . 258
29 The l3fparraypackage: fast global floating point arrays 261 29.1 l3fparraydocumentation. . . 261
30 The l3cctabpackage: Category code tables 262 30.1 Creating and initialising category code tables . . . 262
30.2 Using category code tables . . . 262
30.3 Category code table conditionals. . . 263
30.4 Constant category code tables . . . 263
V Text manipulation 264
31 The l3unicodepackage: Unicode support functions 265 32 The l3text package: text processing 266 32.1 Expanding text . . . 26632.2 Case changing . . . 267
32.3 Removing formatting from text . . . 269
33 The l3boxpackage: Boxes 272
33.1 Creating and initialising boxes . . . 272
33.2 Using boxes . . . 273
33.3 Measuring and setting box dimensions . . . 274
33.4 Box conditionals. . . 275
33.5 The last box inserted . . . 275
33.6 Constant boxes . . . 275
33.7 Scratch boxes . . . 275
33.8 Viewing box contents . . . 276
33.9 Boxes and color . . . 276
33.10 Horizontal mode boxes . . . 276
33.11 Vertical mode boxes. . . 277
33.12 Using boxes efficiently . . . 279
33.13 Affine transformations . . . 280
33.14 Primitive box conditionals . . . 283
34 The l3coffinspackage: Coffin code layer 284 34.1 Creating and initialising coffins . . . 284
34.2 Setting coffin content and poles . . . 285
34.3 Coffin affine transformations . . . 286
34.4 Joining and using coffins . . . 286
34.5 Measuring coffins . . . 287
34.6 Coffin diagnostics . . . 287
34.7 Constants and variables. . . 288
35 The l3colorpackage: Color support 290 35.1 Color in boxes . . . 290
35.2 Color models. . . 290
35.3 Color expressions . . . 292
35.4 Named colors . . . 293
35.5 Selecting colors . . . 293
35.6 Colors for fills and strokes . . . 294
35.6.1 Coloring math mode material . . . 294
35.7 Multiple color models . . . 294
35.8 Exporting color specifications . . . 295
35.9 Creating new color models . . . 296
35.9.1 Color profiles . . . 297
36 The l3pdf package: Core PDF support 298 36.1 Objects. . . 298
36.2 Version . . . 299
36.3 Compression . . . 300
36.4 Destinations . . . 300
36.5 Deprecated functions . . . 301
VII Additions and removals 302
37 The l3candidatespackage: Experimental additions to l3kernel 303
37.1 Important notice . . . 303
37.2 Additions tol3box . . . 304
37.3 Additions tol3expan . . . 304
37.4 Additions tol3fp. . . 304
37.5 Additions tol3file . . . 305
37.6 Additions tol3flag. . . 305
37.7 Additions tol3intarray . . . 305
37.8 Additions tol3msg . . . 306
37.9 Additions tol3prg . . . 306
37.10 Additions tol3prop . . . 307
37.11 Additions tol3seq . . . 308
37.12 Additions tol3sys . . . 309
37.13 Additions tol3tl . . . 310
37.14 Additions tol3token. . . 311
Index 313
Part I
Introduction
Chapter 1
Introduction to expl3 and this document
This document is intended to act as a comprehensive reference manual for the expl3 language. A general guide to the LATEX3 programming language is found inexpl3.pdf.
1.1 Naming functions and variables
LATEX3 does not use@as a “letter” for defining internal macros. Instead, the symbols _ and: are used in internal macro names to provide structure. The name of eachfunction is divided into logical units using_, while: separates thenameof the function from the argument specifier (“arg-spec”). This describes the arguments expected by the function.
In most cases, each argument is represented by a single letter. The complete list of arg-spec letters for a function is referred to as thesignature of the function.
Each function name starts with themodule to which it belongs. Thus apart from a small number of very basic functions, allexpl3function names contain at least one under- score to divide the module name from the descriptive name of the function. For example, all functions concerned with comma lists are in module clistand begin\clist_.
Every function must include an argument specifier. For functions which take no arguments, this will be blank and the function name will end:. Most functions take one or more arguments, and use the following argument specifiers:
\foo:V \MyVariable; on the other hand, usingva csname is constructed first, and then the value is recovered, for example\foo:v {MyVariable}.
o This means expansion once. In general, the V and v specifiers are favoured over o for recovering stored information. However, o is useful for correctly processing information with delimited arguments.
x The xspecifier stands forexhaustive expansion: every token in the argument is fully expanded until only unexpandable ones remain. The TEX \edef primitive carries out this type of expansion. Functions which feature an x-type argument arenot expandable.
e The e specifier is in many respects identical to x, but with a very different imple- mentation. Functions which feature an e-type argument may be expandable. The drawback is that eis extremely slow (often more than 200 times slower) in older engines, more precisely in non-LuaTEX engines older than 2019.
f The fspecifier stands for full expansion, and in contrast to xstops at the first non- expandable token (reading the argument from left to right) without trying to expand it. If this token is a ⟨space token⟩, it is gobbled, and thus won’t be part of the resulting argument. For example, when setting a token list variable (a macro used for storage), the sequence
\tl_set:Nn \l_mya_tl { A }
\tl_set:Nn \l_myb_tl { B }
\tl_set:Nf \l_mya_tl { \l_mya_tl \l_myb_tl }
will leave\l_mya_tl with the contentA\l_myb_tl, as Acannot be expanded and so terminates expansion before\l_myb_tlis considered.
T and F For logic tests, there are the branch specifiers T (true) and F (false). Both specifiers treat the input in the same way as n (no change), but make the logic much easier to see.
p The letterpindicates TEXparameters. Normally this will be used for delimited func- tions asexpl3 provides better methods for creating simple sequential arguments.
w Finally, there is the w specifier forweird arguments. This covers everything else, but mainly applies to delimited values (where the argument must be terminated by some specified string).
D TheDstands forDo not use. All of the TEX primitives are initially\letto aDname, and some are then given a second name. These functions have no standardized syntax, they are engine dependent and their name can change without warning, thus their use isstrongly discouragedin package code: programmers should instead use the interfaces documented in interface3.pdf1.
Notice that the argument specifier describes how the argument is processed prior to being passed to the underlying function. For example,\foo:cwill take its argument, convert it to a control sequence and pass it to\foo:N.
1If a primitive offers a functionality not yet in the kernel, programmers and users are encouraged to write to the LaTeX-L mailing list (mailto:[email protected]) describing their use-case and intended behaviour, so that a possible interface can be discussed. Temporarily, while an interface is not provided, programmers may use the procedure described in thel3styleguide.pdf.
Variables are named in a similar manner to functions, but begin with a single letter to define the type of variable:
c Constant: global parameters whose value should not be changed.
g Parameters whose value should only be set globally.
l Parameters whose value should only be set locally.
Each variable name is then build up in a similar way to that of a function, typically starting with the module2 name and then a descriptive part. Variables end with a short identifier to show the variable type:
clist Comma separated list.
dim “Rigid” lengths.
fp Floating-point values;
int Integer-valued count register.
muskip “Rubber” lengths for use in mathematics.
seq “Sequence”: a data-type used to implement lists (with access at both ends) and stacks.
skip “Rubber” lengths.
str String variables: contain character data.
tl Token list variables: placeholder for a token list.
ApplyingV-type orv-type expansion to variables of one of the above types is supported, while it is not supported for the following variable types:
bool Either true or false.
box Box register.
coffin A “box with handles” — a higher-level data type for carrying outboxalignment operations.
1.1.1 Scratch variables
Modules focussed on variable usage typically provide four scratch variables, two local and two global, with names of the form\⟨scope⟩_tmpa_⟨type⟩/\⟨scope⟩_tmpb_⟨type⟩. These are never used by the core code. The nature of TEX grouping means that as with any other scratch variable, these should only be set and used with no intervening third-party code.
1.1.2 Terminological inexactitude
A word of warning. In this document, and others referring to the expl3 programming modules, we often refer to “variables” and “functions” as if they were actual constructs from a real programming language. In truth, TEX is a macro processor, and functions are simply macros that may or may not take arguments and expand to their replacement text. Many of the common variables arealsomacros, and if placed into the input stream will simply expand to their definition as well — a “function” with no arguments and a “token list variable” are almost the same.3 On the other hand, some “variables” are actually registers that must be initialised and their values set and retrieved with specific functions.
The conventions of the expl3 code are designed to clearly separate the ideas of
“macros that contain data” and “macros that contain code”, and a consistent wrapper is applied to all forms of “data” whether they be macros or actually registers. This means that sometimes we will use phrases like “the function returns a value”, when actually we just mean “the macro expands to something”. Similarly, the term “execute” might be used in place of “expand” or it might refer to the more specific case of “processing in TEX’s stomach” (if you are familiar with the TEXbook parlance).
If in doubt, please ask; chances are we’ve been hasty in writing certain definitions and need to be told to tighten up our terminology.
1.2 Documentation conventions
This document is typeset with the experimentall3docclass; several conventions are used to help describe the features of the code. A number of conventions are used here to make the documentation clearer.
Each group of related functions is given in a box. For a function with a “user” name, this might read:
\ExplSyntaxOn ... \ExplSyntaxOff
The textual description of how the function works would appear here. The syntax of the function is shown in mono-spaced text to the right of the box. In this example, the function takes no arguments and so the name of the function is simply reprinted.
\ExplSyntaxOn
\ExplSyntaxOff
For programming functions, which use_ and: in their name there are a few addi- tional conventions: If two related functions are given with identical names but different argument specifiers, these are termedvariantsof each other, and the latter functions are printed in grey to show this more clearly. They will carry out the same function but will take different types of argument:
3TEXnically, functions with no arguments are\longwhile token list variables are not.
\seq_new:N ⟨sequence⟩
When a number of variants are described, the arguments are usually illustrated only for the base function. Here, ⟨sequence⟩ indicates that \seq_new:N expects the name of a sequence. From the argument specifier, \seq_new:c also expects a sequence name, but as a name rather than as a control sequence. Each argument given in the illustration should be described in the following text.
\seq_new:N
\seq_new:c
Fully expandable functions Some functions are fully expandable, which allows them to be used within anx-type ore-type argument (in plain TEX terms, inside an\edefor
\expanded), as well as within anf-type argument. These fully expandable functions are indicated in the documentation by a star:
\cs_to_str:N ⟨cs⟩
As with other functions, some text should follow which explains how the function works.
Usually, only the star will indicate that the function is expandable. In this case, the function expects a⟨cs⟩, shorthand for a ⟨control sequence⟩.
\cs_to_str:N ⋆
Restricted expandable functions A few functions are fully expandable but cannot be fully expanded within anf-type argument. In this case a hollow star is used to indicate this:
\seq_map_function:NN ⟨seq⟩ ⟨function⟩
\seq_map_function:NN ✩
Conditional functions Conditional (if) functions are normally defined in three vari- ants, with T, F and TF argument specifiers. This allows them to be used for different
“true”/“false” branches, depending on which outcome the conditional is being used to test. To indicate this without repetition, this information is given in a shortened form:
\sys_if_engine_xetex:TF {⟨true code⟩} {⟨false code⟩}
The underlining and italic of TFindicates that three functions are available:
• \sys_if_engine_xetex:T
• \sys_if_engine_xetex:F
\sys_if_engine_xetex:TF ⋆
\token_to_str:N ⟨token⟩ The normal description text.
TEXhackers note: Detail for the experienced TEX or LATEX 2εprogrammer. In this case, it would point out that this function is the TEX primitive\string.
\token_to_str:N ⋆
Changes to behaviour When new functions are added to expl3, the date of first inclusion is given in the documentation. Where the documented behaviour of a function changes after it is first introduced, the date of the update will also be given. This means that the programmer can be sure that any release ofexpl3after the date given will contain the function of interest with expected behaviour as described. Note that changes to code internals, including bug fixes, are not recorded in this way unless they impact on the expected behaviour.
1.3 Formal language conventions which apply gener- ally
As this is a formal reference guide for LATEX3 programming, the descriptions of functions are intended to be reasonably “complete”. However, there is also a need to avoid repeti- tion. Formal ideas which apply to general classes of function are therefore summarised here.
For tests which have a TF argument specification, the test if evaluated to give a logically TRUE or FALSE result. Depending on this result, either the⟨true code⟩or the
⟨false code⟩ will be left in the input stream. In the case where the test is expandable, and a predicate (_p) variant is available, the logical value determined by the test is left in the input stream: this will typically be part of a larger logical construct.
1.4 TEX concepts not supported by L
ATEX3
The TEX concept of an “\outer” macro isnot supported at all by LATEX3. As such, the functions provided here may break when used on top of LATEX2ε if \outer tokens are used in the arguments.
Part II
Bootstrapping
Chapter 2
The l3bootstrap package Bootstrap code
2.1 Using the L
ATEX3 modules
The modules documented in source3 are designed to be used on top of LATEX2ε and are loaded all as one with the usual\usepackage{expl3}or \RequirePackage{expl3}
instructions.
As the modules use a coding syntax different from standard LATEX2ε it provides a few functions for setting it up.
\ExplSyntaxOn ⟨code⟩ \ExplSyntaxOff
The \ExplSyntaxOn function switches to a category code regime in which spaces and new lines are ignored, and in which the colon (:) and underscore (_) are treated as
“letters”, thus allowing access to the names of code functions and variables. Within this environment, ~is used to input a space. The\ExplSyntaxOff reverts to the document category code regime.
TEXhackers note:Spaces introduced by~behave much in the same way as normal space characters in the standard category code regime: they are ignored after a control word or at the start of a line, and multiple consecutive~are equivalent to a single one. However,~isnot ignored at the end of a line.
\ExplSyntaxOn
\ExplSyntaxOff
Updated: 2011-08-13
\RequirePackage{expl3}
\ProvidesExplPackage {⟨package⟩} {⟨date⟩} {⟨version⟩} {⟨description⟩}
These functions act broadly in the same way as the corresponding LATEX2ε kernel func- tions\ProvidesPackage,\ProvidesClassand\ProvidesFile. However, they also im- plicitly switch \ExplSyntaxOn for the remainder of the code with the file. At the end of the file, \ExplSyntaxOffwill be called to reverse this. (This is the same concept as LATEX2ε provides in turning on \makeatletter within package and class code.) The
⟨date⟩ should be given in the format ⟨year⟩/⟨month⟩/⟨day⟩ or in the ISO date format
⟨year⟩-⟨month⟩-⟨day⟩. If the ⟨version⟩ is given then it will be prefixed with v in the package identifier line.
\ProvidesExplPackage
\ProvidesExplClass
\ProvidesExplFile
Updated: 2017-03-19
\RequirePackage{l3bootstrap}
\GetIdInfo $Id: ⟨SVN info field⟩ $ {⟨description⟩}
Extracts all information from a SVN field. Spaces are not ignored in these fields. The in- formation pieces are stored in separate control sequences with\ExplFileNamefor the part of the file name leading up to the period, \ExplFileDatefor date, \ExplFileVersion for version and\ExplFileDescriptionfor the description.
\GetIdInfo
Updated: 2012-06-04
To summarize: Every single package using this syntax should identify itself using one of the above methods. Special care is taken so that every package or class file loaded with\RequirePackageor similar are loaded with usual LATEX2εcategory codes and the LATEX3 category code scheme is reloaded when needed afterwards. See implementation for details. If you use the \GetIdInfo command you can use the information when loading a package with
\ProvidesExplPackage{\ExplFileName}
{\ExplFileDate}{\ExplFileVersion}{\ExplFileDescription}
Chapter 3
The l3names package
Namespace for primitives
3.1 Setting up the L
ATEX3 programming language
This module is at the core of the LATEX3 programming language. It performs the following tasks:
• defines new names for all TEX primitives;
• emulate required primitives not provided by default in LuaTEX;
• switches to the category code régime for programming;
This module is entirely dedicated to primitives (and emulations of these), which should not be used directly within LATEX3 code (outside of “kernel-level” code). As such, the primitives are not documented here: The TEXbook, TEX by Topic and the manuals for pdfTEX, X E TEX, LuaTEX, pTEX and upTEX should be consulted for details of the primitives. These are named\tex_⟨name⟩:D, typically based on the primitive’s⟨name⟩
in pdfTEX and omitting a leadingpdfwhen the primitive is not related to pdf output.
Part III
Programming Flow
Chapter 4
The l3basics package Basic definitions
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.
4.1 No operation functions
\prg_do_nothing:
An expandable function which does nothing at all: leaves nothing in the input stream after a single expansion.
\prg_do_nothing: ⋆
\scan_stop:
A non-expandable function which does nothing. Does not vanish on expansion but pro- duces no typeset output.
\scan_stop:
4.2 Grouping material
\group_begin:
\group_end:
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\group_begin:must be matched by a \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.
\group_begin:
\group_end:
\group_insert_after:N ⟨token⟩
Adds⟨token⟩to the list of⟨tokens⟩to be inserted when the current group level ends. The list of⟨tokens⟩to be inserted is empty at the beginning of a group: multiple applications of\group_insert_after:Nmay be used to build the inserted list one⟨token⟩at a time.
The current group level may be closed by a \group_end: function or by a token with category code 2 (close-group), namely a }if standard category codes apply.
\group_insert_after:N
\group_show_list:
\group_log_list:
Display (to the terminal or log file) a list of the groups that are currently opened. This is intended for tracking down problems.
TEXhackers note: This is a wrapper around the\showgroupsprimitive.
\group_show_list:
\group_log_list:
New: 2021-05-11
4.3 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 (“code”) in which each parameter in the code (#1, #2, etc.) is replaced the appropriate arguments absorbed by the function.
In the following,⟨code⟩is therefore used as a shorthand for “replacement text”.
Functions which are not “protected” are fully expanded inside anx expansion. In contrast, “protected” functions are not expanded withinxexpansions.
4.3.1 Defining functions
Functions can be created with no requirement that they are declared first (in contrast to variables, which must always be declared). Declaring a function before setting up the code means that the name chosen is checked and an error raised if it is already in use.
The name of a function can be checked at the point of definition using the\cs_new...
functions: this is recommended for all functions which are defined for the first time.
There are three ways to define new functions. All classes define a function to ex- pand to the substitution text. Within the substitution text the actual parameters are substituted for the formal parameters (#1,#2, . . . ).
Create a new function with the scope, such as . The definition is
protected Create a new function with the protected restriction, such as \cs_set_- protected:Npn. The parameter may contain\partokens but the function will not expand within an x-type ore-type expansion.
Finally, the functions in Subsections 4.3.2and 4.3.3 are primarily meant to define base functionsonly. Base functions can only have the following argument specifiers:
N and n No manipulation.
T and F Functionally equivalent ton (you are actually encouraged to use the family of
\prg_new_conditional:functions described in Section9.1).
p and w These are special cases.
The\cs_new:functions below (and friends) do not stop you from using other argu- ment specifiers in your function names, but they do not handle expansion for you. You should define the base function and then use \cs_generate_variant:Nn to generate custom variants as described in Section5.2.
4.3.2 Defining new functions using parameter text
\cs_new:Npn ⟨function⟩ ⟨parameters⟩ {⟨code⟩}
Creates ⟨function⟩ to expand to ⟨code⟩ as replacement text. Within the ⟨code⟩, the
⟨parameters⟩ (#1, #2, etc.) will be replaced by those absorbed by the function. The definition is global and an error results if the⟨function⟩is already defined.
\cs_new:Npn
\cs_new:cpn
\cs_new:Npx
\cs_new:cpx
\cs_new_nopar:Npn ⟨function⟩ ⟨parameters⟩ {⟨code⟩}
Creates ⟨function⟩ to expand to ⟨code⟩ as replacement text. Within the ⟨code⟩, the
⟨parameters⟩(#1,#2,etc.) will be replaced by those absorbed by the function. When the
⟨function⟩is used the⟨parameters⟩absorbed cannot contain\partokens. The definition is global and an error results if the ⟨function⟩is already defined.
\cs_new_nopar:Npn
\cs_new_nopar:cpn
\cs_new_nopar:Npx
\cs_new_nopar:cpx
\cs_new_protected:Npn ⟨function⟩ ⟨parameters⟩ {⟨code⟩}
Creates ⟨function⟩ to expand to ⟨code⟩ as replacement text. Within the ⟨code⟩, the
⟨parameters⟩ (#1, #2, etc.) will be replaced by those absorbed by the function. The
⟨function⟩ will not expand within an x-type or or e-type argument. The definition is global and an error results if the ⟨function⟩is already defined.
\cs_new_protected:Npn
\cs_new_protected:cpn
\cs_new_protected:Npx
\cs_new_protected:cpx
\cs_new_protected_nopar:Npn ⟨function⟩ ⟨parameters⟩ {⟨code⟩}
\cs_new_protected_nopar:Npn
\cs_new_protected_nopar:cpn
\cs_new_protected_nopar:Npx
\cs_new_protected_nopar:cpx
Creates ⟨function⟩ to expand to ⟨code⟩ as replacement text. Within the ⟨code⟩, the
⟨parameters⟩(#1,#2,etc.) will be replaced by those absorbed by the function. When the
⟨function⟩is used the⟨parameters⟩absorbed cannot contain\partokens. The⟨function⟩ will not expand within an x-type or e-type argument. The definition is global and an error results if the⟨function⟩is already defined.
\cs_set:Npn ⟨function⟩ ⟨parameters⟩ {⟨code⟩}
Sets ⟨function⟩ to expand to ⟨code⟩ as replacement text. Within the ⟨code⟩, the
⟨parameters⟩ (#1, #2, etc.) will be replaced by those absorbed by the function. The assignment of a meaning to the⟨function⟩is restricted to the current TEX group level.
\cs_set:Npn
\cs_set:cpn
\cs_set:Npx
\cs_set:cpx
\cs_set_nopar:Npn ⟨function⟩ ⟨parameters⟩ {⟨code⟩}
Sets ⟨function⟩ to expand to ⟨code⟩ as replacement text. Within the ⟨code⟩, the
⟨parameters⟩(#1,#2,etc.) will be replaced by those absorbed by the function. When the
⟨function⟩is used the⟨parameters⟩absorbed cannot contain\partokens. The assignment of a meaning to the⟨function⟩is restricted to the current TEX group level.
\cs_set_nopar:Npn
\cs_set_nopar:cpn
\cs_set_nopar:Npx
\cs_set_nopar:cpx
\cs_set_protected:Npn ⟨function⟩ ⟨parameters⟩ {⟨code⟩}
Sets ⟨function⟩ to expand to ⟨code⟩ as replacement text. Within the ⟨code⟩, the
⟨parameters⟩ (#1, #2, etc.) will be replaced by those absorbed by the function. The assignment of a meaning to the ⟨function⟩is restricted to the current TEX group level.
The⟨function⟩will not expand within anx-type ore-type argument.
\cs_set_protected:Npn
\cs_set_protected:cpn
\cs_set_protected:Npx
\cs_set_protected:cpx
\cs_set_protected_nopar:Npn ⟨function⟩ ⟨parameters⟩ {⟨code⟩}
\cs_set_protected_nopar:Npn
\cs_set_protected_nopar:cpn
\cs_set_protected_nopar:Npx
\cs_set_protected_nopar:cpx
Sets ⟨function⟩ to expand to ⟨code⟩ as replacement text. Within the ⟨code⟩, the
⟨parameters⟩(#1, #2, etc.) will be replaced by those absorbed by the function. When the ⟨function⟩is used the ⟨parameters⟩ absorbed cannot contain \par tokens. The as- signment of a meaning to the⟨function⟩is restricted to the current TEX group level. The
⟨function⟩will not expand within anx-type ore-type argument.
\cs_gset:Npn ⟨function⟩ ⟨parameters⟩ {⟨code⟩}
Globally sets ⟨function⟩ to expand to ⟨code⟩ as replacement text. Within the ⟨code⟩, the⟨parameters⟩(#1,#2,etc.) will be replaced by those absorbed by the function. The assignment of a meaning to the ⟨function⟩ is not restricted to the current TEX group level: the assignment is global.
\cs_gset:Npn
\cs_gset:cpn
\cs_gset:Npx
\cs_gset:cpx
\cs_gset_protected_nopar:Npn ⟨function⟩ ⟨parameters⟩ {⟨code⟩}
\cs_gset_protected_nopar:Npn
\cs_gset_protected_nopar:cpn
\cs_gset_protected_nopar:Npx
\cs_gset_protected_nopar:cpx
Globally sets ⟨function⟩ to expand to ⟨code⟩ as replacement text. Within the ⟨code⟩, the ⟨parameters⟩ (#1, #2, etc.) will be replaced by those absorbed by the function.
When the⟨function⟩is used the⟨parameters⟩absorbed cannot contain\partokens. The assignment of a meaning to the ⟨function⟩ is not restricted to the current TEX group level: the assignment is global. The ⟨function⟩ will not expand within an x-type or e-type argument.
4.3.3 Defining new functions using the signature
\cs_new:Nn ⟨function⟩ {⟨code⟩}
Creates ⟨function⟩ to expand to ⟨code⟩ as replacement text. Within the ⟨code⟩, the number of ⟨parameters⟩ is detected automatically from the function signature. These
⟨parameters⟩ (#1, #2, etc.) will be replaced by those absorbed by the function. The definition is global and an error results if the⟨function⟩is already defined.
\cs_new:Nn
\cs_new:(cn|Nx|cx)
\cs_new_nopar:Nn ⟨function⟩ {⟨code⟩}
Creates ⟨function⟩ to expand to ⟨code⟩ as replacement text. Within the ⟨code⟩, the number of ⟨parameters⟩ is detected automatically from the function signature. These
⟨parameters⟩(#1,#2,etc.) will be replaced by those absorbed by the function. When the
⟨function⟩is used the⟨parameters⟩absorbed cannot contain\partokens. The definition is global and an error results if the ⟨function⟩is already defined.
\cs_new_nopar:Nn
\cs_new_nopar:(cn|Nx|cx)
\cs_new_protected:Nn ⟨function⟩ {⟨code⟩}
Creates ⟨function⟩ to expand to ⟨code⟩ as replacement text. Within the ⟨code⟩, the number of ⟨parameters⟩ is detected automatically from the function signature. These
⟨parameters⟩ (#1, #2, etc.) will be replaced by those absorbed by the function. The
⟨function⟩will not expand within anx-type ore-type argument. The definition is global and an error results if the ⟨function⟩is already defined.
\cs_new_protected:Nn
\cs_new_protected:(cn|Nx|cx)
\cs_new_protected_nopar:Nn ⟨function⟩ {⟨code⟩}
\cs_new_protected_nopar:Nn
\cs_new_protected_nopar:(cn|Nx|cx)
Creates ⟨function⟩ to expand to ⟨code⟩ as replacement text. Within the ⟨code⟩, the number of ⟨parameters⟩ is detected automatically from the function signature. These
⟨parameters⟩(#1,#2,etc.) will be replaced by those absorbed by the function. When the
⟨function⟩is used the⟨parameters⟩absorbed cannot contain\partokens. The⟨function⟩ will not expand within an x-type or e-type argument. The definition is global and an error results if the⟨function⟩is already defined.
\cs_set:Nn ⟨function⟩ {⟨code⟩}
Sets⟨function⟩to expand to⟨code⟩as replacement text. Within the⟨code⟩, the number of
⟨parameters⟩is detected automatically from the function signature. These⟨parameters⟩
(#1,#2, etc.) will be replaced by those absorbed by the function. The assignment of a meaning to the is restricted to the current TEX group level.
\cs_set:Nn
\cs_set:(cn|Nx|cx)
\cs_set_nopar:Nn ⟨function⟩ {⟨code⟩}
Sets⟨function⟩to expand to⟨code⟩as replacement text. Within the⟨code⟩, the number of
⟨parameters⟩is detected automatically from the function signature. These⟨parameters⟩
(#1,#2, etc.) will be replaced by those absorbed by the function. When the ⟨function⟩ is used the ⟨parameters⟩ absorbed cannot contain \par tokens. The assignment of a meaning to the⟨function⟩is restricted to the current TEX group level.
\cs_set_nopar:Nn
\cs_set_nopar:(cn|Nx|cx)
\cs_set_protected:Nn ⟨function⟩ {⟨code⟩}
Sets⟨function⟩to expand to⟨code⟩as replacement text. Within the⟨code⟩, the number of
⟨parameters⟩is detected automatically from the function signature. These⟨parameters⟩
(#1, #2, etc.) will be replaced by those absorbed by the function. The ⟨function⟩ will not expand within anx-type ore-type argument. The assignment of a meaning to the
⟨function⟩is restricted to the current TEX group level.
\cs_set_protected:Nn
\cs_set_protected:(cn|Nx|cx)
\cs_set_protected_nopar:Nn ⟨function⟩ {⟨code⟩}
\cs_set_protected_nopar:Nn
\cs_set_protected_nopar:(cn|Nx|cx)
Sets⟨function⟩to expand to⟨code⟩as replacement text. Within the⟨code⟩, the number of
⟨parameters⟩is detected automatically from the function signature. These⟨parameters⟩
(#1,#2, etc.) will be replaced by those absorbed by the function. When the ⟨function⟩ is used the⟨parameters⟩absorbed cannot contain \par tokens. The⟨function⟩will not expand within an x-type or e-type argument. The assignment of a meaning to the
⟨function⟩is restricted to the current TEX group level.
\cs_gset:Nn ⟨function⟩ {⟨code⟩}
Sets⟨function⟩to expand to⟨code⟩as replacement text. Within the⟨code⟩, the number of
⟨parameters⟩is detected automatically from the function signature. These⟨parameters⟩
(#1,#2, etc.) will be replaced by those absorbed by the function. The assignment of a meaning to the⟨function⟩is global.
\cs_gset:Nn
\cs_gset:(cn|Nx|cx)
\cs_gset_nopar:Nn ⟨function⟩ {⟨code⟩}
Sets⟨function⟩to expand to⟨code⟩as replacement text. Within the⟨code⟩, the number of
⟨parameters⟩is detected automatically from the function signature. These⟨parameters⟩
(#1,#2, etc.) will be replaced by those absorbed by the function. When the ⟨function⟩
\cs_gset_nopar:Nn
\cs_gset_nopar:(cn|Nx|cx)
\cs_gset_protected_nopar:Nn ⟨function⟩ {⟨code⟩}
\cs_gset_protected_nopar:Nn
\cs_gset_protected_nopar:(cn|Nx|cx)
Sets⟨function⟩to expand to⟨code⟩as replacement text. Within the⟨code⟩, the number of
⟨parameters⟩is detected automatically from the function signature. These⟨parameters⟩
(#1,#2, etc.) will be replaced by those absorbed by the function. When the ⟨function⟩ is used the⟨parameters⟩absorbed cannot contain \par tokens. The⟨function⟩will not expand within an x-type or e-type argument. The assignment of a meaning to the
⟨function⟩is global.
\cs_generate_from_arg_count:NNnn ⟨function⟩ ⟨creator⟩ {⟨number⟩}
{⟨code⟩}
\cs_generate_from_arg_count:NNnn
\cs_generate_from_arg_count:(cNnn|Ncnn)
Updated: 2012-01-14
Uses the⟨creator⟩function (which should have signatureNpn, for example\cs_new:Npn) to define a ⟨function⟩ which takes ⟨number⟩ arguments and has ⟨code⟩as replacement text. The ⟨number⟩ of arguments is an integer expression, evaluated as detailed for
\int_eval:n.
4.3.4 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 copy of the first (rather than a pointer to it). Thus the old and new control sequence are not tied together: changes to one are not reflected in the other.
In the following text “cs” is used as an abbreviation for “control sequence”.
\cs_new_eq:NN ⟨cs1⟩ ⟨cs2⟩
\cs_new_eq:NN ⟨cs1⟩ ⟨token⟩
Globally creates ⟨control sequence1⟩ and sets it to have the same meaning as ⟨control sequence2⟩or⟨token⟩. The second control sequence may subsequently be altered without affecting the copy.
\cs_new_eq:NN
\cs_new_eq:(Nc|cN|cc)
\cs_set_eq:NN ⟨cs1⟩ ⟨cs2⟩
\cs_set_eq:NN ⟨cs1⟩ ⟨token⟩
Sets ⟨control sequence1⟩ to have the same meaning as ⟨control sequence2⟩ (or ⟨token⟩).
The second control sequence may subsequently be altered without affecting the copy.
The assignment of a meaning to the⟨control sequence1⟩is restricted to the current TEX group level.
\cs_set_eq:NN
\cs_set_eq:(Nc|cN|cc)
\cs_gset_eq:NN ⟨cs1⟩ ⟨cs2⟩
\cs_gset_eq:NN ⟨cs1⟩ ⟨token⟩
Globally sets ⟨control sequence1⟩ to have the same meaning as ⟨control sequence2⟩ (or
⟨token⟩). The second control sequence may subsequently be altered without affecting the copy. The assignment of a meaning to the ⟨control sequence1⟩ is not restricted to the current TEX group level: the assignment is global.
\cs_gset_eq:NN
\cs_gset_eq:(Nc|cN|cc)
4.3.5 Deleting control sequences
There are occasions where control sequences need to be deleted. This is handled in a very simple manner.
\cs_undefine:N ⟨control sequence⟩
Sets⟨control sequence⟩to be globally undefined.
\cs_undefine:N
\cs_undefine:c
Updated: 2011-09-15
4.3.6 Showing control sequences
\cs_meaning:N ⟨control sequence⟩
This function expands to the meaning of the⟨control sequence⟩control sequence. For a macro, this includes the⟨replacement text⟩.
TEXhackers note: This is TEX’s \meaning primitive. For tokens that are not control sequences, it is more logical to use \token_to_meaning:N. The c variant correctly reports undefined arguments.
\cs_meaning:N ⋆
\cs_meaning:c ⋆
Updated: 2011-12-22
\cs_show:N ⟨control sequence⟩
Displays the definition of the⟨control sequence⟩on the terminal.
TEXhackers note: This is similar to the TEX primitive\show, wrapped to a fixed number of characters per line.
\cs_show:N
\cs_show:c
Updated: 2017-02-14
\cs_log:N ⟨control sequence⟩
Writes the definition of the⟨control sequence⟩in the log file. See also \cs_show:Nwhich displays the result in the terminal.
\cs_log:N
\cs_log:c
New: 2014-08-22 Updated: 2017-02-14
4.3.7 Converting to and from control sequences
would be equivalent to
\abc
after two expansions of\use:c.
\cs_if_exist_use:N ⟨control sequence⟩
\cs_if_exist_use:NTF ⟨control sequence⟩ {⟨true code⟩} {⟨false code⟩}
Tests whether the ⟨control sequence⟩ is currently defined according to the conditional
\cs_if_exist:NTF(whether as a function or another control sequence type), and if it is inserts the⟨control sequence⟩into the input stream followed by the⟨true code⟩. Otherwise the⟨false code⟩is used.
\cs_if_exist_use:N ⋆
\cs_if_exist_use:c ⋆
\cs_if_exist_use:NTF ⋆
\cs_if_exist_use:cTF ⋆
New: 2012-11-10
\cs:w ⟨control sequence name⟩ \cs_end:
Converts the given ⟨control sequence name⟩ into a single control sequence token. This process requires one expansion. The content for ⟨control sequence name⟩may be literal material or from other expandable functions. The ⟨control sequence name⟩ must, when fully expanded, consist of character tokens which are not active: typically of category code 10 (space), 11 (letter) or 12 (other), or a mixture of these.
TEXhackers note: These are the TEX primitives\csnameand\endcsname.
\cs:w ⋆
\cs_end: ⋆
As an example of the\cs:wand\cs_end:functions, both
\cs:w a b c \cs_end:
and
\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:
would be equivalent to
\abc
after one expansion of\cs:w.
\cs_to_str:N ⟨control sequence⟩
Converts the given ⟨control sequence⟩ into a series of characters with category code 12 (other), except spaces, of category code 10. The result does not include the current escape token, contrarily to \token_to_str:N. Full expansion of this function requires exactly 2 expansion steps, and so anx-type ore-type expansion, or twoo-type expansions are required to convert the ⟨control sequence⟩to a sequence of characters in the input stream. In most cases, an f-expansion is correct as well, but this loses a space at the start of the result.
\cs_to_str:N ⋆
4.4 Analysing control sequences
\cs_split_function:N ⟨function⟩
Splits the⟨function⟩into the⟨name⟩(i.e.the part before the colon) and the⟨signature⟩
(i.e. after the colon). This information is then placed in the input stream in three parts: the⟨name⟩, the ⟨signature⟩and a logic token indicating if a colon was found (to differentiate variables from function names). The ⟨name⟩ does not include the escape character, and both the ⟨name⟩ and ⟨signature⟩ are made up of tokens with category code 12 (other).
\cs_split_function:N ⋆
New: 2018-04-06
The next three functions decompose TEX macros into their constituent parts: if the
⟨token⟩ passed is not a macro then no decomposition can occur. In the latter case, all three functions leave\scan_stop:in the input stream.
\cs_prefix_spec:N ⟨token⟩
If the⟨token⟩is a macro, this function leaves the applicable TEX prefixes in input stream as a string of tokens of category code 12 (with spaces having category code 10). Thus for example
\cs_set:Npn \next:nn #1#2 { x #1~y #2 }
\cs_prefix_spec:N \next:nn
leaves\longin the input stream. If the⟨token⟩is not a macro then\scan_stop:is left in the input stream.
TEXhackers note: The prefix can be empty,\long,\protectedor\protected\longwith backslash replaced by the current escape character.
\cs_prefix_spec:N ⋆
New: 2019-02-27
\cs_parameter_spec:N ⟨token⟩
If the⟨token⟩is a macro, this function leaves the primitive TEX parameter specification in input stream as a string of character tokens of category code 12 (with spaces having category code 10). Thus for example
\cs_set:Npn \next:nn #1#2 { x #1 y #2 }
\cs_parameter_spec:N \next:nn
\cs_parameter_spec:N ⋆
New: 2022-06-24
\cs_replacement_spec:N ⟨token⟩
If the ⟨token⟩ is a macro, this function leaves the replacement text in input stream as a string of character tokens of category code 12 (with spaces having category code 10).
Thus for example
\cs_set:Npn \next:nn #1#2 { x #1~y #2 }
\cs_replacement_spec:N \next:nn
leavesx#1␣y#2 in the input stream. If the⟨token⟩is not a macro then \scan_stop:is left in the input stream.
TEXhackers note: If the parameter specification contains the string->, then the function produces incorrect results.
\cs_replacement_spec:N ⋆
New: 2019-02-27
4.5 Using or removing tokens and arguments
Tokens in the input can be read and used or read and discarded. If one or more tokens are wrapped in braces then when absorbing them the outer set is removed. At the same time, the category code of each token is set when the token is read by a function (if it is read more than once, the category code is determined by the situation in force when first function absorbs the token).
\use:n {⟨group1⟩}
\use:nn {⟨group1⟩} {⟨group2⟩}
\use:nnn {⟨group1⟩} {⟨group2⟩} {⟨group3⟩}
\use:nnnn {⟨group1⟩} {⟨group2⟩} {⟨group3⟩} {⟨group4⟩}
As illustrated, these functions absorb between one and four arguments, as indicated by the argument specifier. The braces surrounding each argument are removed and the remaining tokens are left in the input stream. The category code of these tokens is also fixed by this process (if it has not already been by some other absorption). All of these functions require only a single expansion to operate, so that one expansion of
\use:nn { abc } { { def } } results in the input stream containing
abc { def }
i.e. only the outer braces are removed.
TEXhackers note: The\use:nfunction is equivalent to LATEX 2ε’s\@firstofone.
\use:n ⋆
\use:nn ⋆
\use:nnn ⋆
\use:nnnn ⋆
\use_i:nn {⟨arg1⟩} {⟨arg2⟩}
These functions absorb two arguments from the input stream. The function\use_i:nn discards the second argument, and leaves the content of the first argument in the input stream. \use_ii:nn discards the first argument and leaves the content of the second argument in the input stream. The category code of these tokens is also fixed (if it has not already been by some other absorption). A single expansion is needed for the functions to take effect.
TEXhackers note: These are equivalent to LATEX 2ε’s\@firstoftwoand\@secondoftwo.
\use_i:nn ⋆
\use_ii:nn ⋆
\use_i:nnn {⟨arg1⟩} {⟨arg2⟩} {⟨arg3⟩}
These functions absorb three arguments from the input stream. The function\use_i:nnn discards the second and third arguments, and leaves the content of the first argument in the input stream. \use_ii:nnn and \use_iii:nnn work similarly, leaving the content of second or third arguments in the input stream, respectively. The category code of these tokens is also fixed (if it has not already been by some other absorption). A single expansion is needed for the functions to take effect.
\use_i:nnn ⋆
\use_ii:nnn ⋆
\use_iii:nnn ⋆
\use_i:nnnn {⟨arg1⟩} {⟨arg2⟩} {⟨arg3⟩} {⟨arg4⟩}
These functions absorb four arguments from the input stream. The function \use_- i:nnnn discards the second, third and fourth arguments, and leaves the content of the first argument in the input stream. \use_ii:nnnn, \use_iii:nnnn and\use_iv:nnnn work similarly, leaving the content of second, third or fourth arguments in the input stream, respectively. The category code of these tokens is also fixed (if it has not already been by some other absorption). A single expansion is needed for the functions to take effect.
\use_i:nnnn ⋆
\use_ii:nnnn ⋆
\use_iii:nnnn ⋆
\use_iv:nnnn ⋆
\use_i_ii:nnn {⟨arg1⟩} {⟨arg2⟩} {⟨arg3⟩}
This function absorbs three arguments and leaves the content of the first and second in the input stream. The category code of these tokens is also fixed (if it has not already been by some other absorption). A single expansion is needed for the function to take effect. An example:
\use_i_ii:nnn ⋆
\use_none:n {⟨group1⟩}
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 thenarguments may be an unbraced single token (i.e.anNargument).
TEXhackers note: These are equivalent to LATEX 2ε’s\@gobble,\@gobbbletwo,etc.
\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 ⋆
\use:e {⟨expandable tokens⟩}
Fully expands the ⟨token list⟩ in an x-type manner, but the function remains fully ex- pandable, and parameter character (usually#) need not be doubled.
TEXhackers note: \use:eis a wrapper around the primitive\expandedwhere it is avail- able: it requires two expansions to complete its action. When \expandedis not available this function is very slow.
\use:e ⋆
New: 2018-06-18
\use:x {⟨expandable tokens⟩}
Fully expands the⟨expandable tokens⟩and inserts the result into the input stream at the current location. Any hash characters (#) in the argument must be doubled.
\use:x
Updated: 2011-12-31
4.5.1 Selecting tokens from delimited arguments
A different kind of function for selecting tokens from the token stream are those that use delimited arguments.
\use_none_delimit_by_q_nil:w ⟨balanced text⟩ \q_nil
\use_none_delimit_by_q_stop:w ⟨balanced text⟩ \q_stop
\use_none_delimit_by_q_recursion_stop:w ⟨balanced text⟩
\q_recursion_stop
\use_none_delimit_by_q_nil:w ⋆
\use_none_delimit_by_q_stop:w ⋆
\use_none_delimit_by_q_recursion_stop:w ⋆
Absorb the ⟨balanced text⟩from the input stream delimited by the marker given in the function name, leaving nothing in the input stream.
\use_i_delimit_by_q_nil:nw {⟨inserted tokens⟩} ⟨balanced text⟩
\q_nil
\use_i_delimit_by_q_stop:nw {⟨inserted tokens⟩} ⟨balanced text⟩ \q_stop
\use_i_delimit_by_q_recursion_stop:nw {⟨inserted tokens⟩}
⟨balanced text⟩ \q_recursion_stop
\use_i_delimit_by_q_nil:nw ⋆
\use_i_delimit_by_q_stop:nw ⋆
\use_i_delimit_by_q_recursion_stop:nw ⋆
Absorb the ⟨balanced text⟩from the input stream delimited by the marker given in the function name, leaving⟨inserted tokens⟩in the input stream for further processing.
4.6 Predicates and conditionals
LATEX3 has three concepts for conditional flow processing:
Branching conditionals Functions that carry out a test and then execute, depending on its result, either the code supplied as the⟨true code⟩or the⟨false code⟩. These arguments are denoted with Tand F, respectively. An example would be
\cs_if_free:cTF {abc} {⟨true code⟩} {⟨false code⟩}
a function that turns the first argument into a control sequence (since it’s marked as c) then checks whether this control sequence is still free and then depending on the result carries out the code in the second argument (true case) or in the third argument (false case).
These type of functions are known as “conditionals”; whenever a TF function is defined it is usually accompanied by TandFfunctions as well. These are provided for convenience when the branch only needs to go a single way. Package writers are free to choose which types to define but the kernel definitions always provide all three versions.
Important to note is that these branching conditionals with ⟨true code⟩ and/or
⟨false code⟩are always defined in a way that the code of the chosen alternative can operate on following tokens in the input stream.
These conditional functions may or may not be fully expandable, but if they are expandable they are accompanied by a “predicate” for the same test as described below.
Predicates “Predicates” are functions that return a special type of boolean value which can be tested by the boolean expression parser. All functions of this type are expandable and have names that end with_pin the description part. For example,
\cs_if_free_p:N
would be a predicate function for the same type of test as the conditional described above. It would return “true” if its argument (a single token denoted byN) is still free for definition. It would be used in constructions like
\bool_if:nTF {
\cs_if_free_p:N \l_tmpz_tl || \cs_if_free_p:N \g_tmpz_tl } {⟨true code⟩} {⟨false code⟩}
For each predicate defined, a “branching conditional” also exists that behaves like
4.6.1 Tests on control sequences
\cs_if_eq_p:NN ⟨cs1⟩ ⟨cs2⟩
\cs_if_eq:NNTF ⟨cs1⟩ ⟨cs2⟩ {⟨true code⟩} {⟨false code⟩}
Compares the definition of two⟨control sequences⟩and is logically true if they are the same,i.e.if they have exactly the same definition when examined with\cs_show:N.
\cs_if_eq_p:NN ⋆
\cs_if_eq:NNTF ⋆
\cs_if_exist_p:N ⟨control sequence⟩
\cs_if_exist:NTF ⟨control sequence⟩ {⟨true code⟩} {⟨false code⟩}
Tests whether the⟨control sequence⟩is currently defined (whether as a function or another control sequence type). Any definition of⟨control sequence⟩other than\relaxevaluates astrue.
\cs_if_exist_p:N ⋆
\cs_if_exist_p:c ⋆
\cs_if_exist:NTF ⋆
\cs_if_exist:cTF ⋆
\cs_if_free_p:N ⟨control sequence⟩
\cs_if_free:NTF ⟨control sequence⟩ {⟨true code⟩} {⟨false code⟩}
Tests whether the⟨control sequence⟩is currently free to be defined. This test isfalseif the⟨control sequence⟩currently exists (as defined by\cs_if_exist:NTF).
\cs_if_free_p:N ⋆
\cs_if_free_p:c ⋆
\cs_if_free:NTF ⋆
\cs_if_free:cTF ⋆
4.6.2 Primitive conditionals
The ε-TEX engine itself provides many different conditionals. Some expand whatever comes after them and others don’t. Hence the names for these underlying functions often contains a :wpart but higher level functions are often available. See for instance
\int_compare_p:nNnwhich is a wrapper for\if_int_compare:w.
Certain conditionals deal with specific data types like boxes and fonts and are de- scribed there. The ones described below are either the universal conditionals or deal with control sequences. We prefix primitive conditionals with\if_.
\if_true: ⟨true code⟩ \else: ⟨false code⟩ \fi:
\if_false: ⟨true code⟩ \else: ⟨false code⟩ \fi:
\reverse_if:N ⟨primitive conditional⟩
\if_true:always executes⟨true code⟩, while\if_false: always executes⟨false code⟩.
\reverse_if:N reverses any two-way primitive conditional. \else: and \fi: delimit the branches of the conditional. The function \or: is documented in l3intand used in case switches.
TEXhackers note:These are equivalent to their corresponding TEX primitive conditionals;
\reverse_if:Nisε-TEX’s\unless.
\if_true: ⋆
\if_false: ⋆
\else: ⋆
\fi: ⋆
\reverse_if:N ⋆
\if_meaning:w ⟨arg1⟩ ⟨arg2⟩ ⟨true code⟩ \else: ⟨false code⟩ \fi:
\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 theunexpandeddefinitions are compared.
TEXhackers note: This is TEX’s\ifx.
\if_meaning:w ⋆
