gopls/internal/lsp/protocol: move MappedRange

It was formerly in the source package; now it lives adjacent
to ColumnMapper, to which it is closely related.

Also,  encapsulate its start/end offsets and
establish the invariant that they are always valid
by defining a constructor method, ColumnMapper.OffsetMappedRange.

A TODO comment sketches a possible next step:
make its conversion methods infallible.

Change-Id: I1e148ccdb37a762c0c387a77240a41237612e2cc
Reviewed-on: https://go-review.googlesource.com/c/tools/+/460915
TryBot-Result: Gopher Robot <[email protected]>
Reviewed-by: Robert Findley <[email protected]>
Run-TryBot: Alan Donovan <[email protected]>
gopls-CI: kokoro <[email protected]>

Author: adonovan

gopls/internal/lsp/protocol/span.go

@@ -6,14 +6,13 @@
 
 // Here's a handy guide for your tour of the location zoo:
 //
-// Imports: source  --> lsppos  -->  protocol  -->  span  -->  token
-//
-// source.MappedRange = (protocol.ColumnMapper, {start,end}Offset int)
+// Imports: lsppos  -->  protocol  -->  span  -->  token
 //
 // lsppos.TokenMapper = (token.File, lsppos.Mapper)
 // lsppos.Mapper = (line offset table, content)
 //
 // protocol.ColumnMapper = (URI, Content). Does all offset <=> column conversions.
+// protocol.MappedRange = (protocol.ColumnMapper, {start,end} int)
 // protocol.Location = (URI, protocol.Range)
 // protocol.Range = (start, end Position)
 // protocol.Position = (line, char uint32) 0-based UTF-16
@@ -37,6 +36,10 @@
 //   - Replace all uses of lsppos.TokenMapper by the underlying ParsedGoFile,
 //     which carries a token.File and a ColumnMapper.
 //   - Then delete lsppos package.
+//   - ColumnMapper.OffsetPoint and .Position aren't used outside this package.
+//     OffsetSpan is barely used, and its user would better off with a MappedRange
+//     or protocol.Range. The span package data tyes are mostly used in tests
+//     and in argument parsing (without access to file content).
 
 package protocol
 
@@ -287,6 +290,54 @@ func (m *ColumnMapper) Point(p Position) (span.Point, error) {
 	return span.FromUTF16Column(lineStart, int(p.Character)+1, m.Content)
 }
 
+// OffsetMappedRange returns a MappedRange for the given byte offsets.
+// A MappedRange can be converted to any other form.
+func (m *ColumnMapper) OffsetMappedRange(start, end int) (MappedRange, error) {
+	if !(0 <= start && start <= end && end <= len(m.Content)) {
+		return MappedRange{}, fmt.Errorf("invalid offsets (%d, %d) (file %s has size %d)", start, end, m.URI, len(m.Content))
+	}
+	return MappedRange{m, start, end}, nil
+}
+
+// A MappedRange represents a valid byte-offset range of a file.
+// Through its ColumnMapper it can be converted into other forms such
+// as protocol.Range or span.Span.
+//
+// Construct one by calling ColumnMapper.OffsetMappedRange with start/end offsets.
+// From the go/token domain, call safetoken.Offsets first,
+// or use a helper such as ParsedGoFile.MappedPosRange.
+type MappedRange struct {
+	Mapper     *ColumnMapper
+	start, end int // valid byte offsets
+}
+
+// Offsets returns the (start, end) byte offsets of this range.
+func (mr MappedRange) Offsets() (start, end int) { return mr.start, mr.end }
+
+// -- convenience functions --
+
+// URI returns the URI of the range's file.
+func (mr MappedRange) URI() span.URI {
+	return mr.Mapper.URI
+}
+
+// TODO(adonovan): once the fluff is removed from all the
+// location-conversion methods, it will be obvious that a properly
+// constructed MappedRange is always valid and its Range and Span (and
+// other) methods simply cannot fail.
+// At that point we might want to provide variants of methods such as
+// Range and Span below that don't return an error.
+
+// Range returns the range in protocol form.
+func (mr MappedRange) Range() (Range, error) {
+	return mr.Mapper.OffsetRange(mr.start, mr.end)
+}
+
+// Span returns the range in span form.
+func (mr MappedRange) Span() (span.Span, error) {
+	return mr.Mapper.OffsetSpan(mr.start, mr.end)
+}
+
 func IsPoint(r Range) bool {
 	return r.Start.Line == r.End.Line && r.Start.Character == r.End.Character
 }

gopls/internal/lsp/source/folding_range.go

