ExPanda

ExPanda

CI Hex.pm Docs

Full macro expansion for Elixir AST introspection.

ExPanda takes Elixir source code (or a pre-parsed AST) and produces an AST where all macros have been expanded to their underlying forms, while preserving structural constructs (defmodule, def/defp) as-is.

The Problem

Code.string_to_quoted/1 returns the surface-level AST. Macros such as unless, use GenServer, Ecto's schema, and Phoenix macros all remain as opaque calls:

{:ok, ast} = Code.string_to_quoted("unless true, do: :never")
# => {:unless, _, [true, [do: :never]]}

For tools that need to reason about the actual control flow or data flow, this is insufficient. ExPanda resolves macros to their expanded forms:

{:ok, expanded} = ExPanda.expand_string("unless true, do: :never")
# => {:case, _, [true, [do: [false -> :never, true -> nil]]]}

Installation

Add ex_panda to your list of dependencies in mix.exs:

def deps do
  [
    {:ex_panda, "~> 0.2"}
  ]
end

Usage

Expanding a Source String

{:ok, expanded} = ExPanda.expand_string("unless true, do: :never")
# `unless` is expanded to `case`:
# {:case, _, [true, [do: [{:->, _, [[false], :never]}, {:->, _, [[true], nil]}]]]}

Expanding a File

{:ok, expanded} = ExPanda.expand_file("lib/my_module.ex")

Expanding a Pre-parsed AST

{:ok, ast} = Code.string_to_quoted("unless true, do: :never")
{:ok, expanded} = ExPanda.expand(ast)
# => {:case, _, [true, [do: _]]}

Expanding to Formatted Source Code

To get back formatted Elixir source instead of AST, use expand_to_string/2. It accepts both source strings and pre-parsed AST:

{:ok, code} = ExPanda.expand_to_string("unless true, do: :never")
# => "case true do\n  false -> :never\n  true -> nil\nend"

Operators: :expand_operators

By default (expand_operators: true) operators are expanded like any other macro or special form, matching historical behaviour:

{:ok, expanded} = ExPanda.expand_string("1 + 2")
# => {{:., _, [:erlang, :+]}, _, [1, 2]}

{:ok, expanded} = ExPanda.expand_string("1 |> to_string()")
# => {{:., _, [String.Chars, :to_string]}, _, [1]}

Pass expand_operators: false to keep operators verbatim and expand only their operands. This yields more readable, round-trip-safe output:

{:ok, expanded} = ExPanda.expand_string("1 + 2", expand_operators: false)
# => {:+, _, [1, 2]}

{:ok, expanded} = ExPanda.expand_string("a && b", expand_operators: false)
# => {:&&, _, [a, b]}

{:ok, expanded} = ExPanda.expand_string("1 |> to_string()", expand_operators: false)
# => {:|>, _, [1, {:to_string, _, []}]}

This applies to arithmetic (+, -, *, /), comparison (==, <, ...), boolean (&&, ||, and, or, not), and other operators (<>, ++, in, |>, ..). Macros nested inside operands are still expanded either way:

{:ok, expanded} = ExPanda.expand_string("x + unless(true, do: 1)", expand_operators: false)
# => {:+, _, [x, {:case, _, _}]}

The option is accepted by expand_string/2, expand_file/2, expand/2, expand/3, expand_to_string/2 and ExPanda.Walker.walk/3.

Capture Operator

The & capture operator is treated as a reference, never as a call, so captures survive expansion intact:

{:ok, expanded} = ExPanda.expand_string("&Enum.map/2")
# => {:&, _, [{:/, _, [{{:., _, [Enum, :map]}, _, []}, 2]}]}

{:ok, expanded} = ExPanda.expand_string("&(&1 + 1)")
# => {:&, _, [{:+, _, [{:&, _, [1]}, 1]}]}

Expanding with a Custom Environment

When running inside a Mix project where all dependencies are compiled, you can pass __ENV__ so that library macros (use GenServer, Ecto schemas, Phoenix macros) are also expanded:

{:ok, expanded, _final_env} = ExPanda.expand(ast, __ENV__, [])

use Expansion

use GenServer and similar use directives are expanded by calling the target module's MACRO-__using__/2 function directly, bypassing the standard macro dispatch that requires a compile-time module table. This means use works inside defmodule even without full compilation:

{:ok, expanded} = ExPanda.expand_string("""
defmodule MyServer do
  use GenServer
end
""")

