evokeExamples · 01 of 06
Your Mac does everyday things at a word.
Thirteen reflexes, installed with one line. Set the volume, turn Wi-Fi off, start a timer, lock the screen, draft a mail. Each is a small program with its manifest, and you can read every file. This example runs today, on a Mac.
The request and the result
01Three sentences, three outcomes.
A volume change runs at once. A less certain one asks, and learns from your answer. A restart asks every time. Every line is what the terminal printed.
- 1Sure enough, so it ran. «40 percent» is a number read from the sentence and checked against the range 0 to 100. At 0.93, over the write bar of 0.8, nothing asked.
- 2«kill» meant off at only 0.72. Under the bar, so evoke asked. Typing
trecorded the phrase in your overlay, then ran. The next time, it is sure. - 3Sure at 0.97, and it still asked. A restart is destructive. No number and no
flag skips that question.
[2]means you said no.
The operations
02A manifest and a body, per reflex.
This is volume, one of the thirteen. The manifest says what it does and what it asks.
The body is thirty lines that run one AppleScript line. The other twelve look the same.
reflex = 1 description = """ Set the output volume. A percentage of the maximum; 0 is silent.""" not_for = ["muting and unmuting", "screen brightness", "one app's volume"] tags = ["sound"] effect = "write" confirm = "Set the volume to {level}?" run = "volume.mts" [args.level] ask = "How loud, in percent?" pick = "number" range = [0, 100] [examples] "set the volume to 40 percent" = { level = "40 percent" } "volume 15" = { level = "15" } "turn the sound up to 80" = { level = "80" } [tests] "make it 100 percent loud" = { level = "100 percent" } "turn the volume down a bit" = { level = false } "mute the sound" = false "set the brightness to 50" = false
// Set the output volume through AppleScript: `set volume output volume <0–100>`. import { execFile } from "node:child_process" import { promisify } from "node:util" import type { Reflex } from "./reflex.d.ts" const exec = promisify(execFile) export default (async ({ level }, { signal }) => { const percent = Math.round(level) // The one value written into AppleScript source: an integer, so it can only ever be digits. if (!Number.isInteger(percent)) throw new Error(`level ${level} is not a number`) if (process.platform !== "darwin") throw new Error("runs on macOS only") try { await exec("osascript", ["-e", `set volume output volume ${percent}`], { signal }) } catch (error) { if (signal.aborted) throw signal.reason throw new Error(said(error) ?? "the volume did not change") } return `volume ${percent}%` }) satisfies Reflex /** What a failed command said on stderr, when it said anything; else nothing, and the caller's own words stand. */ function said(error: unknown): string | undefined { const text = typeof error === "object" && error !== null && "stderr" in error ? error.stderr : undefined return typeof text === "string" && text.trim() !== "" ? text.trim() : undefined }
# a word per folder; the value is its path $ evoke vocab places add desktop "The desktop." --value ~/Desktop # a word per site; the value is its URL $ evoke vocab sites add github "GitHub." --value https://github.com # where the note reflex appends its lines $ evoke config note file ~/notes.txt
- 1The manifest is the whole interface. A description, the near misses, one input read as a number with a range, and the sentences that teach.
- 2The body says no to another platform first. Then it runs
osascriptand returns one line. A body that fails prints why, and exits 1. - 3Three reflexes wait for your words.
open,visitandnotestay inactive until a folder, a site or a file is named. The other ten work at once.
The thirteen, in one table: The collection →
One boundary
03A value outside its range never reaches the program.
The manifest gives level a range of 0 to 100. A sentence can choose a value. It
cannot make one up, and it cannot push one past its range.
$ evoke "set the volume to 150 percent" How loud, in percent? 150 percent is outside 0–100 > 40 volume level="40" 0.93 volume 40%
evoke asked the input's own question, with the reason on the line. The answer was checked the same way. Ask, in the manual →
Before you run it
04What this example needs.
- macOSThe collection's programs are for a Mac. The binary itself also runs on Linux.
- Node 24 or newerEleven of the thirteen run a JavaScript file.
openandtrashrun a program the Mac has. - git
evoke addfetches the collection from GitHub at its newest tag. - A classifier keyIn
TYPESAFE_API_KEY, orOPENJEV_API_KEYwithadapter = "openjev". Its provider bills the use. - Your words, for three of themA folder, a site, a notes file. Optional, and one line each.