source-lang 0.2.0

Source file and buffer management with multi-file source maps.
Documentation

Installation

[dependencies]
source-lang = "0.2"

Or from the terminal:

cargo add source-lang

Usage

Add sources to a map and resolve a global position back to the file and local offset it came from.

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

// Which file does global position 13 belong to, and where inside 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 for the life of the map.
assert_eq!(map.source(main).unwrap().name(), "main.rs");
# Ok::<(), source_lang::SourceMapError>(())

Read the located text back out of the resolved source:

use source_lang::{BytePos, SourceMap};

let mut map = SourceMap::new();
map.add("a", "let x = 1;")?;
let two = map.add("b", "let y = 2;")?;

let (id, local) = map.locate(BytePos::new(14)).expect("in range");
assert_eq!(id, two);
let file = map.source(id).unwrap();
assert_eq!(&file.text()[local.to_usize()..], "y = 2;");
# Ok::<(), source_lang::SourceMapError>(())

Walk every loaded source in order — id order is also global-offset order:

use source_lang::SourceMap;

let mut map = SourceMap::new();
map.add("a.txt", "one")?;
map.add("b.txt", "two")?;

let names: Vec<_> = map.iter().map(|(_, f)| f.name()).collect();
assert_eq!(names, ["a.txt", "b.txt"]);
# Ok::<(), source_lang::SourceMapError>(())

See docs/API.md for the full reference.

How it works

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. The ranges never overlap, and because each base is the running total of all earlier sources, the internal list stays sorted by offset — so locate is a binary search, O(log files), that borrows the resolved source rather than copying it. The shared space is 32 bits wide (the same envelope a single BytePos addresses), so the combined length of every source is capped at 4 GiB; overrunning it is a defined error, never a silent wrap into a neighbour's range.

Status

v0.2.0 implements the core: the SourceMap, stable SourceIds, the non-overlapping global position space, and the O(log files) resolver — each invariant property-tested against a naive linear scan. File loading from disk, line/column integration, and serde land across the rest of the 0.x series per the ROADMAP; the public API is frozen at 1.0.0.

Contributing

See dev/DIRECTIVES.md for engineering standards and the definition of done. Before a PR: cargo fmt --all, cargo clippy --all-targets --all-features -- -D warnings, and cargo test --all-features must be clean.