Struct miden_diagnostics::CodeMap

pub struct CodeMap { /* private fields */ }

CodeMap is a thread-safe structure for recording source code files and their contents for use in diagnostics and parsing/compilation.

The CodeMap maintains a set of SourceFile entries corresponding to the sources added to it, with various auxiliary structures for tracking the FileName under which each source was added, the SourceId assigned to it, and which files on disk have been read into memory and added to it.

The CodeMap is designed to de-duplicate files and avoid reading from disk multiple times for the same Path. It is also designed to live for the entire lifetime of the compilation pipeline, so that at any point, diagnostics may be generated which refer to the original sources.

It is generally advised to allocate the CodeMap in an std::sync::Arc, so that it may be freely passed around and accessed from multiple threads and/or contexts which need it. Internally it uses thread-safe datastructures, so there isn’t any reason to prefer passing it around by reference.

Implementations

impl CodeMap

pub fn new() -> Self

Creates an empty CodeMap.

pub fn add(&self, name: impl Into<FileName>, source: String) -> SourceId

Add a file to this CodeMap, returning the SourceId assigned to it.

The SourceId acts as a unique identifier for the file and content. However, it is not guaranteed that a FileName always maps to a single SourceId, as multiple threads may attempt to add the same file at the same time, which in some cases may result in a duplicate entry. In general though, they are 1:1.

pub fn add_file<P: AsRef<Path>>(&self, path: P) -> Result<SourceId>

Adds a file to the map from the given path, if not already present.

Returns Ok if successfully added, or Err if an error occurred while reading the file from disk.

pub fn add_child( &self, name: impl Into<FileName>, source: String, parent: SourceSpan ) -> SourceId

Add a file to the map with the given SourceSpan as a parent.

This is intended for use cases such as a preprocessor which needs to include content from another file directly into the content of its parent, as if they are part of the same logical file. When a SourceSpan spans the region in which the included content occurs, it only gets the content in the original parent file.

NOTE: This always results in a new entry in the map in order to record the lineage of the source content.

pub fn get(&self, file_id: SourceId) -> Result<Arc<SourceFile>, Error>

Get the SourceFile corresponding to the given SourceId

pub fn get_with_span(&self, span: SourceSpan) -> Result<Arc<SourceFile>, Error>

Get the SourceFile corresponding to the given SourceSpan

Returns Err if the span is SourceSpan::UNKNOWN

pub fn parent(&self, file_id: SourceId) -> Option<SourceSpan>

Get the SourceSpan corresponding to the parent of a given SourceId.

Returns None if the given SourceId has no parent

pub fn get_file_id(&self, filename: &FileName) -> Option<SourceId>

Get the SourceId corresponding to the given FileName

pub fn get_by_name(&self, filename: &FileName) -> Option<Arc<SourceFile>>

Get the SourceFile corresponding to the given FileName

pub fn name(&self, file_id: SourceId) -> Result<FileName, Error>

Get the FileName corresponding to the given SourceId

Returns Err if file_id is not in this map.

pub fn name_for_spanned<S: Spanned>( &self, spanned: &S ) -> Result<FileName, Error>

Get the FileName associated with the given SourceSpan

Returns Err if span is SourceSpan::UNKNOWN.

pub fn line_column_to_span( &self, file_id: SourceId, line: impl Into<LineIndex>, column: impl Into<ColumnIndex> ) -> Result<SourceSpan, Error>

Get a SourceSpan corresponding to the given line:column

NOTE: The returned SourceSpan points only to line:column, it does not span any neighboring source locations, callers must extend the returned span if so desired.

pub fn location<S: Spanned>(&self, spanned: &S) -> Result<Location, Error>

Get a Location from a SourceSpan

Returns Err if span is SourceSpan::UNKNOWN.

pub fn location_at_index( &self, file_id: SourceId, byte_index: impl Into<ByteIndex> ) -> Result<Location, Error>

Get a Location from a given SourceId and byte index.

pub fn source_span(&self, file_id: SourceId) -> Result<SourceSpan, Error>

Get a SourceSpan representing the entire content of file_id

pub fn source_slice<'a, S: Spanned>( &'a self, spanned: &S ) -> Result<&'a str, Error>

Get the original source content corresponding to spanned as a &str

Trait Implementations

impl Debug for CodeMap

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for CodeMap

fn default() -> Self

Returns the “default value” for a type.

impl<'a> Files<'a> for CodeMap

type FileId = SourceId

A unique identifier for files in the file provider. This will be used for rendering diagnostic::Labels in the corresponding source files.

type Name = String

The user-facing name of a file, to be displayed in diagnostics.

type Source = &'a str

The source code of a file.

fn name(&self, file_id: Self::FileId) -> Result<Self::Name, Error>

The user-facing name of a file.

fn source(&self, file_id: Self::FileId) -> Result<&'a str, Error>

The source code of a file.

fn line_index( &self, file_id: Self::FileId, byte_index: usize ) -> Result<usize, Error>

The index of the line at the given byte index. If the byte index is past the end of the file, returns the maximum line index in the file. This means that this function only fails if the file is not present.

fn line_range( &self, file_id: Self::FileId, line_index: usize ) -> Result<Range<usize>, Error>

The byte range of line in the source of the file.

fn line_number( &'a self, id: Self::FileId, line_index: usize ) -> Result<usize, Error>

The user-facing line number at the given line index. It is not necessarily checked that the specified line index is actually in the file.

fn column_number( &'a self, id: Self::FileId, line_index: usize, byte_index: usize ) -> Result<usize, Error>

The user-facing column number at the given line index and byte index.

fn location( &'a self, id: Self::FileId, byte_index: usize ) -> Result<Location, Error>

Convenience method for returning line and column number at the given byte index in the file.