file

Documentation

Overview

The file package defines types used for working with LSP files.

Index

• Constants
• type Action
  • func (a Action) String() string
• type Handle
• type Hash
  • func HashOf(data []byte) Hash
  • func (h Hash) String() string
  • func (h *Hash) XORWith(h2 Hash)
• type Identity
  • func (id Identity) String() string
• type Kind
  • func KindForLang(langID protocol.LanguageKind) Kind
  • func (k Kind) String() string
• type Modification
• type Source

Constants

const (
	// UnknownKind is a file type we don't know about.
	UnknownKind = Kind(iota)

	// Go is a Go source file.
	Go
	// Mod is a go.mod file.
	Mod
	// Sum is a go.sum file.
	Sum
	// Tmpl is a template file.
	Tmpl
	// Work is a go.work file.
	Work
)

const (
	UnknownAction = Action(iota)
	Open
	Change
	Close
	Save
	Create
	Delete
)

Types

type Action

type Action int

An Action is a type of file state change.

func (Action) String

func (a Action) String() string

type Handle

type Handle interface {
	// URI is the URI for this file handle.
	URI() protocol.DocumentURI
	// Identity returns an Identity for the file, even if there was an error
	// reading it.
	Identity() Identity
	// SameContentsOnDisk reports whether the file has the same content on disk:
	// it is false for files open on an editor with unsaved edits.
	SameContentsOnDisk() bool
	// Version returns the file version, as defined by the LSP client.
	// For on-disk file handles, Version returns 0.
	Version() int32
	// Content returns the contents of a file.
	// If the file is not available, returns a nil slice and an error.
	Content() ([]byte, error)
}

A FileHandle represents the URI, content, hash, and optional version of a file tracked by the LSP session.

File content may be provided by the file system (for Saved files) or from an overlay, for open files with unsaved edits. A FileHandle may record an attempt to read a non-existent file, in which case Content returns an error.

type Hash

type Hash [sha256.Size]byte

A Hash is a cryptographic digest of the contents of a file. (Although at 32B it is larger than a 16B string header, it is smaller and has better locality than the string header + 64B of hex digits.)

func HashOf

func HashOf(data []byte) Hash

HashOf returns the hash of some data.

func (Hash) String

func (h Hash) String() string

String returns the digest as a string of hex digits.

func (*Hash) XORWith

func (h *Hash) XORWith(h2 Hash)

XORWith updates *h to *h XOR h2.

type Identity

type Identity struct {
	URI  protocol.DocumentURI
	Hash Hash // digest of file contents
}

An Identity identifies the name and contents of a file.

TODO(rfindley): Identity may not carry its weight. Consider instead just exposing Handle.Hash, and using an ad-hoc key type where necessary. Or perhaps if mod/work parsing is moved outside of the memoize cache, a notion of Identity simply isn't needed.

func (Identity) String

func (id Identity) String() string

type Kind

type Kind int

Kind describes the kind of the file in question. It can be one of Go,mod, Sum, or Tmpl.

func KindForLang

func KindForLang(langID protocol.LanguageKind) Kind

KindForLang returns the gopls file Kind associated with the given LSP LanguageKind string from protocol.TextDocumentItem.LanguageID, or UnknownKind if the language is not one recognized by gopls.

func (Kind) String

func (k Kind) String() string

type Modification

type Modification struct {
	URI    protocol.DocumentURI
	Action Action

	// OnDisk is true if a watched file is changed on disk.
	// If true, Version will be -1 and Text will be nil.
	OnDisk bool

	// Version will be -1 and Text will be nil when they are not supplied,
	// specifically on textDocument/didClose and for on-disk changes.
	Version int32
	Text    []byte

	// LanguageID is only sent from the language client on textDocument/didOpen.
	LanguageID protocol.LanguageKind
}

Modification represents a modification to a file.

type Source

type Source interface {
	// ReadFile returns the Handle for a given URI, either by reading the content
	// of the file or by obtaining it from a cache.
	//
	// Invariant: ReadFile must only return an error in the case of context
	// cancellation. If ctx.Err() is nil, the resulting error must also be nil.
	ReadFile(ctx context.Context, uri protocol.DocumentURI) (Handle, error)
}

A Source maps URIs to Handles.