Minga.Core.PositionEncoding (Minga v0.1.0)

Copy Markdown View Source

Converts between byte-indexed positions and external text position encodings.

Minga stores positions as {line, byte_col} where byte_col is a byte offset within the line. Some external protocols, including LSP, use UTF-16 or UTF-32 character offsets instead. This module keeps that conversion pure so Layer 0 data structures can translate ranges without depending on stateful LSP services.

Summary

Types

encoding()

An external offset encoding for character positions.

position()

A zero-indexed line and byte-column position.

Functions

client_supported_encodings()

Returns the supported encoding strings in client preference order.

exact_byte_column(line_text, column, encoding)

Converts an exact external column to a byte column without clamping invalid positions.

from_lsp(map, line_text, encoding)

Converts an external position map back to a byte-column position.

negotiate(server_encodings)

Negotiates the best offset encoding from a supported list.

to_lsp(arg, line_text, encoding)

Converts a byte-column position to an external position map.

Types

encoding()

@type encoding() :: :utf8 | :utf16 | :utf32

An external offset encoding for character positions.

position()

@type position() :: {line :: non_neg_integer(), col :: non_neg_integer()}

A zero-indexed line and byte-column position.

Functions

client_supported_encodings()

@spec client_supported_encodings() :: [String.t()]

Returns the supported encoding strings in client preference order.

exact_byte_column(line_text, column, encoding)

@spec exact_byte_column(String.t(), non_neg_integer(), encoding()) ::
  {:ok, non_neg_integer()}
  | {:error, :column_out_of_range | :column_not_boundary}

Converts an exact external column to a byte column without clamping invalid positions.

from_lsp(map, line_text, encoding)

@spec from_lsp(map(), String.t(), encoding()) :: position()

Converts an external position map back to a byte-column position.

negotiate(server_encodings)

@spec negotiate([String.t()]) :: encoding()

Negotiates the best offset encoding from a supported list.

Prefers UTF-8, then UTF-16, then UTF-32. Falls back to UTF-16 when the server or external source does not advertise support.

to_lsp(arg, line_text, encoding)

@spec to_lsp(position(), String.t(), encoding()) :: map()

Converts a byte-column position to an external position map.