View Source Matcha.Spec (Matcha v0.1.6)

About specs.

Link to this section Summary

Functions

Wraps an existing match specification source code into a Matcha.Spec struct for usage in Matcha APIs.

Wraps an existing match specification source code into a Matcha.Spec struct for usage in Matcha APIs.

Wraps an existing match specification source code into a Matcha.Spec struct for usage in Matcha APIs.

Wraps an existing match specification source code into a Matcha.Spec struct for usage in Matcha APIs.

Runs a match spec over each item in an enumerable.

Runs a match spec over each item in an enumerable.

Produces a Stream that filters out and manipulates elements of an enumerable.

Link to this section Types

@type t() :: %Matcha.Spec{
  context: Matcha.Context.t(),
  source: Matcha.Source.uncompiled()
}

Link to this section Functions

@spec from_source(Matcha.Source.spec()) ::
  {:ok, t()} | {:error, Matcha.Error.problems()}

Wraps an existing match specification source code into a Matcha.Spec struct for usage in Matcha APIs.

Assumes the spec is written to be used in Matcha.Context.Table context, and validates it as such. To modify this validation behaviour, see from_source/2.

Returns {:ok, %{Matcha.Spec}}if validation succeeds, or` if not.

Link to this function

from_source(source, context)

View Source
@spec from_source(Matcha.Source.spec(), Matcha.Context.t() | Matcha.Source.type()) ::
  {:ok, t()} | {:error, Matcha.Error.problems()}

Wraps an existing match specification source code into a Matcha.Spec struct for usage in Matcha APIs.

Accepts a context module or specifier against which to validate.

Returns {:ok, %{Matcha.Spec}}if validation succeeds, or` if not.

@spec from_source!(Matcha.Source.spec()) :: t() | no_return()

Wraps an existing match specification source code into a Matcha.Spec struct for usage in Matcha APIs.

Assumes the spec is written to be used in Matcha.Context.Table context, and validates it as such. To modify this validation behaviour, see from_source!/2.

Returns a Matcha.Spec struct if validation succeeds, otherwise raises a Matcha.Spec.Error.

Link to this function

from_source!(source, context)

View Source
@spec from_source!(Matcha.Source.spec(), Matcha.Context.t() | Matcha.Source.type()) ::
  t() | no_return()

Wraps an existing match specification source code into a Matcha.Spec struct for usage in Matcha APIs.

Accepts a context module or specifier against which to validate.

Returns a Matcha.Spec struct if validation succeeds, otherwise raises a Matcha.Spec.Error.

@spec run(t(), Enumerable.t()) :: {:ok, list()} | {:error, Matcha.Error.problems()}

Runs a match spec over each item in an enumerable.

examples

Examples

iex> require Matcha
...> Matcha.spec(:filter_map) do
...>   {amount, tax} when is_integer(amount) and amount > 0 -> {:credit, amount + tax}
...> end
...> |> Matcha.Spec.run!([
...>   {9001, 0},
...>   {-200, -2.50},
...>   {-3, -0.5},
...>   {:error, "bank was offline"},
...>   {100, 0},
...>   {-743, -16.0},
...> ])
[credit: 9001, credit: 100]

note

Note

This function converts the enumerable to a list, which will trigger full enumeration of things like lazy Streams. If used with an infinite stream, it will run forever! Consider using stream/2 if you need lazy filter/mapping. It isn't as efficient, but plays nicer with infinite streams, and fits into the Stream APIs.

@spec run!(t(), Enumerable.t()) :: list() | no_return()

Runs a match spec over each item in an enumerable.

Link to this function

stream(spec, enumerable)

View Source
@spec stream(t(), Enumerable.t()) :: Enumerable.t()

Produces a Stream that filters out and manipulates elements of an enumerable.

Elements of the enumerable that match one of the spec's clauses will transformed as instructed. Elements that do not match will be filtered out of the result.

Always returns a lazy Stream enumerable.

examples

Examples

# FIXME: context stream logic broken, re-enable after fix
# iex> require Matcha
...> Matcha.spec do
...>   {amount, tax} when is_integer(amount) and amount < 0 -> {:charge, amount + tax}
...> end
...> |> Matcha.Spec.stream([
...>   {9001, 0},
...>   {-200, -2.50},
...>   {-3, -0.5},
...>   {:error, "bank was offline"},
...>   {100, 0},
...>   {-743, -16.0},
...> ])
...> |> Stream.take(2)
...> |> Enum.to_list
[charge: -202.5, charge: -3.5]

note

Note

This function wraps the enumerable in a lazy Stream. If the enumerable is something you can safely convert to a list without going on forever or loading too much into memory, consider using run/2 instead, as it is more efficient.

@spec valid?(t()) :: boolean()
@spec validate(t()) :: {:ok, t()} | {:error, Matcha.Error.problems()}
@spec validate!(t()) :: t() | no_return()