Spitfire.Env (spitfire v0.4.0)

Environment querying

Summary

Types

ast()

Alias for Macro.t()

cursor_env()

The environment at the cursor position

cursor_envs()

Environments at tagged cursor positions

cursor_id()

An identifier read from a cursor node's :cursor_id metadata

env()

The environment

final_env()

The environment after expanding the entire syntax tree

func()

A name/arity pair

macro()

A name/arity pair

state()

The expansion state. Contains a total listing of local functions, macros, and module attributes.

Functions

expand(ast, file)

Expands the environment of the given AST.

expand_with_cursor_envs(ast, file, macro_env \\ Macro.Env)

Expands the environment of the given AST and returns an environment for every tagged __cursor__() node.

Types

Link to this type

ast()

@type ast() :: Macro.t()

Alias for Macro.t()

Link to this type

cursor_env()

@type cursor_env() :: env()

The environment at the cursor position

Link to this type

cursor_envs()

@type cursor_envs() :: %{optional(cursor_id()) => cursor_env()}

Environments at tagged cursor positions

Link to this type

cursor_id()

@type cursor_id() :: term()

An identifier read from a cursor node's :cursor_id metadata

Link to this type

env()

@type env() :: %{
  functions: [{module(), [func()]}],
  macros: [{module(), [macro()]}],
  attrs: [String.t()],
  variables: [atom()]
}

The environment

Link to this type

final_env()

@type final_env() :: env()

The environment after expanding the entire syntax tree

Link to this type

func()

@type func() :: {atom(), arity()}

A name/arity pair

Link to this type

macro()

@type macro() :: {atom(), arity()}

A name/arity pair

Link to this type

state()

@type state() :: %{functions: [func()], macros: [macro()], attrs: [String.t()]}

The expansion state. Contains a total listing of local functions, macros, and module attributes.

Functions

Link to this function

expand(ast, file)

@spec expand(Macro.t(), String.t()) ::
  {ast :: ast(), final_state :: state(), final_env :: final_env(),
   cursor_env :: cursor_env()}

Expands the environment of the given AST.

In order to get the environment at the given cursor position, expand/2 expects to find a __cursor__() node inside the AST to indicate where the cursor is.

This can be achieved by passing your code fragment (meaning, a string of your code from the top to where the cursor is) to Spitfire.container_cursor_to_quoted/1, and then passing that to expand/2.

Please see the tests for example usage.

Link to this function

expand_with_cursor_envs(ast, file, macro_env \\ Macro.Env)

@spec expand_with_cursor_envs(ast(), String.t(), module()) ::
  {ast(), state(), final_env(), cursor_envs()}

Expands the environment of the given AST and returns an environment for every tagged __cursor__() node.

Cursor IDs come from the node's :cursor_id metadata. Untagged cursors use :default, and duplicate IDs use the last cursor encountered.

The third argument may provide a module implementing the Macro.Env expansion API.