span

Documentation

Overview

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

Index

• Variables
• func SameExistingFile(a, b URI) bool
• func SortSpans(spans []Span)
• type Point
  • 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 Span
  • 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 (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
• 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 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.

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 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 Span

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

A Span represents a range of text within a source file. The start and end points of a valid span may be hold either its byte offset, or its (line, column) pair, or both. Columns are measured in bytes.

Spans are appropriate in user interfaces (e.g. command-line tools) and tests where a position is notated without access to the content of the file.

Use protocol.Mapper to convert between Span and other representations, such as go/token (also UTF-8) or the LSP protocol (UTF-16). The latter requires access to file contents.

See overview comments at ../lsp/protocol/mapper.go.

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) 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

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

TODO(adonovan): document this function, and any invariants of span.URI that it is supposed to establish.

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