Trait Files

pub trait Files<'a> {
    type FileId: 'a + Copy + PartialEq;
    type Name: 'a + Display;
    type Source: 'a + AsRef<str>;

    // Required methods
    fn name(&'a self, id: Self::FileId) -> Result<Self::Name, Error>;
    fn source(&'a self, id: Self::FileId) -> Result<Self::Source, Error>;
    fn line_index(
        &'a self,
        id: Self::FileId,
        byte_index: usize,
    ) -> Result<usize, Error>;
    fn line_range(
        &'a self,
        id: Self::FileId,
        line_index: usize,
    ) -> Result<Range<usize>, Error>;

    // Provided methods
    fn line_number(
        &'a self,
        id: Self::FileId,
        line_index: usize,
    ) -> Result<usize, Error> { ... }
    fn column_number(
        &'a self,
        id: Self::FileId,
        line_index: usize,
        byte_index: usize,
    ) -> Result<usize, Error> { ... }
    fn location(
        &'a self,
        id: Self::FileId,
        byte_index: usize,
    ) -> Result<Location, Error> { ... }
}

A minimal interface for accessing source files when rendering diagnostics.

A lifetime parameter 'a is provided to allow any of the returned values to returned by reference. This is to workaround the lack of higher kinded lifetime parameters. This can be ignored if this is not needed, however.

Required Associated Types

type FileId: 'a + Copy + PartialEq

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

type Name: 'a + Display

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

type Source: 'a + AsRef<str>

The source code of a file.

Required Methods

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

The user-facing name of a file.

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

The source code of a file.

fn line_index( &'a self, 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.

Note for trait implementors

This can be implemented efficiently by performing a binary search over a list of line starts that was computed by calling the line_starts function that is exported from the files module. It might be useful to pre-compute and cache these line starts.

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

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

Provided Methods

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.

Note for trait implementors

This is usually 1-indexed from the beginning of the file, but can be useful for implementing something like the C preprocessor’s #line macro.

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.

Note for trait implementors

This is usually 1-indexed from the the start of the line. A default implementation is provided, based on the column_index function that is exported from the files module.

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.

Implementors

impl<'a, Name, Source> Files<'a> for SimpleFile<Name, Source>

where Name: 'a + Display + Clone, Source: 'a + AsRef<str>,

type FileId = ()

type Name = Name

type Source = &'a str

impl<'a, Name, Source> Files<'a> for SimpleFiles<Name, Source>

where Name: 'a + Display + Clone, Source: 'a + AsRef<str>,

type FileId = usize

type Name = Name

type Source = &'a str