Trait Source 

pub trait Source {
    // Required methods
    fn length(&self) -> usize;
    fn get_text_in(&self, range: Range<usize>) -> &str;
    fn offset_to_position(&self, offset: usize) -> Position;
    fn position_to_offset(&self, position: Position) -> usize;

    // Provided methods
    fn is_empty(&self) -> bool { ... }
    fn get_char_at(&self, offset: usize) -> Option<char> { ... }
    fn get_text_from(&self, offset: usize) -> &str { ... }
    fn get_url(&self) -> Option<&Url> { ... }
    fn span_to_lsp_range(&self, span: Range<usize>) -> Range { ... }
    fn lsp_range_to_span(&self, range: Range) -> Range<usize> { ... }
    fn find_char_from(&self, offset: usize, ch: char) -> Option<usize> { ... }
    fn find_str_from(&self, offset: usize, pattern: &str) -> Option<usize> { ... }
    fn syntax_error(
        &self,
        message: impl Into<String>,
        position: usize,
    ) -> OakError { ... }
}

Trait for abstract text sources with error position management.

This trait provides a unified interface for different text sources that may have:

• Different character representations (Unicode escapes, HTML entities)
• Different internal storage formats
• Different error handling requirements

All offsets exposed by this trait are simple text ranges from the start of this source. Internal complexity like global offset mapping, character encoding transformations, and position tracking are handled internally.

Required Methods

fn length(&self) -> usize

Get the length of this source.

This represents the total size of this source in bytes.

fn get_text_in(&self, range: Range<usize>) -> &str

Get the text content at the specified range.

The range is specified as simple offsets from the start of this source. The returned text should have any character encoding transformations already applied (e.g., Unicode escapes decoded, HTML entities resolved).

Arguments

• range - The byte range to extract text from (relative to this source)

Returns

The text content in the specified range, or None if the range is invalid

fn offset_to_position(&self, offset: usize) -> Position

Convert an offset to position information for error reporting.

This method handles the mapping from offsets to human-readable line/column positions for error reporting.

Arguments

• offset - The byte offset from the start of this source

Returns

A [SourcePosition] with line and column information, or None if the offset is invalid

fn position_to_offset(&self, position: Position) -> usize

Convert a position to an offset.

Arguments

• position - The position to convert

Returns

The offset corresponding to the position

Provided Methods

fn is_empty(&self) -> bool

Check if the source is empty.

fn get_char_at(&self, offset: usize) -> Option<char>

Get a single character at the specified offset.

This method should handle any character encoding transformations and return the actual character that would be seen by the parser.

Arguments

• offset - The byte offset from the start of this source

Returns

The character at the specified offset, or None if the offset is invalid

fn get_text_from(&self, offset: usize) -> &str

Get the text from the current position to the end of the source.

Arguments

• offset - The byte offset to start from (relative to this source)

Returns

The remaining text from the offset to the end, or None if the offset is invalid

fn get_url(&self) -> Option<&Url>

Get the URL of this source, if available.

This method returns a reference to the URL associated with this source, typically used for file-based sources or remote resources.

Returns

An optional reference to the source URL, or None if no URL is available

fn span_to_lsp_range(&self, span: Range<usize>) -> Range

Converts a byte range to an LSP Range.

Arguments

• span - The byte range to convert

Returns

An lsp_types::Range with line/column positions.

Availability

This method is only available when the lsp-types feature is enabled.

fn lsp_range_to_span(&self, range: Range) -> Range<usize>

Converts an LSP Range to a byte-based source span.

Arguments

• range - The LSP Range to convert

Returns

A Range<usize> representing the byte offset range.

Availability

This method is only available when the lsp-types feature is enabled.

fn find_char_from(&self, offset: usize, ch: char) -> Option<usize>

Find the next occurrence of a character starting from an offset.

Arguments

• offset - The byte offset to start searching from (relative to this source)
• ch - The character to search for

Returns

The offset of the next occurrence, or None if not found

fn find_str_from(&self, offset: usize, pattern: &str) -> Option<usize>

Find the next occurrence of a substring starting from an offset.

Arguments

• offset - The byte offset to start searching from (relative to this source)
• pattern - The substring to search for

Returns

The offset of the next occurrence, or None if not found

fn syntax_error(&self, message: impl Into<String>, position: usize) -> OakError

Create an error for an invalid range.

Arguments

• range - The invalid range
• message - The error message

Returns

An OakError with position information at the start of the range

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl<'input> Source for &'input SourceText

impl<'view> Source for SourceView<'view>