# yarnspinnex v0.3.0 - API Reference

## Modules

- [Yarnspinnex](Yarnspinnex.md): Parses Yarn Spinner dialogue into a `Yarnspinnex.Script` (plain data, safe to cache) and runs
it one event at a time: `step/3` returns the next line, command, or option group along with an
updated `Yarnspinnex.Cursor`, and `choose/4` answers an option group. Nothing blocks.
- [Yarnspinnex.Analysis](Yarnspinnex.Analysis.md): Static walks over parsed statements, for compile-time checks and tooling. `bodies/1` is the one
place that knows how statements nest; `flatten/1` and the walks built on it follow from that.

- [Yarnspinnex.Cursor](Yarnspinnex.Cursor.md): A position in a running dialogue: the current node, the path into it, the variables the
dialogue owns (keyed by bare name, so `$gold` in a script is `"gold"` here), and the fingerprint
of the node it is in. Plain data with no reference to the script itself and none of the
host's context, so it can be persisted (`:erlang.term_to_binary/1`), copied, and resumed later.

- [Yarnspinnex.Functions](Yarnspinnex.Functions.md): Built-in Yarn Spinner expression functions. Game-specific functions belong in a
`Yarnspinnex.HostFunctions` module passed to `Yarnspinnex.compile_string/2`.

- [Yarnspinnex.HostFunctions](Yarnspinnex.HostFunctions.md): Behaviour for the game-specific functions a script may call, beyond `Yarnspinnex.Functions`.
- [Yarnspinnex.Interpreter](Yarnspinnex.Interpreter.md): Advances a `Yarnspinnex.Cursor` through a `Yarnspinnex.Script` one event at a time. Statements
with nothing to show the host (`<<set>>`, `<<declare>>`, `<<if>>`, `<<jump>>`) are absorbed
inside `step/3`, so every result is a line, a command, an option group, or the end.

- [Yarnspinnex.Line](Yarnspinnex.Line.md): One line of dialogue as returned by `Yarnspinnex.step/3`: the speaker, the text with its
interpolations applied, and the `#tags` written after it. `id` is the value of the `#line:`
tag when present - Yarn's localization key for the line.

- [Yarnspinnex.Mermaid](Yarnspinnex.Mermaid.md): Renders a compiled script as Mermaid flowchart source: `node_graph/1` draws one box per node
with an edge per `<<jump>>`, and `flowchart/2` draws every line, choice, and branch inside
each node with edges following control flow between them.

- [Yarnspinnex.Node](Yarnspinnex.Node.md): A single parsed Yarn node: its title, the source line its header starts on, its headers, and
its statement body.

- [Yarnspinnex.Ops](Yarnspinnex.Ops.md): Operator semantics for `Yarnspinnex.Interpreter`: `binop/3` for every binary operator except
`and`/`or` (those short-circuit in the interpreter), `negate/1` for unary minus, `get_field/2`
for `.` access, and `to_text/1` for how values render inside dialogue text.
- [Yarnspinnex.Option](Yarnspinnex.Option.md): One choice in a `->` option group, as returned by `Yarnspinnex.step/3`. `index` is what
`Yarnspinnex.choose/4` takes; `enabled?` reflects the option's trailing `<<if>>` and is false
for choices that should be shown but cannot be picked. `tags` and `id` come from the `#tags`
written after the option, as on a `Yarnspinnex.Line`.

- [Yarnspinnex.Parser](Yarnspinnex.Parser.md): Splits a Yarn source string into nodes (`title: ...` header, `---` body
separator, `===` terminator) and parses each node's body.

- [Yarnspinnex.Parser.Body](Yarnspinnex.Parser.Body.md): Parses the lines inside one Yarn node (between `---` and `===`) into a tree of statements
consumed by `Yarnspinnex.Interpreter`. Every statement and option ends with the source line it
came from; consecutive `->` options are folded into one `{:options, ...}` statement.

- [Yarnspinnex.Parser.Expression](Yarnspinnex.Parser.Expression.md): Parses a Yarn expression (as found inside `{...}` interpolation, `<<if
...>>`, `<<set ... = ...>>`, and command arguments) into a small, plain
data AST that `Yarnspinnex.Interpreter` evaluates against the cursor's
variables. Tokenizing is delegated to `Yarnspinnex.Parser.Lexer`; this
module only builds the AST from the resulting tokens.

- [Yarnspinnex.Parser.Lexer](Yarnspinnex.Parser.Lexer.md): Tokenizes a Yarn expression source string. Pure source-to-tokens - no
knowledge of expression grammar or the AST; that lives in
`Yarnspinnex.Parser.Expression`.

- [Yarnspinnex.Projection](Yarnspinnex.Projection.md): A host-built view of game state that dialogue is allowed to read. `fields` holds the readable
values; `source` keeps a reference to whatever it was projected from, for the host's own use.
Dialogue reads `fields` and can never reach `source`.

- [Yarnspinnex.Script](Yarnspinnex.Script.md): A parsed Yarn script ready to run: nodes indexed by title, which one `Yarnspinnex.start/2`
should enter, the `Yarnspinnex.HostFunctions` module its calls resolve against, and a
fingerprint per node that cursors carry so a stale one is caught. Plain data - safe to cache
(in ETS, a map, wherever) across dialogue turns.

- [Yarnspinnex.Vars](Yarnspinnex.Vars.md): Name lookup shared by the interpreter and `Yarnspinnex.Ops`: `$player` finds `"player"` or
`:player` in a map or `Yarnspinnex.Projection`, string key first. A keyword list is accepted at
the top level only, as context (`lookup!/1`) or vars (`normalize/1`); nested values are maps.

- Exceptions
  - [Yarnspinnex.CompileError](Yarnspinnex.CompileError.md): Why a script could not be compiled: a parse failure, or a validation failure such as a jump to
a missing node. `line` (1-based, in the source string) and `node` locate the problem when known.

  - [Yarnspinnex.RuntimeError](Yarnspinnex.RuntimeError.md): Raised by `Yarnspinnex.step/3` and `Yarnspinnex.choose/4` when a statement cannot run: a type
error in an expression, a host function that failed, a cursor that does not fit the script, or
a script that loops without ever producing an event. `node` and `line` locate the statement;
`path` and `index` are the cursor position for cases with no statement to point at.