@spec describe(anim :: Ascii.Animation.t()) :: String.t()

What the animation shows, in words, for a screen reader: told from its options by a piece that can (Ascii.Piece.describe/1), such as a gauge's reading or a boot log's steps; else the piece's name and note. The Phoenix players and components label their picture with it.

iex> Ascii.new!("donut") |> Ascii.describe()
"donut: a lit torus turning on two axes, after donut.c"

@spec frame(
  anim :: Ascii.Animation.t(),
  t :: number(),
  opts :: [{:now, DateTime.t()}]
) ::
  {Ascii.Frame.t(), Ascii.Animation.t()}

The frame at t seconds of play time, and the animation to draw the next one from. Pieces with state (simulations, mostly) step by how far t moved since the last frame, so play t forward.

opts may give :now, a DateTime for pieces that read the clock.

@spec handle_event(anim :: Ascii.Animation.t(), event :: event()) ::
  {:ok, Ascii.Animation.t()} | :ignore

An event for a piece that can be used: a file tree's cursor moving or a folder opening, a form's box ticked, a date picked. The piece takes up what it changes as new options (as put_options/2 would), so what was chosen is in anim.options (a tree's cursor, a form's values). :ignore if the piece has no use for the event, or takes none at all.

{:ok, anim} = Ascii.handle_event(anim, {:key, "down"})
anim.options.cursor

@spec loop(anim :: Ascii.Animation.t()) ::
  {:ok, [Ascii.Frame.t()], fps :: number()} | :error

One cycle of a piece that closes a loop (see Ascii.Meta): its frames from t = 0, evenly spaced through the period, and the rate to show them at, the animation's own or as near as a whole number of frames allows. Played over and over, they are the piece, so a player can draw a loop once and repeat it rather than draw every frame anew.

The period is measured with the piece's default options and frame rate. With others, which can change it (a longer text takes longer to scroll), the frames of a second cycle are drawn too, and the loop stands only if they match the first. :error means the piece is to be drawn frame by frame.

iex> {:ok, frames, fps} = Ascii.new!("elixir") |> Ascii.loop()
iex> {length(frames), fps}
{150, 30}

@spec meta(piece :: piece()) :: {:ok, Ascii.Meta.t()} | {:error, :unknown_piece}

A piece's Ascii.Meta.

@spec meta!(piece :: piece()) :: Ascii.Meta.t()

Like meta/1, raising for an unknown piece.

@spec new(piece :: piece(), opts :: keyword()) :: {:ok, Ascii.Animation.t()} | error()

Starts playing a piece.

Options

• :options - the piece's own options, a map or keyword list, checked against its defaults (see Ascii.Options).
• :fps - frames a second for stream/2 and players, 0 to 60. Defaults to the piece's own.
• :paper - the picture is dark ink on a light ground, so shaded pieces flip their ramps. Defaults to false. A coloured piece drawn in colour over its own ground takes this from the ground instead, as upstream.
• :color - draw coloured pieces in colour (true, the default) or as text in one ink.
• :ink - the colour of a piece drawn in one ink, where it is shown in colour: "#rrggbb", or a CSS variable ("var(--accent, #7fdbca)") for a page, or several colours (a list, or comma-separated) for a gradient across the picture. Without it, the renderer's own ink. A coloured piece drawn in colour keeps its palette. See Ascii.Ink.
• :gradient - which way several inks run: :horizontal (the default), :vertical or :diagonal.
• :parts - colours for the parts of a piece in one ink that knows them (its meta's parts): a map of part names to colours, or true for the ones it suggests (for a light page, with :paper). Over the :ink, or the renderer's own. See Ascii.Parts.

@spec new!(piece :: piece(), opts :: keyword()) :: Ascii.Animation.t()

Like new/2, raising on an error.

@spec part_at(
  anim :: Ascii.Animation.t(),
  frame :: Ascii.Frame.t(),
  x :: integer(),
  y :: integer()
) ::
  {Ascii.Parts.name() | nil, String.t()} | nil

The part of the frame at column x, row y (see Ascii.Parts), and the text of its run there: {"file.ex", "ascii.ex"} for a file in a tree, {"status.warn", "[ WARN ]"} in a boot log, {nil, text} for cells in no part. nil outside the frame, or for a piece that does not know its parts. For a click: which file, which bar, which day.

@spec pieces(opts :: [{:category, Ascii.Meta.category()}]) :: [String.t()]

Every piece's slug, sorted. category: keeps one category.

iex> "night-coast" in Ascii.pieces(category: :scenes)
true

@spec put_options(anim :: Ascii.Animation.t(), options :: map() | keyword()) ::
  {:ok, Ascii.Animation.t()} | error()

New options for a playing animation, for live data in a dashboard or a terminal UI: a reading for a gauge, the latest samples for a sparkline.

options are checked as new/2 checks them and merged over the animation's own, so only what changes need be given. A piece that can carries its state over (a gauge's needle swings from where it was to the new reading); any other starts afresh with the new options. A piece whose size follows its options takes its new size.

anim = Ascii.new!("gauge", options: %{value: 40})
anim = Ascii.put_options!(anim, value: 72)

@spec put_options!(anim :: Ascii.Animation.t(), options :: map() | keyword()) ::
  Ascii.Animation.t()

Like put_options/2, raising on an error.

@spec render(piece :: piece(), t :: number(), opts :: keyword()) ::
  {:ok, String.t()} | error()

One frame of a piece as text, from a fresh start. Takes the options of new/2, and :now.

iex> {:ok, text} = Ascii.render("spinners")
iex> text |> String.split("\n") |> length()
13

@spec render!(piece :: piece(), t :: number(), opts :: keyword()) :: String.t()

Like render/3, raising on an error.

@spec resolve(piece :: piece()) :: {:ok, module()} | {:error, :unknown_piece}

The module for a piece, given its slug or a module that implements Ascii.Piece (registered or not).

@spec still(piece :: piece(), opts :: keyword()) :: {:ok, Ascii.Frame.t()} | error()

Frame 0 of a piece: what a page shows before it plays, and what a reader who prefers reduced motion sees. Takes the options of new/2, and :now.

With the piece's default options it is drawn once and kept for the life of the VM, so later calls have it at once: a scene takes up to a second to set up, and a page that shows stills, or a player's first render, pays for that once rather than on every request. A piece that reads the clock is drawn every time, as are other options. An :ink and :parts are laid over the kept frame, so every ink shares it.

iex> {:ok, frame} = Ascii.still("elixir")
iex> {frame.cols, frame.rows, frame.t}
{38, 28, 0.0}

@spec stream(piece :: piece(), opts :: keyword()) ::
  {:ok, Enumerable.t(Ascii.Frame.t())} | error()

The piece's frames as a lazy stream, one every 1/fps seconds from 0. A still (fps 0) gives one frame. Takes the options of new/2.

iex> {:ok, frames} = Ascii.stream("spinners")
iex> frames |> Enum.take(3) |> Enum.map(& &1.t)
[0.0, 0.08333333333333333, 0.16666666666666666]

@spec stream!(piece :: piece(), opts :: keyword()) :: Enumerable.t(Ascii.Frame.t())

Like stream/2, raising on an error.

@spec upstream_commit() :: String.t()

The upstream commit this port follows.