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 '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!hwith 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 writtennote{ {{hours}} }.
#Operator precedence
From tightest to loosest:
- brackets, and calls such as
round(x); ^, right to left:{{2^3^2}}is 512;- unary
-:{{-3^2}}is −9; *,/and implied multiplication,2k, left to right: withkat 3,{{6 / 2k}}is 9;+and-, left to right;- comparisons,
<<=>>==!===!==, andin; comparisons do not chain; not;and;or;->, left to right.
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;1e3is1times a namee3. - Text:
"night"or'night'. - Boolean:
true,false. - Date:
2026,2026-10,2026-10-21, without spaces.2026 - 10 - 21is a subtraction. - Colour: a hue,
teal, or one of its tones,light-teal,dark-teal;neutral; or a fixed colour,hex(0064FA)orrgb(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 value, a dataset cell and a loop's value are plain text until used, and each becomes what its use needs:
(hours: 6)is a number inhours * 2and a word in prose.(unit: km)inunit + 1fails: “kmis not a number and cannot be used in arithmetic”.- Two such values compare as text: with
(a: 2.0; b: 2),a = bis false anda = 2is true. - Under
<, such a value is read as a number, else a date. - A
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(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.
(item: - first) spliced on its own line is a paragraph, not a list item. Inline markup does survive: (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:
Rateandrateare one name. - A run of letters is one name:
kxis notk * x. Writek 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,
(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 onetrue.
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;logandln— 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 unlesswithis given, at the"start"unlesssideis"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 — “
stringhas no<”; - arity — “
roundtakes 1 or 2 arguments, not 3”; - a parameter — “
format's second argument is one of comma, percent, scientific, fixed, notmoney”; - missing brackets — “
sinis 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 < cfails, “comparisons do not chain — writea < b and b < c”.=,!=— loose: numbers by value, text ignoring case and spacing.Night = nightis true.==,!==— exact.Night == nightis false.x in 0..5— both ends included.0..<5excludes 5,0<..5excludes 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 constant there must be braced, hidden: a > {{limit}}. '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 byin. Withhoursat 6,{{hours -> (..5: short; otherwise: long)}}is long; - interval — the position of
xalong 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 withxin 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
constant: with(lengths: (..5: short; otherwise: long)),{{6 -> lengths}}is long. - A constant may hold a whole application:
(parties: #d.party (DEM: blue; otherwise: red)), thencolour: 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
otherwisegives 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
(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
cannot read each other;payabove needs its own. - A bare key is
true:(overtime). bodyanddetailare reserved: “bodyis a reserved constant name”.- No implicit attribute:
@let:xfails, “@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: “
ais defined through itself”.
#Attributes, bindings and parameters
- Template attributes, inside a
@definetemplate. They shadow constants of the same name (Modularity). - Loop bindings, inside a
. Over a dataset the binding is a row, androw.cellreads a cell: in:#runs,{{i.km * 2}}. Outside such a loop: “iis not a dataset row, so it has no memberkm— onlyover 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 attributenosuch”. #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
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:
when:— “is decided while the document compiles and cannot depend on#f.slope”;n:— “: nis decided while the document compiles and cannot take the bound value#f.slope”;- code lines and
cells — “… which cannot be written into a literal body”; $…$maths — “the plain-text body oflatexis decided while the document compiles”;- every other attribute — “attribute
size: astringposition 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.