Search documentation of Metastatic

# Metastatic.Supplemental behaviour (Metastatic v0.2.0)

View Source

Behaviour for supplemental modules that extend language adapter capabilities.

Supplemental modules enable cross-language transformation by providing mappings from MetaAST constructs to library-specific code when native language support is unavailable.

## Example

A supplemental module for Python's Pykka actor library:

    defmodule MyApp.Supplemental.Python.Pykka do
      @behaviour Metastatic.Supplemental

      @impl true
      def info do
        %Metastatic.Supplemental.Info{
          name: :pykka_actor,
          language: :python,
          constructs: [:actor_call, :actor_cast, :spawn_actor],
          requires: ["pykka >= 3.0"],
          description: "Actor model support via Pykka library"
        }
      end

      @impl true
      def transform({:actor_call, actor, message, _timeout}, _language, _metadata) do
        # Build Python AST for: actor_ref.ask(message)
        {:ok, python_ast}
      end

      def transform(_, _, _), do: :error
    end

## Usage

Supplementals are registered at application startup and automatically used during MetaAST transformation when needed constructs are encountered.

See `Metastatic.Supplemental.Registry` for registration details.

# Summary

## Callbacks

info()

Returns information about this supplemental module.

transform(meta_ast, language, metadata)

Transforms a MetaAST construct to target language AST.

## Functions

dependencies(module)

Returns external library dependencies required by this supplemental.

language(module)

Returns the target language for this supplemental.

supported_constructs(module)

Lists all MetaAST construct types supported by this supplemental.

# Callbacks

# info()

    @callback info() :: Metastatic.Supplemental.Info.t()

Returns information about this supplemental module.

Must return a `Metastatic.Supplemental.Info` struct containing:

- `:name` - Unique identifier for this supplemental
- `:language` - Target language (e.g., :python, :javascript)
- `:constructs` - List of MetaAST construct types this module handles
- `:requires` - External library dependencies with version constraints
- `:description` - Human-readable description

## Example

    @impl true
    def info do
      %Info{
        name: :pykka_actor,
        language: :python,
        constructs: [:actor_call, :actor_cast],
        requires: ["pykka >= 3.0"],
        description: "Actor model support for Python"
      }
    end

# transform(meta_ast, language, metadata)

    @callback transform(meta_ast :: term(), language :: atom(), metadata :: map()) ::
      {:ok, term()} | :error

Transforms a MetaAST construct to target language AST.

Receives a MetaAST node, target language, and metadata. Returns either:

- `{:ok, language_ast}` - Successfully transformed
- `:error` - Cannot handle this construct

The supplemental should only transform constructs listed in its `info/0`.

## Example

    @impl true
    def transform({:actor_call, actor, message, timeout}, :python, _metadata) do
      python_ast = build_pykka_ask_call(actor, message, timeout)
      {:ok, python_ast}
    end

    def transform(_, _, _), do: :error

# Functions

# dependencies(module)

    @spec dependencies(module()) :: [String.t()]

Returns external library dependencies required by this supplemental.

## Example

    iex> MySupplemental.dependencies()
    ["pykka >= 3.0", "typing-extensions"]

# language(module)

    @spec language(module()) :: atom()

Returns the target language for this supplemental.

## Example

    iex> MySupplemental.language()
    :python

# supported_constructs(module)

    @spec supported_constructs(module()) :: [atom()]

Lists all MetaAST construct types supported by this supplemental.

Convenience function that extracts constructs from info/0.

## Example

    iex> MySupplemental.supported_constructs()
    [:actor_call, :actor_cast, :spawn_actor]