@text Directive

The @text directive defines a text variable that can store string values.

Syntax

@text identifier = "value"
@text identifier = @embed [content]
@text identifier = @run [command]

Where:

  • identifier is the variable name (must be a valid identifier)
  • value can be a quoted string, the result of an @embed directive, or the result of an @run directive

Identifier Requirements

  • Must start with a letter or underscore
  • Can contain letters, numbers, and underscores
  • Case-sensitive
  • Cannot be empty

String Values

Text values can be defined using different quote styles:

@text simple = "Plain string"       # Double quotes
@text also_simple = 'Single quotes' # Single quotes
@text template = `Hello {{name}}`    # Template literal with variable

For multi-line strings, use template literals with the [[ and ]] delimiters:

@text multiline = [[`
  This is a
  multi-line
  string with {{variables}}
`]]

Referencing Text Variables

Text variables are referenced using the {{identifier}} syntax:

@text name = "World"
@text greeting = `Hello, {{name}}!`

Variable Interpolation

Template literals (using backticks) support variable interpolation:

  • Text variables: Hello, {{name}}!
  • Nested variables: Hello, {{user.{{userType}}}}

String Concatenation

@text first = "Hello"
@text second = "World"
@text message = {{first}} ++ " " ++ {{second}}
  • Requires spaces on both sides of the ++ operator
  • Joins string parts without adding spaces between them
  • Cannot concatenate across multiple lines

Examples

Basic text variable:

@text title = "My Document"
@text author = "Jane Smith"

Using the result of a command:

@text date = @run [date +"%Y-%m-%d"]

Embedding file content:

@text header = @embed [header.md]

Error Handling

  • Empty values are not allowed
  • Quotes must match (no mixing of quote types)
  • Circular references in variables will be detected and prevented
  • Variable resolution has a maximum depth (10 levels) to prevent infinite recursion

Notes

  • Text variables cannot have field access (use data variables for structured data)
  • Text variables can be used in template strings, commands, and data structures
  • Only backtick strings support variable interpolation