# The output contains the expanded @behaviour, def child_spec, etc.
# with no @unexpanded markers.

Structural Preservation

defmodule and def/defp/defmacro/defmacrop forms are kept intact in the output. Only their bodies are expanded:

{:ok, expanded} = ExPanda.expand_string("""
defmodule Foo do
  def bar(x), do: unless(x, do: :fallback)
end
""")

# Output preserves defmodule + def structure:
# {:defmodule, _, [{:__aliases__, _, [:Foo]},
#   [do: {:def, _, [{:bar, _, _}, [do: {:case, _, _}]]}]]}

Directives (alias, import, require) are also preserved in the output and applied to the environment so that subsequent macro expansions resolve correctly.

with and for

with and for keep their keyword options (do:, else:, into:, reduce:) as a single trailing keyword list, exactly as the Elixir parser produces them. The option pairs are never spliced into the positional argument list, so the expanded AST always round-trips:

{:ok, expanded} = ExPanda.expand_string("with {:ok, x} <- {:ok, 1}, do: x")
# => {:with, _, [{:<-, _, _}, [do: {:x, _, nil}]]}

{:ok, expanded} = ExPanda.expand_string("for x <- [1, 2], into: %{}, do: {x, x}")
# => {:for, _, [{:<-, _, _}, [into: {:%{}, _, []}, do: _]]}

defdelegate

defdelegate is a Kernel macro implemented in terms of def, so the compiler's expander (:elixir_expand) rejects it with no function clause matching in :elixir_bootstrap.def/2. ExPanda therefore expands it itself, mirroring Kernel.Utils.defdelegate_all/3 and Kernel.Utils.defdelegate_each/2:

{:ok, expanded} = ExPanda.expand_string("""
defmodule Foo do
  defdelegate bar(x), to: Baz, as: :quux
end
""")

# => def bar(x), do: Baz.quux(x)

All forms are supported — single function, zero-arity without parentheses, and the list form (which yields one def per delegated function):

defdelegate bar, to: Baz                 # def bar(), do: Baz.bar()
defdelegate [a(x), b(y)], to: Baz        # def a(x), do: Baz.a(x)
                                         # def b(y), do: Baz.b(y)

The :to target is resolved like any other alias, so the emitted call references the module atom (Baz), exactly as a compiled defdelegate would. A defdelegate without a :to option is reported with an @unexpanded marker.

Unexpandable Macros

When a macro cannot be expanded (e.g., the target module is not loaded in the current runtime), the original node is kept with an @unexpanded error marker prepended:

{:__block__, [], [
  {:@, [], [{:unexpanded, [], ["use/1: function NonExistentModule.__using__/1 is undefined"]}]},
  {:use, [], [{:__aliases__, [], [:NonExistentModule]}]}
]}

This makes it straightforward to detect which parts of the AST could not be fully resolved, without crashing the expansion process.

How It Works

ExPanda combines two expansion strategies:

  1. :elixir_expand.expand/3 (primary engine) -- the Elixir compiler's internal expansion function. It recursively expands all nested macros, resolves aliases, and handles special forms. Used for expression-level expansion within function bodies.

  2. Macro.expand/2 (fallback) -- the public API. Used as a fallback when the internal engine fails (e.g., undefined variables).

  3. Direct MACRO-__using__/2 call -- for use directives, the target module's __using__ macro is called directly, bypassing the compiler dispatch that requires an ETS module table. This enables use GenServer and similar expansions inside defmodule without full compilation.

The Walker module implements a recursive top-down traversal that threads a Macro.Env struct through the AST, updating it as directives are encountered:

Integration with Metastatic

ExPanda serves as the foundation for Metastatic’s Elixir adapter, enabling accurate cross-language code analysis on real, fully-resolved ASTs.

The expanded AST produced by ExPanda feeds directly into Metastatic.Adapters.Elixir.ToMeta.transform/1, since it produces standard Elixir AST ({form, meta, args} tuples) -- just with all macros resolved. This gives Metastatic a true representation of the code's semantics rather than its surface syntax.

Development

# Run tests
mix test

# Run with coverage
MIX_ENV=test mix coveralls

# Code quality
mix quality

# Generate documentation
mix docs

Technical Risks

License

Copyright 2026 Aleksei Matiushkin

This project is licensed under the MIT License. See the LICENSE file for details.