xrefs

Documentation

Overview

Package xrefs defines the xrefs Service interface and some useful utility functions.

Index

• Variables
• func ConvertFilters(filters []string) []*regexp.Regexp
• func FixTickets(tickets []string) ([]string, error)
• func InSpanBounds(kind xpb.DecorationsRequest_SpanKind, ...) bool
• func IsCallerKind(requestedKind xpb.CrossReferencesRequest_CallerKind, edgeKind string) bool
• func IsDeclKind(requestedKind xpb.CrossReferencesRequest_DeclarationKind, edgeKind string, ...) bool
• func IsDefKind(requestedKind xpb.CrossReferencesRequest_DefinitionKind, edgeKind string, ...) bool
• func IsInternalKind(kind string) bool
• func IsRefKind(requestedKind xpb.CrossReferencesRequest_ReferenceKind, edgeKind string) bool
• func IsRelatedNodeKind(requestedKinds stringset.Set, kind string) bool
• func MatchesAny(str string, patterns []*regexp.Regexp) bool
• func RegisterHTTPHandlers(ctx context.Context, xs Service, mux *http.ServeMux)
• type BoundedRequests
  • func (b BoundedRequests) CrossReferences(ctx context.Context, req *xpb.CrossReferencesRequest) (*xpb.CrossReferencesReply, error)
  • func (b BoundedRequests) Documentation(ctx context.Context, req *xpb.DocumentationRequest) (*xpb.DocumentationReply, error)
• type ByName
  • func (s ByName) Len() int
  • func (s ByName) Less(i, j int) bool
  • func (s ByName) Swap(i, j int)
• type Normalizer
  • func NewNormalizer(text []byte) *Normalizer
  • func (n *Normalizer) ByteOffset(offset int32) *cpb.Point
  • func (n *Normalizer) Location(loc *xpb.Location) (*xpb.Location, error)
  • func (n *Normalizer) Point(p *cpb.Point) *cpb.Point
  • func (n *Normalizer) Span(s *cpb.Span) *cpb.Span
  • func (n *Normalizer) SpanOffsets(start, end int32) *cpb.Span
• type Patcher
  • func NewPatcher(oldText, newText []byte) *Patcher
  • func (p *Patcher) Patch(spanStart, spanEnd int32) (newStart, newEnd int32, exists bool)
  • func (p *Patcher) PatchSpan(span *cpb.Span) (newStart, newEnd int32, exists bool)
• type Service
  • func WebClient(addr string) Service

Variables

var (
	// ErrDecorationsNotFound is returned by an implementation of the Decorations
	// method when decorations for the given file cannot be found.
	ErrDecorationsNotFound = status.Error(codes.NotFound, "file decorations not found")

	// ErrCanceled is returned by services when the caller cancels the RPC.
	ErrCanceled = status.Error(codes.Canceled, "canceled")

	// ErrDeadlineExceeded is returned by services when something times out.
	ErrDeadlineExceeded = status.Error(codes.DeadlineExceeded, "deadline exceeded")
)

Functions

func ConvertFilters

func ConvertFilters(filters []string) []*regexp.Regexp

ConvertFilters converts each filter glob into an equivalent regexp.

func FixTickets

func FixTickets(tickets []string) ([]string, error)

FixTickets converts the specified tickets, which are expected to be Kythe URIs, into canonical form. It is an error if len(tickets) == 0.

func InSpanBounds

func InSpanBounds(kind xpb.DecorationsRequest_SpanKind, start, end, startBoundary, endBoundary int32) bool

InSpanBounds reports whether [start,end) is bounded by the specified [startBoundary,endBoundary) span.

func IsCallerKind

func IsCallerKind(requestedKind xpb.CrossReferencesRequest_CallerKind, edgeKind string) bool

IsCallerKind determines whether the given edgeKind matches the requested caller kind.

func IsDeclKind

func IsDeclKind(requestedKind xpb.CrossReferencesRequest_DeclarationKind, edgeKind string, incomplete bool) bool

IsDeclKind reports whether the given edgeKind matches the requested declaration kind

func IsDefKind

func IsDefKind(requestedKind xpb.CrossReferencesRequest_DefinitionKind, edgeKind string, incomplete bool) bool

IsDefKind reports whether the given edgeKind matches the requested definition kind.

func IsInternalKind

func IsInternalKind(kind string) bool

IsInternalKind determines whether the given edge kind is an internal variant.

func IsRefKind

func IsRefKind(requestedKind xpb.CrossReferencesRequest_ReferenceKind, edgeKind string) bool

IsRefKind determines whether the given edgeKind matches the requested reference kind.

func IsRelatedNodeKind

func IsRelatedNodeKind(requestedKinds stringset.Set, kind string) bool

IsRelatedNodeKind determines whether the give edge kind matches the requested related node kinds.

func MatchesAny

func MatchesAny(str string, patterns []*regexp.Regexp) bool

