Handling missing values
If you try to access a missing variable, an error will occur that terminates template processing. To handle such cases, you can use two special operators: the default value operator and the missing value test operator. These operators handles missing variables, as well as cases when a method call does not return a value. The missing variable can be top-level variable, hash sub-variable, or sequence sub-variable.
NOTE: RPL treats null values as missing values. For example, if the value of a field property is null, RPL treats it the same way as if that property did not exist. As a result, a method call that returns null is treated as a missing variable.
Using the default value operator
unsafe_expr!default_expr
or
unsafe_expr!
or(unsafe_expr)!default_expr
or
(unsafe_expr)!
The default value operator ! allows you to specify a default value when the value is missing.
Example:
${xml.animals.mouse!"No mouse."}
Assuming no variable called xml.animals.mouse exists, produces this output:
No mouse.
IMPORTANT: Undefined fields in the root namespace return an empty string. As such, they will not return the default expression value.
The default value can be any kind of expression, it does not have to be a string. For example, you can write xml.hits!0 or xml.colors!["red", "green", "blue"]. There is no restriction regarding the complexity of the expression that specifies the default value, for example you can write: cargo.weight!(item.weight * itemCount + 10).
WARNING: If you have a composite expression after the !, such as 1 + x, always use parentheses, for example ${x!(1 + y)} or ${(x!1) + y)}, depending on which interpretation you meant. This is because the precedence of ! (when used as the default value operator) is very low on the right of the expression. This means that, for example, RPL interprets ${x!1 + y} as ${x!(1 + y)} when it should mean ${(x!1) + y}.
If the default value is omitted, it will be an empty string, and an empty sequence, and an empty hash at the same time. (This is possible because RPL allows multi-type values.) This means that you cannot omit the default value if you want it to be 0 or false. For example:
(${xml.animals.mouse!})
produces this output:
()
WARNING: Due to syntactical ambiguities, <@something a=x! b=y /> will be interpreted as <@something a=x!(b=y) />, that is, the b=y will be interpreted as a comparison that gives the default value for x, rather than the specification of the b parameter. To prevent this, write: <@something a=(x!) b=y />.
Using the! operator with sub-variables
The following example:
product.color!"red"
Handles the case when the sub-variable color is missing, but not when the top-level variable product is missing. That is, the product variable must exist, otherwise template processing will terminate with an error. To avoid this situation, enclose the variable name in parentheses as shown in the following example:
(product.color)!"red"
This will handle the case when product.color is missing. In this case, if product is missing or product exists but it does not contain color, the result will be "red", and no error will occur.
When enclosed in parentheses, any component of the expression may be undefined, while without the parentheses only the last component of the expression may be undefined.
You can use the default value operator with sequence sub-variables as well:
<#assign seq = ['a', 'b']>
${seq[0]!'-'}${seq[1]!'-'}${seq[2]!'-'}${seq[3]!'-'}
produces this output:
a
b
-
-
NOTE: A negative sequence index (as seq[-1]!'-') will always cause an error.
Using the missing value test operator
unsafe_expr??
or
(unsafe_expr)??
The missing value test operator ?? determines whether a value is missing and returns either true or false.
For example:
<#if xml.animals.mouse??>
Mouse found
<#else>
No mouse found
</#if>
Assuming the variable mouse is not present, produces this output:
No mouse found
For sub-variables, the rules are the same as with the default value operator: enclose both the top-level and sub-variable in parentheses for example (product.color)??.