Pentiment.Span (pentiment v0.1.5)

Span types for representing regions in source code.

Pentiment supports three span representations:

The first two can be used interchangeably through the Pentiment.Spannable protocol. Search spans are resolved to Position spans when the diagnostic is formatted.

Examples

# Byte offset span: starts at byte 42, spans 10 bytes
Pentiment.Span.byte(42, 10)

# Line/column span: line 5, columns 10-20
Pentiment.Span.position(5, 10, 5, 20)

# Single-point span (just a position)
Pentiment.Span.position(5, 10)

# Deferred search span: find "error" on line 5
Pentiment.Span.search(line: 5, pattern: "error")

Summary

Types

t()

Functions

byte(start, length)

Creates a byte offset span.

position(start_line, start_column \\ 1, end_line \\ nil, end_column \\ nil)

Creates a line/column position span.

search(opts)

Creates a deferred search span.

Types

t()

@type t() ::
  Pentiment.Span.Byte.t()
  | Pentiment.Span.Position.t()
  | Pentiment.Span.Search.t()

Functions

byte(start, length)

@spec byte(non_neg_integer(), pos_integer()) :: Pentiment.Span.Byte.t()

Creates a byte offset span.

Examples

iex> Pentiment.Span.byte(42, 10)
%Pentiment.Span.Byte{start: 42, length: 10}

position(start_line, start_column \\ 1, end_line \\ nil, end_column \\ nil)

@spec position(pos_integer(), pos_integer(), pos_integer() | nil, pos_integer() | nil) ::
  Pentiment.Span.Position.t()

Creates a line/column position span.

Can be called with 2 arguments for a single point, or 4 arguments for a range.

Examples

# Single point at line 5, column 10
iex> Pentiment.Span.position(5, 10)
%Pentiment.Span.Position{start_line: 5, start_column: 10, end_line: nil, end_column: nil}

# Range from line 5 col 10 to line 5 col 20
iex> Pentiment.Span.position(5, 10, 5, 20)
%Pentiment.Span.Position{start_line: 5, start_column: 10, end_line: 5, end_column: 20}

search(opts)

@spec search(keyword()) :: Pentiment.Span.Search.t()

Creates a deferred search span.

Search spans are resolved at format time by searching for the pattern in the source content. This is useful when exact positions aren't available at diagnostic creation time, such as in macros.

Options

  • :line - The starting line number to search from (required)
  • :pattern - The string pattern to find (required)
  • :after_column - Only match patterns starting at or after this column on the first line (default: 1)
  • :max_lines - Maximum number of lines to search (default: 1)

Examples

# Search for "hoost:" on line 3
iex> Pentiment.Span.search(line: 3, pattern: "hoost:")
%Pentiment.Span.Search{line: 3, pattern: "hoost:", after_column: 1, max_lines: 1}

# Search after column 10 to skip earlier matches
iex> Pentiment.Span.search(line: 3, pattern: "host", after_column: 10)
%Pentiment.Span.Search{line: 3, pattern: "host", after_column: 10, max_lines: 1}

# Search across multiple lines (for multi-line constructs)
iex> Pentiment.Span.search(line: 3, pattern: "key:", max_lines: 5)
%Pentiment.Span.Search{line: 3, pattern: "key:", after_column: 1, max_lines: 5}