ExAST.Selector (ExAST v0.11.0)

CSS-like AST selector builder.

Selectors are built from a starting pattern and relationship steps:

import ExAST.Selector

pattern("defmodule _ do ... end")
|> descendant("def _ do ... end")
|> child("IO.inspect(_)")

The final step is the selected node. Use where/2 with predicates such as has_child/1, has_descendant/1, parent/1, and ancestor/1 to filter the selected node without changing it.

pattern("def _ do ... end")
|> where(has_descendant("Repo.transaction(_)"))
|> where(not(has_descendant("IO.inspect(_)")))

where/2 also accepts quoted boolean predicate expressions, so you can use Kernel.not/1 without excluding it from imports:

pattern("def _ do ... end")
|> where(not has_descendant("IO.inspect(_)"))

where/2 supports capture guards using ^ to pin captured values, allowing runtime checks on matched nodes:

pattern("Enum.take(_, count)")
|> where(match?({:-, _, [_]}, ^count))

Summary

Types

relation()

step()

t()

Functions

all(predicates)

Matches when all nested predicates match.

ancestor(pattern)

Builds or applies a semantic ancestor predicate.

ancestor(selector, pattern)

any(predicates)

Matches when any nested predicate matches.

child(selector, pattern)

Selects direct semantic children matching pattern.

comment(matcher)

Matches comments associated with the selected node.

comment_after(matcher)

Matches comments immediately after the selected node.

comment_before(matcher)

Matches comments immediately before the selected node.

comment_inline(matcher)

Matches inline comments on the selected node start line.

comment_inside(matcher)

Matches comments inside the selected node range.

contains(pattern)

SQL-like alias for has_descendant/1 and has_descendant/2.

contains(selector, pattern)

descendant(selector, pattern)

Selects semantic descendants matching pattern.

exact(value, opts \\ [])

Builds an exact comment matcher.

find(selector, pattern)

SQL-like alias for descendant/2.

find_all(input, selector, opts \\ [])

Finds selector matches in source text, AST, or a Sourceror zipper.

find_child(selector, pattern)

SQL-like alias for child/2.

first()

Matches the first semantic child in its parent.

follows(pattern)

Matches when a previous sibling matches pattern.

from(pattern)

SQL-like alias for pattern/1.

has(pattern)

Alias for has_descendant/1 and has_descendant/2.

has(selector, pattern)

has_child(pattern)

Builds or applies a direct semantic child predicate.

has_child(selector, pattern)

has_descendant(pattern)

Builds or applies a semantic descendant predicate.

has_descendant(selector, pattern)

immediately_follows(pattern)

Matches when the immediately previous sibling matches pattern.

immediately_precedes(pattern)

Matches when the immediately following sibling matches pattern.

inside(pattern)

SQL-like alias for ancestor/1 and ancestor/2.

inside(selector, pattern)

last()

Matches the last semantic child in its parent.

match?(input, selector, opts \\ [])

Returns true when the selector matches at least once.

not predicate

Negates a predicate for use with where/2.

nth(index)

Matches the nth semantic child in its parent, using 1-based indexing.

parent(pattern)

Builds or applies a direct semantic parent predicate.

parent(selector, pattern)

pattern(pattern)

Starts a selector at pattern.

precedes(pattern)

Matches when a following sibling matches pattern.

prefix(value, opts \\ [])

Builds a comment prefix matcher.

requires_comments?(selector)

Returns true when matching this selector depends on comments.

requires_source?(selector)

Returns true when matching this selector requires source text.

selector(pattern)

Alias for pattern/1.

suffix(value, opts \\ [])

Builds a comment suffix matcher.

text(value, opts \\ [])

Builds a substring comment matcher.

where(selector, expr)

Adds a predicate filter without changing the selected node.