Source style

#Multiline nodes and multiline attribute groups

A .chalk file is read and edited by hand, and the two forms of an attribute group are chosen to match the node carrying them. A node written entirely on one line takes semicolons. A node whose body or detail spans lines takes a group that spans lines too, one attribute per line — including where there is only one attribute, so that the closing brackets of a nested construct always read the same way.

curve(f: sin(x); colour: blue; dashed)

cue{
    curve(f: sin(x); colour: blue)
}(
    in: 1
)

#Bare booleans, written last

Booleans take the bare-word shorthand — runnable, dashed, !fill, !show ticks — never : true or : false. They are written last in every group, the document header included, so a group reads as values and then flags.

#Spaced names in attribute groups

A hyphenated attribute name is written with spaces inside a group — x domain, y axis label, in duration, header row, highlight rows, show background — which reads as English in a group that is already one key per line. It applies to keys only: a binding carries the canonical spelling through to the renderer, so #plot.x-domain keeps its hyphen and #plot.x domain resolves to nothing.

#Seconds and milliseconds

A duration of a second or more is written in seconds — 1.4s, 2s, 2.9s — and anything shorter in milliseconds — 400ms, 900ms. Both suffixes are accepted wherever a time is written; the convention exists so a scene's timings can be compared down a column without converting them first.

#Bulk data and repeated expressions

Rows of data live in a @data block, even where they are read once. A hundred readings written inline turn the environment holding them into a wall of digits, and the structure of the graph disappears behind its own numbers; the block is also where a reader looks to find what a document's numbers actually are. Columns bind where they are read — one column per axis on scatter, line and polygon.

A long expression, and anything written more than once, is declared in @let and spliced back with {{name}}. That is also what keeps a number appearing in two places — a curve and the code beside it — from being edited in one of them.

@data#samples{
    x     | y
    0.31  | 0.18
    0.52  | -0.09
    -0.66 | 0.76
}

@let(
    surface: exp(-(x^2 + y^2) / 2) / (2 * pi)
)

scene{
    …
}[
    canvas.graph{
        heatmap(expression: {{surface}}; colour: temperature)
        scatter(x: #samples.x; y: #samples.y; colour: grey)
    }
]

#What a comment is for

// at the start of a line keeps it out of the output and @ignore does the same for a block. The comment worth writing is the one saying where a constant came from — the source of a rate, the reason for a cutoff, the year a survey was run — which is the one fact the source cannot recover on its own.