Matcha.Context behaviour (Matcha v0.1.3) View Source

Different types of match spec are intended to be used for different purposes, and support different instructions in their bodies for different use-cases.

The modules implementing the Matcha.Context behaviour define the different types of Matcha.Spec, provide documentation for what specialized instructions that type supports, and are used during Elixir-to-match spec conversion as a concrete function definition to use when expanding instructions (since most of these specialized instructions do not exist anywhere as an actual functions, this lets the Elixir compiler complain about invalid instructions as UndefinedFunctionErrors).

Predefined contexts

Currently there are three applications of match specs supported:

  • :filter_map:

    Matchspecs intended to be used to filter/map over a list in an optimized fashion. These types of match spec reference the Matcha.Context.FilterMap module.

  • :table:

    Matchspecs intended to be used to efficiently select data from BEAM VM "table" tools, such as :ets, :dets, and :mnesia, and massage the values returned. These types of match spec reference the Matcha.Context.Table module.

  • :trace:

    Matchspecs intended to be used to instruct tracing utilities such as :dbg and :recon_trace exactly what function calls with what arguments to trace, and allows invoking special trace command instructions in response. These types of match spec reference the Matcha.Context.Trace module.

Custom contexts

The context mechanism is technically extensible: any module can implement the Matcha.Context behaviour, define the callbacks, and list public no-op functions to allow their usage in specs compiled with that context (via Matcha.spec(CustomContext) do...).

In practice there is little point in defining a custom context: the supported use-cases for match specs are tightly coupled to the erlang language, and Matcha covers all of them with its provided contexts, which should be sufficient for any application. The module+behaviour+callback implementation used in Matcha is less about offering extensibility, but instead used to simplify special-casing in Matcha.Spec function implementations, raise Elixir-flavored errors when an invalid instruction is used in the different types of spec, and provide a place to document what they do when invoked.

Link to this section Summary

Link to this section Types

Link to this section Callbacks

Specs

__context_name__() :: atom()
Link to this callback

__default_test_target__()

View Source

Specs

__default_test_target__() :: any()
Link to this callback

__emit_test_result__(result)

View Source

Specs

__emit_test_result__(result :: any()) :: any()

Specs

__erl_test_type__() :: Matcha.Source.erl_test_type()
Link to this callback

__handle_erl_test_results__(return)

View Source

Specs

__handle_erl_test_results__(return :: any()) ::
  {:ok, result :: any()} | {:error, Matcha.Error.problems()}
Link to this callback

__invalid_test_target_error_message__(test_target)

View Source

Specs

__invalid_test_target_error_message__(test_target :: any()) :: String.t()
Link to this callback

__prepare_source__(source)

View Source

Specs

__prepare_source__(source :: any()) :: any()
Link to this callback

__valid_test_target__(test_target)

View Source

Specs

__valid_test_target__(test_target :: any()) :: boolean()