Reference option

Reference options accept a variable name rather than a literal value, allowing an imported template to read and write a variable from the caller's scope.

By default, imported templates run in their own scope and cannot access the caller's variables. A reference option creates a shared binding between the two scopes, so the imported template can read the current value and write back changes that the caller will see.

Example

Consider a utility template that converts a variable to uppercase. It receives the variable name through the target option and uses bracket notation to access it:

{  "$schema": "https://schema.croct.com/json/v1/template.json",  "title": "To uppercase",  "description": "Converts a variable value to uppercase.",  "options": {    "target": {      "type": "reference",      "description": "The variable to convert."    }  },  "actions": [    {      "name": "define",      "variables": {        "${options.target}": "${this[options.target].toUpperCase()}"      }    }  ]}

Here, options.target holds the variable name (e.g., "greeting"), and this[options.target] reads the current value of that variable. Because target is a reference option, the imported template shares access to the caller's variable.

The following template imports to-upper.json5 to transform a greeting:

{  "$schema": "https://schema.croct.com/json/v1/template.json",  "title": "Greeting",  "description": "Prints an uppercase greeting.",  "options": {    "name": {      "type": "string",      "description": "The name to greet.",      "default": "World"    }  },  "actions": [    {      "name": "define",      "variables": {        "greeting": "Hello, ${options.name}!"      }    },    {      "name": "import",      "template": "./to-upper.json5",      "options": {        "target": "greeting"      }    },    {      "name": "print",      "semantics": "info",      "message": "${this.greeting}"    }  ]}

npx croct@latest use template.json5 --name Alice

This prints HELLO, ALICE!. The imported template reads this.greeting from the caller's scope, converts it to uppercase, and writes the result back. If target were a regular string option instead, the imported template would not be able to access or modify the caller's variable.

Properties

The following list describes the properties for reference options:

type

string

The option type. Always reference for reference options.

description

string

A description displayed when prompting the user.

default(optional)

string

The default variable name used when the user does not provide one.