MatchesAny reports whether if str matches any of the patterns

func RegisterHTTPHandlers

func RegisterHTTPHandlers(ctx context.Context, xs Service, mux *http.ServeMux)

RegisterHTTPHandlers registers JSON HTTP handlers with mux using the given xrefs Service. The following methods with be exposed:

GET /decorations
  Request: JSON encoded xrefs.DecorationsRequest
  Response: JSON encoded xrefs.DecorationsReply
GET /xrefs
  Request: JSON encoded xrefs.CrossReferencesRequest
  Response: JSON encoded xrefs.CrossReferencesReply
GET /documentation
  Request: JSON encoded xrefs.DocumentationRequest
  Response: JSON encoded xrefs.DocumentationReply

Note: /nodes, /edges, /decorations, and /xrefs will return their responses as serialized protobufs if the "proto" query parameter is set.

Types

type BoundedRequests

type BoundedRequests struct {
	MaxTickets int
	Service
}

BoundedRequests guards against requests for more tickets than allowed per the MaxTickets configuration.

func (BoundedRequests) CrossReferences

func (b BoundedRequests) CrossReferences(ctx context.Context, req *xpb.CrossReferencesRequest) (*xpb.CrossReferencesReply, error)

CrossReferences implements part of the Service interface.

func (BoundedRequests) Documentation

func (b BoundedRequests) Documentation(ctx context.Context, req *xpb.DocumentationRequest) (*xpb.DocumentationReply, error)

Documentation implements part of the Service interface.

type ByName

type ByName []*cpb.Fact

ByName orders a slice of facts by their fact names.

func (ByName) Len

func (s ByName) Len() int

func (ByName) Less

func (s ByName) Less(i, j int) bool

func (ByName) Swap

func (s ByName) Swap(i, j int)

type Normalizer

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

Normalizer fixes xref.Locations within a given source text so that each point has consistent byte_offset, line_number, and column_offset fields within the range of text's length and its line lengths.

func NewNormalizer

func NewNormalizer(text []byte) *Normalizer

NewNormalizer returns a Normalizer for Locations within text.

func (*Normalizer) ByteOffset

func (n *Normalizer) ByteOffset(offset int32) *cpb.Point

ByteOffset returns a normalized point based on the given offset within the Normalizer's text. A normalized point has all of its fields set consistently and clamped within the range [0,len(text)).

func (*Normalizer) Location

func (n *Normalizer) Location(loc *xpb.Location) (*xpb.Location, error)

Location returns a normalized location within the Normalizer's text. Normalized FILE locations have no start/end points. Normalized SPAN locations have fully populated start/end points clamped in the range [0, len(text)).

func (*Normalizer) Point

func (n *Normalizer) Point(p *cpb.Point) *cpb.Point

Point returns a normalized point within the Normalizer's text. A normalized point has all of its fields set consistently and clamped within the range [0,len(text)).

func (*Normalizer) Span

func (n *Normalizer) Span(s *cpb.Span) *cpb.Span

Span returns a Span with its start and end normalized.

func (*Normalizer) SpanOffsets

func (n *Normalizer) SpanOffsets(start, end int32) *cpb.Span

SpanOffsets returns a Span based on normalized start and end byte offsets.

type Patcher

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

Patcher uses a computed diff between two texts to map spans from the original text to the new text.

func NewPatcher

func NewPatcher(oldText, newText []byte) *Patcher

NewPatcher returns a Patcher based on the diff between oldText and newText.

func (*Patcher) Patch

func (p *Patcher) Patch(spanStart, spanEnd int32) (newStart, newEnd int32, exists bool)

Patch returns the resulting span of mapping the given span from the Patcher's constructed oldText to its newText. If the span no longer exists in newText or is invalid, the returned bool will be false. As a convenience, if p==nil, the original span will be returned.

func (*Patcher) PatchSpan

func (p *Patcher) PatchSpan(span *cpb.Span) (newStart, newEnd int32, exists bool)

PatchSpan returns the given Span's byte offsets mapped from the Patcher's oldText to its newText using Patcher.Patch.

type Service

type Service interface {
	// Decorations returns an index of the nodes associated with a specified file.
	Decorations(context.Context, *xpb.DecorationsRequest) (*xpb.DecorationsReply, error)

	// CrossReferences returns the global cross-references for the given nodes.
	CrossReferences(context.Context, *xpb.CrossReferencesRequest) (*xpb.CrossReferencesReply, error)

	// Documentation takes a set of tickets and returns documentation for them.
	Documentation(context.Context, *xpb.DocumentationRequest) (*xpb.DocumentationReply, error)
}

Service defines the interface for file based cross-references. Informally, the cross-references of an entity comprise the definitions of that entity, together with all the places where those definitions are referenced through constructs such as type declarations, variable references, function calls, and so on.

func WebClient

func WebClient(addr string) Service

WebClient returns an xrefs Service based on a remote web server.