span

Documentation

Overview

Package span contains support for representing with positions and ranges in text files.

Index

• Variables
• func ComparePoint(a, b Point) int
• func NewTokenFile(filename string, content []byte) *token.File
• func SameExistingFile(a, b URI) bool
• func SortSpans(spans []Span)
• func ToOffset(tf *token.File, line, col int) (int, error)
• func ToPosition(tf *token.File, offset int) (int, int, error)
• func ToUTF16Column(p Point, content []byte) (int, error)
• type Point
  • func FromUTF16Column(p Point, chr int, content []byte) (Point, error)
  • func NewPoint(line, col, offset int) Point
  • func (p Point) Column() int
  • func (p Point) HasOffset() bool
  • func (p Point) HasPosition() bool
  • func (p Point) IsValid() bool
  • func (p Point) Line() int
  • func (p *Point) MarshalJSON() ([]byte, error)
  • func (p Point) Offset() int
  • func (p *Point) UnmarshalJSON(b []byte) error
• type Range
  • func NewRange(file *token.File, start, end token.Pos) Range
  • func (r Range) IsPoint() bool
  • func (r Range) Span() (Span, error)
• type Span
  • func FileSpan(posFile, srcFile *token.File, start, end token.Pos) (Span, error)
  • func New(uri URI, start, end Point) Span
  • func Parse(input string) Span
  • func ParseInDir(input, wd string) Span
  • func (s Span) End() Point
  • func (s Span) Format(f fmt.State, c rune)
  • func (s Span) HasOffset() bool
  • func (s Span) HasPosition() bool
  • func (s Span) IsPoint() bool
  • func (s Span) IsValid() bool
  • func (s *Span) MarshalJSON() ([]byte, error)
  • func (s Span) Range(tf *token.File) (Range, error)
  • func (span *Span) SetRange(file *token.File, start, end token.Pos)
  • func (s Span) Start() Point
  • func (s Span) URI() URI
  • func (s *Span) UnmarshalJSON(b []byte) error
  • func (s Span) WithAll(tf *token.File) (Span, error)
  • func (s Span) WithOffset(tf *token.File) (Span, error)
• type URI
  • func URIFromPath(path string) URI
  • func URIFromURI(s string) URI
  • func (uri URI) Filename() string
  • func (uri URI) IsFile() bool

Variables

var Invalid = Span{/* contains filtered or unexported fields */}

Invalid is a span that reports false from IsValid

Functions

func ComparePoint

func ComparePoint(a, b Point) int

func NewTokenFile

func NewTokenFile(filename string, content []byte) *token.File

NewTokenFile returns a token.File for the given file content.

func SameExistingFile

func SameExistingFile(a, b URI) bool

SameExistingFile reports whether two spans denote the same existing file by querying the file system.

func SortSpans

func SortSpans(spans []Span)

SortSpans sorts spans into a stable but unspecified order.

func ToOffset

func ToOffset(tf *token.File, line, col int) (int, error)

ToOffset converts a 1-based line and utf-8 column index into a byte offset in the file corresponding to tf.

func ToPosition

func ToPosition(tf *token.File, offset int) (int, int, error)

ToPosition converts a byte offset in the file corresponding to tf into 1-based line and utf-8 column indexes.

func ToUTF16Column

func ToUTF16Column(p Point, content []byte) (int, error)

ToUTF16Column calculates the utf16 column expressed by the point given the supplied file contents. This is used to convert from the native (always in bytes) column representation and the utf16 counts used by some editors.

TODO(adonovan): this function is unused except by its test. Delete, or consolidate with (*protocol.ColumnMapper).utf16Column.

Types

type Point

type Point struct {
	// contains filtered or unexported fields
}

Point represents a single point within a file. In general this should only be used as part of a Span, as on its own it does not carry enough information.

func FromUTF16Column

func FromUTF16Column(p Point, chr int, content []byte) (Point, error)

FromUTF16Column advances the point by the utf16 character offset given the supplied line contents. This is used to convert from the utf16 counts used by some editors to the native (always in bytes) column representation.

The resulting Point always has an offset.

TODO: it looks like this may incorrectly confer a "position" to the resulting Point, when it shouldn't. If p.HasPosition() == false, the resulting Point will return p.HasPosition() == true, but have the wrong position.

func NewPoint

