Talemark operator registry

Talemark is the language inside .tale files. This is the authoritative list of its markers and operators, after the property and pronoun changes in #191 and #190. See the syntax reference for complete stories and the language-change checklist before proposing new syntax.

Status matters. Unless marked decided, not implemented, examples below describe the current compiler. This documentation does not add syntax. The implementation status section separates decisions from features you can use today.

Names and values

Story identifiers start with an ASCII letter (A-Z, a-z) or _. The remaining characters are ASCII letters, digits or _, with optional single . or - separators between groups. Separators cannot be adjacent or end a name. Names are case-sensitive. Lowercase kebab-case is a style recommendation, not a parser restriction. The scene/story naming lint diagnostics TWL001 and TWL002 are warnings about that style.

• Valid: weapon.knife, camp.arrival, _guide, north-gate, act.2.
• Invalid: 2doors, camp..arrival, north.-gate, door-, café.
• weapon.knife is one name, not a read of knife on weapon.
• Use : for access: faction:explorers-guild:name, player:hp.
• Use spaces around subtraction: var:coins - 1. var:coins-1 reads the name coins-1. A minus at the start of a numeric operand means negation: -3.

The same story-name character set applies in the compiler, manifest schema and editor grammar. Expression words such as true, false, and, or, not, has and visited have special meanings in their expression positions; a valid spelling is not a guarantee that a name is available there. C#-registered predicate and modifier names also depend on their registration contracts. The five legacy names pronoun.subject, pronoun.object, pronoun.possessive, pronoun.possessive-pronoun and pronoun.reflexive are rejected as character reads even if a stat has that name. The error names the replacement.

Reader text, quotes and escapes

Decided, not fully implemented: reader-facing text inside syntax uses double quotes. Names remain bare. "Joel's cat" is text; weapon.knife is a name. Single quotes are not a second Talemark string delimiter: apostrophes are ordinary text.

Backslash is the escape character everywhere. Inside double quotes, \" means a literal double quote and \\ means a literal backslash. In prose, \{ and \} mean literal braces. For example, the decided string "She said \"Go\"." contains She said "Go".. Image path and alt arguments implement these escapes today. These rules do not introduce a quoted choice-label spelling or a new formatting feature.

Today: expression string literals and the possessive modifier argument use double quotes, but their scanners do not decode \" or \\. Unclosed strings can produce TW1001, TW2006, or TW1004 when the enclosing brace cannot be found. Prose already supports \{ and \}. Existing scene titles, dialogue and choice labels still use their current unquoted forms: @title The door, > guide: Hello., * [Open the door] -> hall. Do not add quotes to those forms expecting them to be removed. Image calls use {image("path", "alt text")} with literal arguments; both \" and \\ are decoded there. Unknown image escapes produce TW1014. This does not change expression-string or modifier-argument decoding.

The manifest is YAML, not Talemark: YAML quoting and escaping still apply there. A Talemark expression stored in YAML must first survive YAML decoding.

Structural markers

These markers select a construct rather than taking part in arithmetic. Their precedence is structural: line directives are recognized before prose formatting; braces inside prose are recognized before bold, italic and code formatting. A code span does not hide a substitution. Each row gives its arguments and boundaries. Escaping follows the quote/prose rules above; there is no general escape for a line directive today. Do not assume that \@ or \=== escapes one.

END is the reserved divert destination that ends the story, not a scene declaration. skill-check and dc are words, not new sigils. On a choice, write * [Climb] skill-check athletics dc 14 and follow it with success: and failure: lines. Unknown names, incorrect types and malformed expressions can also produce the expression diagnostics below. See error codes for the complete messages.

Value and expression operators

Precedence numbers refer to the binding order below. Structural means the operator belongs to a surrounding construct; name means it is part of a token, not an operation. No expression operator has an escape that turns it into a name. Put literal punctuation in text, using the quoted-text rules when it is inside syntax.

Effects also use set flag:id, clear flag:id, give character item [number-expression] and take character item [number-expression]. An omitted inventory quantity is one. These are word commands, not additional sigils.

Variable assignment can introduce integer or text state without YAML declarations. Discovery is story-wide; implicit text starts empty until an assignment executes. The first declaration fixes the type and assignments copy values, not live links. See declaration ordering and inference.

Binding order

From tightest to loosest:

1. Parenthesized expressions, literals, references, has, visited(...), named predicates.
2. Unary numeric -.
3. *, /.
4. +, binary -.
5. One comparison (==, !=, <, <=, >, >=); comparisons do not chain.
6. not.
7. and.
8. or.

Arithmetic at the same level groups left to right: 8 - 3 - 1 is (8 - 3) - 1. not player:hp > 0 means not (player:hp > 0). Use parentheses when the intended grouping is not obvious. In a substitution, the value expression is evaluated before the # chain. #upper#lower applies upper case, then lower case.

Modifier arguments

The general decided shape is #name("first", "second"): commas separate double-quoted arguments. Argument values belong to the modifier; they are not globally reserved names. Each modifier validates its own supported values and reports a clear diagnostic for invalid ones. This shape is a contract for future modifiers, not permission to pass extra arguments to today’s ones.

Today, only pronoun #possessive accepts an argument: "determiner" (default, as in her book) or "independent" (as in hers). For example, {player:pronoun#possessive("independent")}. The compiler accepts one string, not a comma-separated list. Other built-in modifiers take no arguments: #capitalize, #upper, #lower, #a, and #possessive on a name. #object and #reflexive select a pronoun form and must immediately follow pronoun. Plain pronoun is the subject form; #subject is an error. See the pronoun forms table.

Completion offers finite values after #possessive( and identifies "determiner" as the default. "hers" is not an alias for "independent": it produces TW2006 pointing at the argument.

Image syntax decision

The approved form is {image("path", "alt text")}, with optional literal alt text, in every narrative-template context. It constructs media; it is not an expression function returning text. The value is the media node, with no arithmetic precedence or # chaining. Its strings decode \" and \\ once. Quoted paths can contain filename punctuation without becoming story identifiers. Existing {image:name} character access is unchanged.

The alternatives considered for #197 were @image(path | "alt"), @image("path", "alt"), a line-only @image directive, a colon form and #image. Braces give narrative insertion an explicit boundary without a new distinction between scene metadata and image content. Commas follow the argument convention instead of adding |. The line-only form unnecessarily limits authoring; : already means access, and # returns text, not media. Markdown images remain rejected, rather than supported as a second spelling. Image placement is not restricted for presentation preferences; authors control their content. Plain-string fields are a separate model boundary, not an image-specific prohibition.

Prose formatting and legacy images

These are current formatting delimiters, not a promise of general Markdown support. The formatting design is still being considered in #200.

Dotted-prefix completion

In a recognized reference position, completion filters on the whole typed name, including dots. With items weapon.knife, weapon.sword and rope, {item:weapon. offers only the two weapon.* items. The dot is part of the replacement range, not a traversal into another object. The same prefix filtering applies to scene targets, character references, stats, factions, flags and variables in their recognized positions. It does not imply completion in prose, a new declaration, or inside an arbitrary quoted string. The language server uses the shared authoring completion provider.

Implementation status

Unimplemented contracts need scoped implementation issues agreed with the project manager before coding. This registry records the gaps; it does not silently expand #197 or change the tracker.

These docs are maintained with the code in squid-farm/talewright. Found a problem? Open an issue.