Checks options from outside (code, LiveView params and session, the CLI) against a piece's defaults.
Every key must name one of the piece's options. String keys are compared with the names of the defaults, so input never creates an atom. Every value must have the shape of its default:
| default | accepted |
|---|---|
| number | a number, or a string that reads as one |
| boolean | a boolean, or "true" / "false" |
| string | a valid UTF-8 string, cut to 256 characters |
nil | nil, or a number as above |
| list | a list whose entries match the default's entries (any string, if the default is empty); or JSON text for one; or, for a list of strings, comma-separated text, each entry trimmed |
| map | a map whose keys name some default entry's keys, values checked the same way |
Numbers are clamped to the piece's meta.bounds for that option, or to
±1,000,000. A bound reaches inside an option that holds lists or maps: a
range {lo, hi} holds every number within it, and a map of ranges by key
holds each map's values, %{processes: %{pid: {0, 4_294_967_295}}}; a
number with no range of its own keeps the million. Lists are cut to 256
entries.
Where a default cannot show what an option takes (an empty list that takes
numbers), the piece's meta.shapes gives an example to check against
instead: %{values: [0.0]} takes a list of numbers.
Summary
Functions
The piece's options: base (its defaults, unless given), with given
cast and merged over them.
The atom naming one of defaults' keys, given that atom or its name as a
string. Never creates an atom.
Types
@type error() :: {:error, {:invalid_option, term()}}
Functions
@spec cast(meta :: Ascii.Meta.t(), given :: map() | keyword(), base :: map() | nil) :: {:ok, map()} | error()
The piece's options: base (its defaults, unless given), with given
cast and merged over them.
The atom naming one of defaults' keys, given that atom or its name as a
string. Never creates an atom.