Reference

Lexicon

Source Lexicon.cs, lexicon.md

The lexicon is the file you write beside your features to say what their words mean: who acts, the machines, their states, triggers, guards and trains, and the views. It is line-based, in the style of Gherkin, one file per features directory, named <anything>.lexicon, and it may hold any number of machines. trax machine from-gherkin elaborates it to the glossary, filling in everything that follows a rule, and writes that glossary.json beside the IRs, where it is committed and checked like the other derived files. The glossary's keys are in the feature files reference. Why the lexicon is the source and the glossary is derived is ADR 0059, and the grammar the reader is held to is conformance/lexicon.md.

A lexicon is read by the .NET tooling only. Every engine reads the glossary.

Version: 1
 
Actor: customer "a customer"
  Roles: customer
 
Machine: order
  Owned by: customer
  Started by: "has an order"
  Context: approved is a boolean, may be empty
 
  State: Draft     "is a draft"
  State: Paying    "is being paid for"
  State: Placed    "is placed"
  State: Declined  "was declined"
 
  Trigger: Order "orders {loaves} loaves for {subject}"
    Input: loaves is an integer
    Sets: loaves
  Trigger: Place "places {subject}"
 
  Guard: hasLoaves when loaves is more than 0
    Holds: "has something in it"
    Fails: "has nothing in it"
 
  Runs: Bakery.Trains.ITakePayment in Paying
    Input: amount from loaves
    Returns: approved is a boolean
    Outcome: "the payment goes through"     when approved is true
    Outcome: "the payment is declined"      when approved is false
    Outcome: "the payment cannot be taken"  when it fails
 
View: "orders"
  Reads: order
  Field: status from order's state
    Label: Draft  "Not sent"

Lines

  • Every line starts with a keyword from the tables below. A line that does not is a problem, and the nearest keyword is suggested (Outcom: gives Outcome:). There is no free text: a note goes after #.
  • Whitespace outside quotes never matters. Indentation and lined-up columns are for reading; trax lexicon format lays a lexicon out one way.
  • Phrases, labels, names of views and text values are quoted. Inside quotes, \" is a quote, \\ a backslash and # is text. Any other backslash is a problem.
  • A keyword belongs under one kind of block and attaches to the nearest one still open, closing every block opened after it. A machine's Context: lines therefore come before its first State:: after one, Context: belongs to that state.
  • Each keyword has one form, given in the tables. A line not in that form is a problem that names the form.
  • A name, phrase or outcome is defined once. A second definition is a problem naming the first one's line.
  • A lexicon with any problem gives no glossary. Every problem names its lexicon line, including the ones the glossary reader and derivation find later.
  • A second lexicon in the same directory is a problem, and so is a glossary.json beside a lexicon.
  • Version: 1 is the first line; only notes and blank lines come before it. A keyword's colon may be written against the word after it (Version:1), and a lone surrogate anywhere on a line is a problem.

Top level

KeywordFormGlossary
Version:Version: 1, the first lineversion
Trains in:Trains in: Bakery.Trainsthe namespace of every train a Runs: line names without a dot
Actor:Actor: customer "a customer"actors.customer.noun
Constant:Constant: EmptyBoard is "...."nothing: a value used by name in Sets:, Example: and Starts with:
Type:Type: Squarenothing: a type a field names (is a Square)
Machine:Machine: answer-sheet, or Machine: shop "the shop"machines.<id>; its noun, or a system machine's name, is the id with hyphens as spaces unless quoted
View:View: "the shop sign"views.<name>

Under Actor:

KeywordFormGlossary
Roles:Roles: Clerk, Managerroles
Any signed-inalone on its lineanyAuthenticated: true

An actor has one of the two, and is refused with both.

Under Type:

KeywordFormGlossary
Values:Values: "S", "M", "L", or a range: Values: A to J, each followed by 1 to 10a string field with that enum (A1 to J10)
Has:Has: postcode is a string, may be empty, one per fieldan object field with those fields