@@ -17,7 +17,7 @@ import (
 
 // FoldingRangeInfo holds range and kind info of folding for an ast.Node
 type FoldingRangeInfo struct {
-	MappedRange MappedRange
+	MappedRange protocol.MappedRange
 	Kind        protocol.FoldingRangeKind
 }
 

gopls/internal/lsp/source/identifier.go

@@ -26,10 +26,10 @@ import (
 type IdentifierInfo struct {
 	Name        string
 	Snapshot    Snapshot // only needed for .View(); TODO(adonovan): reduce.
-	MappedRange MappedRange
+	MappedRange protocol.MappedRange
 
 	Type struct {
-		MappedRange MappedRange
+		MappedRange protocol.MappedRange
 		Object      types.Object
 	}
 
@@ -54,7 +54,7 @@ func (i *IdentifierInfo) IsImport() bool {
 }
 
 type Declaration struct {
-	MappedRange []MappedRange
+	MappedRange []protocol.MappedRange
 
 	// The typechecked node
 	node     ast.Node
@@ -140,7 +140,7 @@ func findIdentifier(ctx context.Context, snapshot Snapshot, pkg Package, pgf *Pa
 			Declaration: Declaration{
 				node:        decl.File.Name,
 				nodeFile:    decl,
-				MappedRange: []MappedRange{declRng},
+				MappedRange: []protocol.MappedRange{declRng},
 			},
 		}, nil
 	}

gopls/internal/lsp/source/references.go

@@ -24,7 +24,7 @@ import (
 // ReferenceInfo holds information about reference to an identifier in Go source.
 type ReferenceInfo struct {
 	Name          string
-	MappedRange   MappedRange
+	MappedRange   protocol.MappedRange
 	ident         *ast.Ident
 	obj           types.Object
 	pkg           Package

gopls/internal/lsp/source/util.go

@@ -23,33 +23,12 @@ import (
 	"golang.org/x/tools/internal/typeparams"
 )
 
-// A MappedRange represents a byte-offset interval within a file.
-// Through the ColumnMapper it can be converted into other forms such
-// as protocol.Range or span.Span.
+// IsGenerated gets and reads the file denoted by uri and reports
+// whether it contains a "go:generated" directive as described at
+// https://golang.org/s/generatedcode.
 //
-// Call ParsedGoFile.MappedPosRange to construct from the go/token domain.
-type MappedRange struct {
-	Mapper     *protocol.ColumnMapper
-	Start, End int // byte offsets
-}
-
-// -- convenience functions --
-
-// Range returns the range in protocol form.
-func (mr MappedRange) Range() (protocol.Range, error) {
-	return mr.Mapper.OffsetRange(mr.Start, mr.End)
-}
-
-// Span returns the range in span form.
-func (mr MappedRange) Span() (span.Span, error) {
-	return mr.Mapper.OffsetSpan(mr.Start, mr.End)
-}
-
-// URI returns the URI of the range's file.
-func (mr MappedRange) URI() span.URI {
-	return mr.Mapper.URI
-}
-
+// TODO(adonovan): opt: this function does too much.
+// Move snapshot.GetFile into the caller (most of which have already done it).
 func IsGenerated(ctx context.Context, snapshot Snapshot, uri span.URI) bool {
 	fh, err := snapshot.GetFile(ctx, uri)
 	if err != nil {
@@ -72,7 +51,7 @@ func IsGenerated(ctx context.Context, snapshot Snapshot, uri span.URI) bool {
 	return false
 }
 
-func objToMappedRange(pkg Package, obj types.Object) (MappedRange, error) {
+func objToMappedRange(pkg Package, obj types.Object) (protocol.MappedRange, error) {
 	nameLen := len(obj.Name())
 	if pkgName, ok := obj.(*types.PkgName); ok {
 		// An imported Go package has a package-local, unqualified name.
@@ -98,18 +77,18 @@ func objToMappedRange(pkg Package, obj types.Object) (MappedRange, error) {
 // TODO(adonovan): many of the callers need only the ParsedGoFile so
 // that they can call pgf.PosRange(pos, end) to get a Range; they
 // don't actually need a MappedRange.
-func posToMappedRange(pkg Package, pos, end token.Pos) (MappedRange, error) {
+func posToMappedRange(pkg Package, pos, end token.Pos) (protocol.MappedRange, error) {
 	if !pos.IsValid() {
-		return MappedRange{}, fmt.Errorf("invalid start position")
+		return protocol.MappedRange{}, fmt.Errorf("invalid start position")
 	}
 	if !end.IsValid() {
-		return MappedRange{}, fmt.Errorf("invalid end position")
+		return protocol.MappedRange{}, fmt.Errorf("invalid end position")
 	}
 
 	logicalFilename := pkg.FileSet().File(pos).Name() // ignore line directives
 	pgf, _, err := findFileInDeps(pkg, span.URIFromPath(logicalFilename))
 	if err != nil {
-		return MappedRange{}, err
+		return protocol.MappedRange{}, err
 	}
 	return pgf.PosMappedRange(pos, end)
 }

gopls/internal/lsp/source/view.go

@@ -401,12 +401,12 @@ func (pgf *ParsedGoFile) PosRange(start, end token.Pos) (protocol.Range, error)
 
 // PosMappedRange returns a MappedRange for the token.Pos interval in this file.
 // A MappedRange can be converted to any other form.
-func (pgf *ParsedGoFile) PosMappedRange(startPos, endPos token.Pos) (MappedRange, error) {
+func (pgf *ParsedGoFile) PosMappedRange(startPos, endPos token.Pos) (protocol.MappedRange, error) {
 	start, end, err := safetoken.Offsets(pgf.Tok, startPos, endPos)
 	if err != nil {
-		return MappedRange{}, nil
+		return protocol.MappedRange{}, nil
 	}
-	return MappedRange{pgf.Mapper, start, end}, nil
+	return pgf.Mapper.OffsetMappedRange(start, end)
 }
 
 // RangeToSpanRange parses a protocol Range back into the go/token domain.