# `ExAST.Pattern`
[🔗](https://github.com/elixir-vibe/ex_ast/blob/v0.16.0/lib/ex_ast/pattern.ex#L1)

AST pattern matching with captures.

Patterns are valid Elixir syntax where:
- `name`, `expr` — capture the matched AST node
- `_` or `_name` — wildcard, matches anything, not captured
- `...` — matches zero or more nodes (args, list items, block statements)
- Structs and maps match partially (only specified keys must be present)
- Pipes are normalized (`data |> Enum.map(f)` matches `Enum.map(data, f)`)
- Multi-statement patterns match contiguous sequences in blocks

Repeated variable names require the same value at every position.

Patterns can be given as strings or as quoted expressions:

    Pattern.match(node, "IO.inspect(_)")
    Pattern.match(node, quote(do: IO.inspect(_)))

Use `...` for variable-arity matching:

    Pattern.match(node, "IO.inspect(...)")       # any arity
    Pattern.match(node, "foo(first, ...)")        # 1+ args, capture first
    Pattern.match(node, "def foo(_) do ... end")  # any body

Constrain a definition by argument count with `name/arity`. Like the
parenthesized head form, it needs a body clause: `def name/2 do ... end`
mirrors `def name(_, _) do ... end`. The name is captured (or `_` to ignore
it) and the arity is an integer or `_` for any:

    Pattern.match(node, "def name/2 do ... end")  # 2-arity def, capture name
    Pattern.match(node, "def _/0 do ... end")     # any 0-arity def
    Pattern.match(node, "def name/_ do ... end")  # any arity, capture name

# `captures`

```elixir
@type captures() :: %{required(atom()) =&gt; term()}
```

# `pattern`

```elixir
@type pattern() :: String.t() | Macro.t()
```

# `compile`

```elixir
@spec compile(pattern() | ExAST.CompiledPattern.t()) :: ExAST.CompiledPattern.t()
```

Compiles a pattern into reusable matching metadata.

Most callers should prefer the higher-level search and patching APIs. Use this
when matching the same pattern repeatedly and passing it to functions that
accept compiled patterns.

Since v0.12.0 this returns `%ExAST.CompiledPattern{}`. If you need the
normalized pattern AST returned by earlier versions, use `compile_ast/1`.

# `compile_ast`

```elixir
@spec compile_ast(pattern() | ExAST.CompiledPattern.t()) :: Macro.t()
```

Returns the normalized AST for a pattern.

This preserves the pre-v0.12.0 `compile/1` return shape for callers that need
to inspect or reuse the normalized pattern AST directly.

# `match`

```elixir
@spec match(Macro.t(), pattern()) :: {:ok, captures()} | :error
```

Matches an AST node against a pattern.

The pattern can be a string or a quoted expression.
Returns `{:ok, captures}` on match, `:error` otherwise. When the pattern has
`...`, captures also hold what it matched under the `:...` key, which
`substitute/2` uses.

Alias directives found in the surrounding AST can be expanded before matching,
so `alias AshPhoenix.Form` followed by `Form.for_update(...)` matches
`AshPhoenix.Form.for_update(...)`.

# `match`

```elixir
@spec match(Macro.t(), pattern(), %{optional(atom()) =&gt; [atom()]}) ::
  {:ok, captures()} | :error
```

# `match_ast`

```elixir
@spec match_ast(Macro.t(), Macro.t()) :: {:ok, captures()} | :error
```

Matches an AST node against an already-parsed pattern AST.

Equivalent to `match/2` with a quoted pattern, kept for
backward compatibility.

# `match_ast`

```elixir
@spec match_ast(Macro.t(), Macro.t(), %{optional(atom()) =&gt; [atom()]}) ::
  {:ok, captures()} | :error
```

# `match_sequences`

```elixir
@spec match_sequences([Macro.t()], [Macro.t()]) :: [{captures(), Range.t()}]
```

Finds all contiguous subsequences of `nodes` matching `pattern_asts`.

Returns a list of `{captures, start_index..end_index}` tuples.
Captures are accumulated across all matched nodes and must be consistent.

# `match_sequences`

```elixir
@spec match_sequences([Macro.t()], [Macro.t()], %{optional(atom()) =&gt; [atom()]}) :: [
  {captures(), Range.t()}
]
```

# `multi_node?`

```elixir
@spec multi_node?(pattern()) :: boolean()
```

Returns `true` if the pattern contains multiple statements
(separated by `;` or newlines), enabling sequential matching.

# `pattern_nodes`

```elixir
@spec pattern_nodes(pattern()) :: [Macro.t()]
```

Returns the individual pattern ASTs from a (possibly multi-node) pattern.

# `substitute`

```elixir
@spec substitute(Macro.t(), captures()) :: Macro.t()
```

Substitutes captured values into a replacement template AST.

Variables in the template that match capture names are replaced
with the captured AST nodes.

A `...` in the template is replaced with what a `...` in the pattern matched,
recorded under the `:...` capture key: the matched arguments, list elements or
map pairs are spliced in. When the pattern has one `...`, every `...` in the
template refers to it; with several, the template must use the same number,
in the same order. A `...` is kept as written when the pattern had none.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
