Expressions

Computing a value in {{…}}: its values and operators, the names it reads — @let constants among them — and when it is worked out, as the document compiles or as the page renders.

On this page

#Writing an expression

An expression is a calculation: values joined by operators, such as rate * hours. Chalk has one expression language, written two ways.

#Braced and bare

Braced, {{expression}}, is valid anywhere source is read: prose, headings, attribute values and lines of code. The result replaces the braces.

@let(rate: 12.5; hours: 6)

The job pays {{rate * hours}} for the day.

Result: The job pays 75 for the day.

Bare is the whole value of an attribute that takes an expression: an @if's when:, a condition such as hidden:, and a data mark's style attributes.

@if(when: hours > 4){
    A long shift.
}

The two differ only in names nothing declares. Bare, such a name is text: when: shift = night compares a constant with the word night. Braced, it is an error, “{{night}}: undefined constant night”, except beside = or ==.

#An expression as a micronode body

!name:implicit{{expression}}(attributes). A micronode's body is written in braces, !bold{…}, and an expression is written in double braces. When the expression is the whole body, the two pairs share braces: !bold{{hours}} is the micronode !bold whose body is the expression hours.

@let(hours: 6)

Total !bold{{hours}} hours.

Result: Total 6 hours. Formatting a number is not a micronode's job: it is an operator in the expression, {{format(share, "percent")}}, bound or not (Named operators).

  • The parts keep Chalk's order — head, implicit value, body, attributes. Attributes before the body, !h(colour: teal){{hours}}, leave !h with no body and the number outside it.
  • Text may sit beside the expression in the body: !bold{{{hours}} h} and !bold{Total {{hours}}}.
  • Spaces inside the outer braces are part of the body: !bold{ {{hours}} } sets a space either side of the 6 in bold.
  • A block construct has no shared form. note{{hours}} is a note containing the word hours; the expression is written note{ {{hours}} }.

#Operator precedence

From tightest to loosest:

  1. brackets, and calls such as round(x);
  2. ^, right to left: {{2^3^2}} is 512;
  3. unary -: {{-3^2}} is −9;
  4. *, / and implied multiplication, 2k, left to right: with k at 3, {{6 / 2k}} is 9;
  5. + and -, left to right;
  6. comparisons, < <= > >= = != == !==, and in; comparisons do not chain;
  7. not;
  8. and;
  9. or;
  10. ->, left to right.
Warning
Implied multiplication binds no tighter than division. 6 / 2k is (6 / 2) * k; write 6 / (2k) for the other reading.

#Values and operators

#Values

  • Number: 6, 12.5, pi, e. No exponent form; 1e3 is 1 times a name e3.
  • Text: "night" or 'night'.
  • Boolean: true, false.
  • Date: 2026, 2026-10, 2026-10-21, without spaces. 2026 - 10 - 21 is a subtraction.
  • Colour: a hue, teal, or one of its tones, light-teal, dark-teal; neutral; or a fixed colour, hex(0064FA) or rgb(0, 100, 250) (Value types).
  • List: (5, 8, 3). Interval: 0..10. Map: (..5: short; otherwise: long).

Numbers are written to 15 significant digits, so a sum reads as its decimals rather than its floating-point noise: {{1 + round(pi, 2)}} is 4.14. Round for display with round, or write it with format.

A @let value, a dataset cell and a loop's value are plain text until used, and each becomes what its use needs:

  • @let(hours: 6) is a number in hours * 2 and a word in prose.
  • @let(unit: km) in unit + 1 fails: “km is not a number and cannot be used in arithmetic”.
  • Two such values compare as text: with @let(a: 2.0; b: 2), a = b is false and a = 2 is true.
  • Under <, such a value is read as a number, else a date.
  • A @let value written as an expression, with an operator, a ->, a map, an interval, a list or a reference, is that expression wherever an expression reads it: with @let(k: 2 + 3), {{k + 1}} is 6. On its own, {{k}} is the text 2 + 3. A dataset cell or a loop's value is always text.
Warning
A value is never markup structure: @let(item: - first) spliced on its own line is a paragraph, not a list item. Inline markup does survive: @let(name: **Ada**) is bold. Constructs are passed with a @define section.

#Arithmetic

+ - * / ^ and a leading - on numbers. Values written side by side multiply: 2k, 3(k + 1), (k)(k), 2 sin(k). |x| is not supported; use abs(x). A boolean has no arithmetic: “a boolean cannot be used in arithmetic”.

