# `Ascii.ExRatatui.Viewer`
[🔗](https://github.com/houllette/ascii_art/blob/main/lib/ascii/ex_ratatui/viewer.ex#L2)

A terminal app that plays pieces full screen: space pauses, ← and →
step through the pieces, q quits.

    Ascii.ExRatatui.Viewer.run(piece: "donut")

It is an `ExRatatui.App`, so it runs under a supervisor too, and over
ExRatatui's other transports. Served over SSH, each client gets a viewer
of its own:

    children = [
      {Ascii.ExRatatui.Viewer,
       transport: :ssh, port: 2222, auto_host_key: true, app_opts: [piece: "matrix-rain"]}
    ]

then `ssh -p 2222 localhost`. Each viewer plays its piece with an
`Ascii.Player`, so keys still work while a scene sets up, and a piece
that closes a loop is drawn once a cycle.

## Options

  * `:piece` - the piece to play first: a slug or a module. Defaults to
    the first of `:pieces`.
  * `:pieces` - the pieces ← and → step through, in order. Defaults to
    every piece. A `:piece` not among them comes first.
  * `:options` - options for `:piece`, whenever it plays; the others
    play with their own.
  * `:fps`, `:paper`, `:color`, `:ink`, `:gradient` - as for
    `Ascii.new/2`, for every piece: `ink: "#7fdbca"` draws each piece
    in one ink in that colour.
  * `:parts` - colours for parts (see `Ascii.Parts`): `true` for
    those each piece suggests, or a map for `:piece`'s, whenever it
    plays.
  * `:mode`, `:ground` - how colour is drawn, as for `Ascii.ExRatatui`:
    `mode: :ansi256` for terminals without 24-bit colour.
  * `:interactive` - keys go to a piece that can be used first (see
    `Ascii.handle_event/2`): a file tree's arrows, a form's typing.
    Those it has no use for are the viewer's, so q still quits unless
    the piece takes it; Ctrl-C always does.

        Ascii.ExRatatui.Viewer.run(piece: "file-tree", options: %{walk: false}, interactive: true)

and `ExRatatui.App`'s own, such as `:transport`, `:name` and
`:test_mode`.

Only available when `ex_ratatui` is a dependency.

# `run`

```elixir
@spec run(opts :: keyword()) :: :ok | {:error, term()}
```

Plays in this terminal until it is quit, for a script or `mix run`:

    mix run -e 'Ascii.ExRatatui.Viewer.run(piece: "donut")'

Takes the options above.

---

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