A board frozen at one instant: the board, its window and its now, every cell's component and the data it was drawn from, and the theme, as one value (spec/15 §12.2, D-150).
A snapshot draws every cell exactly as the cell would draw the same data — through the
same steps (views/2) — with no store, no feed and no process, so it can be written to
a file, sent to someone and reopened anywhere. It carries data: a bundle
(spec/15 §11) carries a board's definitions, by id, to be imported into a store and
edited; a snapshot carries each cell's component already resolved and prepared, with
the rows it showed, to be looked at. A snapshot is never imported into a store.
Take one from a running board with Visualize.Board.Server.snapshot/1, or purely from
the board, the store and the cells' pools with realise/4, the snapshot form of
Visualize.Board.realise/4. Visualize.Board.Export draws it as one SVG document, a
PNG or printed pages.
The value has a map form (to_map/1, from_map/2) and a JSON form (to_json/1,
from_json/2) stamped "$version", read under the version policy and the sanity
limits of spec/14 §9.1–§9.2 as a board is (spec/15 §2.3).
Fields
version- the schema version it was written atboard- the%Visualize.Board{}now- the board's now when it was taken, a UTCDateTime, ornilwindow- the window resolved at now,{from, to}in UTC, ornilwidth- the container width the board was drawn attheme- the%Visualize.Theme{}the cells were drawn incells- by name:chart, the prepared component (Visualize.Board.components/3);vars, its variables;slots, each slot's%{delivery, schema, status}as the board handed them to the cell, ornilbefore any data; andcrashed,nil, or the words of the reason a cell's process had died
Summary
Types
What a snapshot holds of one cell.
What a snapshot holds of one slot: as the board hands it to a cell (spec/15 §8.2).
Functions
One fault as a line a person reads, the root named snapshot, in the words of
Visualize.Chart.Validator.format/1.
The snapshot of a JSON document (spec/15 §12.3), with limits: as from_map/2 takes
them: "$version" checked and the structural limits applied before a key is decoded,
then read as from_map/2 reads. A document that does not parse, or is not an object, is
{:error, [{[], {:json, message}}]}.
The snapshot of a map (spec/15 §12.3), or every fault of it by path: the version gate
first (spec/14 §9.1), then the depth and items limits under limits:, then every
key — the board read by Visualize.Board.from_map/2, the theme by
Visualize.Chart.Theme.from_map/2, each cell's component by
Visualize.Chart.from_map/2 and each schema by Visualize.Data.Schema.new/1, with
their faults under their own paths. Every cell of the board must be in cells, and
cells must name no other.
As realise/4 with [] options.
A snapshot of a board realised purely (spec/15 §6, §12.2): Visualize.Board.realise/4
over the same arguments, every fault of it as it reports them, and on success each
cell's prepared component, its variables and its pool's sources as deliveries, with the
schema application found for each slot.
The snapshot as a JSON document stamped "$version" (spec/15 §12.3), or
{:error, {:missing_dependency, :jason}}. from_json(to_json(s)) is {:ok, s}.
The snapshot as a map of plain data (spec/15 §12.3): version, board in its map
form, now, window as nil or %{from, to}, width, theme as a theme node
(Visualize.Chart.Theme.node/1), and cells, each with its chart in a design's map
form, its vars, its slots — each a delivery's rows, window, resolution,
capped, reduced_by and version, the schema's fields as schema, and the status
— and crashed.
Every cell drawn, purely (spec/15 §12.2): %{name => %Visualize.Board.View{}}, each
the view a cell process draws of the same data as its first frame — its component
applied at its box, compiled and stepped once, the state decided and drawn — or, for a
cell that had crashed, its crashed panel.
Types
@type cell() :: %{ chart: Visualize.Chart.t(), vars: %{required(atom()) => term()}, slots: %{required(atom()) => slot()} | nil, crashed: String.t() | nil }
What a snapshot holds of one cell.
@type slot() :: %{ delivery: Visualize.Data.Delivery.t() | nil, schema: Visualize.Data.Schema.t() | nil, status: :loading | :live | :stale | {:down, String.t()} }
What a snapshot holds of one slot: as the board hands it to a cell (spec/15 §8.2).
@type t() :: %Visualize.Board.Snapshot{ board: Visualize.Board.t(), cells: %{required(atom()) => cell()}, now: DateTime.t() | nil, theme: Visualize.Theme.t(), version: pos_integer(), width: number(), window: {DateTime.t(), DateTime.t()} | nil }
Functions
@spec format_error(Visualize.Board.error()) :: String.t()
One fault as a line a person reads, the root named snapshot, in the words of
Visualize.Chart.Validator.format/1.
@spec from_json(String.t(), keyword()) :: {:ok, t()} | {:error, [Visualize.Board.error(), ...] | {:missing_dependency, :jason}}
The snapshot of a JSON document (spec/15 §12.3), with limits: as from_map/2 takes
them: "$version" checked and the structural limits applied before a key is decoded,
then read as from_map/2 reads. A document that does not parse, or is not an object, is
{:error, [{[], {:json, message}}]}.
@spec from_map(term(), keyword()) :: {:ok, t()} | {:error, [Visualize.Board.error(), ...]}
The snapshot of a map (spec/15 §12.3), or every fault of it by path: the version gate
first (spec/14 §9.1), then the depth and items limits under limits:, then every
key — the board read by Visualize.Board.from_map/2, the theme by
Visualize.Chart.Theme.from_map/2, each cell's component by
Visualize.Chart.from_map/2 and each schema by Visualize.Data.Schema.new/1, with
their faults under their own paths. Every cell of the board must be in cells, and
cells must name no other.
@spec realise(Visualize.Board.t(), Visualize.Board.store(), %{ required(atom()) => map() }) :: {:ok, t()} | {:error, [Visualize.Board.error(), ...]}
As realise/4 with [] options.
@spec realise( Visualize.Board.t(), Visualize.Board.store(), %{required(atom()) => map()}, keyword() ) :: {:ok, t()} | {:error, [Visualize.Board.error(), ...]}
A snapshot of a board realised purely (spec/15 §6, §12.2): Visualize.Board.realise/4
over the same arguments, every fault of it as it reports them, and on success each
cell's prepared component, its variables and its pool's sources as deliveries, with the
schema application found for each slot.
The options are realise/4's — width: (default 1200), theme: (default
Visualize.Theme.default/0), now:, schemas:, describe: and limits:. With now:
the window is the board's resolved at it; without, a fixed window is kept and a trailing
one resolves to nil.
The snapshot as a JSON document stamped "$version" (spec/15 §12.3), or
{:error, {:missing_dependency, :jason}}. from_json(to_json(s)) is {:ok, s}.
A row's field names are kept as they were spelt, an atom or a string, by writing the rows column by column; every value is a tagged term of spec/14 §11.2.
The snapshot as a map of plain data (spec/15 §12.3): version, board in its map
form, now, window as nil or %{from, to}, width, theme as a theme node
(Visualize.Chart.Theme.node/1), and cells, each with its chart in a design's map
form, its vars, its slots — each a delivery's rows, window, resolution,
capped, reduced_by and version, the schema's fields as schema, and the status
— and crashed.
@spec views(t(), keyword()) :: %{required(atom()) => Visualize.Board.View.t()}
Every cell drawn, purely (spec/15 §12.2): %{name => %Visualize.Board.View{}}, each
the view a cell process draws of the same data as its first frame — its component
applied at its box, compiled and stepped once, the state decided and drawn — or, for a
cell that had crashed, its crashed panel.
Options
:width- the container width (default the snapshot's): each cell is drawn at its box there (Visualize.Board.boxes/2), so a snapshot redraws at any width:theme- the theme to draw in (default the snapshot's), such asVisualize.Theme.print/0for paper:system- the unit system the cells' measures are shown in (default:as_posted): the reader's, so a snapshot does not record it (spec/14 §4.4, D-156)