adoption.cheatmd

# Adoption Cheatsheet

Convert your project to `Matcha` quickly! For a more in-depth description of how to move your project over, see the [adoption guide](guide-adoption.html).

At a high level, you will want to:

- [Choose a `Matcha.Context`](#choosing-a-matcha-context) for each spec
- [Build a `Matcha.Spec`](#creating-matcha-spec-structs) in that context
- [Use that spec](#using-matcha-specs) in the corresponding `Matcha` APIs

## Choosing a `Matcha.Context`

### The `:table` context

Use the `:table` context if you intend to trace code execution with the [`Matcha.Table`](https://hexdocs.pm/matcha/Matcha.Table.html) functions.

```elixir
require Matcha
matcha_spec = Matcha.spec(:table) do
  { x, y } = z when x > 10 -> z
end
```

### The `:trace` context

Use the `:trace` context if you intend to query data with [`Matcha.Trace`](https://hexdocs.pm/matcha/Matcha.Trace.html) functions.

```elixir
require Matcha
matcha_spec = Matcha.spec(:table) do
  { x, y } = z when x > 10 -> z
end
```

### Other contexts

Use the `:filter_map` or `:match` contexts if you intend to play with specs and in-memory data
using the [`Matcha.Spec`](https://hexdocs.pm/matcha/Matcha.Spec.html).

```elixir
require Matcha
matcha_spec = Matcha.spec(:table) do
  { x, y } = z when x > 10 -> z
end
```

## Creating `Matcha.Spec` structs

### Building Specs With Elixir

`Matcha` provides an Elixir-to-Matcha compiler with the [`Matcha.spec/2`](https://hexdocs.pm/matcha/Matcha.html#spec/2) macro.

```elixir
require Matcha
matcha_spec = Matcha.spec(:table) do
  { x, y } = z when x > 10 -> z
end
```

### Wrapping Raw Specs

You can make existing raw match specs play nice with `Matcha` APIs using [`Matcha.Spec.from_source!/2`](https://hexdocs.pm/matcha/Matcha.Spec.html#from_source!/2)

```elixir
raw_spec = [{{:"$1", :"$2"}, [{:>, :"$1", 10}], [:"$_"]}]
matcha_spec = Matcha.Spec.from_source!(:table, raw_spec)
```

## Using Matcha Specs

### Outside of Matcha

You can always extract the raw source of any `Matcha.Spec` and pass it into other APIs that do not support `Matcha` with [`Matcha.Spec.source/1`](https://hexdocs.pm/matcha/Matcha.Spec.html#source/1).

```elixir
require Matcha
matcha_spec = Matcha.spec(:table) do
  { x, y } = z when x > 10 -> z
end

raw_spec = Matcha.Spec.source(matcha_spec)
```

[`call/2`](https://hexdocs.pm/matcha/Matcha.Spec.html#call/2),
[`run/2`](https://hexdocs.pm/matcha/Matcha.Spec.html#run/2), and [`stream/2`](https://hexdocs.pm/matcha/Matcha.Spec.html#stream/2) functions.