Documentation
¶
Overview ¶
Package source provides a standard interfaces for working with source files and spans within them.
File is a source code file read from somewhere, which tracks its contents, its on-disk path, and book-keeping information for looking up offsets. Span is a region of some File which is used for diagnostics. Opener is a common interface for loading [File]s on disk.
Index ¶
- type FS
- type File
- func (f *File) EOF() Span
- func (f *File) Indentation(offset int) string
- func (f *File) InverseLocation(line, column int, units length.Unit) Location
- func (f *File) Line(line int) string
- func (f *File) LineByOffset(offset int) (number int)
- func (f *File) LineOffsets(line int) (start, end int)
- func (f *File) Location(offset int, units length.Unit) Location
- func (f *File) Path() string
- func (f *File) Span(start, end int) Span
- func (f *File) Text() string
- type Location
- type Map
- type Opener
- type Openers
- type Span
- func (s Span) After() string
- func (s Span) Before() string
- func (s Span) EndLoc() Location
- func (s Span) GrowLeft(p func(r rune) bool) Span
- func (s Span) GrowRight(p func(r rune) bool) Span
- func (s Span) Indentation() string
- func (s Span) IsZero() bool
- func (s Span) Len() int
- func (s Span) Range(i, j int) Span
- func (s Span) Rune(i int) Span
- func (s Span) RuneRange(i, j int) Span
- func (s Span) Span() Span
- func (s Span) StartLoc() Location
- func (s Span) String() string
- func (s Span) Text() string
- type Spanner
- type Workspace
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type FS ¶
type File ¶
type File struct {
// contains filtered or unexported fields
}
File is a source code file involved in a diagnostic.
It contains additional book-keeping information for resolving span locations. Files are immutable once created.
A nil *File behaves like an empty file with the path name "".
func (*File) Indentation ¶
Indentation calculates the indentation some offset.
Indentation is defined as the substring between the last newline in before the offset and the first non-Pattern_White_Space after that newline.
func (*File) InverseLocation ¶
InverseLocation inverts the operation in File.Location.
line and column should be 1-indexed, and units should be the units used to measure the column width. If units is [TermWidth], this function panics, because inverting a [TermWidth] location is not supported.
func (*File) Line ¶
Line returns the given line, including its trailing newline.
line is expected to be 1-indexed.
func (*File) LineByOffset ¶
LineByOffset searches this index to find the line number for the line containing this byte offset.
This operation is O(log n).
func (*File) LineOffsets ¶
LineOffsets returns the offsets for the given line, including its trailing newline.
line is expected to be 1-indexed.
func (*File) Location ¶
Location searches this index to build full Location information for the given byte offset.
This operation is O(log n).
func (*File) Path ¶
Path returns this file's filesystem path.
It doesn't need to be a real path, but it will be used to deduplicate spans according to their file.
type Location ¶
type Location struct {
// The byte offset for this location.
Offset int
// The line and column for this location, 1-indexed.
//
// The units of measurement for column depend on the [length.Unit] used when
// constructing it.
//
// Because these are 1-indexed, a zero Line can be used as a sentinel.
Line, Column int
}
Location is a user-displayable location within a source code file.
type Map ¶
type Map cmpx.MapWrapper[string, *File]
Map implements Opener via lookup of a built-in map. This map is not directly accessible, to help avoid mistaken uses that cause different *Map pointer values (for the same built-in map value) to wind up in different queries, which breaks query caching.
Missing entries result in fs.ErrNotExist.
func NewMap ¶
NewMap creates a new Map wrapping the given map.
If passed nil, this will update the map to be an empty non-nil map.
type Opener ¶
type Opener interface {
// Open opens a file, potentially returning an error.
//
// Note that the path of the returned file need not he path; this path should
// *only* be used for diagnostics.
//
// A return value of [fs.ErrNotExist] is given special treatment by some
// Opener adapters, such as the [Openers] type.
Open(path string) (*File, error)
}
Opener is a mechanism for opening files.
Opener implementations are assumed by Protocompile to be comparable. It is sufficient to always ensure that the implementation uses a pointer receiver.
type Openers ¶
type Openers []Opener
Openers wraps a sequence of [Opener]s.
When calling Open, it calls each Opener in sequence until one does not return fs.ErrNotExist.
type Span ¶
type Span struct {
// The file this span refers to. The file must be indexed, since we plan to
// convert Start/End into editor coordinates.
*File
// The start and end byte offsets for this span.
Start, End int
}
Span is a location within a File.
func Between ¶
Between is a helper function that returns a Span for the space between spans a and b, inclusive. If a and b do not have the same File or if the spans overlap, then this returns a zero span.
func GetSpan ¶
GetSpan extracts a span from a Spanner, but returns the zero span when s is zero, which would otherwise panic.
func Join ¶
Join joins a collection of spans, returning the smallest span that contains all of them.
IsZero spans among spans are ignored. If every span in spans is zero, returns the zero span.
If there are at least two distinct files among the non-zero spans, this function panics.
func (Span) GrowLeft ¶
GrowLeft returns a new span which contains the largest suffix of Span.Before which match p.
func (Span) GrowRight ¶
GrowRight returns a new span which contains the largest prefix of Span.After which match p.
func (Span) Indentation ¶
Indentation calculates the indentation at this span.
Indentation is defined as the substring between the last newline in Span.Before and the first non-Pattern_White_Space after that newline.
func (Span) Range ¶
Range slices this span along the given byte indices.
Unlike slicing into a string, out-of-bounds indices are snapped to the boundaries of the string, and negative indices are taken from the back of the span. For example, s.RuneRange(-2, -1) is the final rune of the span (or an empty span, if s is empty).
func (Span) Rune ¶
Rune is a shorthand for RuneRange(i, i+1) or RuneRange(i-1, i), depending on the sign of i.
func (Span) RuneRange ¶
RuneRange slices this span along the given rune indices.
For example, s.RuneRange(0, 2) returns at most the first two runes of the span.
Unlike slicing into a string, out-of-bounds indices are snapped to the boundaries of the string, and negative indices are taken from the back of the span. For example, s.RuneRange(-2, -1) is the final rune of the span (or an empty span, if s is empty).
type Spanner ¶
type Spanner interface {
// Should return the zero [Span] to indicate that it does not contribute
// span information.
Span() Span
}
Spanner is any type with a Span.
type Workspace ¶
type Workspace interface {
// Paths returns an iterator for the paths of the Workspace.
Paths() []string
}
Workspace is a set of Protobuf source paths.
Workspace implementations are assumed by Protocompile to be comparable. It is sufficient to always ensure that the implementation uses a pointer receiver.
func NewWorkspace ¶
NewWorkspace returns a Workspace implementation for the given paths that is comparable.
No validations/transformations are performed on the given paths, it is the responsibility of the caller to enforce path order and validity.
Source Files
Directories