# `Yarnspinnex.Interpreter`
[🔗](https://github.com/atavistock/yarnspinnex/blob/main/lib/yarnspinnex/interpreter.ex#L1)

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.

# `choose_error`

```elixir
@type choose_error() :: :no_options | :invalid_option | :option_disabled
```

# `cursor_error`

```elixir
@type cursor_error() :: :stale_script | :unknown_node | :invalid_position
```

# `event`

```elixir
@type event() ::
  {:line, Yarnspinnex.Line.t(), Yarnspinnex.Cursor.t()}
  | {:command, String.t(), [term()], Yarnspinnex.Cursor.t()}
  | {:options, [Yarnspinnex.Option.t()], Yarnspinnex.Cursor.t()}
  | {:done, Yarnspinnex.Cursor.t()}
```

# `check_cursor`

```elixir
@spec check_cursor(Yarnspinnex.Script.t(), Yarnspinnex.Cursor.t()) ::
  :ok | {:error, cursor_error()}
```

Checks that `cursor` points at a valid position in this version of `script`.

# `choose`

```elixir
@spec choose(
  Yarnspinnex.Script.t(),
  Yarnspinnex.Cursor.t(),
  term(),
  Yarnspinnex.Vars.collection()
) ::
  {:ok, Yarnspinnex.Cursor.t()} | {:error, choose_error()}
```

Picks the option at `index` from the option group the cursor is paused on.

# `step`

```elixir
@spec step(
  Yarnspinnex.Script.t(),
  Yarnspinnex.Cursor.t(),
  Yarnspinnex.Vars.collection()
) :: event()
```

Runs from `cursor` until the next line, command, option group, or end of the script.

---

*Consult [api-reference.md](api-reference.md) for complete listing*