#Names

  • A name is a letter followed by letters and digits, case-insensitive: Rate and rate are one name.
  • A run of letters is one name: kx is not k * x. Write k x.
  • A declared name before ( multiplies: k(x + 1). An undeclared one is a written value: rgb(0, 100, 250) is a colour, and {{total(5)}} writes total(5).
  • A name may contain a hyphen or a space, @let(shift-length: 8). It resolves only when it is the whole expression, {{shift-length}}. In arithmetic the hyphen is a minus.
@let(shift-length: 8)

A double shift is {{shift-length * 2}} hours.

[constant]`{{shift-length * 2}}`: undefined constant `shift`

#Lists, item by item

A dataset column is a list. In prose, a list is written as its items joined by , . The examples below use:

@data#runs{
    day | km
    mon | 5
    tue | 8
    wed | 3
}
  • Arithmetic and named operators pair items of lists of equal length: {{#runs.km + #runs.km}} is 10, 16, 6; {{(1, 2) + (3, 4)}} is 4, 6.
  • Unequal lengths fail: “+ needs lists of one length, and these have 2 and 3 items”.
  • A list and a single value fail; the message names the fix, an application with ->.
  • =, < and the other comparisons do not pair: (1, 2) = (1, 2) is one true.
Doubled: {{#runs.km * 2}}.

[expression]`{{#runs.km * 2}}`: `*` needs lists on every side, or none — `#runs.km` is a list and `2` is a single value; to compute with each item, apply it: `#runs.km -> _ * 2`

{{#runs.km -> _ * 2}} is 10, 16, 6 (Applying a value).

#Named operators

Named operators are written as calls, name(arguments), and the set is closed. On numbers:

  • round(x), round(x, places) — halves away from zero, round(-2.5) is −3;
  • ceil(x), floor(x), abs(x);
  • min(…), max(…) — one argument or more; clamp(x, lo, hi);
  • sin, cos, tan, asin, acos, atan, sinh, cosh, tanh — radians;
  • exp, sqrt, log10; log and ln — both natural;
  • erf, gamma, choose(n, k), factorial(n).

On text — the first argument is the value, text or a number written as text; the rest are written as strings or numbers:

  • format(x, as), format(x, as, places) — a number written as "comma" ({{format(1234567, "comma")}} is 1,234,567), "percent" ({{format(0.4567, "percent", 1)}} is 45.7%), "fixed" (two places unless given, 3.10) or "scientific" (five mantissa places unless given, 1.23450e3); separators only, never a currency symbol;
  • upper(s), lower(s), title(s) — {{title("santa cruz")}} is Santa Cruz; the first letter of each word raised, the rest lowered;
  • truncate(s, length), truncate(s, length, ellipsis) — {{truncate("internationalisation", 8)}} is interna…; the ellipsis (… unless given) counts inside the length, and shorter text is untouched;
  • pad(s, length), pad(s, length, with), pad(s, length, with, side) — {{pad(7, 4, "0")}} is 0007; one space unless with is given, at the "start" unless side is "end"; longer text is untouched.

On dates, min and max give the earlier and the later. Given a list, an operator applies to each item, {{round(#runs.km)}}, and other arguments must be lists of the same length; min and max of one list reduce it, {{max(#runs.km)}} is 8. A text operator applies to each item of its first argument alone: {{upper(#runs.day)}} is MON, TUE, WED.

Errors:

  • an operator the type lacks — “string has no <”;
  • arity — “round takes 1 or 2 arguments, not 3”;
  • a parameter — “format's second argument is one of comma, percent, scientific, fixed, not money”;
  • missing brackets — “sin is an operator written as a call and needs its arguments in parentheses”;
  • domain — “sqrt: the argument must be 0 or more”, “log: needs a positive number, not 0”, “division by zero”.

A name outside the set is not called: {{sum(#runs.km)}} writes its own text.

#Conditions

A condition evaluates to true or false.

  • < <= > >= — numbers, and dates in order. a < b < c fails, “comparisons do not chain — write a < b and b < c”.
  • =, != — loose: numbers by value, text ignoring case and spacing. Night = night is true.
  • ==, !== — exact. Night == night is false.
  • x in 0..5 — both ends included. 0..<5 excludes 5, 0<..5 excludes 0, 5.. is unbounded above.
  • and, or, not.

Beside =, undeclared words are text and may run to several: city = new york. Quote them, "new york", to be explicit.

In a mark's condition attribute, such as hidden:, a control's letter is read bare and decided as the page renders: beside slider:a(range: [0, 4]), hidden: a > 2. A @let constant there must be braced, hidden: a > {{limit}}. @if's when: reads constants bare (Control structures).

#Applying a value

x -> f passes x to f. The kind of f determines the result:

  • map — the value of the first matching key, else otherwise. A key matches by =, or an interval key by in. With hours at 6, {{hours -> (..5: short; otherwise: long)}} is long;
  • interval — the position of x along it, 0 to 1, clamped: {{4 -> 0..10}} is 0.4;
  • list — the item at x, from 1: {{2 -> (10, 20, 30)}} is 20;
  • dataset — row x, for an attribute or a loop to read (Datasets);
  • expression with the placeholder _ — evaluated with x in place of _: {{hours -> _ / 2}} is 3;
  • ramp name — in a colour attribute, a number from 0 to 1 to a colour (Styling marks from data).

Rules:

  • Chains run left to right: {{4 -> 0..10 -> 100_}} is 40.
  • The placeholder, _, is the value arriving at the nearest -> to its left. It is valid only on that arrow's right, map values included: k -> (..3: 2_; otherwise: 6). Elsewhere: “_ stands for the value on the left of -> and is only valid on its right”.
  • The right may be a @let constant: with @let(lengths: (..5: short; otherwise: long)), {{6 -> lengths}} is long.
  • A constant may hold a whole application: @let(parties: #d.party -> (DEM: blue; otherwise: red)), then colour: parties.
  • A list on the left is passed item by item and gives a list: {{#runs.day -> _ = tue}} is false, true, false.
  • No match and no otherwise gives no value. In prose that fails, “{{k -> (1: one)}} chose no value, and this position needs one”; in an attribute, the attribute takes its default.

#Names an expression reads

#Constants with @let

@let(key: value; …) declares constants.

@let(rate: 12.5; hours: 6)
@let(pay: {{rate * hours}})

Today's pay is {{pay}}.
  • Scope: after the declaration, within the enclosing construct. A scene's constants are its own.
  • Redeclaring a key replaces it from that point. A scene may shadow a document constant.
  • Keys of one @let cannot read each other; pay above needs its own.
  • A bare key is true: @let(overtime).
  • body and detail are reserved: “body is a reserved constant name”.
  • No implicit attribute: @let:x fails, “@let takes no implicit attribute — its attribute group holds the author's bindings”.
  • Out of scope or before declaration: “undefined constant”.
  • A constant that reads itself, directly or through another, fails: “a is defined through itself”.

#Attributes, bindings and parameters

  • Template attributes, inside a @define template. They shadow constants of the same name (Modularity).
  • Loop bindings, inside a @for. Over a dataset the binding is a row, and row.cell reads a cell: in @for:#runs, {{i.km * 2}}. Outside such a loop: “i is not a dataset row, so it has no member km — only @for over a dataset binds columns”.
  • Control letters, in the scene's detail: beside slider:a, label: {{2a}} follows the slider. Not in the scene's prose, which reads the control by id (Controls).

#Reading another construct

#id.member reads an attribute, a derived value or a dataset column of the construct #id, declared anywhere in the document. An attribute reads as its compiled value, default included.

The curve is drawn in {{#path.colour}}, {{#path.width}} wide.

With curve#path(expression: x^2; colour: teal) in the detail, the result is The curve is drawn in teal, 2 wide.

  • Unknown id: “unknown id #zz”.
  • Unknown member: “curve (#path) declares no attribute nosuch”.
  • #self.member, in a data mark's style attribute, reads the mark's own values: colour: #self.value -> (..3: grey; otherwise: teal).

References covers ids and members.

#Compiled and bound expressions

An expression whose values are all known when the document compiles is compiled: its result replaces it. One that reads a value the page computes, a derived attribute such as a fit's slope, is bound: it is kept and evaluated as the page renders.

  • Any expression that uses a bound value is bound: {{round(#trend.slope, 2)}}.
  • A bound number displays to four significant figures, and as a dash until its value exists.
  • A @let may hold a bound expression; the constant is bound where it is read.

#Where a bound value is refused

Bound values are accepted in prose, rich-text attributes such as label:, and bare expression attributes. Places the compiler must settle itself refuse them:

  • @if when: — “@if is decided while the document compiles and cannot depend on #f.slope”;
  • @for n: — “@for: n is decided while the document compiles and cannot take the bound value #f.slope”;
  • code lines and @data cells — “… which cannot be written into a literal body”;
  • $…$ maths — “the plain-text body of latex is decided while the document compiles”;
  • every other attribute — “attribute size: a string position takes a value known while the document compiles, and this one is finished at render”.

These places also read references in document order. A reference to a construct declared further down fails even when its member is known: “#f has not been compiled at this point — {{#…}} resolves in document order here”.

#Text operators on a live value

The text operators — format, upper, lower, title, truncate and pad — take a bound value as any operator does: the expression stays bound, and the renderer formats the live value each time it moves.

The trend gains {{round(#trend.slope, 2)}} a year.
It explains {{format(#trend.r2, "percent")}} of the variance.

Maths drawn on a canvas, such as a curve's expression:, is a separate language: Canvas expressions.

#Writing guidance

  • Source style — The conventions that keep a .chalk file legible to the next person editing it by hand.

Last updated