The L A TEX3 Sources
The L
ATEX Project
∗Released 2021-10-12
Abstract
This is the reference documentation for the expl3 programming environment. The expl3 modules set up an experimental naming scheme for L
ATEX commands, which allow the L
ATEX 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: the expl3 modules define an independent low-level L
ATEX3 programming language.
The expl3 modules are designed to be loaded on top of L
ATEX 2ε. With an up-to- date L
ATEX 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: latex-team@latex-project.org
Contents
I Introduction 1
1 Introduction to expl3 and 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 L
ATEX3 . . . . 7
II Bootstrapping 8 2 The l3bootstrap package: Bootstrap code 9 2.1 Using the L
ATEX3 modules . . . . 9
3 The l3names package: Namespace for primitives 11 3.1 Setting up the L
ATEX3 programming language . . . 11
III Programming Flow 12 4 The l3basics package: Basic definitions 13 4.1 No operation functions . . . 13
4.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
4.5 Using or removing tokens and arguments . . . 23
4.5.1 Selecting tokens from delimited arguments . . . 25
4.6 Predicates and conditionals . . . 25
4.6.1 Tests on control sequences . . . 27
4.6.2 Primitive conditionals . . . 27
4.7 Starting a paragraph . . . 28
4.8 Debugging support . . . 29
5 The l3expan package: 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 . . . 37
5.7 Unbraced expansion . . . 38
5.8 Preventing expansion . . . 38
5.9 Controlled expansion . . . 40
5.10 Internal functions . . . 42
6 The l3sort package: Sorting functions 43 6.1 Controlling sorting . . . 43
7 The l3tl-analysis package: Analysing token lists 45 8 The l3regex package: Regular expressions in TEX 46 8.1 Syntax of regular expressions . . . 47
8.1.1 Regex 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 . . . 54
8.5 Submatch extraction . . . 55
8.6 Replacement . . . 56
8.7 Constants and variables . . . 57
8.8 Bugs, misfeatures, future work, and other possibilities . . . 57
9 The l3prg package: Control structures 60 9.1 Defining a set of conditional functions . . . 60
9.2 The boolean data type . . . 62
9.2.1 Scratch booleans . . . 64
9.3 Boolean expressions . . . 64
9.4 Logical loops . . . 66
9.5 Producing multiple copies . . . 67
9.6 Detecting TEX’s mode . . . 68
9.7 Primitive conditionals . . . 68
9.8 Nestable recursions and mappings . . . 68
9.8.1 Simple mappings . . . 69
9.9 Internal programming functions . . . 69
10 The l3sys package: System/runtime functions 70
10.1 The name of the job . . . 70
10.2 Date and time . . . 70
10.3 Engine . . . 71
10.4 Output format . . . 71
10.5 Platform . . . 72
10.6 Random numbers . . . 72
10.7 Access to the shell . . . 72
10.8 Loading configuration data . . . 73
10.8.1 Final settings . . . 74
11 The l3msg package: Messages 75 11.1 Creating new messages . . . 75
11.2 Customizable information for message modules . . . 76
11.3 Contextual information for messages . . . 76
11.4 Issuing messages . . . 78
11.4.1 Messages for showing material . . . 81
11.4.2 Expandable error messages . . . 81
11.5 Redirecting messages . . . 81
12 The l3file package: File and I/O operations 83 12.1 Input–output stream management . . . 83
12.1.1 Reading from files . . . 85
12.1.2 Writing to files . . . 88
12.1.3 Wrapping lines in output . . . 90
12.1.4 Constant input–output streams, and variables . . . 91
12.1.5 Primitive conditionals . . . 91
12.2 File operation functions . . . 91
13 The l3luatex package: LuaTEX-specific functions 96 13.1 Breaking out to Lua . . . 96
13.2 Lua interfaces . . . 97
14 The l3legacy package: Interfaces to legacy concepts 99 IV Data types 100 15 The l3tl package: Token lists 101 15.1 Creating and initialising token list variables . . . 101
15.2 Adding data to token list variables . . . 102
15.3 Modifying token list variables . . . 103
15.4 Reassigning token list category codes . . . 103
15.5 Token list conditionals . . . 105
15.6 Mapping over token lists . . . 107
15.7 Using token lists . . . 109
15.8 Working with the content of token lists . . . 109
15.9 The first token from a token list . . . 111
15.10 Using a single item . . . 114
15.11 Viewing token lists . . . 116
15.12 Constant token lists . . . 116
15.13 Scratch token lists . . . 117
16 The l3str package: Strings 118 16.1 Building strings . . . 119
16.2 Adding data to string variables . . . 119
16.3 Modifying string variables . . . 120
16.4 String conditionals . . . 121
16.5 Mapping over strings . . . 123
16.6 Working with the content of strings . . . 124
16.7 String manipulation . . . 128
16.8 Viewing strings . . . 129
16.9 Constant strings . . . 130
16.10 Scratch strings . . . 130
17 The l3str-convert package: string encoding conversions 131 17.1 Encoding and escaping schemes . . . 131
17.2 Conversion functions . . . 133
17.3 Conversion by expansion (for PDF contexts) . . . 133
17.4 Possibilities, and things to do . . . 133
18 The l3quark package: Quarks 135 18.1 Quarks . . . 135
18.2 Defining quarks . . . 136
18.3 Quark tests . . . 136
18.4 Recursion . . . 137
18.4.1 An example of recursion with quarks . . . 138
18.5 Scan marks . . . 139
19 The l3seq package: Sequences and stacks 140 19.1 Creating and initialising sequences . . . 140
19.2 Appending data to sequences . . . 142
19.3 Recovering items from sequences . . . 142
19.4 Recovering values from sequences with branching . . . 143
19.5 Modifying sequences . . . 145
19.6 Sequence conditionals . . . 145
19.7 Mapping over sequences . . . 146
19.8 Using the content of sequences directly . . . 148
19.9 Sequences as stacks . . . 149
19.10 Sequences as sets . . . 150
19.11 Constant and scratch sequences . . . 151
19.12 Viewing sequences . . . 152
20 The l3int package: Integers 153
20.1 Integer expressions . . . 154
20.2 Creating and initialising integers . . . 155
20.3 Setting and incrementing integers . . . 156
20.4 Using integers . . . 157
20.5 Integer expression conditionals . . . 157
20.6 Integer expression loops . . . 159
20.7 Integer step functions . . . 161
20.8 Formatting integers . . . 162
20.9 Converting from other formats to integers . . . 163
20.10 Random integers . . . 164
20.11 Viewing integers . . . 165
20.12 Constant integers . . . 165
20.13 Scratch integers . . . 165
20.14 Direct number expansion . . . 166
20.15 Primitive conditionals . . . 166
21 The l3flag package: Expandable flags 168 21.1 Setting up flags . . . 168
21.2 Expandable flag commands . . . 169
22 The l3clist package: Comma separated lists 170 22.1 Creating and initialising comma lists . . . 171
22.2 Adding data to comma lists . . . 172
22.3 Modifying comma lists . . . 173
22.4 Comma list conditionals . . . 174
22.5 Mapping over comma lists . . . 174
22.6 Using the content of comma lists directly . . . 176
22.7 Comma lists as stacks . . . 177
22.8 Using a single item . . . 178
22.9 Viewing comma lists . . . 179
22.10 Constant and scratch comma lists . . . 179
23 The l3token package: Token manipulation 180 23.1 Creating character tokens . . . 181
23.2 Manipulating and interrogating character tokens . . . 182
23.3 Generic tokens . . . 185
23.4 Converting tokens . . . 186
23.5 Token conditionals . . . 186
23.6 Peeking ahead at the next token . . . 190
23.7 Description of all possible tokens . . . 195
24 The l3prop package: Property lists 198
24.1 Creating and initialising property lists . . . 198
24.2 Adding and updating property list entries . . . 199
24.3 Recovering values from property lists . . . 200
24.4 Modifying property lists . . . 201
24.5 Property list conditionals . . . 201
24.6 Recovering values from property lists with branching . . . 202
24.7 Mapping over property lists . . . 202
24.8 Viewing property lists . . . 204
24.9 Scratch property lists . . . 204
24.10 Constants . . . 205
25 The l3skip package: Dimensions and skips 206 25.1 Creating and initialising dim variables . . . 206
25.2 Setting dim variables . . . 207
25.3 Utilities for dimension calculations . . . 207
25.4 Dimension expression conditionals . . . 208
25.5 Dimension expression loops . . . 210
25.6 Dimension step functions . . . 211
25.7 Using dim expressions and variables . . . 212
25.8 Viewing dim variables . . . 213
25.9 Constant dimensions . . . 214
25.10 Scratch dimensions . . . 214
25.11 Creating and initialising skip variables . . . 214
25.12 Setting skip variables . . . 215
25.13 Skip expression conditionals . . . 216
25.14 Using skip expressions and variables . . . 216
25.15 Viewing skip variables . . . 216
25.16 Constant skips . . . 217
25.17 Scratch skips . . . 217
25.18 Inserting skips into the output . . . 217
25.19 Creating and initialising muskip variables . . . 218
25.20 Setting muskip variables . . . 218
25.21 Using muskip expressions and variables . . . 219
25.22 Viewing muskip variables . . . 219
25.23 Constant muskips . . . 220
25.24 Scratch muskips . . . 220
25.25 Primitive conditional . . . 220
26 The l3keys package: Key–value interfaces 221 26.1 Creating keys . . . 222
26.2 Sub-dividing keys . . . 226
26.3 Choice and multiple choice keys . . . 227
26.4 Setting keys . . . 229
26.5 Handling of unknown keys . . . 230
26.6 Selective key setting . . . 231
26.7 Utility functions for keys . . . 232
26.8 Low-level interface for parsing key–val lists . . . 232
27 The l3intarray package: fast global integer arrays 235
27.1 l3intarray documentation . . . 235
27.1.1 Implementation notes . . . 236
28 The l3fp package: Floating points 237 28.1 Creating and initialising floating point variables . . . 239
28.2 Setting floating point variables . . . 239
28.3 Using floating points . . . 240
28.4 Floating point conditionals . . . 241
28.5 Floating point expression loops . . . 243
28.6 Some useful constants, and scratch variables . . . 245
28.7 Floating point exceptions . . . 246
28.8 Viewing floating points . . . 247
28.9 Floating point expressions . . . 248
28.9.1 Input of floating point numbers . . . 248
28.9.2 Precedence of operators . . . 249
28.9.3 Operations . . . 249
28.10 Disclaimer and roadmap . . . 256
29 The l3fparray package: fast global floating point arrays 259 29.1 l3fparray documentation . . . 259
30 The l3cctab package: Category code tables 260 30.1 Creating and initialising category code tables . . . 260
30.2 Using category code tables . . . 260
30.3 Category code table conditionals . . . 261
30.4 Constant category code tables . . . 261
V Text manipulation 262 31 The l3unicode package: Unicode support functions 263 32 The l3text package: text processing 264 32.1 Expanding text . . . 264
32.2 Case changing . . . 265
32.3 Removing formatting from text . . . 266
32.4 Control variables . . . 266
VI Typesetting 268
33 The l3box package: Boxes 269
33.1 Creating and initialising boxes . . . 269
33.2 Using boxes . . . 270
33.3 Measuring and setting box dimensions . . . 271
33.4 Box conditionals . . . 272
33.5 The last box inserted . . . 272
33.6 Constant boxes . . . 272
33.7 Scratch boxes . . . 272
33.8 Viewing box contents . . . 273
33.9 Boxes and color . . . 273
33.10 Horizontal mode boxes . . . 273
33.11 Vertical mode boxes . . . 274
33.12 Using boxes efficiently . . . 276
33.13 Affine transformations . . . 277
33.14 Primitive box conditionals . . . 280
34 The l3coffins package: Coffin code layer 281 34.1 Creating and initialising coffins . . . 281
34.2 Setting coffin content and poles . . . 282
34.3 Coffin affine transformations . . . 283
34.4 Joining and using coffins . . . 283
34.5 Measuring coffins . . . 284
34.6 Coffin diagnostics . . . 284
34.7 Constants and variables . . . 285
35 The l3color package: Color support 287 35.1 Color in boxes . . . 287
35.2 Color models . . . 287
35.3 Color expressions . . . 288
35.4 Named colors . . . 289
35.5 Selecting colors . . . 290
35.6 Colors for fills and strokes . . . 290
35.7 Multiple color models . . . 291
35.8 Exporting color specifications . . . 291
35.9 Creating new color models . . . 292
36 The l3pdf package: Core PDF support 294 36.1 Objects . . . 294
36.2 Version . . . 295
36.3 Compression . . . 296
36.4 Destinations . . . 296
VII Additions and removals 298
37 The l3candidates package: Experimental additions to l3kernel 299
37.1 Important notice . . . 299
37.2 Additions to l3box . . . 300
37.3 Additions to l3expan . . . 300
37.4 Additions to l3fp . . . 300
37.5 Additions to l3file . . . 301
37.6 Additions to l3flag . . . 301
37.7 Additions to l3intarray . . . 301
37.8 Additions to l3msg . . . 302
37.9 Additions to l3prg . . . 302
37.10 Additions to l3prop . . . 303
37.11 Additions to l3seq . . . 304
37.12 Additions to l3sys . . . 305
37.13 Additions to l3tl . . . 306
37.14 Additions to l3token . . . 307
VIII Implementation 309 38 l3bootstrap implementation 310 38.1 LuaTEX-specific code . . . 310
38.2 The \pdfstrcmp primitive in X E TEX . . . 310
38.3 Loading support Lua code . . . 311
38.4 Engine requirements . . . 311
38.5 Extending allocators . . . 313
38.6 The L
ATEX3 code environment . . . 313
39 l3names implementation 316 40 l3kernel-functions: kernel-reserved functions 342 40.1 Internal kernel functions . . . 342
40.2 Kernel backend functions . . . 348
41 l3basics implementation 350 41.1 Renaming some TEX primitives (again) . . . 350
41.2 Defining some constants . . . 352
41.3 Defining functions . . . 352
41.4 Selecting tokens . . . 353
41.5 Gobbling tokens from input . . . 355
41.6 Debugging and patching later definitions . . . 355
41.7 Conditional processing and definitions . . . 356
41.8 Dissecting a control sequence . . . 362
41.9 Exist or free . . . 364
41.10 Preliminaries for new functions . . . 366
41.11 Defining new functions . . . 367
41.12 Copying definitions . . . 369
41.13 Undefining functions . . . 369
41.14 Generating parameter text from argument count . . . 370
41.15 Defining functions from a given number of arguments . . . 371
41.16 Using the signature to define functions . . . 372
41.17 Checking control sequence equality . . . 374
41.18 Diagnostic functions . . . 374
41.19 Decomposing a macro definition . . . 376
41.20 Doing nothing functions . . . 377
41.21 Breaking out of mapping functions . . . 377
41.22 Starting a paragraph . . . 378
42 l3expan implementation 379 42.1 General expansion . . . 379
42.2 Hand-tuned definitions . . . 383
42.3 Last-unbraced versions . . . 386
42.4 Preventing expansion . . . 388
42.5 Controlled expansion . . . 389
42.6 Emulating e-type expansion . . . 390
42.7 Defining function variants . . . 397
42.8 Definitions with the automated technique . . . 407
43 l3sort implementation 409 43.1 Variables . . . 409
43.2 Finding available \toks registers . . . 410
43.3 Protected user commands . . . 412
43.4 Merge sort . . . 414
43.5 Expandable sorting . . . 417
43.6 Messages . . . 422
44 l3tl-analysis implementation 425 44.1 Internal functions . . . 425
44.2 Internal format . . . 425
44.3 Variables and helper functions . . . 426
44.4 Plan of attack . . . 428
44.5 Disabling active characters . . . 429
44.6 First pass . . . 430
44.7 Second pass . . . 435
44.8 Mapping through the analysis . . . 438
44.9 Showing the results . . . 438
44.10 Peeking ahead . . . 441
44.11 Messages . . . 446
45 l3regex implementation 448 45.1 Plan of attack . . . 448
45.2 Helpers . . . 449
45.2.1 Constants and variables . . . 451
45.2.2 Testing characters . . . 452
45.2.3 Internal auxiliaries . . . 452
45.2.4 Character property tests . . . 456
45.2.5 Simple character escape . . . 458
45.3 Compiling . . . 463
45.3.1 Variables used when compiling . . . 464
45.3.2 Generic helpers used when compiling . . . 465
45.3.3 Mode . . . 466
45.3.4 Framework . . . 469
45.3.5 Quantifiers . . . 472
45.3.6 Raw characters . . . 474
45.3.7 Character properties . . . 476
45.3.8 Anchoring and simple assertions . . . 477
45.3.9 Character classes . . . 478
45.3.10 Groups and alternations . . . 481
45.3.11 Catcodes and csnames . . . 484
45.3.12 Raw token lists with \u . . . 488
45.3.13 Other . . . 491
45.3.14 Showing regexes . . . 491
45.4 Building . . . 498
45.4.1 Variables used while building . . . 498
45.4.2 Framework . . . 498
45.4.3 Helpers for building an nfa . . . 500
45.4.4 Building classes . . . 501
45.4.5 Building groups . . . 503
45.4.6 Others . . . 508
45.5 Matching . . . 509
45.5.1 Variables used when matching . . . 510
45.5.2 Matching: framework . . . 512
45.5.3 Using states of the nfa . . . 515
45.5.4 Actions when matching . . . 516
45.6 Replacement . . . 519
45.6.1 Variables and helpers used in replacement . . . 519
45.6.2 Query and brace balance . . . 520
45.6.3 Framework . . . 521
45.6.4 Submatches . . . 524
45.6.5 Csnames in replacement . . . 526
45.6.6 Characters in replacement . . . 527
45.6.7 An error . . . 531
45.7 User functions . . . 531
45.7.1 Variables and helpers for user functions . . . 533
45.7.2 Matching . . . 535
45.7.3 Extracting submatches . . . 535
45.7.4 Replacement . . . 540
45.7.5 Peeking ahead . . . 543
45.8 Messages . . . 549
45.9 Code for tracing . . . 555
46 l3prg implementation 556 46.1 Primitive conditionals . . . 556
46.2 Defining a set of conditional functions . . . 556
46.3 The boolean data type . . . 556
46.4 Internal auxiliaries . . . 558
46.5 Boolean expressions . . . 559
46.6 Logical loops . . . 564
46.7 Producing multiple copies . . . 565
46.8 Detecting TEX’s mode . . . 566
46.9 Internal programming functions . . . 567
47 l3sys implementation 569
47.1 Kernel code . . . 569
47.1.1 Detecting the engine . . . 569
47.1.2 Randomness . . . 571
47.1.3 Platform . . . 571
47.1.4 Configurations . . . 571
47.1.5 Access to the shell . . . 573
47.2 Dynamic (every job) code . . . 576
47.2.1 The name of the job . . . 576
47.2.2 Time and date . . . 576
47.2.3 Random numbers . . . 577
47.2.4 Access to the shell . . . 579
47.2.5 Held over from l3file . . . 579
47.3 Last-minute code . . . 579
47.3.1 Detecting the output . . . 580
47.3.2 Configurations . . . 580
48 l3msg implementation 582 48.1 Internal auxiliaries . . . 582
48.2 Creating messages . . . 582
48.3 Messages: support functions and text . . . 584
48.4 Showing messages: low level mechanism . . . 585
48.5 Displaying messages . . . 587
48.6 Kernel-specific functions . . . 596
48.7 Internal messages . . . 597
48.8 Expandable errors . . . 603
48.9 Message formatting . . . 604
49 l3file implementation 605 49.1 Input operations . . . 605
49.1.1 Variables and constants . . . 605
49.1.2 Stream management . . . 606
49.1.3 Reading input . . . 609
49.2 Output operations . . . 612
49.2.1 Variables and constants . . . 612
49.2.2 Internal auxiliaries . . . 613
49.3 Stream management . . . 613
49.3.1 Deferred writing . . . 615
49.3.2 Immediate writing . . . 615
49.3.3 Special characters for writing . . . 616
49.3.4 Hard-wrapping lines to a character count . . . 617
49.4 File operations . . . 626
49.4.1 Internal auxiliaries . . . 628
49.5 GetIdInfo . . . 643
49.6 Checking the version of kernel dependencies . . . 644
49.7 Messages . . . 646
49.8 Functions delayed from earlier modules . . . 647
50 l3luatex implementation 649
50.1 Breaking out to Lua . . . 649
50.2 Messages . . . 650
50.3 Lua functions for internal use . . . 650
51 l3legacy Implementation 657 52 l3tl implementation 659 52.1 Functions . . . 659
52.2 Constant token lists . . . 661
52.3 Adding to token list variables . . . 661
52.4 Internal quarks and quark-query functions . . . 664
52.5 Reassigning token list category codes . . . 664
52.6 Modifying token list variables . . . 667
52.7 Token list conditionals . . . 671
52.8 Mapping over token lists . . . 676
52.9 Using token lists . . . 678
52.10 Working with the contents of token lists . . . 679
52.11 The first token from a token list . . . 682
52.12 Token by token changes . . . 687
52.13 Using a single item . . . 689
52.14 Viewing token lists . . . 692
52.15 Internal scan marks . . . 694
52.16 Scratch token lists . . . 694
53 l3str implementation 695 53.1 Internal auxiliaries . . . 695
53.2 Creating and setting string variables . . . 696
53.3 Modifying string variables . . . 697
53.4 String comparisons . . . 698
53.5 Mapping over strings . . . 701
53.6 Accessing specific characters in a string . . . 703
53.7 Counting characters . . . 708
53.8 The first character in a string . . . 709
53.9 String manipulation . . . 710
53.10 Viewing strings . . . 712
54 l3str-convert implementation 713 54.1 Helpers . . . 713
54.1.1 Variables and constants . . . 713
54.2 String conditionals . . . 715
54.3 Conversions . . . 716
54.3.1 Producing one byte or character . . . 716
54.3.2 Mapping functions for conversions . . . 717
54.3.3 Error-reporting during conversion . . . 718
54.3.4 Framework for conversions . . . 719
54.3.5 Byte unescape and escape . . . 723
54.3.6 Native strings . . . 724
54.3.7 clist . . . 725
54.3.8 8-bit encodings . . . 725
54.4 Messages . . . 728
54.5 Escaping definitions . . . 729
54.5.1 Unescape methods . . . 730
54.5.2 Escape methods . . . 734
54.6 Encoding definitions . . . 736
54.6.1 utf-8 support . . . 736
54.6.2 utf-16 support . . . 741
54.6.3 utf-32 support . . . 746
54.7 PDF names and strings by expansion . . . 749
54.7.1 iso 8859 support . . . 750
55 l3quark implementation 767 55.1 Quarks . . . 767
55.2 Scan marks . . . 775
56 l3seq implementation 777 56.1 Allocation and initialisation . . . 778
56.2 Appending data to either end . . . 781
56.3 Modifying sequences . . . 782
56.4 Sequence conditionals . . . 784
56.5 Recovering data from sequences . . . 786
56.6 Mapping over sequences . . . 790
56.7 Using sequences . . . 794
56.8 Sequence stacks . . . 795
56.9 Viewing sequences . . . 796
56.10 Scratch sequences . . . 797
57 l3int implementation 798 57.1 Integer expressions . . . 799
57.2 Creating and initialising integers . . . 801
57.3 Setting and incrementing integers . . . 803
57.4 Using integers . . . 804
57.5 Integer expression conditionals . . . 804
57.6 Integer expression loops . . . 808
57.7 Integer step functions . . . 809
57.8 Formatting integers . . . 811
57.9 Converting from other formats to integers . . . 816
57.10 Viewing integer . . . 819
57.11 Random integers . . . 820
57.12 Constant integers . . . 820
57.13 Scratch integers . . . 820
57.14 Integers for earlier modules . . . 821
58 l3flag implementation 822 58.1 Non-expandable flag commands . . . 822
58.2 Expandable flag commands . . . 823
59 l3clist implementation 825
59.1 Removing spaces around items . . . 826
59.2 Allocation and initialisation . . . 827
59.3 Adding data to comma lists . . . 829
59.4 Comma lists as stacks . . . 830
59.5 Modifying comma lists . . . 832
59.6 Comma list conditionals . . . 835
59.7 Mapping over comma lists . . . 836
59.8 Using comma lists . . . 840
59.9 Using a single item . . . 842
59.10 Viewing comma lists . . . 844
59.11 Scratch comma lists . . . 845
60 l3token implementation 846 60.1 Internal auxiliaries . . . 846
60.2 Manipulating and interrogating character tokens . . . 846
60.3 Creating character tokens . . . 849
60.4 Generic tokens . . . 857
60.5 Token conditionals . . . 858
60.6 Peeking ahead at the next token . . . 868
61 l3prop implementation 874 61.1 Internal auxiliaries . . . 875
61.2 Allocation and initialisation . . . 876
61.3 Accessing data in property lists . . . 879
61.4 Property list conditionals . . . 883
61.5 Recovering values from property lists with branching . . . 884
61.6 Mapping over property lists . . . 884
61.7 Viewing property lists . . . 886
62 l3skip implementation 887 62.1 Length primitives renamed . . . 887
62.2 Internal auxiliaries . . . 887
62.3 Creating and initialising dim variables . . . 887
62.4 Setting dim variables . . . 888
62.5 Utilities for dimension calculations . . . 889
62.6 Dimension expression conditionals . . . 890
62.7 Dimension expression loops . . . 892
62.8 Dimension step functions . . . 893
62.9 Using dim expressions and variables . . . 895
62.10 Viewing dim variables . . . 897
62.11 Constant dimensions . . . 897
62.12 Scratch dimensions . . . 897
62.13 Creating and initialising skip variables . . . 897
62.14 Setting skip variables . . . 899
62.15 Skip expression conditionals . . . 899
62.16 Using skip expressions and variables . . . 900
62.17 Inserting skips into the output . . . 900
62.18 Viewing skip variables . . . 901
62.19 Constant skips . . . 901
62.20 Scratch skips . . . 901
62.21 Creating and initialising muskip variables . . . 901
62.22 Setting muskip variables . . . 902
62.23 Using muskip expressions and variables . . . 903
62.24 Viewing muskip variables . . . 903
62.25 Constant muskips . . . 904
62.26 Scratch muskips . . . 904
63 l3keys Implementation 905 63.1 Low-level interface . . . 905
63.2 Constants and variables . . . 912
63.2.1 Internal auxiliaries . . . 914
63.3 The key defining mechanism . . . 914
63.4 Turning properties into actions . . . 916
63.5 Creating key properties . . . 922
63.6 Setting keys . . . 927
63.7 Utilities . . . 936
63.8 Messages . . . 938
64 l3intarray implementation 940 64.1 Allocating arrays . . . 940
64.2 Array items . . . 941
64.3 Working with contents of integer arrays . . . 943
64.4 Random arrays . . . 946
65 l3fp implementation 948 66 l3fp-aux implementation 949 66.1 Access to primitives . . . 949
66.2 Internal representation . . . 949
66.3 Using arguments and semicolons . . . 950
66.4 Constants, and structure of floating points . . . 951
66.5 Overflow, underflow, and exact zero . . . 954
66.6 Expanding after a floating point number . . . 954
66.7 Other floating point types . . . 955
66.8 Packing digits . . . 958
66.9 Decimate (dividing by a power of 10) . . . 961
66.10 Functions for use within primitive conditional branches . . . 963
66.11 Integer floating points . . . 964
66.12 Small integer floating points . . . 965
66.13 Fast string comparison . . . 966
66.14 Name of a function from its l3fp-parse name . . . 966
66.15 Messages . . . 966
67 l3fp-traps Implementation 967 67.1 Flags . . . 967
67.2 Traps . . . 967
67.3 Errors . . . 971
67.4 Messages . . . 971
68 l3fp-round implementation 973
68.1 Rounding tools . . . 973
68.2 The round function . . . 977
69 l3fp-parse implementation 982 69.1 Work plan . . . 982
69.1.1 Storing results . . . 983
69.1.2 Precedence and infix operators . . . 984
69.1.3 Prefix operators, parentheses, and functions . . . 987
69.1.4 Numbers and reading tokens one by one . . . 988
69.2 Main auxiliary functions . . . 990
69.3 Helpers . . . 991
69.4 Parsing one number . . . 992
69.4.1 Numbers: trimming leading zeros . . . 998
69.4.2 Number: small significand . . . 999
69.4.3 Number: large significand . . . 1001
69.4.4 Number: beyond 16 digits, rounding . . . 1003
69.4.5 Number: finding the exponent . . . 1006
69.5 Constants, functions and prefix operators . . . 1009
69.5.1 Prefix operators . . . 1009
69.5.2 Constants . . . 1012
69.5.3 Functions . . . 1013
69.6 Main functions . . . 1014
69.7 Infix operators . . . 1016
69.7.1 Closing parentheses and commas . . . 1018
69.7.2 Usual infix operators . . . 1019
69.7.3 Juxtaposition . . . 1020
69.7.4 Multi-character cases . . . 1020
69.7.5 Ternary operator . . . 1021
69.7.6 Comparisons . . . 1021
69.8 Tools for functions . . . 1024
69.9 Messages . . . 1026
70 l3fp-assign implementation 1027 70.1 Assigning values . . . 1027
70.2 Updating values . . . 1028
70.3 Showing values . . . 1028
70.4 Some useful constants and scratch variables . . . 1029
71 l3fp-logic Implementation 1030 71.1 Syntax of internal functions . . . 1030
71.2 Tests . . . 1030
71.3 Comparison . . . 1031
71.4 Floating point expression loops . . . 1034
71.5 Extrema . . . 1037
71.6 Boolean operations . . . 1039
71.7 Ternary operator . . . 1040
72 l3fp-basics Implementation 1042
72.1 Addition and subtraction . . . 1042
72.1.1 Sign, exponent, and special numbers . . . 1043
72.1.2 Absolute addition . . . 1045
72.1.3 Absolute subtraction . . . 1047
72.2 Multiplication . . . 1051
72.2.1 Signs, and special numbers . . . 1051
72.2.2 Absolute multiplication . . . 1053
72.3 Division . . . 1055
72.3.1 Signs, and special numbers . . . 1055
72.3.2 Work plan . . . 1056
72.3.3 Implementing the significand division . . . 1059
72.4 Square root . . . 1064
72.5 About the sign and exponent . . . 1071
72.6 Operations on tuples . . . 1072
73 l3fp-extended implementation 1074 73.1 Description of fixed point numbers . . . 1074
73.2 Helpers for numbers with extended precision . . . 1075
73.3 Multiplying a fixed point number by a short one . . . 1076
73.4 Dividing a fixed point number by a small integer . . . 1076
73.5 Adding and subtracting fixed points . . . 1077
73.6 Multiplying fixed points . . . 1078
73.7 Combining product and sum of fixed points . . . 1079
73.8 Extended-precision floating point numbers . . . 1082
73.9 Dividing extended-precision numbers . . . 1084
73.10 Inverse square root of extended precision numbers . . . 1088
73.11 Converting from fixed point to floating point . . . 1090
74 l3fp-expo implementation 1092 74.1 Logarithm . . . 1092
74.1.1 Work plan . . . 1092
74.1.2 Some constants . . . 1093
74.1.3 Sign, exponent, and special numbers . . . 1093
74.1.4 Absolute ln . . . 1093
74.2 Exponential . . . 1100
74.2.1 Sign, exponent, and special numbers . . . 1100
74.3 Power . . . 1105
74.4 Factorial . . . 1111
75 l3fp-trig Implementation 1114
75.1 Direct trigonometric functions . . . 1115
75.1.1 Filtering special cases . . . 1115
75.1.2 Distinguishing small and large arguments . . . 1118
75.1.3 Small arguments . . . 1119
75.1.4 Argument reduction in degrees . . . 1119
75.1.5 Argument reduction in radians . . . 1120
75.1.6 Computing the power series . . . 1128
75.2 Inverse trigonometric functions . . . 1130
75.2.1 Arctangent and arccotangent . . . 1131
75.2.2 Arcsine and arccosine . . . 1136
75.2.3 Arccosecant and arcsecant . . . 1138
76 l3fp-convert implementation 1140 76.1 Dealing with tuples . . . 1140
76.2 Trimming trailing zeros . . . 1140
76.3 Scientific notation . . . 1141
76.4 Decimal representation . . . 1142
76.5 Token list representation . . . 1144
76.6 Formatting . . . 1145
76.7 Convert to dimension or integer . . . 1145
76.8 Convert from a dimension . . . 1146
76.9 Use and eval . . . 1147
76.10 Convert an array of floating points to a comma list . . . 1148
77 l3fp-random Implementation 1150 77.1 Engine support . . . 1150
77.2 Random floating point . . . 1154
77.3 Random integer . . . 1154
78 l3fparray implementation 1160 78.1 Allocating arrays . . . 1160
78.2 Array items . . . 1161
79 l3cctab implementation 1165 79.1 Variables . . . 1165
79.2 Allocating category code tables . . . 1166
79.3 Saving category code tables . . . 1167
79.4 Using category code tables . . . 1168
79.5 Category code table conditionals . . . 1173
79.6 Constant category code tables . . . 1174
79.7 Messages . . . 1176
80 l3unicode implementation 1178 81 l3text implementation 1182 81.1 Internal auxiliaries . . . 1182
81.2 Utilities . . . 1183
81.3 Configuration variables . . . 1186
81.4 Expansion to formatted text . . . 1187
82 l3text-case implementation 1195
82.1 Case changing . . . 1195
82.2 Case changing data for 8-bit engines . . . 1216
83 l3text-purify implementation 1228 83.1 Purifying text . . . 1228
83.2 Accent and letter-like data for purifying text . . . 1234
84 l3box implementation 1242 84.1 Support code . . . 1242
84.2 Creating and initialising boxes . . . 1242
84.3 Measuring and setting box dimensions . . . 1243
84.4 Using boxes . . . 1244
84.5 Box conditionals . . . 1245
84.6 The last box inserted . . . 1245
84.7 Constant boxes . . . 1245
84.8 Scratch boxes . . . 1246
84.9 Viewing box contents . . . 1246
84.10 Horizontal mode boxes . . . 1247
84.11 Vertical mode boxes . . . 1249
84.12 Affine transformations . . . 1252
85 l3coffins Implementation 1262 85.1 Coffins: data structures and general variables . . . 1262
85.2 Basic coffin functions . . . 1263
85.3 Measuring coffins . . . 1269
85.4 Coffins: handle and pole management . . . 1269
85.5 Coffins: calculation of pole intersections . . . 1273
85.6 Affine transformations . . . 1275
85.7 Aligning and typesetting of coffins . . . 1283
85.8 Coffin diagnostics . . . 1288
85.9 Messages . . . 1294
86 l3color Implementation 1295 86.1 Basics . . . 1295
86.2 Predefined color names . . . 1296
86.3 Setup . . . 1297
86.4 Utility functions . . . 1297
86.5 Model conversion . . . 1297
86.6 Color expressions . . . 1298
86.7 Selecting colors (and color models) . . . 1306
86.8 Fill and stroke color . . . 1307
86.9 Defining named colors . . . 1308
86.10 Exporting colors . . . 1311
86.11 Additional color models . . . 1313
86.12 Diagnostics . . . 1326
86.13 Messages . . . 1327
87 l3pdf implementation 1330 87.1 Compression . . . 1330 87.2 Objects . . . 1331 87.3 Version . . . 1331 87.4 Destinations . . . 1333
88 l3candidates Implementation 1334
88.1 Additions to l3box . . . 1334 88.1.1 Viewing part of a box . . . 1334 88.2 Additions to l3flag . . . 1336 88.3 Additions to l3msg . . . 1337 88.4 Additions to l3prg . . . 1338 88.5 Additions to l3prop . . . 1339 88.6 Additions to l3seq . . . 1339 88.7 Additions to l3sys . . . 1344 88.8 Additions to l3file . . . 1345 88.9 Additions to l3tl . . . 1345 88.9.1 Building a token list . . . 1345 88.9.2 Other additions to l3tl . . . 1349 88.10 Additions to l3token . . . 1349
89 l3deprecation implementation 1352
89.1 Helpers and variables . . . 1352 89.2 Patching definitions to deprecate . . . 1353 89.3 Removed functions . . . 1356 89.4 Loading the patches . . . 1360 89.5 Deprecated l3str functions . . . 1360 89.6 Deprecated l3seq functions . . . 1361 89.7 Deprecated l3tl functions . . . 1361 89.8 Deprecated l3token functions . . . 1362
Index 1363
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 L
ATEX3 programming language is found in expl3.pdf.
1.1 Naming functions and variables
L
ATEX3 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 each function is divided into logical units using _, while : separates the name of 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 the signature of the function.
Each function name starts with the module to which it belongs. Thus apart from a small number of very basic functions, all expl3 function 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 clist and 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:
N and n These mean no manipulation, of a single token for N and of a set of tokens given in braces for n. Both pass the argument through exactly as given. Usually, if you use a single token for an n argument, all will be well.
c This means csname, and indicates that the argument will be turned into a csname before being used. So \foo:c {ArgumentOne} will act in the same way as \foo:N
\ArgumentOne .
V and v These mean value of variable. The V and v specifiers are used to get the con- tent of a variable without needing to worry about the underlying TEX structure containing the data. A V argument will be a single token (similar to N), for example
\foo:V \MyVariable ; on the other hand, using v a 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 x specifier stands for exhaustive 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 are not 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 e is extremely slow (often more than 200 times slower) in older engines, more precisely in non-LuaTEX engines older than 2019.
f The f specifier stands for full expansion, and in contrast to x stops 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 content A\l_myb_tl, as A cannot be expanded and so terminates expansion before \l_myb_tl is 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 letter p indicates TEX parameters. Normally this will be used for delimited func- tions as expl3 provides better methods for creating simple sequential arguments.
w Finally, there is the w specifier for weird arguments. This covers everything else, but mainly applies to delimited values (where the argument must be terminated by some specified string).
D The D stands for Do not use. All of the TEX primitives are initially \let to a D name, 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 is strongly discouraged in package code: programmers should instead use the interfaces documented in interface3.pdf
1.
Notice that the argument specifier describes how the argument is processed prior to being passed to the underlying function. For example, \foo:c will take its argument, convert it to a control sequence and pass it to \foo:N.
Variables are named in a similar manner to functions, but begin with a single letter to define the type of variable:
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:LATEX-L@listserv.uni-heidelberg.de) 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.
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 module
2name 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.
Applying V-type or v-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 out box alignment operations.
flag Integer that can be incremented expandably.
fparray Fixed-size array of floating point values.
intarray Fixed-size array of integers.
ior/iow An input or output stream, for reading from or writing to, respectively.
prop Property list: analogue of dictionary or associative arrays in other languages.
regex Regular expression.
2The module names are not used in case of generic scratch registers defined in the data type modules, e.g., the int module contains some scratch variables called \l_tmpa_int, \l_tmpb_int, and so on. In such a case adding the module name up front to denote the module and in the back to indicate the type, as in \l_int_tmpa_int would be very unreadable.
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 are also macros, 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.
3On 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 experimental l3doc class; 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 termed variants of 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 \long while 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 an x-type or e-type argument (in plain TEX terms, inside an \edef or
\expanded ), as well as within an f-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 an f-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 TF indicates that three functions are available:
• \sys_if_engine_xetex:T
• \sys_if_engine_xetex:F
• \sys_if_engine_xetex:TF
Usually, the illustration will use the TF variant, and so both ⟨true code⟩ and ⟨false code⟩
will be shown. The two variant forms T and F take only ⟨true code⟩ and ⟨false code⟩, respectively. Here, the star also shows that this function is expandable. With some minor exceptions, all conditional functions in the expl3 modules should be defined in this way.
\sys_if_engine_xetex:TF ⋆
Variables, constants and so on are described in a similar manner:
A short piece of text will describe the variable: there is no syntax illustration in this case.
\l_tmpa_tl
In some cases, the function is similar to one in L
ATEX2ε or plain TEX. In these cases,
the text will include an extra “TEXhackers note” section:
\token_to_str:N ⟨token ⟩ The normal description text.
TEXhackers note: Detail for the experienced T EX or L
ATEX 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 of expl3 after 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 L
ATEX3 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 A TEX3
The TEX concept of an “\outer” macro is not supported at all by L
ATEX3. As such, the
functions provided here may break when used on top of L
ATEX2ε if \outer tokens are
used in the arguments.
Part II
Bootstrapping
Chapter 2
The l3bootstrap package Bootstrap code
2.1 Using the L A TEX3 modules
The modules documented in source3 are designed to be used on top of L
ATEX2ε 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 L
ATEX2ε 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, ~ is not 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 L
ATEX2ε kernel func- tions \ProvidesPackage, \ProvidesClass and \ProvidesFile. However, they also im- plicitly switch \ExplSyntaxOn for the remainder of the code with the file. At the end of the file, \ExplSyntaxOff will be called to reverse this. (This is the same concept as L
ATEX2ε 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 \ExplFileName for the part of the file name leading up to the period, \ExplFileDate for date, \ExplFileVersion for version and \ExplFileDescription for the description.
\GetIdInfo
Updated: 2012-06-04