spw.quest · a guide to Spw · install
A small language for the shape of a thought.
Put one together#
~door(morning)[closed]{hinge, frame, key}
~potentialKeep a path open without taking it.( )sceneWhere it happens.[ ]modeWhich lens you are using.{ }definitionWhat belongs together inside it. 3 parts
1 write
Scene: (morning)
Passes.
No marks and no braces: Spw keeps these as words.
2 act
Scene: (threshold)
Passes.
~potential Keep a path open without taking it.
3 hold
Scene: (threshold)
Passes.
[ ]mode Which lens you are using.{ }definition What belongs together inside it. 3 parts
4 name
Scene: (desk)
Passes.
#>vibration A frame address: the name this page answers to, so other pages can point here.
5 point
Scene: (kitchen)
Passes.
@perspective Say who is looking, and from where.~potential Keep a path open without taking it.
6 ask
Scene: (kitchen)
Passes.
?wonder Open a question you can close again.!action Commit a move so its consequence can be seen.[ ]mode Which lens you are using.{ }definition What belongs together inside it. 1 part
7 grow
Scene: (repository)
Runs in a terminal. In a repository with the workbench mounted, both commands should exit 0. They run in a terminal; this page does not run them.
Install the workbench, or give an agent the recipe; it ends with this panel.
Read one page#
A journal entry, written in Spw. Every line is still readable as a note.
#>morning_pages
#:journal #!sunday
@yesterday: ~"./2026-09-27.spw"
^"entry"{
noticed = `the dream kept circling back`
wonder = `why the same door every time`
next = #[`one page`, `the walk`]
}[reg=facet]
#>morning_pages- A frame: the name this file answers to. Other files can point here.
#:journal #!sunday- A layer line: what kind of writing this is, and a tag for this one.
@yesterday: ~"./2026-09-27.spw"- A perspective held as potential: yesterday's page, reachable but not pulled in.
^"entry"{ … }- Ascension over a definition: the parts inside are one entry you can inspect whole.
noticed = `…`- Configuration: a value kept under a name. Backticks hold a phrase as written.
next = #[ … ]- Vibration over a mode bracket: a set, two things to do next.
[reg=facet]- A mode after the braces: read this entry as a facet, a property sheet.
Twelve sigils#
Each operator has a reader's name, which is how you think with it, and a runtime behavior, which is what the interpreter does today. They are kept separate on purpose: a name is not a promise about evaluation.
-
potential
~Keep a path open without taking it.
Runtime: Defers its first argument.
-
wonder
?Open a question you can close again.
Runtime: Returns the second argument when the first is true.
-
action
!Commit a move so its consequence can be seen.
Runtime: Returns its first argument.
-
value
*Mark what carries weight here.
Runtime: Writes and returns a collapsed first argument.
-
ground
.Come back to the local default.
Runtime: Reads a property path, or the base value.
-
ascension
^Lift parts into one relation you can inspect.
Runtime: Wraps its arguments as one integrated value.
-
vibration
#Name a structure so it can be found again.
Runtime: Reduces its arguments into a register.
-
perspective
@Say who is looking, and from where.
Runtime: Observes its first argument through a named observer.
-
subject
&Name what the relation is about.
Runtime: Merges its arguments into one register.
-
configuration
=Keep this here, under this name.
Runtime: Writes its first argument to a register.
-
measure
%Compare, weigh, or level the field.
Runtime: Measures a named or focused register.
-
substrate
$Name what carries the charge: time, money, memory, attention.
Runtime: Materializes a register's metadata.
Four ways to hold things#
Brace pairs are containers. Read together, they make a sentence: <concept>(scene)[mode]{definition}, what it is about, where, through which lens, and what belongs inside.
< >concept What this is about.( )scene Where it happens.[ ]mode Which lens you are using. 3 hold 6 ask{ }definition What belongs together inside it. 3 hold 6 ask
Operators and containers compose: #[…] is a set, .{…} is a property sheet.
You might find it interesting if…#
- People who wonder why languages are shaped the way they are. Each sigil is a small claim about what a word is doing. The claims are argued in the open, in the repository's theory files.
- People who enjoy symmetry. Open and close, before and after, prefix and postfix. Four brace pairs, and operators that compose with them into register frames like #[…] and .{…}.
- People who like plugins and IDEs. A parser, a CLI, and a language server. Plain-text files gain frames, references, and structure an editor can navigate.
- People who wonder about maintained software. The workbench is kept like a garden: pinned revisions, a doctor command, and plans that say what changed and why.
- People who journal. A page stays a page. Spw only adds handles, so last Tuesday's note can be found, linked, and read again.
The shape it came from#
The difficulty was not having language for what I was thinking about, so I could not tell when a thought was ready to set down. Spw gives a thought somewhere to land: one character says what a word is doing, braces say what belongs together, and a thought can be set down whole instead of chased.
It started in 2017, alongside reading about how people learn from text and helping with research in an adult learning lab. Part of it was wanting language to share what I was learning, in a place where I could keep learning what I wanted to. The question it keeps asking is about cognition: where do two understandings stop sharing ground, and what would help them share more?
And it wonders about geometry: how a mind represents the thoughts it holds, what shape a circuit of thought might take on a page, and how findings from different fields could sit side by side in one form you can read.
It is not built for anyone in particular. It has been designed with care, and it has turned out to be useful, most of all toward a culture where media literacy can grow across generations.