format

Substitutes named placeholders in a text template with values from a record.

The format function provides a powerful and safe way to construct text from a template by substituting named placeholders with corresponding values from a record or map. It is a fundamental tool for generating dynamic messages, logging information, or creating formatted output.

This operation is conceptually similar to string interpolation or printf-style functions found in many other programming languages.

Signature

from sourceText format values
from sourceText format (values, numDelimiters)

Parameters

• sourceText: The input text (text) containing placeholders. By default, placeholders are denoted by single curly braces, e.g., {name}.
• values: A record or map ({text -> value }) whose keys match the names of the placeholders in the sourceText. Values from this record will be converted to text and substituted into the template. Keys in the record that do not correspond to a placeholder in the text are ignored.
• numDelimiters (optional): An integer between 1 and 9 (number) specifying the number of opening and closing curly braces required for a placeholder. The default value is 1. For example, a value of 2 would match placeholders like {{name}}.

Returns

A new text value (Text) with all matching placeholders replaced by their corresponding values. The original sourceText and values record are not modified.

Examples

1. Basic Placeholder Substitution

The most common use is to replace simple named placeholders in a string literal.

import 'text'
from 'Order {orderId} was placed by {customerName}.' format {
  orderId = 'ORD-001',
  customerName = 'Alex'
}

Result: The placeholders are replaced with the values from the record.

'Order ORD-001 was placed by Alex.'

2. Using a Record Variable

In practice, the values often come from a variable that holds a record, such as the result of a database query or an API call.

import 'text'
let order = {
  id = 'ORD-002',
  amount = 49.50,
  status = 'SHIPPED'
}
from 'Notification for order {id}: status is now {status}.' format order

Result: The format function uses the order record to fill in the template.

'Notification for order ORD-002: status is now SHIPPED.'

3. Specifying Custom Delimiters

The optional numDelimiters parameter allows you to change the placeholder style. This is particularly useful when the source text might already contain single curly braces for another purpose (e.g., JSON content) or to integrate with templates that use a different convention (e.g., Mustache-style {{placeholder}}).

import 'text'
let template = 'Invoice for {{user}} - Amount: {{amount}}'
let data = { user = 'Casey', amount = 199.99 }
from template format (data, 2)

Result: The function correctly identifies and replaces the double-brace placeholders.

'Invoice for Casey - Amount: 199.99'

4. Behavior with Unmatched Placeholders

For robustness, if a placeholder is found in the sourceText but no corresponding key exists in the values record, the placeholder is removed in the final text. This prevents unexpected errors from incomplete data.

import 'text'
let userData = {
  firstName = 'Jordan'
  // Note: 'lastName' is missing
}
from 'Welcome, {firstName} {lastName}!' format user_data

Result: The missing placeholder {lastName} is treated as an empty value.

'Welcome, Jordan !'