ifeval Directive
Content between ifeval
and endif
gets included if the expression inside the square brackets evaluates to true.
ifeval::[{sectnumlevels} == 3]
If the `sectnumlevels` attribute has the value 3, this sentence is included.
endif::[]
The ifeval
directive does not have a single-line or long-form variant like ifdef
and ifndef
.
Unlike ifdef
and ifndef
, you cannot terminate a specific ifeval
directive using its complement.
For example, the following ifeval
block is not valid:
ifeval::[<condition>]
conditional content
endif::[<condition>]
You can only terminate the previous ifeval
directive using an anonymous endif::[]
directive, as shown here:
ifeval::[<condition>]
conditional content
endif::[]
If you’re mixing ifeval
directives with ifdef
or ifndef
directives, you should always terminate the ifdef
and ifndef
directives by name (endif::attribute-name[]
) so the ifeval
directive does not get terminated prematurely.
Anatomy
The expression consists of a left-hand value and a right-hand value with an operator in between.
ifeval::[2 > 1]
...
endif::[]
ifeval::["{backend}" == "html5"]
...
endif::[]
ifeval::[{sectnumlevels} == 3]
...
endif::[]
// the value of outfilesuffix includes a leading period (e.g., .html)
ifeval::["{docname}{outfilesuffix}" == "main.html"]
...
endif::[]
Values
Each expression value can reference the name of zero or more AsciiDoc attribute using the attribute reference syntax (for example, {backend}
).
Attribute references are resolved (substituted) first. Once attributes references have been resolved, each value is coerced to a recognized type.
When you expect the attribute reference to resolve to a string, that is, a sequence of characters, enclose that side of the expression in quotes. For example:
ifeval::["{backend}" == "html5"]
Whereas if you expect the attribute to resolve to a number, you do not need to enclose the expression in quotes. In this case, the values will be compared as numbers. The same rule applies to boolean values.
The following values types are recognized:
- number
-
Either an integer or floating-point value.
- quoted string
-
Enclosed in either single (
'
) or double ("
) quotes. - boolean
-
Literal value of
true
orfalse
.
How value type coercion works
If a value is enclosed in quotes, the characters between the quotes are preserved and coerced to a string.
If a value is not enclosed in quotes, it is subject to the following type coercion rules:
-
an empty value becomes nil (aka null).
-
a value of
true
orfalse
becomes a boolean value. -
a value of only repeating whitespace becomes a single whitespace string.
-
a value containing a period becomes a floating-point number.
-
any other value is coerced to an integer value.
Operators
The value on each side is compared using the operator to derive an outcome.
==
-
Checks if the two values are equal.
!=
-
Checks if the two values are not equal.
<
-
Checks whether the left-hand side is less than the right-hand side.
<=
-
Checks whether the left-hand side is less than or equal to the right-hand side.
>
-
Checks whether the left-hand side is greater than the right-hand side.
>=
-
Checks whether the left-hand side is greater than or equal to the right-hand side.
The operators follow the same rules as operators in Ruby. |