The L A TEX3 Sources

Introduction

Introduction to expl3 and this document

Naming functions and variables

Scratch variables
Terminological inexactitude

Documentation conventions
Formal language conventions which apply gener- allyally
TEX concepts not supported by L A TEX3

This means that sometimes we'll use phrases like "the function returns a value" when we actually just mean "the macro expands to something". Changes in behavior When new features are added to expl3, the date of first inclusion is given in the documentation.

Bootstrapping

The l3bootstrap package Bootstrap code

Using the L A TEX3 modules

Pieces of information are stored in separate control sequences with \ExplFileName for the part of the file name leading to the period, \ExplFileDate for date, \ExplFileVersion for version, and \ExplFileDescription for description. To summarize: Every single package that uses this syntax must identify itself using one of the methods above.

The l3names package

Namespace for primitives

Setting up the L A TEX3 programming language

Programming Flow

The l3basics package Basic definitions

No operation functions
Grouping material
Control sequences and functions

Defining functions
Defining new functions using parameter text
Defining new functions using the signature
Copying control sequences
Deleting control sequences
Showing control sequences
Converting to and from control sequences

Analysing control sequences
Using or removing tokens and arguments

Selecting tokens from delimited arguments

Predicates and conditionals

Tests on control sequences
Primitive conditionals

Starting a paragraph
Debugging support

Assigning a meaning to the ⟨function⟩is limited to the current TEX group level. Assigning a meaning to the ⟨function⟩ is limited to the current TEX group level.

The l3expan package Argument expansion

Defining new variants
Methods for defining variants
Introducing the variants
Manipulating the first argument
Manipulating two arguments
Manipulating three arguments
Unbraced expansion
Preventing expansion
Controlled expansion
Internal functions

The first argument of the function is then the next item on the input stream, followed by the expansion of the second and third arguments. The first argument of the function is then the next item on the input stream, followed by the expansion of the second argument, etc.

The l3sort package Sorting functions

Controlling sorting

Indicates whether to keep the order or swap the order of two items compared in the sort code. Only one of the\sort_return_..functions should be used by the code, according to the results of some tests on the items#1and#2 to be compared.

The l3tl-analysis package

Analysing token lists

The l3regex package: Regular expressions in TEX

Syntax of regular expressions

Regular expression examples
Characters in regular expressions
Characters classes
Structure: alternatives, groups, repetitions
Matching exact tokens
Miscellaneous

Syntax of the replacement text
Pre-compiling regular expressions
Matching
Submatch extraction
Replacement
Scratch regular expressions
Bugs, misfeatures, future work, and other possi- bilitiesbilities

Sequence\Keyscape resets the start of the match to the current position in the cue list. If none of the ⟨regex⟩ matches, the code ⟨false⟩ is left in the input stream. If none of the ⟨regex⟩ matches anywhere in the ⟨token⟩ list, then nothing is left in the input stream.

Splits the ⟨token list⟩ into a series of parts separated by matches of the ⟨regular expression⟩. Searches for the ⟨regular expression⟩ in the contents of the ⟨tl var⟩ and replaces the first match with the ⟨replacement⟩.

The l3prg package Control structures

Defining a set of conditional functions
The boolean data type

Scratch booleans

Boolean expressions
Logical loops
Producing multiple copies
Detecting TEX’s mode
Nestable recursions and mappings

Simple mappings

Internal programming functions

Puts ⟨code⟩ into the input stream for TEX to process and then checks the boolean value of ⟨boolean⟩. Puts ⟨code⟩ into the input stream for TEX to process, and then checks the boolean value of ⟨boolean⟩. Puts ⟨code⟩ into the input stream for TEX to process, and then checks the boolean value of the ⟨boolean⟩ expression as described for\bool_if:nTF.

Place the ⟨code⟩ in the input stream for TEX to process, then check the logical value of the⟨boolean expression⟩ as described for \bool_if:nTF. This function first checks the logical value of the ⟨boolean expression⟩(as described for . \bool_if:nTF).

The l3sys package

System/runtime functions

The name of the job
Date and time
Engine
Output format
Platform
Random numbers
Access to the shell
Loading configuration data

Final settings

The name of the default executable file for the current TEX engine given as a lowercase string: one ofluatex,luahbtex,pdftex,eptex,euptex, orxetex. Globally sets the seed for the engine's pseudo-random number generator to the ⟨integer expression⟩. If shell escape is disabled, the ⟨tl var⟩ is set to \q_no_value in the non-branching version.

If ⟨backend⟩ is empty, the default backend for the engine in use will be loaded. Set the name of the backend in use by\sys_load_backend when launched.

