Macaw.Data.Operations.Option (macaw_data v0.5.3)

Copy Markdown View Source

An operation's option declaration and the check of a value against it (spec/04 §1.3).

An option is %Option{type: type, default: value, required: boolean, frame: :width | nil, doc: text}. A required option has no default; an optional one's default is filled in when a node omits it. frame: :width makes it frame-bound: a node may write "plot", the plot's width in whole pixels, resolved before the step runs (spec/04 §3.2).

TypeHolds
:fielda column name, a string or an atom
{:list, type}a list of type
{:pair, type}a two-element list of type
:namethe name of a column a step adds, a string or an atom
:number, {:number, low, high}any number; one in low..high, both inclusive
:positivea number above zero
:integer, {:integer, min}any integer; one at least min
:power_of_twoa positive integer power of two
:booleantrue or false
{:enum, atoms}one of atoms, written as the atom or its string
{:keys, type}a fixed order: {:keys, list}, or a map whose one key is keys
{:one_of, types}a value of the first of types that holds it
:duration[n, unit], unit one of units/0 by spelling
:aggregatethe name of an aggregate in the registry, checked to its module
:termany value

No atom is ever made: an enum value or a unit is matched against the declaration's own atoms by their strings.

Summary

Types

t()
type()

Functions

check(registry, type, value)

The value as a step is given it, or {:error, reason}: {:type, type} for a value the type does not hold, {:unknown, :aggregate, name} for an aggregate the registry lacks.

units()

A duration's units and the seconds each names, in order.

Types

t()

@type t() :: %Macaw.Data.Operations.Option{
  default: term(),
  doc: String.t(),
  frame: :width | nil,
  required: boolean(),
  type: type()
}

type()

@type type() ::
  :field
  | :name
  | :number
  | {:number, number(), number()}
  | :positive
  | :integer
  | {:integer, integer()}
  | :power_of_two
  | :boolean
  | {:enum, [atom()]}
  | {:keys, type()}
  | {:list, type()}
  | {:pair, type()}
  | {:one_of, [type()]}
  | :duration
  | :aggregate
  | :term

Functions

check(registry, type, value)

@spec check(Macaw.Data.Operations.Registry.t() | term(), t() | type(), term()) ::
  {:ok, term()} | {:error, term()}

The value as a step is given it, or {:error, reason}: {:type, type} for a value the type does not hold, {:unknown, :aggregate, name} for an aggregate the registry lacks.

iex> alias Macaw.Data.Operations.Option
iex> Option.check(:term, {:enum, [:ascending, :descending]}, "descending")
{:ok, :descending}
iex> Option.check(:term, {:integer, 0}, -1)
{:error, {:type, {:integer, 0}}}

units()

@spec units() :: [{atom(), pos_integer()}]

A duration's units and the seconds each names, in order.