func NewPoint(line, col, offset int) Point

func (Point) Column

func (p Point) Column() int

func (Point) HasOffset

func (p Point) HasOffset() bool

func (Point) HasPosition

func (p Point) HasPosition() bool

func (Point) IsValid

func (p Point) IsValid() bool

func (Point) Line

func (p Point) Line() int

func (*Point) MarshalJSON

func (p *Point) MarshalJSON() ([]byte, error)

func (Point) Offset

func (p Point) Offset() int

func (*Point) UnmarshalJSON

func (p *Point) UnmarshalJSON(b []byte) error

type Range

type Range struct {
	TokFile    *token.File // non-nil
	Start, End token.Pos   // both IsValid()
}

Range represents a source code range in token.Pos form. It also carries the token.File that produced the positions, so that it is self contained.

func NewRange

func NewRange(file *token.File, start, end token.Pos) Range

NewRange creates a new Range from a token.File and two positions within it. The given start position must be valid; if end is invalid, start is used as the end position.

(If you only have a token.FileSet, use file = fset.File(start). But most callers know exactly which token.File they're dealing with and should pass it explicitly. Not only does this save a lookup, but it brings us a step closer to eliminating the global FileSet.)

func (Range) IsPoint

func (r Range) IsPoint() bool

IsPoint returns true if the range represents a single point.

func (Range) Span

func (r Range) Span() (Span, error)

Span converts a Range to a Span that represents the Range. It will fill in all the members of the Span, calculating the line and column information.

type Span

type Span struct {
	// contains filtered or unexported fields
}

Span represents a source code range in standardized form.

func FileSpan

func FileSpan(posFile, srcFile *token.File, start, end token.Pos) (Span, error)

FileSpan returns a span within the file referenced by start and end, using a token.File to translate between offsets and positions.

The start and end position must be contained within posFile, though due to line directives they may reference positions in another file. If srcFile is provided, it is used to map the line:column positions referenced by start and end to offsets in the corresponding file.

TODO(adonovan): clarify whether it is valid to pass posFile==srcFile when //line directives are in use. If so, fix this function; if not, fix Range.Span.

func New

func New(uri URI, start, end Point) Span

func Parse

func Parse(input string) Span

Parse returns the location represented by the input. Only file paths are accepted, not URIs. The returned span will be normalized, and thus if printed may produce a different string.

func ParseInDir

func ParseInDir(input, wd string) Span

ParseInDir is like Parse, but interprets paths relative to wd.

func (Span) End

func (s Span) End() Point

func (Span) Format

func (s Span) Format(f fmt.State, c rune)

Format implements fmt.Formatter to print the Location in a standard form. The format produced is one that can be read back in using Parse.

func (Span) HasOffset

func (s Span) HasOffset() bool

func (Span) HasPosition

func (s Span) HasPosition() bool

func (Span) IsPoint

func (s Span) IsPoint() bool

func (Span) IsValid

func (s Span) IsValid() bool

func (*Span) MarshalJSON

func (s *Span) MarshalJSON() ([]byte, error)

func (Span) Range

func (s Span) Range(tf *token.File) (Range, error)

Range converts a Span to a Range that represents the Span for the supplied File.

func (*Span) SetRange

func (span *Span) SetRange(file *token.File, start, end token.Pos)

SetRange implements packagestest.rangeSetter, allowing gopls' test suites to use Spans instead of Range in parameters.

func (Span) Start

func (s Span) Start() Point

func (Span) URI

func (s Span) URI() URI

func (*Span) UnmarshalJSON

func (s *Span) UnmarshalJSON(b []byte) error

func (Span) WithAll

func (s Span) WithAll(tf *token.File) (Span, error)

func (Span) WithOffset

func (s Span) WithOffset(tf *token.File) (Span, error)

type URI

type URI string

URI represents the full URI for a file.

func URIFromPath

func URIFromPath(path string) URI

URIFromPath returns a span URI for the supplied file path.

For empty paths, URIFromPath returns the empty URI "". For non-empty paths, URIFromPath returns a uri with the file:// scheme.

func URIFromURI

func URIFromURI(s string) URI

func (URI) Filename

func (uri URI) Filename() string

Filename returns the file path for the given URI. It is an error to call this on a URI that is not a valid filename.

func (URI) IsFile

func (uri URI) IsFile() bool