The l3msg package Messages

Creating new messages
Customizable information for message modules
Contextual information for messages
Issuing messages

Messages for showing material
Expandable error messages

Redirecting messages

Expand to the public name of the ⟨module⟩ as defined by \g_msg_module_name_prop (or otherwise leave the⟨module⟩ unchanged). Issues ⟨module⟩ error ⟨message⟩, passing ⟨arg one⟩ to ⟨arg four⟩ to the text creation functions. Issue ⟨module⟩warning⟨message⟩, pass⟨arg one⟩ to⟨arg four⟩ to the text creation functions.

Warning text is added to the log file and to the terminal, but TEX execution is not terminated. Issues⟨module⟩info⟨message⟩, passing⟨arg one⟩⟨arg four⟩ to text creation functions.

The l3file package

File and I/O operations

Input–output stream management

Reading from files
Writing to files
Wrapping lines in output
Constant input–output streams, and variables

Function that reads one or more lines (until an even number of left and right curly braces exist) from the file input⟨stream⟩and stores the result locally in the⟨tokenlist⟩variable. Function that reads one line from the file input stream⟩and stores the result locally in the variable⟨tokenlist⟩. For each⟨line⟩in⟨stream⟩ store⟨line⟩in⟨variable⟩and apply⟨code⟩.

This function writes ⟨tokens⟩ to the stream⟨defined⟩immediately (i.e. the write operation is called with the extension of\iow_now:Nn). The output of i\iow_- wrap:nnnN (i.e. the argument passed to the function⟨) consists of category characters.

File operation functions

It is then expanded, leaving a hex dump of the file contents in the input stream. If the file is not found, ⟨tl var⟩ will be set to\q_no_value. If the file is not found, ⟨tl var⟩ will be set to \q_no_value.

It then expands to leave the size of the file in bytes in the input stream. It is then expanded to leave the file's modification timestamp in the input stream.

The l3luatex package

LuaTEX-specific functions

Breaking out to Lua

Convert the ⟨character list⟩ so that it can be safely ported to Lua: embedded backslashes, double and single quotes, and newlines and carriage returns are escaped. This is done by prefixing an extra character consisting of a backslash with category code 12, and for the line endings, converting them to \n\r respectively. TEXhackers note: \lua_escape:is a macro wrapper around\luaescapestring: when LuaTEX is in use, two extensions are needed to render the result of the Lua code.

Therefore, package authors should not write significant amounts of Lua code in the arguments to \lua_- now:n. Instead, it is highly recommended that they write most of their Lua code in a separate file and then load it with \lua_load_module:n.

Lua interfaces

The l3legacy package

Interfaces to legacy concepts

Data types

The l3tl package Token lists

Creating and initialising token list variables
Adding data to token list variables
Token list conditionals

Testing the first token

Working with token lists as a whole

Using token lists
Counting and reversing token lists
Viewing token lists

Manipulating items in token lists

Mapping over token lists
Head and tail of token lists
Items and ranges in token lists
Sorting token lists

Manipulating tokens in token lists

Replacing tokens
Reassigning category codes

Constant token lists
Scratch token lists

The ⟨tokenlist⟩ cannot contain tokens{,}or# (more precisely, explicit character tokens with category code 1 (start-group) or 2 (end-group) and tokens with category code 6). Tests whether the first⟨token⟩in the⟨tokenlist⟩has the same category code as the⟨test token⟩. Tests whether the first⟨token⟩in the⟨tokenlist⟩has the same character code as the⟨test token⟩.

Tests whether ⟨token⟩ in the ⟨token⟩ list has the same meaning as ⟨token⟩. Tests whether the first ⟨token⟩ in the ⟨token⟩ list is an explicit space character (explicit token with character code 12 and category code 10).

The l3str package: Strings

Creating and initialising string variables
Adding data to string variables
String conditionals
Mapping over strings
Working with the content of strings
Modifying string variables
String manipulation
Viewing strings
Constant strings
Scratch strings

Convert the⟨character list⟩ to a⟨string⟩ and test if that⟨string⟩ is found in the contents of the⟨str var⟩. Convert the ⟨character list⟩ to a ⟨string⟩ and then store each ⟨character⟩ in the ⟨string⟩ (including spaces) in turn in the (string or character list)⟨variable⟩ and apply the⟨code⟩. Leave in the input stream the number of space characters in the string representation of.

Converts the list ⟨token⟩ to a ⟨string⟩ and leaves in the input stream the character at position ⟨integer expression⟩ of ⟨string⟩, starting at 1 for the first (leftmost) character. Converts the list ⟨token⟩ to a ⟨string⟩, and leaves in the input stream the characters from index ⟨start⟩ to index ⟨end⟩ inclusive.

