Macaw.Data.Operations (macaw_data v0.16.0)

View Source

macaw_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}.

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.

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

fault()

@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

__members__()

@spec __members__() :: [module()]

The modules of macaw_data's package: its table operations and statistics.

aggregate(registry, name)

@spec aggregate(Macaw.Data.Operations.Registry.t(), String.t() | atom()) ::
  {:ok, module()} | :error

The aggregate named name, by spelling: {:ok, module} or :error.

aggregate(registry, name, values, options)

@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).

aggregates(registry)

@spec aggregates(Macaw.Data.Operations.Registry.t()) :: [String.t()]

Every aggregate's name, sorted.

apply(registry, nodes, source, context \\ %{})

@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}.

apply!(registry, nodes, source, context \\ %{})

As apply/4, raising Macaw.Data.Error naming every fault.

columns(table)

A table's columns in order, each with its type: what outputs/2 is given.

digest(registry)

A digest of every member's name and module, which a compile cache keys by.

format_error(arg)

@spec format_error(fault()) :: String.t()

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"

outputs(registry, nodes, columns, context \\ %{})

@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}.

packages(registry)

@spec packages(Macaw.Data.Operations.Registry.t()) :: [module()]

The registry's packages, this one first.

registry()

@spec registry() :: Macaw.Data.Operations.Registry.t()

The registry of this package alone (spec/04 §2), which nothing a caller passes can fail.

registry(packages)

@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.

registry!(packages)

@spec registry!([module()]) :: Macaw.Data.Operations.Registry.t()

As registry/1, raising Macaw.Data.Error naming every fault.

same?(a, b)

@spec same?(term(), term()) :: boolean()

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

step_digest(registry, node)

@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.

step_digest!(registry, node)

@spec step_digest!(Macaw.Data.Operations.Registry.t(), map()) :: String.t()

As step_digest/2, raising Macaw.Data.Error naming the fault.

step_keys()

@spec step_keys() :: [String.t()]

The keys of the steps that name an aggregate, which an aggregate may not declare.

table(rows, columns)

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.

transform(registry, name)

@spec transform(Macaw.Data.Operations.Registry.t(), String.t() | atom()) ::
  {:ok, module()} | :error

The transform named name, by spelling: {:ok, module} or :error.

transforms(registry)

@spec transforms(Macaw.Data.Operations.Registry.t()) :: [String.t()]

Every transform's name, sorted.

validate(registry, nodes, context)

@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.