golang.org/x/tools/gopls@v0.15.3/internal/file/file.go (about)

     1  // Copyright 2023 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  // The file package defines types used for working with LSP files.
     6  package file
     7  
     8  import (
     9  	"context"
    10  	"fmt"
    11  
    12  	"golang.org/x/tools/gopls/internal/protocol"
    13  )
    14  
    15  // An Identity identifies the name and contents of a file.
    16  //
    17  // TODO(rfindley): Identity may not carry its weight. Consider instead just
    18  // exposing Handle.Hash, and using an ad-hoc key type where necessary.
    19  // Or perhaps if mod/work parsing is moved outside of the memoize cache,
    20  // a notion of Identity simply isn't needed.
    21  type Identity struct {
    22  	URI  protocol.DocumentURI
    23  	Hash Hash // digest of file contents
    24  }
    25  
    26  func (id Identity) String() string {
    27  	return fmt.Sprintf("%s%s", id.URI, id.Hash)
    28  }
    29  
    30  // A FileHandle represents the URI, content, hash, and optional
    31  // version of a file tracked by the LSP session.
    32  //
    33  // File content may be provided by the file system (for Saved files)
    34  // or from an overlay, for open files with unsaved edits.
    35  // A FileHandle may record an attempt to read a non-existent file,
    36  // in which case Content returns an error.
    37  type Handle interface {
    38  	// URI is the URI for this file handle.
    39  	URI() protocol.DocumentURI
    40  	// Identity returns an Identity for the file, even if there was an error
    41  	// reading it.
    42  	Identity() Identity
    43  	// SameContentsOnDisk reports whether the file has the same content on disk:
    44  	// it is false for files open on an editor with unsaved edits.
    45  	SameContentsOnDisk() bool
    46  	// Version returns the file version, as defined by the LSP client.
    47  	// For on-disk file handles, Version returns 0.
    48  	Version() int32
    49  	// Content returns the contents of a file.
    50  	// If the file is not available, returns a nil slice and an error.
    51  	Content() ([]byte, error)
    52  }
    53  
    54  // A Source maps URIs to Handles.
    55  type Source interface {
    56  	// ReadFile returns the Handle for a given URI, either by reading the content
    57  	// of the file or by obtaining it from a cache.
    58  	//
    59  	// Invariant: ReadFile must only return an error in the case of context
    60  	// cancellation. If ctx.Err() is nil, the resulting error must also be nil.
    61  	ReadFile(ctx context.Context, uri protocol.DocumentURI) (Handle, error)
    62  }