Engine

5.1. Definition files🔗

A definition file is read in two steps: its text to a YAML tree (Yaml.parse), the tree to what it defines (blockOf): under entities, each entity's name and its section, with the entity's key field, event types and rules (sectionOf). Under views, the views (Views, viewOf). An example is on the overview.

The files use a fixed subset of YAML: block mappings and sequences indented by spaces; plain scalars, which may continue on more indented lines; 'single' and "double" quotes; one-line flow collections of plain scalars ({ a: text }, [A, B], {}); comments with #. What is outside the subset doesn't load, and the error is a LoadError with the line. The subset on small texts:

Text

Result

Claim

b: [A, and B] on two lines

rejected, line 1: a flow collection is one line

Flow collections are one line of plain scalars.

a: b and c on the next line

the text b c

A plain scalar may continue on more indented lines.

entity: a # note, key: b#c

a and b#c: # starts a comment after a space

A hash starts a comment after a space or at the start of a line.

"x\ny"

rejected: only \" and \\ are escapes

Quotes know only the escapes quote and backslash.

a tab in the indentation

rejected, with its line

A tab in the indentation is rejected.

&x, *x, !t, |, >

rejected, with their line

Anchors aliases tags and block scalars are rejected.

[[A]], { A: [x] }

rejected: no nested flow collections

Nested flow collections are rejected.

key: | with its block

the file does not load, the error names line 3

A file outside the subset does not load and the error carries the line.

What the keys mean:

🔗def
Spec.keyOf (fs : List DefFile) (e : String) : Except LoadError (Option String)
Spec.keyOf (fs : List DefFile) (e : String) : Except LoadError (Option String)

The key field name of an entity: given by at least one file if it has events, the same in every file that gives it, not an engine field name and not a field of the entity's events (in a request it sits next to them).

🔗def
Spec.combine (fs : List DefFile) : Except LoadError Defs
Spec.combine (fs : List DefFile) : Except LoadError Defs

The files together: per entity (in order of first mention) its event types and its rules from all its files, in file order.

An entity's sections may be spread over several blocks and files: its events in one, its rules in another. They are merged as if written in one section.

A file may also hold several blocks, separated by lines that are exactly --- (YAML's multi-document stream), each block in the format above (loadText). A --- line may also come before the first block. Two entities in two blocks of one file:

entities:
  guest:
    key: guest_id
    events:
      GuestRegistered: { name: text }
---
entities:
  room:
    key: room_no
    events:
      RoomCleaned: { cleaner: text }