Expressions
Learn about the expression syntax available in templates.
Templates support dynamic values using the ${expression} syntax. Expressions use a subset of JavaScript and can appear in both keys and values throughout a template.
You can find the full list of available variables and functions in the variables and functions references.
Resolution
When a value consists entirely of a single expression, the result preserves the original type. If the expression evaluates to a number, the result is a number, not a string. This lets you pass non-string values like numbers, booleans, objects, and arrays through expressions.
If the value contains anything outside the expression, even a leading space, it is treated as string interpolation and the result is always a string.
For example, consider these two templates where the outer passes a value to the inner:
{ "$schema": "https://schema.croct.com/json/v1/template.json", "title": "Inner", "description": "Expects a number option.", "options": { "count": { "type": "number", "description": "The item count." } }, "actions": [ { "name": "print", "message": "You have ${options.count} items." } ]}{ "$schema": "https://schema.croct.com/json/v1/template.json", "title": "Outer", "description": "Passes a number to another template.", "actions": [ { "name": "import", "template": "./inner.json5", "options": { // Resolves to the number 42, not the string "42" "count": "${40 + 2}" } } ]}Running this template prints You have 42 items. because "${40 + 2}" resolves to the number 42. Writing "Total: ${40 + 2}" instead would produce the string "Total: 42", and the CLI would report the error:
Expected value of type number for option count, but got string.Operators
Expressions support the following operators:
| Category | Operators |
|---|---|
| Arithmetic | +, -, *, /, %, ** |
| Comparison | ==, !=, ===, !==, <, >, <=, >= |
| Logical | &&, ||, ! |
| Nullish coalescing | ?? |
| Conditional | condition ? then : else |
Literals
The following literal types are supported:
| Type | Syntax |
|---|---|
| Strings | 'hello', "world" |
| Numbers | 42, 3.14 |
| Booleans | true, false |
| Null | null |
| Arrays | [1, 2, 3] |
| Objects | {key: 'value'} |
| Regex | /pattern/flags |
Property access
You can use dot or bracket notation to access properties:
"source": "${project.path.source}","name": "${options['name']}"Built-in API
Expressions support a subset of JavaScript methods and properties. See below for the full list available for each value type.
Strings
| Name | Description |
|---|---|
| length | The number of characters in the string. |
| slice | Extracts a section of the string. |
| indexOf | Returns the index of the first occurrence of a value. |
| match | Matches the string against a regular expression. |
| matchAll | Returns all matches of a regular expression. |
| replace | Replaces the first match of a pattern. |
| replaceAll | Replaces all matches of a pattern. |
| includes | Checks whether the string contains a value. |
| startsWith | Checks whether the string starts with a value. |
| endsWith | Checks whether the string ends with a value. |
| toLowerCase | Converts the string to lowercase. |
| toUpperCase | Converts the string to uppercase. |
| repeat | Repeats the string a given number of times. |
| split | Splits the string into an array of substrings. |
Arrays
| Name | Description |
|---|---|
| length | The number of elements in the array. |
| slice | Returns a shallow copy of a portion of the array. |
| join | Joins all elements into a string. |
| includes | Checks whether the array contains a value. |
| indexOf | Returns the index of the first occurrence of a value. |