sourceinfo

Documentation

Overview

Package sourceinfo contains the logic for computing source code info for a file descriptor.

The inputs to the computation are an AST for a file as well as the index of interpreted options for that file.

Index

• func GenerateSourceInfo(file *ast.FileNode, opts OptionIndex, genOpts ...GenerateOption) *descriptorpb.SourceCodeInfo
• type ArrayLiteralSourceInfo
• type GenerateOption
  • func WithExtraComments() GenerateOption
  • func WithExtraOptionLocations() GenerateOption
• type MessageLiteralSourceInfo
• type OptionChildrenSourceInfo
• type OptionIndex
• type OptionSourceInfo

Functions

func GenerateSourceInfo

func GenerateSourceInfo(file *ast.FileNode, opts OptionIndex, genOpts ...GenerateOption) *descriptorpb.SourceCodeInfo

GenerateSourceInfo generates source code info for the given AST. If the given opts is present, it can generate source code info for interpreted options. Otherwise, any options in the AST will get source code info as uninterpreted options.

Types

type ArrayLiteralSourceInfo

type ArrayLiteralSourceInfo struct {
	Elements []OptionSourceInfo
}

ArrayLiteralSourceInfo represents source info paths for the child elements of an *ast.ArrayLiteralNode. This value is only useful for non-empty array literals that contain messages.

type GenerateOption

type GenerateOption interface {
	// contains filtered or unexported methods
}

GenerateOption represents an option for how source code info is generated.

func WithExtraComments

func WithExtraComments() GenerateOption

WithExtraComments will result in source code info that contains extra comments. By default, comments are only generated for full declarations. Inline comments around elements of a declaration are not included in source code info. This option changes that behavior so that as many comments as possible are described in the source code info.

func WithExtraOptionLocations

func WithExtraOptionLocations() GenerateOption

WithExtraOptionLocations will result in source code info that contains extra locations to describe elements inside of a message literal. By default, option values are treated as opaque, so the only locations included are for the entire option value. But with this option, paths to the various fields set inside a message literal will also have locations. This makes it possible for usages of the source code info to report precise locations for specific fields inside the value.

type MessageLiteralSourceInfo

type MessageLiteralSourceInfo struct {
	Fields map[*ast.MessageFieldNode]*OptionSourceInfo
}

MessageLiteralSourceInfo represents source info paths for the child elements of an *ast.MessageLiteralNode.

type OptionChildrenSourceInfo

type OptionChildrenSourceInfo interface {
	// contains filtered or unexported methods
}

OptionChildrenSourceInfo represents source info paths for child elements of an option value.

type OptionIndex

type OptionIndex map[*ast.OptionNode]*OptionSourceInfo

OptionIndex is a mapping of AST nodes that define options to corresponding paths into the containing file descriptor. The path is a sequence of field tags and indexes that define a traversal path from the root (the file descriptor) to the resolved option field. The info also includes similar information about child elements, for options whose values are composite (like a list or message literal).

type OptionSourceInfo

type OptionSourceInfo struct {
	// The source info path to this element. If this element represents a
	// declaration with an array-literal value, the last element of the
	// path is the index of the first item in the array.
	//
	// This path is relative to the options message. So the first element
	// is a field number of the options message.
	//
	// If the first element is negative, it indicates the number of path
	// components to remove from the path to the relevant options. This is
	// used for field pseudo-options, so that the path indicates a field on
	// the descriptor, which is a parent of the options message (since that
	// is how the pseudo-options are actually stored).
	Path []int32
	// Children can be an *ArrayLiteralSourceInfo, a *MessageLiteralSourceInfo,
	// or nil, depending on whether the option's value is an
	// [*ast.ArrayLiteralNode], an [*ast.MessageLiteralNode], or neither.
	// For [*ast.ArrayLiteralNode] values, this is only populated if the
	// value is a non-empty array of messages. (Empty arrays and arrays
	// of scalar values do not need any additional info.)
	Children OptionChildrenSourceInfo
}

OptionSourceInfo describes the source info path for an option value and contains information about the value's descendants in the AST.