The l3str-convert package

Encoding and escaping schemes
Conversion functions
Conversion by expansion (for PDF contexts)
Possibilities, and things to do

Non-alphanumeric characters are ignored and capital letters are reduced to lower case before searching this list for the encoding. This function converts the ⟨string⟩ from the encoding given by ⟨name 1⟩ to the encoding given by ⟨name 2⟩, and stores the result in the ⟨str var⟩. Note the presence of a (big-endian) byte order mark "FEFF, which can be avoided by specifying utf16be/hex encoding.

Erroneous input is replaced by the Unicode wildcard character "FFFD, and characters that cannot be reencoded are replaced by the wildcard character "FFFD if it exists in encoding 2⟩, or an encoding-specific wildcard character, or the question mark character. . As\str_set_convert:Nnnn, converts the string⟨from the encoding given by⟨name 1⟩ to the encoding given by ⟨name 2⟩, and assigns the result to ⟨str var⟩.

Table 1: Supported encodings. Non-alphanumeric characters are ignored, and capital letters are lower-cased before searching for the encoding in this list.

The l3quark package Quarks

Quarks
Defining quarks
Quark tests
Recursion

An example of recursion with quarks

Scan marks

Tests whether the ⟨token⟩list contains only \q_nil (distinct from the tokenlist⟩which is empty or contains\q_nilplus one or more other tokens). Tests whether the ⟨token⟩list contains only \q_no_value (distinct from the ⟨token⟩list which is empty or contains plus one or more other tokens). The recursion entry must include the \q_recursion_tail and \q_- recursion_stopas markers the last two items.

Test if the ⟨token list⟩ contains only \q_recursion_tail, and if so, use \use_- none_delimit_by_q_recursion_stop:w to end the recursion it belongs to. The recursion input must include the tags \q_recursion_tail and \q_- recursion_stopas the last two items.

The l3seq package

Sequences and stacks

Creating and initialising sequences
Appending data to sequences
Recovering items from sequences
Recovering values from sequences with branch- inging
Modifying sequences
Sequence conditionals
Mapping over sequences
Using the content of sequences directly
Sequences as stacks
Sequences as sets
Constant and scratch sequences
Viewing sequences

Stores the leftmost element from a⟨sequence⟩in the⟨tokenlist variable⟩without removing it from the⟨sequence⟩. Stores the rightmost element from a⟨sequence⟩in the⟨tokenlist variable⟩without removing it from the⟨sequence⟩. The ⟨sequence⟩ is modified globally, while the assignment of the ⟨token list variable⟩ is local.

Reads the top entry of a ⟨string⟩in the ⟨tokenlist variable⟩ without removing it from the ⟨string⟩. If the ⟨series⟩ is not empty, the top item of the ⟨series⟩ is displayed in the ⟨token list variable⟩, i.e. removes the item from the ⟨series⟩.

The l3int package Integers

Integer expressions
Creating and initialising integers
Setting and incrementing integers
Using integers
Integer expression conditionals
Integer expression loops
Integer step functions
Formatting integers
Converting from other formats to integers
Random integers
Viewing integers
Constant integers
Scratch integers
Direct number expansion

Puts the value of ⟨integer expression⟩ into the input stream as a digit, with category code 12 (other). Computes the value of ⟨integer expression⟩ and sets the binary representation of the result to the input stream. Computes the value of ⟨integer expression⟩ and sets the hexadecimal (base 16) representation of the result to the input stream.

Computes the value of the ⟨integer expression⟩ and places the octal (base 8) representation of the result into the input stream. Places the value of the ⟨integer expression⟩ in the input stream as Roman numerals, either lowercase (\int_to_roman:n) or uppercase (\int_to_Roman:n).

The l3flag package

Expandable flags

Setting up flags

Expandable flag commands

The l3clist package

Comma separated lists

Creating and initialising comma lists
Adding data to comma lists
Modifying comma lists
Comma list conditionals
Mapping over comma lists
Using the content of comma lists directly

Remove duplicate items from the ⟨commalist⟩, leaving the leftmost copy of each item in the ⟨commalist⟩. Furthermore, it may fail if any of the items in the ⟨comma list⟩ contain {,} or # (assuming the usual TEX category codes apply). When the comma list is given explicitly, as ann-type argument, spaces around each item are trimmed.

Stores each ⟨item⟩of the ⟨commalist⟩in turn in the (tokenlist) ⟨variable⟩and applies the⟨code⟩. Used to terminate a \clist_map_..function before all entries in the ⟨commalist⟩ have been processed.