Search documentation of Ragex

# Ragex.Analysis.ASTLocationExtractor (Ragex v0.4.0)

View Source

Extracts location information from language-specific ASTs before MetaAST transformation.

## Purpose

Phase 1 of comprehensive location solution: Extract line/column information from native AST representations before Metastatic abstracts them into MetaAST.

This module provides language-specific extractors that traverse the original AST and build a location map that can be correlated with analysis results.

## Supported Languages

- Elixir: Extracts from `{:atom, metadata, args}` tuples
- Erlang: Extracts from erl_parse metadata
- Python: Extracts from ast.AST node attributes (via Metastatic adapter)
- Ruby/Haskell: Planned

## Usage

    alias Ragex.Analysis.ASTLocationExtractor

    # Extract from Elixir code
    {:ok, ast} = Code.string_to_quoted(source)
    location_map = ASTLocationExtractor.extract_elixir(ast)

    # Extract from file content (auto-detect language)
    {:ok, location_map} = ASTLocationExtractor.extract_from_file(path)

## Location Map Structure

The location map stores node identifiers mapped to location information:

    %{
      "Module.function/2" => %{line: 42, column: 5},
      "SomeModule" => %{line: 10, column: 1}
    }

## Summary

### Types

location()
location_map()

### Functions

extract_elixir(ast)

Extracts location information from Elixir AST.

extract_from_content(content, language)

Extracts location information from source code content.

extract_from_file(path, opts \\ [])

Extracts location information from a file.

## Types

# location()

    @type location() :: %{
      line: non_neg_integer(),
      column: non_neg_integer() | nil,
      end_line: non_neg_integer() | nil,
      end_column: non_neg_integer() | nil
    }

# location_map()

    @type location_map() :: %{required(String.t()) => location()}

## Functions

# extract_elixir(ast)

    @spec extract_elixir(Macro.t()) :: location_map()

Extracts location information from Elixir AST.

Traverses the Elixir AST tuple structure and extracts line/column from metadata.

## Examples

    iex> ast = quote do
    ...>   defmodule MyModule do
    ...>     def hello(name), do: "Hello #{name}"
    ...>   end
    ...> end
    iex> locations = ASTLocationExtractor.extract_elixir(ast)
    iex> is_map(locations)
    true

# extract_from_content(content, language)

    @spec extract_from_content(String.t(), atom()) ::
      {:ok, location_map()} | {:error, term()}

Extracts location information from source code content.

## Parameters

- `content` - Source code string
- `language` - Language atom (`:elixir`, `:erlang`, `:python`, etc.)

## Returns

- `{:ok, location_map}` - Map of identifiers to locations
- `{:error, reason}` - Extraction failed

# extract_from_file(path, opts \\ [])

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

Extracts location information from a file.

Auto-detects language and uses appropriate extractor.

## Parameters

- `path` - File path
- `opts` - Keyword options
  - `:language` - Override language detection

## Returns

- `{:ok, location_map}` - Map of identifiers to locations
- `{:error, reason}` - Extraction failed