Macaw.Data.Operations (macaw_data v0.16.0)
View Sourcemacaw_data's own package of operations, the registry, and running them (spec/04).
The package. __members__/0 is the table operations of spec/04 §4 and the
statistics of §5, each a module implementing Macaw.Data.Transform or
Macaw.Data.Aggregate.
The registry (registry/1) is built from an explicit list of packages, this one
always among them: default closed, and a module that is merely loaded is not reachable
(spec/04 §2).
Running. validate/3 checks a list of nodes against the registry and the context,
answering every fault at once; apply/4 runs checked nodes in order over a table;
aggregate/4 reduces values by a named aggregate; outputs/4 names the columns after
every node. Each fault is {path, reason} (spec/04 §3.1) and format_error/1 words one.
iex> alias Macaw.Data.Operations
iex> {:ok, registry} = Operations.registry([Macaw.Data.Test.Ops])
iex> {:ok, table} = Operations.apply(registry, [%{op: "double", field: "v"}], [%{v: 2}], %{})
iex> Macaw.Data.Table.rows!(table)
[%{:v => 2, "double" => 4}]
iex> Operations.validate(registry, [%{op: "doubel"}], %{})
{:error, [{[0, "op"], {:unknown, :transform, "doubel"}}]}
Summary
Types
A fault: the path (a node's index, then its key; "source" and the table's path for a
source that is no table; a package and member, or a member's kind and name, for the
registry) and the reason (spec/04 §2, §3.1).
Functions
The modules of macaw_data's package: its table operations and statistics.
The aggregate named name, by spelling: {:ok, module} or :error.
The value of values by the aggregate named name, its options checked against its
declaration and every nil reading dropped: {:ok, value} or {:error, faults}, each
fault at its option's key ([] for the name itself). A reading the aggregate does not
read (Macaw.Data.Aggregate.reads/1) is {["values"], {:reads, kind}}. An aggregate
call is no step, so no path names a step index; a transform's, through apply/4, do
(spec/04 §6, macaw_data#139).
Every aggregate's name, sorted.
The nodes run in order over source, a Macaw.Data.Table or anything
Macaw.Data.Table.from/2 reads, each step's table the next one's input:
{:ok, table}, or validate/3's {:error, faults} before any step runs. A source that
is no table is Macaw.Data.Table.from/2's faults under "source". A step that refuses its input
at run time stops the run with its fault at its index (spec/04 §3.1): a reading of the
wrong kind, {[i, key], {:reads, kind}}, and the like; a transform answering something
that is not a table is {[i, "op"], :not_a_table}.
As apply/4, raising Macaw.Data.Error naming every fault.
A table's columns in order, each with its type: what outputs/2 is given.
A digest of every member's name and module, which a compile cache keys by.
One fault as a sentence.
The columns after every node, by each transform's outputs/2, over input columns
([{name, type}]): {:ok, columns} or validate/3's {:error, faults}.
The registry's packages, this one first.
The registry of this package alone (spec/04 §2), which nothing a caller passes can fail.
The registry of this package and packages, in order, each once (spec/04 §2):
{:ok, registry}, or every fault, {path, reason}: {[module], :not_a_package} for a
module that is not a package, {[package, member], :no_behavior} for a member
implementing no behavior, {[kind, name], {:named_twice, module, other}} for a name two
members of one behavior share, and {[:aggregate, name], {:step_key, key}} for an
aggregate declaring a step's key.
As registry/1, raising Macaw.Data.Error naming every fault.
Whether two readings are one value: equal, or an atom and a string spelling it, so a category is one value whichever spelling a row or a node gives it (spec/04 §4.1).
A checked step's canonical identity (spec/04 §2): the kernel's term digest of the
transform module the registry gives its name and the node validate/3 checked, its
options by their strings with defaults filled in. Two nodes that mean the same step have
one identity whatever order their options were written in, and a step whose name another
registry gives to another module has another. {:ok, digest}; only a checked node has
an identity, so a node naming no transform of the registry is
{:error, {["op"], {:unknown, :transform, op}}}, one with no "op"
{:error, {["op"], :required}}, and one holding a term that is not data (a function, a
PID, a reference, a port, an improper list) {:error, {path, :not_data}}, its path in
the node.
As step_digest/2, raising Macaw.Data.Error naming the fault.
The keys of the steps that name an aggregate, which an aggregate may not declare.
A table of rows with columns, in their order and of their types, each read from a
row by either spelling (Macaw.Data.Table.get/2): how a member that works on rows
answers the table its outputs/2 names.
The transform named name, by spelling: {:ok, module} or :error.
Every transform's name, sorted.
Every node checked (spec/04 §3.1): {:ok, checked}, each node's options by their
strings with defaults filled in, enum values their atoms, a named aggregate its module
and a frame-bound "plot" the frame's width in whole pixels; or {:error, faults},
every fault of every node, ordered by path.
Types
@type fault() :: {[non_neg_integer() | String.t() | atom() | term()], term()}
A fault: the path (a node's index, then its key; "source" and the table's path for a
source that is no table; a package and member, or a member's kind and name, for the
registry) and the reason (spec/04 §2, §3.1).
Functions
@spec __members__() :: [module()]
The modules of macaw_data's package: its table operations and statistics.
@spec aggregate(Macaw.Data.Operations.Registry.t(), String.t() | atom()) :: {:ok, module()} | :error
The aggregate named name, by spelling: {:ok, module} or :error.
@spec aggregate( Macaw.Data.Operations.Registry.t(), String.t() | atom(), Enumerable.t(), map() ) :: {:ok, term()} | {:error, [fault(), ...]}
The value of values by the aggregate named name, its options checked against its
declaration and every nil reading dropped: {:ok, value} or {:error, faults}, each
fault at its option's key ([] for the name itself). A reading the aggregate does not
read (Macaw.Data.Aggregate.reads/1) is {["values"], {:reads, kind}}. An aggregate
call is no step, so no path names a step index; a transform's, through apply/4, do
(spec/04 §6, macaw_data#139).
@spec aggregates(Macaw.Data.Operations.Registry.t()) :: [String.t()]
Every aggregate's name, sorted.
@spec apply( Macaw.Data.Operations.Registry.t(), [map()], Macaw.Data.Table.source() | Macaw.Data.Table.t(), map() ) :: {:ok, Macaw.Data.Table.t()} | {:error, [fault(), ...]}
The nodes run in order over source, a Macaw.Data.Table or anything
Macaw.Data.Table.from/2 reads, each step's table the next one's input:
{:ok, table}, or validate/3's {:error, faults} before any step runs. A source that
is no table is Macaw.Data.Table.from/2's faults under "source". A step that refuses its input
at run time stops the run with its fault at its index (spec/04 §3.1): a reading of the
wrong kind, {[i, key], {:reads, kind}}, and the like; a transform answering something
that is not a table is {[i, "op"], :not_a_table}.
@spec apply!( Macaw.Data.Operations.Registry.t(), [map()], Macaw.Data.Table.source() | Macaw.Data.Table.t(), map() ) :: Macaw.Data.Table.t()
As apply/4, raising Macaw.Data.Error naming every fault.
@spec columns(Macaw.Data.Table.t()) :: Macaw.Data.Transform.columns()
A table's columns in order, each with its type: what outputs/2 is given.
@spec digest(Macaw.Data.Operations.Registry.t()) :: String.t()
A digest of every member's name and module, which a compile cache keys by.
One fault as a sentence.
iex> Macaw.Data.Operations.format_error({[1, "order"], {:type, {:enum, [:ascending, :descending]}}})
"step 2, order: is one of ascending or descending"
iex> Macaw.Data.Operations.format_error({[0, "op"], {:unknown, :transform, "sankey"}})
"step 1, op: transform \"sankey\" is not available"
@spec outputs( Macaw.Data.Operations.Registry.t(), [map()], Macaw.Data.Transform.columns(), map() ) :: {:ok, Macaw.Data.Transform.columns()} | {:error, [fault(), ...]}
The columns after every node, by each transform's outputs/2, over input columns
([{name, type}]): {:ok, columns} or validate/3's {:error, faults}.
@spec packages(Macaw.Data.Operations.Registry.t()) :: [module()]
The registry's packages, this one first.
@spec registry() :: Macaw.Data.Operations.Registry.t()
The registry of this package alone (spec/04 §2), which nothing a caller passes can fail.
@spec registry([module()]) :: {:ok, Macaw.Data.Operations.Registry.t()} | {:error, [fault(), ...]}
The registry of this package and packages, in order, each once (spec/04 §2):
{:ok, registry}, or every fault, {path, reason}: {[module], :not_a_package} for a
module that is not a package, {[package, member], :no_behavior} for a member
implementing no behavior, {[kind, name], {:named_twice, module, other}} for a name two
members of one behavior share, and {[:aggregate, name], {:step_key, key}} for an
aggregate declaring a step's key.
@spec registry!([module()]) :: Macaw.Data.Operations.Registry.t()
As registry/1, raising Macaw.Data.Error naming every fault.
Whether two readings are one value: equal, or an atom and a string spelling it, so a category is one value whichever spelling a row or a node gives it (spec/04 §4.1).
iex> Macaw.Data.Operations.same?(:ok, "ok")
true
iex> Macaw.Data.Operations.same?(1, 1.0)
true
iex> Macaw.Data.Operations.same?(nil, "nil")
false
@spec step_digest(Macaw.Data.Operations.Registry.t(), map()) :: {:ok, String.t()} | {:error, fault()}
A checked step's canonical identity (spec/04 §2): the kernel's term digest of the
transform module the registry gives its name and the node validate/3 checked, its
options by their strings with defaults filled in. Two nodes that mean the same step have
one identity whatever order their options were written in, and a step whose name another
registry gives to another module has another. {:ok, digest}; only a checked node has
an identity, so a node naming no transform of the registry is
{:error, {["op"], {:unknown, :transform, op}}}, one with no "op"
{:error, {["op"], :required}}, and one holding a term that is not data (a function, a
PID, a reference, a port, an improper list) {:error, {path, :not_data}}, its path in
the node.
@spec step_digest!(Macaw.Data.Operations.Registry.t(), map()) :: String.t()
As step_digest/2, raising Macaw.Data.Error naming the fault.
@spec step_keys() :: [String.t()]
The keys of the steps that name an aggregate, which an aggregate may not declare.
@spec table([map()], Macaw.Data.Transform.columns()) :: Macaw.Data.Table.t()
A table of rows with columns, in their order and of their types, each read from a
row by either spelling (Macaw.Data.Table.get/2): how a member that works on rows
answers the table its outputs/2 names.
@spec transform(Macaw.Data.Operations.Registry.t(), String.t() | atom()) :: {:ok, module()} | :error
The transform named name, by spelling: {:ok, module} or :error.
@spec transforms(Macaw.Data.Operations.Registry.t()) :: [String.t()]
Every transform's name, sorted.
@spec validate(Macaw.Data.Operations.Registry.t(), [map()], map()) :: {:ok, [map()]} | {:error, [fault(), ...]}
Every node checked (spec/04 §3.1): {:ok, checked}, each node's options by their
strings with defaults filled in, enum values their atoms, a named aggregate its module
and a frame-bound "plot" the frame's width in whole pixels; or {:error, faults},
every fault of every node, ordered by path.