Xparse Manual
Xparse Manual
Xparse Manual
Released 2017/04/01
The xparse package provides a high-level interface for producing document-level com-
mands. In that way, it is intended as a replacement for the LATEX 2ε \newcommand macro.
However, xparse works so that the interface to a function (optional arguments, stars
and mandatory arguments, for example) is separate from the internal implementation.
xparse provides a normalised input for the internal form of a function, independent of the
document-level argument arrangement.
At present, the functions in xparse which are regarded as “stable” are:
• \NewDocumentCommand
• \RenewDocumentCommand
• \ProvideDocumentCommand
• \DeclareDocumentCommand
• \NewDocumentEnvironment
• \RenewDocumentEnvironment
• \ProvideDocumentEnvironment
• \DeclareDocumentEnvironment
• \NewExpandableDocumentCommand
• \RenewExpandableDocumentCommand
• \ProvideExpandableDocumentCommand
• \DeclareExpandableDocumentCommand
• \IfNoValue(TF)
• \IfValue(TF)
• \IfBoolean(TF)
with the other functions currently regarded as “experimental”. Please try all of the com-
mands provided here, but be aware that the experimental ones may change or disappear.
∗ E-mail: latex-team@latex-project.org
1
0.1 Specifying arguments
Before introducing the functions used to create document commands, the method for
specifying arguments with xparse will be illustrated. In order to allow each argument to
be defined independently, xparse does not simply need to know the number of arguments
for a function, but also the nature of each one. This is done by constructing an argument
specification, which defines the number of arguments, the type of each argument and
any additional information needed for xparse to read the user input and properly pass it
through to internal functions.
The basic form of the argument specifier is a list of letters, where each letter defines
a type of argument. As will be described below, some of the types need additional
information, such as default values. The argument types can be divided into two, those
which define arguments that are mandatory (potentially raising an error if not found)
and those which define optional arguments. The mandatory types are:
m A standard mandatory argument, which can either be a single token alone or mul-
tiple tokens surrounded by curly braces. Regardless of the input, the argument will
be passed to the internal code surrounded by a brace pair. This is the xparse type
specifier for a normal TEX argument.
l An argument which reads everything up to the first open group token: in standard
LATEX this is a left brace.
r Reads a “required” delimited argument, where the delimiters are given as htoken1 i
and htoken2 i: rhtoken1 ihtoken2 i. If the opening htokeni is missing, the default
marker -NoValue- will be inserted after a suitable error.
2
s An optional star, which will result in a value \BooleanTrue if a star is present and
\BooleanFalse otherwise (as described later).
t An optional htokeni, which will result in a value \BooleanTrue if htokeni is present
and \BooleanFalse otherwise. Given as thtokeni.
g An optional argument given inside a pair of TEX group tokens (in standard LATEX,
{ . . . }), which returns -NoValue- if not present.
G As for g but returns hdefaulti if no value is given: G{hdefaulti}.
e An optional set of embellishments, each of which requires a value. If a key is not
present, -NoValue- is returned. The returned data is a token list comprising one
braced entry per key, ordered as for the key list in the argument specification. Given
as e{htokensi}. All htokensi must be distinct. This is an experimental type.
E As for e but returns one or more hdefaultsi if values are not given: E{htokensi}{hdefaultsi}.
See Section 0.6 for more details.
Using these specifiers, it is possible to create complex input syntax very easily. For
example, given the argument definition ‘s o o m O{default}’, the input ‘*[Foo]{Bar}’
would be parsed as:
• #1 = \BooleanTrue
• #2 = Foo
• #3 = -NoValue-
• #4 = Bar
• #5 = default
whereas ‘[One][Two]{}[Three]’ would be parsed as:
• #1 = \BooleanFalse
• #2 = One
• #3 = Two
• #4 =
• #5 = Three
Delimited argument types (d, o and r) are defined such that they require matched
pairs of delimiters when collecting an argument. For example
\NewDocumentCommand{\foo}{o}{#1}
\foo[[content]] % #1 = "[content]"
\foo[[] % Error: missing closing "]"
Also note that { and } cannot be used as delimiters as they are used by TEX as grouping
tokens. Arguments to be grabbed inside these tokens must be created as either m- or
g-type arguments.
Within delimited arguments, non-balanced or otherwise awkward tokens may be
included by protecting the entire argument with a brace pair
\NewDocumentCommand{\foobar}{o}{#1}
\foobar[{[}] % Allowed as the "[" is ’hidden’
These braces will be stripped if they surround the entire content of the optional argument
\NewDocumentCommand{\foobaz}{o}{#1}
\foobaz[{abc}] % => "abc"
\foobaz[ {abc}] % => " {abc}"
3
Two more tokens have a special meaning when creating an argument specifier. First,
+ is used to make an argument long (to accept paragraph tokens). In contrast to
LATEX 2ε ’s \newcommand, this applies on an argument-by-argument basis. So modify-
ing the example to ‘s o o +m O{default}’ means that the mandatory argument is now
\long, whereas the optional arguments are not.
Secondly, the token > is used to declare so-called “argument processors”, which
can be used to modify the contents of an argument before it is passed to the macro
definition. The use of argument processors is a somewhat advanced topic, (or at least a
less commonly used feature) and is covered in Section 0.9.
When an optional argument is followed by a mandatory argument with the same
delimiter, xparse issues a warning because the optional argument could not be omitted
by the user, thus becoming in effect mandatory. This applies to o, d, O, D, s, t, e, and
E type arguments followed by r or R-type required arguments, but also to g or G type
arguments followed by m type arguments.
4
0.4 Verbatim arguments
Arguments of type v are read in verbatim mode, which will result in the grabbed argument
consisting of tokens of category codes 12 (“other”) and 13 (“active”), except spaces, which
are given category code 10 (“space”). The argument is delimited in a similar manner to
the LATEX 2ε \verb function, or by (correctly nested) pairs of braces.
Functions containing verbatim arguments cannot appear in the arguments of other
functions. The v argument specifier includes code to check this, and will raise an error if
the grabbed argument has already been tokenized by TEX in an irreversible way.
By default, an argument of type v must be at most one line. Prefixing with + allows
line breaks within the argument.
Users should note that support for verbatim arguments is somewhat experimental.
Feedback is therefore very welcome on the LaTeX-L mailing list.
Users should note that support for default arguments referring to other arguments
is somewhat experimental. Feedback is therefore very welcome on the LaTeX-L mailing
list.
5
0.7 Declaring commands and environments
With the concept of an argument specifier defined, it is now possible to describe the
methods available for creating both functions and environments using xparse.
The interface-building commands are the preferred method for creating document-
level functions in LATEX3. All of the functions generated in this way are naturally robust
(using the ε-TEX \protected mechanism).
These commands work in the same way as \NewDocumentCommand, etc., but create en-
vironments (\begin{henvironmenti} . . . \end{henvironmenti}). Both the hstart codei
and hend codei may access the arguments as defined by harg speci. The arguments will
be given following \begin{henvironmenti}.
6
0.8 Testing special values
Optional arguments created using xparse make use of dedicated variables to return infor-
mation about the nature of the argument received.
\IfNoValueTF{-NoValue-}
will be logically false.
When two optional arguments follow each other (a syntax we typically discourage),
it can make sense to allow users of the command to specify only the second argument by
providing an empty first argument. Rather than testing separately for emptyness and for
-NoValue- it is then best to use the argument type O with an empty default value, and
simply test for emptyness using the expl3 conditional \tl_if_blank:nTF or its etoolbox
analogue \ifblank.
\BooleanFalse The true and false flags set when searching for an optional token (using s or thtoken i)
\BooleanTrue have names which are accessible outside of code blocks.
7
\IfBooleanT ? \IfBooleanTF hargument i {htrue code i} {hfalse code i}
\IfBooleanF ?
Used to test if hargumenti (#1, #2, etc.) is \BooleanTrue or \BooleanFalse. For example
\IfBooleanTF ?
\NewDocumentCommand \foo { s m }
{
\IfBooleanTF #1
{ \DoSomethingWithStar {#2} }
{ \DoSomethingWithoutStar {#2} }
}
checks for a star as the first argument, then chooses the action to take based on this
information.
\ProcessedArgument xparse defines a very small set of processor functions. In the main, it is anticipated that
code writers will want to create their own processors. These need to accept one argument,
which is the tokens as grabbed (or as returned by a previous processor function). Proces-
sor functions should return the processed argument as the variable \ProcessedArgument.
\ReverseBoolean \ReverseBoolean
This processor reverses the logic of \BooleanTrue and \BooleanFalse, so that the ex-
ample from earlier would become
\NewDocumentCommand \foo { > { \ReverseBoolean } s m }
{
\IfBooleanTF #1
{ \DoSomethingWithoutStar {#2} }
{ \DoSomethingWithStar {#2} }
}
8
\SplitArgument \SplitArgument {hnumber i} {htoken i}
Updated: 2012-02-12 This processor splits the argument given at each occurrence of the htokeni up to a max-
imum of hnumberi tokens (thus dividing the input into hnumberi + 1 parts). An error
is given if too many htokensi are present in the input. The processed input is placed
inside hnumberi + 1 sets of braces for further use. If there are fewer than {hnumberi} of
{htokensi} in the argument then \NoValue markers are added at the end of the processed
argument.
\NewDocumentCommand \foo
{ > { \SplitArgument { 2 } { ; } } m }
{ \InternalFunctionOfThreeArguments #1 }
Any category code 13 (active) htokensi will be replaced before the split takes place.
Spaces are trimmed at each end of each item parsed.
9
\TrimSpaces \TrimSpaces
Removes any leading and trailing spaces (tokens with character code 32 and category
code 10) for the ends of the argument. Thus for example declaring a function
\NewDocumentCommand \foo
{ > { \TrimSpaces } m }
{ \showtokens {#1} }
and using it in a document as
\foo{ hello world }
will show hello world at the terminal, with the space at each end removed. \TrimSpaces
will remove multiple spaces from the ends of the input in cases where these have been
included such that the standard TEX conversion of multiple spaces to a single space does
not apply.
This function is experimental.
10
\NewExpandableDocumentCommand \NewExpandableDocumentCommand
\RenewExpandableDocumentCommand hfunction i {harg spec i} {hcode i}
\ProvideExpandableDocumentCommand
\DeclareExpandableDocumentCommand
This family of commands is used to create a document-level hfunctioni, which will grab
its arguments in a fully-expandable manner. The argument specification for the function
is given by harg speci, and the function will execute hcodei. In general, hcodei will also
be fully expandable, although it is possible that this will not be the case (for example,
a function for use in a table might expand so that \omit is the first non-expandable
non-space token).
Parsing arguments expandably imposes a number of restrictions on both the type of
arguments that can be read and the error checking available:
• The last argument (if any are present) must be one of the mandatory types m or r.
• All short arguments appear before long arguments.
• The mandatory argument types l and u may not be used after optional arguments.
• The optional argument types g and G are not available.
• The “verbatim” argument type v is not available.
These functions transfer the current argument specification for the requested hfunctioni or
henvironmenti into the token list variable \ArgumentSpecification. If the hfunctioni
or henvironmenti has no known argument specification then an error is issued. The
assignment to \ArgumentSpecification is local to the current TEX group.
These functions show the current argument specification for the requested hfunctioni or
henvironmenti at the terminal. If the hfunctioni or henvironmenti has no known argument
specification then an error is issued.
11
1 Load-time options
log-declarations The package recognises the load-time option log-declarations, which is a key–value
option taking the value true and false. By default, the option is set to true, meaning
that each command or environment declared is logged. By loading xparse using
\usepackage[log-declarations=false]{xparse}
this may be suppressed and no information messages are produced.
Index
The italic numbers denote the pages where the corresponding entry is described, numbers
underlined point to the definition, all others indicate the places where it is used.
Symbols \long . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
\\ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
N
A \New... . . . . . . . . . . . . . . . . . . . . . . . . . 6
\ArgumentSpecification . . . . . . . . 11, 11 \newcommand . . . . . . . . . . . . . . . . . . 1, 4, 6
\NewDocumentCommand . . . . . . 1, 6, 6, 6, 6, 6
B \NewDocumentEnvironment . . . . . . . 1, 6, 6
\begin . . . . . . . . . . . . . . . . . . . . . . . . 6, 6 \NewExpandableDocumentCommand 1, 11, 11
\BooleanFalse . . . . . . . . . . . . 3, 3, 7, 8, 8 \NoValue . . . . . . . . . . . . . . . . . . 5, 5, 8, 9
\BooleanTrue . . . . . . . . . . . . . 3, 3, 7, 8, 8
O
C \omit . . . . . . . . . . . . . . . . . . . . . . . . . . 11
\chapter . . . . . . . . . . . . . . . . . . . . . . . . 6 options:
log-declarations . . . . . . . . . . . . . . 12
D
\Declare... . . . . . . . . . . . . . . . . . . . ... 6 P
\DeclareDocumentCommand . . . . . . . 1, 6, 6 \ProcessedArgument . . . . . . . . . . . . . . 8, 8
\DeclareDocumentEnvironment . . . . . . 1, 6 \ProcessList . . . . . . . . . . . . . . . . . 9, 9, 9
\DeclareExpandableDocumentCommand 1, 11 \ProcessorA . . . . . . . . . . . . . . . . . . . ... 8
\ProcessorB . . . . . . . . . . . . . . . . . . . ... 8
E \protected . . . . . . . . . . . . . . . . . . . ... 6
\end . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 \Provide... . . . . . . . . . . . . . . . . . . . ... 6
\end... . . . . . . . . . . . . . . . . . . . . . . . . . 6 \ProvideDocumentCommand . . . . . . . 1, 6, 6
\ProvideDocumentEnvironment . . . . . . 1, 6
G \ProvideExpandableDocumentCommand 1, 11
\GetDocumentCommandArgSpec . . . . . 11, 11
\GetDocumentEnvironmentArgSpec . 11, 11 R
\Renew... . . . . . . . . . . . . . . . . . . . .... 6
I \RenewDocumentCommand . . . . . . . . . 1, 6, 6
\IfBoolean(TF) . . . .. . . . ........ ... 1 \RenewDocumentEnvironment . . . . . . . . 1, 6
\IfBooleanTF . . . . . .. . . . ........ . 8, 8 \RenewExpandableDocumentCommand . . 1, 11
\IfNoValue(TF) . . . .. . . . . . . . . 1, 7, 7, 7 \ReverseBoolean . . . . . . . . . . . . . . . . 8, 8
\IfNoValueTF . . . . . .. . . . 7, 7, 7, 7, 7, 7, 7
\IfValue(TF) . . . . . .. . . . ........ . 1, 7 S
\IfValueTF . . . . . . .. . . . ........ . 7, 7 \ShowDocumentCommandArgSpec . . . . 11, 11
\ShowDocumentEnvironmentArgSpec . 11, 11
L \SplitArgument . . . . . . . . . . . . . . . . . 9, 9
log-declarations (option) . . . . . . . . . . 12 \SplitList . . . . . . . . . . . . . . . . . . 9, 9, 9
12
T \TrimSpaces . . . . . . . . . . . . . . . . 10, 10, 10
TEX and LATEX 2ε commands: \typesetnormalchapter . . . . . . . . . . . . . 6
\ifblank . . . . . . . . . . . . . . . . . . . . . 7
tl commands: V
\tl_if_blank:nTF . . . . . . . . . . . . . . . 7 \verb . . . . . . . . . . . . . . . . . . . . . . . . . 2, 5
13