Other Macros

Macros That Can Evaluate To Non-Boolean Values

Most of Allowl's macros only evaluate to a boolean result. This is true of the following:

• Numeric_Macro_ArrayCount – Counts the elements of an array
• Array_Macro_Filter – Filters the elements of an array
• Macro_Select – Selects the property of an object
• Macro_Raw – Coerces an expression to its literal value

Numeric_Macro_ArrayCount

The Array Count macro takes an array of anything as its first parameter. If this is the only parameter, the return value of this macro is the whole number count of elements in the array.

The macro accepts an optional second parameter prefixed with the key "by" and a value consisting of a boolean expression. The boolean expression may use the It_Environment_Variable "$it" to perform an evaluation on each element of the array. If this evaluation is true for a given element of the array, that element is counted. If false, that element is not counted.

Array_Macro_Filter

The Filter macro requires two parameters:

• an array of anything – value following the macro name key
• a boolean expression – value following the key named "by"

The boolean expression may use the It_Environment_Variable "$it" to perform an evaluation on each element of the array. The macro returns an array that includes only those elements of the input array for which the boolean expression evaluates to true.

Macro_Select

The Select macro retrieves a specified property from a JSON object. It accepts two parameters:

• any expression – value following the macro name key specifies a property of an object
• a JSON object – the key named "of" followed by a JSON object expression from which a property is to be retrieved

The second parameter is optional and, if not specified, it will be substituted with the Runtime_Environment_Variable "$runtime" by default.

If the first parameter evaluates to a string, it will be interpreted as a property name. If it is an array of strings, it will be interpreted as series of nested property names specifying a path to the desired property.

The Select macro is one of two ways to access the properties of an Environment_Variable. The alternative applies the "$" prefix to the environment variable and appends a series of one or more property accessors using the "." operator followed by a property name.

Macro_Raw

The Raw macro takes a single parameter that can be anything. It evaluates to the value of the this parameter without allowing the parameter itself to be evaluated.

This macro can be used to ensure that a JSON object meant as a value is not evaluated as an expression. It will safely assure a specific, literal value without having to think twice about whether this extra measure of protection is actually necessary.

Credits

Grammar consistency testing and generation of images representing elements of the Allowl grammar were aided by Gunther Rademacher's open source Railroad Diagram Generator program. An online version is hosted at bottlecaps.de/rr/. The software was used with permission and according to its Apache License terms.