A type is one or the other. A range is two letters from A to Z (or a to z) or two whole numbers, and a Values: line gives at most 1000 values. A record that contains itself, directly or through another type, is a problem at its Has: line.

Under Machine:

KeywordFormGlossary
Owned by:Owned by: member, clerkownedBy, a string for one actor and a list for several
Systemalone on its linesystem: "<id>/main"
System at:System at: flight/tx101system: "flight/tx101"
System keyed by:System keyed by: shopId, tillIdsystem: { "keyedBy": [...] }
Started by:Started by: "has an order"start
Begins in:Begins in: Draftinitial; without it, the first state
Version:Version: 2version
Migrates from:Migrates from: 1 with Shop.Migrations.CheckoutFromVersion1migrations."1"
Differentialalone on its linedifferential: true
Starts with:Starts with: items is [], receipt is nothinginitialContext, each value typed by its field
Context:a field (see Fields), or Context: target may be emptycontext (see What is inferred)
State:State: Paid "is paid", or State: Paid "is paid" committedstates.Paid
Trigger:Trigger: Fire "fires at {square} in {subject}"triggers.Fire
Guard:Guard: hasLoaves when loaves is more than 0guards.hasLoaves.rule
Runs:Runs: FireShot in Firing, or Runs: Bakery.Trains.ITakePayment in Payinginvokes.Firing, train <Trains in>.IFireShotTrain or the dotted name as written
Link:Link: "the receipt for {subject}" to order by orderIdlinks
Rule:Rule: checkout:priced with Shop.Rules.TotalIsPriced, example truerules
Reduction:Reduction: checkout:add-item with Shop.Rules.AddItem, example items is ["bread"]reductions

A machine has Owned by: or one of the three System lines, and is refused with both or neither.

Under State:

KeywordFormGlossary
Requires:Requires: receipt is not empty, a rule (see Rules)requires
Context:a field, one per line; no may be empty formthe state's own context, in place of the machine's

Under Trigger:

KeywordFormGlossary
Input:a field, one per line: Input: square is a Squareinput
Sets:Sets: target to square, loaves, shots to EmptyBoardreduce: set; a bare field is set from the input of its name
Keepsalone on its linereduce: keep
Clearsalone on its linereduce: clear
Resetsalone on its linereduce: reset
Reduces with:Reduces with: checkout:add-itemreduce: custom
Guarded by:Guarded by: hasLoavesguard
Effect:Effect: Shop.Effects.ICharge, key prefix "checkout:charge", example "rcpt-1"; the key prefix may be left outeffect

A trigger reduces once: one of Sets:, Keeps, Clears, Resets and Reduces with:.

Under Guard:

KeywordFormGlossary
Holds:Holds: "has something in it"holds
Fails:Fails: "has nothing in it"fails

A guard that reads only the trigger's input may leave both out.

Under Runs:

KeywordFormGlossary
Takes:Takes: fleet, shots, ownerinput, each from the context field of its name; owner from $owner
Input:Input: square from target, or Input: memberId from the ownerinput.square: "target", input.memberId: "$owner"
Returns:Returns: result is a string, shots is a stringoutput, sorted by name
Stores:Stores: shots, result as yourShota set step on every done outcome: yourShot from the output result
Sets:Sets: shots to EmptyBoarda set step on every done outcome, from an output field, a constant or a value
Example:Example: fleet is "f-1", board is EmptyBoardeach done outcome's examples entry, where its when does not give the value
Outcome:Outcome: "the shot misses" when result is "miss", or when it is done, when it fails, when it is called offoutcomes: done with its when, done, failed, cancelled

Given the train assemblies (trax machine from-gherkin --trains, or Lexicon.Read with assemblies), Takes: and Returns: are optional and read from the train's records. A Returns: field that differs from the record's in type, format, nullability or values is a problem at its line; one that agrees is what the glossary holds, so it is the same with the assemblies and without. A train whose types do not load is a problem at its Runs: line.

Under View: and Field:

