@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 {:error, problems} if not.

@spec from_source(Matcha.Context.t() | Matcha.Source.type(), 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.

Accepts a context module or specifier against which to validate.

Returns {:ok, %{Matcha.Spec}} if validation succeeds, or {:error, problems} 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.

@spec from_source!(Matcha.Context.t() | Matcha.Source.type(), Matcha.Source.spec()) ::
  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 merge([t()]) :: {:ok, t()} | {:error, Matcha.Error.problems()}

Merges a list of Matcha.Spec specs into a single matchspec.

All specs provided must be built for the same Matcha.Context.

The clauses of each matchspec are combined in the order provided into a new matchspec. Note that while the new spec is validated via the validate/1 function at runtime, no compile-time checks are applied (for example, that none of the merged clauses overlap).

This means that if an earlier spec provided has a match-all clause; no later clauses can match. This is rarely a problem in practice, as matchspecs tend to not be written with catch-all clauses, since part of their utility is to filter out unwanted matches that are not specified in the spec.

Returns {:ok, %{Matcha.Spec}} if the new matchspec is valid, or {:error, problems} if not.

examples

Examples

iex> require Matcha
...>
...> spec1 = Matcha.spec do
...>   integer when is_integer(integer)
...>     -> integer + 1
...> end
...>
...> spec2 = Matcha.spec do
...>   float when is_float(float)
...>     -> float + 0.5
...> end
...>
...> {:ok, merged_spec} = Matcha.Spec.merge([spec1, spec2])
...> Matcha.Spec.run!(merged_spec, [1, 1.5])
[2, 2.0]

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

Merges spec1 and spec2 into a single matchspec.

All specs provided must be built for the same Matcha.Context.

See merge/1 for more details on how a merged matchspec behaves.

Returns {:ok, %{Matcha.Spec}} if the new matchspec is valid, or {:error, problems} if not.

@spec merge!([t()]) :: t() | no_return()

Merges a list of Matcha.Spec specs into a single matchspec.

All specs provided must be built for the same Matcha.Context.

See merge/1 for more details on how a merged matchspec behaves.

Returns the new Matcha.Spec}} if it is valid, or raises a Matcha.Spec exception if not.

@spec merge!(t(), t()) :: t() | no_return()

Merges spec1 and spec2 into a single matchspec.

All specs provided must be built for the same Matcha.Context.

See merge/1 for more details on how a merged matchspec behaves.

Returns the new Matcha.Spec}} if it is valid, or raises a Matcha.Spec exception if not.

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

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