Data: records, collections & access

Declare data once with #name: value !! — a record { … }, a collection [ … ], or a single value — then read it from prose with @name.field.

#venue: { name: The Granary, capacity: 120 } !!

@venue.name seats @venue.capacity.

That renders The Granary seats 120. For the value model behind this — kinds, JSON mapping, coercion — see Data model.

Records

A record is key: value pairs. A key may contain spaces; the first : ends it. A value runs until the next key:, so it may hold commas.

#venue: { name: The Granary, access: step-free, via the yard, capacity: 120 } !!

@venue.name (@venue.capacity): @venue.access.

That renders The Granary (120): step-free, via the yard. Records may span lines — commas are then optional — and they nest:

#keeper: {
  name: Aldous Vane
  history: { years: 31, incidents: 2 }
} !!

@keeper.name logged @keeper.history.incidents incidents in @keeper.history.years years.

That renders Aldous Vane logged 2 incidents in 31 years. A trailing comma and an empty { } are fine. A value in double quotes is always text: { author: "Boud, D." }.

Form-fill records

A value-block definition whose lines are all key: value is a record too. Keys here are lowercase identifiers.

#trip:
  city: Kyoto
  season: autumn
  nights: 6
!!

@trip.nights nights in @trip.city, @trip.season.

That renders 6 nights in Kyoto, autumn. A line that is not a field is E_MALFORMED_FORM_FIELD.

Collections

A collection is an ordered list in [ … ]. Items are separated by commas or newlines — not spaces — and may be records.

#themes: [ attention, perception, moral failure ] !!
#findings: [
  { claim: Attention precedes perception, strength: strong }
  { claim: Looking is never neutral, strength: moderate }
] !!

@themes.1, and @findings.0.claim.

That renders perception, and Attention precedes perception. — numeric segments index from 0. [ red green blue ] is one item, the text red green blue.

Scalars

In records, collections and condition values:

• -?[0-9]+(.[0-9]+)? is a number — 3, -2, 0.050.
• Exact true / false is a boolean; exact null is null.
• Anything else is text — including .5, 1e3 and +1.

Numbers keep the form they were written in:

#stats: { p: 0.050, isbn: 0262033844, version: 3.10 } !!

p = @stats.p, ISBN @stats.isbn, version @stats.version.

That renders p = 0.050, ISBN 0262033844, version 3.10.

Access

Dot paths reach into records and collections, as deep as the data goes: @keeper.history.years, @findings.1.strength. The path ends at the first character that cannot continue it, so a sentence-final period stays prose.

Keys match loosely: case, spaces, hyphens and underscores are ignored.

#keeper: { years at post: 31 } !!

@keeper.yearsAtPost or @keeper.years_at_post, but not @keeper.years at post.

<p>31 or 31, but not <span class="wit-unresolved">@keeper.years</span> at post.</p>

A space ends the path, so reach a multi-word key through its camel or snake spelling. Two keys that collapse to the same spelling are E_AMBIGUOUS_RECORD_KEY.

A missing field renders the unresolved marker shown above; the build carries on. An undefined name (@nosuch.field) is E_UNRESOLVED_REFERENCE.

Reserved fields

index, count and last are loop positions (see Iteration), so a record may not use them as field names — E_RESERVED_FIELD.

Common mistakes

• Expecting [ a b c ] to be three items — separate them with commas.
• Typing spaces into a path — @keeper.years at post reads only @keeper.years.
• Naming a field last or count — rename it (surname, total).
• Quoting an item in a collection to protect a comma — quotes are recognised in records only for now; use a list of records.

See also

Data model · Conditionals · Iteration · Interpolation & captures · Escapes