Phrase Algebra and Sharpee 2.0
There is still one glaring weakness in Sharpee directly related to separating logic from text emission. Sharpee is intentionally a developer-first/author-second platform and I've leaned into that design. I often use the words, "The Sharpee Way," when talking to Claude.
As an exercise I had Claude review how text is created and manipulated in Inform 6/7 and TADS and how the same capabilities could be wrought within The Sharpee Way. The review was not kind, but not completely without hope either.
I had to keep Claude from going down hacked paths several times, but finally directed it to Phrase Algebra. We want the text emission logic to be deterministic from the turn results (event messages, message IDs, and parameters). This means that everything that is needed to emit complex combinations of text, including: punctuation, pronouns, lists, numerical wording, capitalization, and grammatical person - these all need to be accounted in this as-yet designed Phrase Algebra.
This is clearly a massive breaking change to the currently functioning platform and authors can skirt all of it with clever Typescript programming, so I cut the code as v1 and v2. v1 is now a maintenance branch and main is v2.
After that initial design phase, the ADRs and plans are identified and the implementation is nearing completion.
The Phrase Algebra
This required a large set of architecture decision records all coordinated on the primary goal. Post-turn logical and deterministic text construction.
| kind | Member | Role | What it realizes | ADR |
|---|---|---|---|---|
literal | Literal | Atom | Raw author text (whitespace collapsed, or verbatim-exempt) | 192 |
noun | NounPhrase | Atom | Article + adjectives + noun, agreed as a whole | 192 |
list | PhraseList | Combinator | Group / pluralize / serial-comma join | 192 |
seq | Sequence | Combinator | Ordered join under one punctuation authority | 192 |
empty | Empty | Atom | "" — absorbed by combinators (no dangling comma) | 192 |
verb | Verb | Atom | A verb agreed in number/person with its subject | 199 |
pronoun | Pronoun | Atom | "it/them/his…" agreeing in case × number × gender | 197 |
number | Numeral | Atom | Digits, spelled words, or ordinal | 198 |
verbatim | Verbatim | Atom | Opaque text passed through untouched | 200 |
contents | Contents | Combinator | An entity's live contents, grouped as a list | 194 |
slot | Slot | Combinator | Open named append target; many sources contribute, slot owns all connective grammar | 195 |
optional | Optional | Modifier | Conditionally-present phrase | 196 |
choice | Choice | Modifier | One of several variants (seeded) | 196 |
Examples
These are examples of templates that either reside in the language provider package (lang-en-us is the default) or the author's story.
| Atom | Template | Renders |
|---|---|---|
Literal |
It is pitch black. |
It is pitch black. |
NounPhrase |
You take {the item}. |
You take the brass lantern. |
PhraseList |
You are carrying {items}. |
You are carrying a coin, a key, and a brass lantern. |
Sequence |
You unlock {the door} with {the key}. |
You unlock the oak door with the brass key. |
Empty |
The lamp is here{slot:detail}. (no contribution) |
The lamp is here. |
Verb |
The {doors} {verb:is} open. |
The doors are open. |
Pronoun |
You can't reach {pronoun:object}. |
You can't reach it. |
Numeral |
You count {number:42 word} coins. |
You count forty-two coins. |
Verbatim |
You enter the {verbatim:room}. |
You enter the Hall of Mists. |
Contents |
The box contains {contents:box}. |
The box contains a coin and a key. |
Slot |
You are in a dank cave.{slot:here} |
You are in a dank cave. A troll blocks the far passage. |
Optional |
The chest is closed{optional:locked " and locked"}. |
The chest is closed and locked. |
Choice |
{choice:greeting} the gate opens. |
With a groan, the gate opens. |
I suspect this will go through some growing pains and the syntax may find friendlier definitions, but this change gives the author the means to logically format text without concatenation logic, including being unconcerned about punctuation, capitalization, pronouns, and lists. Those just fall out naturally.
The Slot atom is the really interesting one. It allows other things to add data to an event message. So an NPC can add its own piece to an event message and that will automatically trigger extended formatting logic.
Of course this implementation may land flat and could induce a redesign, but Sharpee is still an experiment. V1.2 is very real and capable of delivering parser-based web IF, but I continue to find things to tweak and that's unlikely to change for the foreseeable future.