5.2 String Interpolation🔗ℹ

String interpolation starts with literal text, but it adds an escape syntax to allow an arbitrary expression that produces text to substitute in place of the escape. In Rhombus, string interpolation is implemented by a combination of shrubbery notation and library functions:

• Shrubbery @ notation provides a general way to write text within {…} with minimal escaping of special characters. It also provides a general escape from (literal) text mode back to shrubbery (expression) mode; the escape form uses @.

  A @ form is desugared at the shrubbery layer, not the langauge layer; it is always equivalent to a function-call form. Text plus escapes turn into a list argument in the function call.

• str and related functions are designed to be called using @ notation. They expect a list argument containing text produced by literal strings and other values produced by arbitrary expressions.

For example, the shrubbery form

@str{Hello}

is equivalent to the shrubbery form

str(["Hello"])

Within a #lang rhombus module, both of those are a call to the str function, which simplify converts every element of the list to a string and then appends the strings.

The shrubbery form

@str{1 + 1 is @(1 + 1).}

is equivalent to

str(["1 + 1 is ", (1 + 1), "."])

which illustrates how @ acts as an escape within the literal-text {…} of an enclosing @ form.

The use of @ to start a literal-text form an to escape within literal text are actually the same @, just in (1) function-call form with a function str to call, and (2) parenthesized-expression form, with no function to call immediately after @. Another option is (3) a function to call immediately after @ and the regular arguments in parentheses after that function name. Any of those @ can be used in a consistent way both inside and outside of literal-text {…}.

> @str{1 + 1 is @(1 + 1).}

"1 + 1 is 2."

> @(1 + 1)

2

> @List{apple}

[["apple"]]

> @List(1, 2, 3)

[1, 2, 3]

> @str{1 + 1 is @str{2}.}

"1 + 1 is 2."

> @str{1 + 1 is @math.sum(1, 1).}

"1 + 1 is 2."

> @str{Text within {} is       not constrained to       a single line.}

"Text within {} is\nnot constrained to\na single line."

Within {…} after @, any character counts as literal text except @, {, and }. Even those characters can be treated as literal by using a locally unique opener-closer pair, such as |-{ and }-|.

> @str|-{The example above: @str{1 + 1 is @(1 + 1).}}-|

"The example above: @str{1 + 1 is @(1 + 1).}"

In general, an opener is either the usual { or it starts with | and ends with { with other characters in between, and the closer is formed by reversing that sequence and flipping parenthesis-like shapes. See At-Notation Using @ and At-Notation Parsing for more information on those pairs and about @ notation generally.

Functions like str.d and str.f are meant to be used with escapes inside the argument of str to format numbers.

See str.d and str.f for additional examples.

String interpolation is just one use of shrubbery @ notation. The same notation is used for writing documentation, See the source to this document, for example. creating slide presentations, and other tasks that involve lots of prose. Those many uses make shrubbery’s @ notation worthwhile.