The manifest

reflex.toml is what the classifier reads and what the body receives. It has no name and no version. A reflex's name is whatever each user installs it as. Its version is the git tag it was fetched at.

This page says what each key is and what evoke does with it. Rules for reflexes, playbooks and collections says how to write each one so that what people type reaches the right reflex.

The whole shape

reflex = 1                                   # the format's version; frozen

description = """
Turn the lights in one room on, off, or dim them.
Ceiling and lamp lights, through the Hue bridge; their colours and schedules stay as they are."""
not_for = ["colour scenes and schedules", "asking whether a light is on"]
tags    = ["home", "lighting"]
effect  = "write"                            # always written; absent means destructive
confirm = "Set the {room} lights {state}?"
run     = "lights.mts"                       # or argv: ["hue", "set", "{room}", "{state}"]

[needs]                                      # what the body touches; absent means its own directory and TMPDIR
hosts = ["*"]                                # the bridge is on the network

[config]
bridge = "Hue bridge address"
token  = { about = "Hue API key", secret = true }

[args.room]
ask   = "Which room of the house?"
vocab = "rooms"                              # options come from the user

[args.state]
ask = "What should the lights do?"
options.on  = "Switch on."                   # options come from the author
options.off = "Switch off."
options.dim = "Lower the brightness without switching off."

[args.brightness]
ask      = "How bright, in percent?"
pick     = "number"                          # options come from the input
range    = [1, 100]
optional = true

[yields]                                     # what the returned data holds, for a later step
level = "number"

[examples]                                   # sent to the classifier
"turn on the kitchen lights"   = { state = "on" }
"dim the office to 30 percent" = { state = "dim", brightness = "30 percent" }
"bedroom lights off"           = { state = "off" }

[tests]                                      # held out, never sent
"make it darker in here"           = { state = "dim", brightness = false }
"flip the hall lights"             = { state = false }
"is the porch light still on"      = false
"set the lounge to a sunset scene" = false
"light a candle"                   = false

After reflex = 1, the keys are written in the order evoke show prints them, which is the order of the table below. Within an argument, ask comes first and its source next, then range, recent, optional and was. The arguments with takes come after the others. In TOML a plain key written below a table header belongs to that table, so the plain keys come first: rule 36.

Key by key

A result another step takes whole

A body may name what it returns: returns = "deploys". The name says what the body's data is, as a whole. A later step whose argument has takes = "deploys" receives that data as the body returned it (Arguments). Two reflexes meet when their names are equal, as two arguments share a vocabulary by naming it. Give each whole result one noun and one shape across the collection: rule 32. A reflex never returns a name it takes: a step that refines a result returns a new name, so a later step has one source. An argv body returns no data, so a reflex whose run is an argv names none, and declares no [yields] either.

What the body touches

[needs]
reads  = ["{place}"]                         # the value of an argument or a config key
writes = ["~/Downloads", "{to}"]             # under the home; or absolute, like "/tmp/out"
hosts  = ["*"]                               # the network, all of it; absent means none
runs   = ["open", "/usr/bin/plutil"]         # by name on PATH, or by absolute path

Each key is a list, and leaving the table out is the tightest declaration: the body's own directory and its private TMPDIR, nothing else. reads and writes name paths: ~/… under the home, absolute, or {name} for the value of an argument or a config key, so a folder the user names reaches the body and nothing beside it. A path names a file, or a folder with everything under it, whichever is on the disk when the body runs. A path in writes may be read too. A declared path must exist when the body runs. A body that makes a file declares its folder, and a path the machine lacks stops the run before the body starts: [needs] reads names ~/nowhere, which is not there; a folder in writes ends in the mkdir -p that makes it. hosts is all or nothing: ["*"] reaches every host, absent reaches none, and a name is refused at check. runs names programs, by name on PATH or by absolute path; each of them runs held to the same declaration, and what it asks the system to do happens outside it. The kernel holds the body to all of this: Security.

A {name} names an argument that carries a value, a word's or a typed one, or a config key; evoke check refuses one that names neither, or a flag. An entry over an optional argument left unstated is dropped. A value that is not a path, a word whose value is a name rather than a folder, refuses the run and points at the value's source: [needs] writes names {to}, whose value "desk" is not a path → evoke vocab places add desk "<meaning>" --value <path>.

A reach past the declaration ends the run with what was reached and the key, ~/secret.txt is not in [needs] reads, and a fix by where the declaration is written: this manifest's line for a local reflex; for a fetched one, evoke update --accept when upstream's declaration already allows it, else evoke remove. [needs] is contract: an overlay cannot touch it; upstream may narrow it at any tag, which is same; widening waits for the user's evoke update --accept, and is minor: Publishing.

Text rules

• Every string is clean text: no control characters, except the line feed in description, and no bidi controls. evoke refuses the rest, so a manifest can never repaint a terminal.
• Names of arguments, tags, config keys and vocabularies match [a-z][a-z0-9_]*. An argument name is also never a JavaScript reserved word, so a body can destructure it.
• Option keys are one clean line each. none and unstated are reserved.
• Unknown keys are reported by evoke check, never fatal: unknown lights: warmth is not a key this evoke reads. The schema at https://evoke.build/schemas/reflex.json is strict, so an editor flags a typo before evoke check does.

What is contract, what is wording

An argument may be renamed by declaring its former names, like was = ["state"]. Every user's overlay and call then follows. Publishing says how evoke check diffs one tag against the next.

Lint

At evoke check and evoke add, lint reports and never refuses. It flags a text or a list longer than its cap, a phrase that addresses a model, a step a plan would misread, and what a reader of the file would miss, like effect left out or fewer than three examples. Each finding names the key, and the text is yours to weigh. Diagnostics lists every line.

Next: Arguments.