Nasty.Interop.CodeGen.Explain (Nasty v0.3.0)

View Source

Generates natural language explanations from Elixir code AST.

This module traverses Elixir AST and generates natural language descriptions, creating the reverse direction of code generation (Code → NL).

Supported Patterns

Function Calls

  • Enum.sort(list) → "Sort the list"
  • Enum.filter(users, fn u -> u.age > 18 end) → "Filter users where age is greater than 18"

Pipelines

  • list |> Enum.map(&(&1 * 2)) |> Enum.sum() → "Map the list to double each element, then sum the results"

Assignments

  • x = 5 → "X is 5"
  • result = a + b → "Result equals A plus B"

Conditionals

  • if x > 5, do: :ok → "If X is greater than 5, return ok"

Examples

# Function call → Natural language
code = "Enum.sort(numbers)"
{:ok, text} = Explain.explain_code(code)
# => "Sort numbers"

# Pipeline → Natural language
code = "list |> Enum.map(&(&1 * 2)) |> Enum.sum()"
{:ok, text} = Explain.explain_code(code)
# => "Map list to double each element, then sum the results"

Summary

Functions

explain_ast_to_document(ast, opts \\ [])

Explains Elixir AST and returns a natural language AST Document.

explain_code(code, opts \\ [])

Explains Elixir code by converting it to natural language.

Functions

explain_ast_to_document(ast, opts \\ [])

@spec explain_ast_to_document(
  Macro.t(),
  keyword()
) :: {:ok, Nasty.AST.Document.t()} | {:error, term()}

Explains Elixir AST and returns a natural language AST Document.

Examples

ast = quote do: Enum.sort(list)
{:ok, document} = Explain.explain_ast_to_document(ast)

explain_code(code, opts \\ [])

@spec explain_code(
  String.t() | Macro.t(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Explains Elixir code by converting it to natural language.

Parameters

  • code - Elixir code string or AST
  • opts - Options:
    • :language - Target language (default: :en)
    • :style - Explanation style: :concise or :verbose (default: :concise)

Returns

  • {:ok, String.t()} - Natural language explanation
  • {:error, reason} - Parse or generation error

Examples

{:ok, explanation} = Explain.explain_code("Enum.sort(list)")
# => "Sort list"

{:ok, explanation} = Explain.explain_code("x = 5")
# => "X is 5"