KeywordFormGlossary
Reads:Reads: order, shopreads; a system machine at a fixed key is read at it
Field:Field: status from game's state, Field: shot from game's yourShotfields.status.from: "game.state"
Label: (under Field:)Label: Dealing "Dealing the fleets"labels.Dealing

Fields

A field is <name> is a <type>, then clauses after commas:

ClauseGlossary
may be emptynullable: true; without it a field is never null
at least 1, at most 12minimum, maximum
one of "S", "M", "L"enum
where <rule>, lastconstraints
TypeWritten
Plaina string, a number, an integer, a boolean, an object, a list
String formatsa uuid, a date, a time, a date-time, a date-time-offset, a duration, a uri, a char
Nameda Type: by name: a Square, an Address
Lista list of <type>: a list of strings, a list of Squares
Mapa map of <type> to <type>: a map of string to integer. Keys that are any string write no keys shape, as the host writes a Dictionary<string, T>.

Nothing nests inside a line: a record in a list is a named type. Returns: holds several fields on one line, separated by commas; a comma followed by a clause goes on with the field before it.

Rules

A rule is one comparison, or several joined by and or by or. A line that mixes the two is a problem: a rule that needs both is a custom rule, written in C#, named in the lexicon (checkout:priced holds) and bound by a Rule: line.

ComparisonIR rule
receipt is present, receipt is absentpresent, absent
receipt is not emptynonEmpty
receipt is a stringofType (string, number, integer, boolean, list, object)
tags is a list of stringsarrayOf
size is one of "S", "M"oneOf
result is "hit"oneOf with the one value: the IR has no string equality
approved is trueboolEquals
loaves is 3, is at least 3, is at most 3, is more than 3, is less than 3compare: eq, gte, lte, gt, lt
tags has 3 items, has at least 3 items, has fewer than 3 itemscount
code is 3 characters long, is at least 3 characters longlength
checkout:priced holdscustom

A field is read from the context in Requires:, Guard: and where, and from what the train returns in an outcome's when. input item and context item say which where it is not the default: a guard on the trigger's input reads input item is not empty. The IR rules are in the IR format.

Values

A value is typed by the field it is for. A string is quoted, a number and an integer bare (an integer whole), a boolean true or false, a list in brackets (["bread", "rye"]), and nothing is null, allowed only where the field may be empty. A bare name is a constant, or, in Sets: and Stores:, a field of what the line reads from. A value of the wrong type is a problem at its line, and so is a value in another case than the field's declared one ("m" for "S", "M", "L"), since rules compare values as written. A list nests at most 32 deep, and a constant that comes back round to itself is a problem at its line. An object field takes no value in a lexicon; set it with a custom reduction.

What is inferred

WhatHow
A machine's nounIts id with hyphens as spaces, unless quoted after the id. A system machine's name likewise, and a system machine at a fixed key is at <id>/main unless System at: says otherwise.
The contextEach field a Context: line declares, in the order written, then each field something writes and no line declares, sorted by name, with the type of what writes it: a trigger's input, a train's output, a constant or a value. A written field is never null unless Context: <field> may be empty says so. Two writes that disagree on the type are a problem at the second.
A train's full nameA dotted name as written; a plain one is I<Name>Train in the namespace of Trains in:, which is then required.
A train's inputEach Takes: field from the context field of its name, owner from the instance owner, and each Input: line as written. Given the train assemblies, every input the record has and no line writes is wired by the same rule.
A train's outputFrom Returns:, sorted by name; given the train assemblies, from the output record as the host reads it.
A done outcomeStores what Stores: and Sets: say. Its example is the value its when pins for each output field, then the Example: line's. An output field with neither is a problem at the outcome.
A view's readsA read of a system machine at a fixed key carries the key.

The generated glossary.json is committed, so a reviewer can see what was filled in. It is written in one canonical form (keys in schema order, maps in declared order, two-space indent, a trailing newline), so from-gherkin --check compares it byte for byte.

SDK Reference

Lexicon | Feature files | Write machines as features | trax CLI