Crate source_lang 

source_lang

The multi-file coordinate layer of a compiler front-end. It holds many sources — files and in-memory buffers — in one SourceMap, gives each a stable SourceId, lays them out across a single global position space, and resolves any global BytePos back to the source and local offset it came from — or, in one step, to the source and a 1-based LineCol.

It is the layer above span_lang: a Span says where in a buffer an error is, and this crate says which buffer, so a diagnostic can name the file as well as the position. It owns source storage and coordinate mapping only — no lexing, no diagnostic rendering.

Loading sources

Sources come from three places, all funnelling through the same checks so a buffer and a file fail and succeed the same way: add for text already in hand, add_bytes for raw bytes validated as UTF-8, and add_file (with the std feature) for a path read from disk. Bad input is a defined SourceMapError — oversize, non-UTF-8, or an I/O failure — never a panic. set_max_source_len caps how much one untrusted source may load.

Model

Sources are placed end to end in the order they are added. The first occupies global offsets 0..len₀, the next len₀..len₀ + len₁, and so on, so the ranges never overlap and the whole project shares one position space. Because each base is the running total, the sources stay sorted by offset and SourceMap::locate is a binary search — O(log files) — that borrows the resolved source rather than copying it. The space is 32 bits wide, so the combined length of every source is capped at u32::MAX; overrunning it is a defined SourceMapError, never a silent wrap.

Quickstart

use source_lang::{BytePos, SourceMap};

let mut map = SourceMap::new();
let main = map.add("main.rs", "fn main() {}")?; // global 0..12
let util = map.add("util.rs", "fn helper() {}")?; // global 12..26

// Resolve a global position to its file and the local offset within it.
let (id, local) = map.locate(BytePos::new(13)).expect("inside util.rs");
assert_eq!(id, util);
assert_eq!(local, BytePos::new(1)); // 13 - 12

// The id is a stable handle back to the source.
assert_eq!(map.source(main).unwrap().name(), "main.rs");

Stability

The public API is stable as of 1.0 and follows Semantic Versioning: no breaking changes before 2.0, additions arrive in minor releases, and the MSRV (Rust 1.85) only rises in a minor. The full promise is in docs/API.md.

Structs

BytePos

A zero-based byte offset into a single source buffer.

LineCol

A resolved human coordinate: a 1-based line and a 1-based column.

LineIndex

An index over a single source string that maps byte offsets to line/column coordinates and back.

SourceFile

A single source held by a SourceMap: a display name, the owned source text, and the half-open Span the text occupies in the map’s global position space.

SourceId

A small, copyable handle to one source in a SourceMap.

SourceMap

A collection of sources laid out end to end in a single global position space.

Span

A half-open byte range start..end into a single source.

Enums

SourceMapError

The reason a source could not be added to a SourceMap.