Clarity.SourceLocation (Clarity v0.4.0)

View Source

Represents source location information with application and module context.

This module centralizes the handling of source location data, eliminating redundant application lookups and file path parsing. It provides a structured way to store and access source information including application, module, and annotation data.

Examples

# From module with annotation
source_location = SourceLocation.from_module_anno(MyModule, anno)

# From module without annotation (line 1)
source_location = SourceLocation.from_module(MyModule)

# From application and file path
source_location = SourceLocation.from_path(:my_app, "/path/to/file.ex")

# Extract information
file_path = SourceLocation.file_path(source_location)
line = SourceLocation.line(source_location)

Summary

Types

t()

Functions

column(source_location)

Extracts the column number from the source location.

file_path(source_location, relative_to \\ :absolute)

Extracts the file path from the source location.

from_application_anno(application, anno)

Creates a SourceLocation from an application and annotation.

from_module(module)

Creates a SourceLocation from a module without annotation.

from_module_anno(module, anno)

Creates a SourceLocation from a module and annotation.

from_path(application, path)

Creates a SourceLocation from an application and file path.

from_spark_entity(module, entity)

Creates a SourceLocation from a Spark DSL entity.

line(source_location)

Extracts the line number from the source location.

Types

t()

@type t() :: %Clarity.SourceLocation{
  anno: :erl_anno.anno(),
  application: Application.app() | nil,
  module: module() | nil
}

Functions

column(source_location)

@spec column(t()) :: pos_integer() | nil

Extracts the column number from the source location.

Returns the column number as a positive integer, or nil if no column information is available.

Examples

iex> SourceLocation.column(source_location)
15

iex> SourceLocation.column(source_location_without_column)
nil

file_path(source_location, relative_to \\ :absolute)

@spec file_path(t(), :absolute | :cwd | :app) :: Path.t() | nil

Extracts the file path from the source location.

Returns the file path as a string, or nil if no file information is available in the annotation.

Parameters

  • source_location - The SourceLocation struct
  • relative_to - How to format the path:
    • :absolute (default) - Return absolute path using Path.expand/1
    • :cwd - Return path relative to current working directory
    • :app - Return path relative to application root (not yet implemented)

Examples

iex> SourceLocation.file_path(source_location)
"/absolute/path/to/file.ex"

iex> SourceLocation.file_path(source_location, :cwd)
"lib/file.ex"

iex> SourceLocation.file_path(source_location, :absolute)
"/absolute/path/to/file.ex"

from_application_anno(application, anno)

@spec from_application_anno(Application.app(), :erl_anno.anno()) :: t()

Creates a SourceLocation from an application and annotation.

The module field will be set to nil since we only have application context.

Examples

iex> anno = :erl_anno.set_file('lib/some_file.ex', :erl_anno.new(10))
...> SourceLocation.from_application_anno(:my_app, anno)
%SourceLocation{application: :my_app, module: nil, anno: anno}

from_module(module)

@spec from_module(module()) :: t()

Creates a SourceLocation from a module without annotation.

This is useful when you have module information but no specific line/location details. The annotation will be created with line 1 and the module's source file if available.

Examples

iex> SourceLocation.from_module(MyModule)
%SourceLocation{application: :my_app, module: MyModule, anno: anno}

from_module_anno(module, anno)

@spec from_module_anno(module(), :erl_anno.anno()) :: t()

Creates a SourceLocation from a module and annotation.

Uses Application.get_application/1 to determine the application the module belongs to.

Examples

iex> anno = :erl_anno.set_file('lib/my_module.ex', :erl_anno.new(42))
...> SourceLocation.from_module_anno(MyModule, anno)
%SourceLocation{application: :my_app, module: MyModule, anno: anno}

from_path(application, path)

@spec from_path(Application.app(), String.t()) :: t()

Creates a SourceLocation from an application and file path.

This is useful when you have a file path and know which application it belongs to, but don't have module information. The annotation will be created with line 1.

Examples

iex> SourceLocation.from_path(:my_app, "/path/to/file.ex")
%SourceLocation{application: :my_app, module: nil, anno: anno}

from_spark_entity(module, entity)

@spec from_spark_entity(module(), Spark.Dsl.Entity.entity()) :: t()

Creates a SourceLocation from a Spark DSL entity.

This function is only available when Spark is loaded. It extracts the annotation from the entity and determines the application that contains the entity's module.

Examples

iex> SourceLocation.from_spark_entity(
...>   My.Ash.Resource,
...>   List.first(Ash.Domain.info().attributes())
...> )
%SourceLocation{application: :my_app, module: My.Ash.Resource, anno: anno}

line(source_location)

@spec line(t()) :: pos_integer()

Extracts the line number from the source location.

Returns the line number as a positive integer. If no line information is available, returns 1 as a sensible default.

Examples

iex> SourceLocation.line(source_location)
42