protosource

package
v1.31.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 23, 2024 License: Apache-2.0 Imports: 15 Imported by: 7

Documentation

Overview

Package protosource defines minimal interfaces for Protobuf descriptor types.

This is done so that the backing package can be swapped out easily.

All values that return SourceLocation can be nil.

Testing is currently implicitly done through the bufcheck packages, however if this were to be split out into a separate library, it would need a separate testing suite.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DirPathToFiles 

func DirPathToFiles(files ...File) (map[string][]File, error)

DirPathToFiles maps the Files to a map from directory to the slice of Files in that directory.

Returns error if file paths are not unique. Directories are normalized.

Files will be sorted by FilePath.

func EnumIsSubset 

func EnumIsSubset(supersetEnum Enum, subsetEnum Enum) (bool, error)

EnumIsSubset checks if subsetEnum is a subset of supersetEnum.

func FilePathToFile 

func FilePathToFile(files ...File) (map[string]File, error)

FilePathToFile maps the Files to a map from Path() to File.

Returns error if file paths are not unique.

func ForEachEnum 

func ForEachEnum(f func(Enum) error, containerDescriptor ContainerDescriptor) error

ForEachEnum calls f on each Enum in the given ContainerDescriptor, including nested Enums.

Returns error and stops iterating if f returns error Never returns error unless f returns error.

func ForEachMessage 

func ForEachMessage(f func(Message) error, containerDescriptor ContainerDescriptor) error

ForEachMessage calls f on each Message in the given ContainerDescriptor, including nested Messages.

Returns error and stops iterating if f returns error Never returns error unless f returns error.

func FreeMessageRangeString 

func FreeMessageRangeString(message Message) string

FreeMessageRangeString returns the string representation of the free ranges for the message.

func FullNameToEnum 

func FullNameToEnum(files ...File) (map[string]Enum, error)

FullNameToEnum maps the Enums in the Files to a map from full name to enum.

Returns error if the Enums do not have unique full names within the Files, which should generally never happen for properly-formed Files.

func FullNameToMessage 

func FullNameToMessage(files ...File) (map[string]Message, error)

FullNameToMessage maps the Messages in the Files to a map from full name to message.

Returns error if the Messages do not have unique full names within the Files, which should generally never happen for properly-formed Files.

func FullNameToMethod 

func FullNameToMethod(files ...File) (map[string]Method, error)

FullNameToMethod maps the Methods in the Files to a map from full name to Method.

Returns error if Methods do not have unique full names within the Files, which should generally never happen for properly-formed Files.

func FullNameToService 

func FullNameToService(files ...File) (map[string]Service, error)

FullNameToService maps the Services in the Files to a map from full name to Service.

Returns error if Services do not have unique full names within the Files, which should generally never happen for properly-formed Files.

func NameInReservedNames 

func NameInReservedNames(name string, reservedNames ...ReservedName) bool

NameInReservedNames returns true if the name is in one of the ReservedNames.

func NameToEnumValue 

func NameToEnumValue(enum Enum) (map[string]EnumValue, error)

NameToEnumValue maps the EnumValues in the Enum to a map from name to EnumValue.

Returns error if the EnumValues do not have unique names within the Enum, which should generally never happen for properly-formed Enums.

func NameToMessageOneof 

func NameToMessageOneof(message Message) (map[string]Oneof, error)

NameToMessageOneof maps the Oneofs in the Message to a map from name to Oneof.

Returns error if the Oneofs do not have unique names within the Message, which should generally never happen for properly-formed Messages.

func NameToMethod 

func NameToMethod(service Service) (map[string]Method, error)

NameToMethod maps the Methods in the Service to a map from name to Method.

Returns error if Methods do not have unique names within the Service, which should generally never happen for properly-formed Services.

func NameToService 

func NameToService(file File) (map[string]Service, error)

NameToService maps the Services in the File to a map from name to Service.

Returns error if Services do not have unique names within the File, which should generally never happen for properly-formed Files.

func NestedNameToEnum 

func NestedNameToEnum(containerDescriptor ContainerDescriptor) (map[string]Enum, error)

NestedNameToEnum maps the Enums in the ContainerDescriptor to a map from nested name to Enum.

Returns error if Enums do not have unique nested names within the ContainerDescriptor, which should generally never happen for properly-formed ContainerDescriptors.

func NestedNameToMessage 

func NestedNameToMessage(containerDescriptor ContainerDescriptor) (map[string]Message, error)

NestedNameToMessage maps the Messages in the ContainerDescriptor to a map from nested name to Message.

Returns error if Messages do not have unique nested names within the ContainerDescriptor, which should generally never happen for properly-formed files.

func NumberInReservedRanges 

func NumberInReservedRanges(number int, reservedRanges ...TagRange) bool

NumberInReservedRanges returns true if the number is in one of the Ranges.

func NumberToMessageField 

func NumberToMessageField(message Message) (map[int]Field, error)

NumberToMessageField maps the Fields in the Message to a map from number to Field.

TODO: is this right? Includes extensions.

Returns error if the Fields do not have unique numbers within the Message, which should generally never happen for properly-formed Messages.

func NumberToMessageFieldForLabel 

func NumberToMessageFieldForLabel(message Message, label descriptorpb.FieldDescriptorProto_Label) (map[int]Field, error)

NumberToMessageFieldForLabel maps the Fields with the given label in the message to a map from number to Field.

TODO: is this right? Includes extensions.

Returns error if the Fields do not have unique numbers within the Message, which should generally never happen for properly-formed Messages.

func NumberToNameToEnumValue 

func NumberToNameToEnumValue(enum Enum) (map[int]map[string]EnumValue, error)

NumberToNameToEnumValue maps the EnumValues in the Enum to a map from number to name to EnumValue.

Duplicates by number may occur if allow_alias = true.

Returns error if the EnumValues do not have unique names within the Enum for a given number, which should generally never happen for properly-formed Enums.

func PackageToDirectlyImportedPackageToFileImports added in v1.0.0 

func PackageToDirectlyImportedPackageToFileImports(files ...File) (map[string]map[string][]FileImport, error)

PackageToDirectlyImportedPackageToFileImports maps packages to directly imported packages to the FileImports that import this package.

For example, if package a imports package b via c/d.proto and c/e.proto, this will have a -> b -> [c/d.proto, c/e.proto].

A directly imported package will not be equal to the package, i.e. there will be no a -> a.

Files with no packages are included with key "" to be consistent with other functions.

func PackageToFiles 

func PackageToFiles(files ...File) (map[string][]File, error)

PackageToFiles maps the Files to a map from Protobuf package to the slice of Files in that package.

Returns error if file paths are not unique.

Files will be sorted by Path.

func PackageToNameToService 

func PackageToNameToService(files ...File) (map[string]map[string]Service, error)

PackageToNameToService maps the Services in the Files to a map from package to name to Service.

Returns error if the Services do not have unique names within the packages, which should generally never happen for properly-formed Files.

func PackageToNestedNameToEnum 

func PackageToNestedNameToEnum(files ...File) (map[string]map[string]Enum, error)

PackageToNestedNameToEnum maps the Enums in the Files to a map from package to nested name to Enum.

Returns error if the Enums do not have unique nested names within the packages, which should generally never happen for properly-formed Files.

func PackageToNestedNameToMessage 

func PackageToNestedNameToMessage(files ...File) (map[string]map[string]Message, error)

PackageToNestedNameToMessage maps the Messages in the Files to a map from package to nested name to Message.

Returns error if the Messages do not have unique nested names within the packages, which should generally never happen for properly-formed Files.

func SortFiles 

func SortFiles(files []File)

SortFiles sorts the Files by FilePath.

func StringToExtensionMessageRange 

func StringToExtensionMessageRange(message Message) map[string]MessageRange

StringToExtensionMessageRange maps the ExtensionMessageRanges in the Message to a map from string string to ExtensionMessageRange.

Ignores duplicates.

func StringToReservedTagRange 

func StringToReservedTagRange(reservedDescriptor ReservedDescriptor) map[string]TagRange

StringToReservedTagRange maps the ReservedTagRanges in the ReservedDescriptor to a map from string string to reserved TagRange.

Ignores duplicates.

func TagRangeString 

func TagRangeString(tagRange TagRange) string

TagRangeString returns the string representation of the range.

func ValueToReservedName 

func ValueToReservedName(reservedDescriptor ReservedDescriptor) map[string]ReservedName

ValueToReservedName maps the ReservedNames in the ReservedDescriptor to a map from string value to ReservedName.

Ignores duplicates.

Types

type ContainerDescriptor 

type ContainerDescriptor interface {
	Enums() []Enum
	Messages() []Message
}

ContainerDescriptor contains Enums and Messages.

type Descriptor 

type Descriptor interface {
	// File returns the associated File.
	//
	// Always non-nil.
	File() File
}

Descriptor is the base interface for a descriptor type.

type Enum 

type Enum interface {
	NamedDescriptor
	ReservedDescriptor
	OptionExtensionDescriptor

	Values() []EnumValue
	ReservedEnumRanges() []EnumRange

	AllowAlias() bool
	DeprecatedLegacyJSONFieldConflicts() bool
	Deprecated() bool
	AllowAliasLocation() Location

	// Will return nil if this is a top-level Enum
	Parent() Message
}

Enum is an enum descriptor.

type EnumRange 

type EnumRange interface {
	TagRange

	Enum() Enum
}

EnumRange is a TagRange for Enums.

type EnumValue 

type EnumValue interface {
	NamedDescriptor
	OptionExtensionDescriptor

	Enum() Enum
	Number() int

	Deprecated() bool
	NumberLocation() Location
}

EnumValue is an enum value descriptor.

type ExtensionRange added in v1.10.0 

type ExtensionRange interface {
	MessageRange
	OptionExtensionDescriptor
}

ExtensionRange represents an extension range in Messages.

type Field 

type Field interface {
	NamedDescriptor
	OptionExtensionDescriptor

	// May be nil if this is attached to a file.
	ParentMessage() Message
	Number() int
	Label() descriptorpb.FieldDescriptorProto_Label
	Type() descriptorpb.FieldDescriptorProto_Type
	TypeName() string
	// may be nil
	Oneof() Oneof
	Proto3Optional() bool
	JSONName() string
	JSType() descriptorpb.FieldOptions_JSType
	CType() descriptorpb.FieldOptions_CType
	Retention() descriptorpb.FieldOptions_OptionRetention
	Targets() []descriptorpb.FieldOptions_OptionTargetType
	DebugRedact() bool
	// Set vs unset matters for packed
	// See the comments on descriptor.proto
	Packed() *bool
	Deprecated() bool
	// Empty string unless the field is part of an extension
	Extendee() string

	NumberLocation() Location
	TypeLocation() Location
	TypeNameLocation() Location
	JSONNameLocation() Location
	JSTypeLocation() Location
	CTypeLocation() Location
	PackedLocation() Location
	ExtendeeLocation() Location
}

Field is a field descriptor.

type File 

type File interface {
	Descriptor
	FileInfo

	// Top-level only.
	ContainerDescriptor
	OptionExtensionDescriptor

	Syntax() Syntax
	Package() string
	FileImports() []FileImport
	Services() []Service
	Extensions() []Field
	Edition() descriptorpb.Edition

	CsharpNamespace() string
	GoPackage() string
	JavaMultipleFiles() bool
	JavaOuterClassname() string
	JavaPackage() string
	JavaStringCheckUtf8() bool
	ObjcClassPrefix() string
	PhpClassPrefix() string
	PhpNamespace() string
	PhpMetadataNamespace() string
	RubyPackage() string
	SwiftPrefix() string
	Deprecated() bool

	OptimizeFor() descriptorpb.FileOptions_OptimizeMode
	CcGenericServices() bool
	JavaGenericServices() bool
	PyGenericServices() bool
	PhpGenericServices() bool
	CcEnableArenas() bool

	SyntaxLocation() Location
	PackageLocation() Location
	CsharpNamespaceLocation() Location
	GoPackageLocation() Location
	JavaMultipleFilesLocation() Location
	JavaOuterClassnameLocation() Location
	JavaPackageLocation() Location
	JavaStringCheckUtf8Location() Location
	ObjcClassPrefixLocation() Location
	PhpClassPrefixLocation() Location
	PhpNamespaceLocation() Location
	PhpMetadataNamespaceLocation() Location
	RubyPackageLocation() Location
	SwiftPrefixLocation() Location

	OptimizeForLocation() Location
	CcGenericServicesLocation() Location
	JavaGenericServicesLocation() Location
	PyGenericServicesLocation() Location
	PhpGenericServicesLocation() Location
	CcEnableArenasLocation() Location

	// FileDescriptor returns the backing FileDescriptor for this File.
	//
	// Users should prefer to use the core protosource API to read properties of the File as opposed
	// to using the FileDescriptor directly, however we needed to add this to be able to build
	// Resolvers, and did not want to rewrite the whole API.
	FileDescriptor() protodescriptor.FileDescriptor
}

File is a file descriptor.

func NewFile 

func NewFile(inputFile InputFile) (File, error)

NewFile returns a new File.

func NewFilesUnstable 

func NewFilesUnstable(ctx context.Context, inputFiles ...InputFile) ([]File, error)

NewFilesUnstable converts the input Files into Files.

This may be done concurrently and the returned Files may not be in the same order as the input FileDescriptors. If ordering matters, use NewFile.

type FileImport 

type FileImport interface {
	LocationDescriptor

	Import() string
	IsPublic() bool
	IsWeak() bool
	IsUnused() bool
}

FileImport is a file import descriptor.

type FileInfo 

type FileInfo interface {
	// Path is the path of the file relative to the root it is contained within.
	// This will be normalized, validated and never empty,
	// This will be unique within a given Image.
	Path() string

	//   Path: one/one.proto
	//   RootDirPath: proto
	//   ExternalPath: /foo/bar/proto/one/one.proto
	ExternalPath() string
	// ModuleIdentity is the module that this file came from.
	//
	// Note this *can* be nil if we did not build from a named module.
	// All code must assume this can be nil.
	// Note that nil checking should work since the backing type is always a pointer.
	ModuleIdentity() ModuleIdentity
	// Commit is the commit for the module that this file came from.
	//
	// This will only be set if ModuleIdentity is set, but may not be set
	// even if ModuleIdentity is set, that is commit is optional information
	// even if we know what module this file came from.
	Commit() string
	// IsImport returns true if this file is an import.
	IsImport() bool
}

FileInfo contains Protobuf file info.

type InputFile 

type InputFile interface {
	FileInfo
	// FileDescriptorProto is the backing FileDescriptorProto for this File.
	//
	// This will never be nil.
	// The value Path() is equal to FileDescriptorProto().GetName() .
	FileDescriptorProto() *descriptorpb.FileDescriptorProto
	// IsSyntaxUnspecified will be true if the syntax was not explicitly specified.
	IsSyntaxUnspecified() bool
	// UnusedDependencyIndexes returns the indexes of the unused dependencies within
	// FileDescriptor.GetDependency().
	//
	// All indexes will be valid.
	// Will return nil if empty.
	UnusedDependencyIndexes() []int32
}

InputFile is an input file for NewFile.

type Location 

type Location interface {
	StartLine() int
	StartColumn() int
	EndLine() int
	EndColumn() int
	LeadingComments() string
	TrailingComments() string
	// NOT a copy. Do not modify.
	LeadingDetachedComments() []string
}

Location defines source code info location information.

May be extended in the future to include comments.

Note that unlike SourceCodeInfo_Location, these are not zero-indexed.

type LocationDescriptor 

type LocationDescriptor interface {
	Descriptor

	// Location returns the location of the entire descriptor.
	//
	// Can return nil, although will generally not be nil.
	Location() Location
}

LocationDescriptor is the base interface for a descriptor type with a location.

type Message 

type Message interface {
	NamedDescriptor
	// Only those directly nested under this message.
	ContainerDescriptor
	ReservedDescriptor
	OptionExtensionDescriptor

	// Includes fields in oneofs.
	Fields() []Field
	Extensions() []Field
	Oneofs() []Oneof
	ExtensionRanges() []ExtensionRange
	ExtensionMessageRanges() []MessageRange
	ReservedMessageRanges() []MessageRange

	// Will return nil if this is a top-level message
	Parent() Message
	IsMapEntry() bool

	MessageSetWireFormat() bool
	NoStandardDescriptorAccessor() bool
	DeprecatedLegacyJSONFieldConflicts() bool
	Deprecated() bool
	MessageSetWireFormatLocation() Location
	NoStandardDescriptorAccessorLocation() Location
}

Message is a message descriptor.

type MessageRange 

type MessageRange interface {
	TagRange

	Message() Message
}

MessageRange is a TagRange for Messages.

func FreeMessageRanges 

func FreeMessageRanges(message Message) []MessageRange

FreeMessageRanges returns the free message ranges for the given message.

Not recursive.

type Method 

type Method interface {
	NamedDescriptor
	OptionExtensionDescriptor

	Service() Service
	InputTypeName() string
	OutputTypeName() string
	ClientStreaming() bool
	ServerStreaming() bool
	InputTypeLocation() Location
	OutputTypeLocation() Location

	Deprecated() bool
	IdempotencyLevel() descriptorpb.MethodOptions_IdempotencyLevel
	IdempotencyLevelLocation() Location
}

Method is a method descriptor.

type ModuleIdentity 

type ModuleIdentity interface {
	Remote() string
	Owner() string
	Repository() string
}

ModuleIdentity is a module identity.

type NamedDescriptor 

type NamedDescriptor interface {
	LocationDescriptor

	// FullName returns the fully-qualified name, i.e. some.pkg.Nested.ParentMessage.FooEnum.ENUM_VALUE.
	//
	// Always non-empty.
	FullName() string
	// NestedName returns the full nested name without the package, i.e. Nested.ParentMessage.FooEnum
	// or Nested.ParentMessage.FooEnum.ENUM_VALUE.
	//
	// Always non-empty.
	NestedName() string
	// Name returns the short name, or the name of a value or field, i.e. FooEnum or ENUM_VALUE.
	//
	// Always non-empty.
	Name() string
	// NameLocation returns the location of the name of the descriptor.
	//
	// If the backing descriptor does not have name-level resolution, this will
	// attempt to return a location of the entire descriptor.
	//
	// If the backing descriptor has comments for the entire descriptor, these
	// will be added to the named location.
	//
	// Can return nil.
	NameLocation() Location
}

NamedDescriptor is the base interface for a named descriptor type.

type Oneof 

type Oneof interface {
	NamedDescriptor
	OptionExtensionDescriptor

	Message() Message
	Fields() []Field
}

Oneof is a oneof descriptor.

type OptionExtensionDescriptor 

type OptionExtensionDescriptor interface {
	// OptionExtension returns the value for an options extension field.
	//
	// Returns false if the extension is not set.
	//
	// See https://pkg.go.dev/google.golang.org/protobuf/proto#HasExtension
	// See https://pkg.go.dev/google.golang.org/protobuf/proto#GetExtension
	OptionExtension(extensionType protoreflect.ExtensionType) (interface{}, bool)

	// OptionExtensionLocation returns the source location where the given extension
	// field value is defined. The extra path can be additional path elements, for
	// getting the location of specific elements inside the extension, for message
	// and repeated values.
	//
	// If a precise location cannot be found, but a general one can be, the general
	// location will be returned. For example, if a specific field inside a message
	// extension is requested but the source code info only includes information
	// about the message itself (and not that particular field), the location of the
	// message value is returned. Conversely, if a message location is requested but
	// the source code info only has information about specific fields inside that
	// message, the first such location is returned. Similarly, if multiple locations
	// are in source code info for the requested value, the first one is returned.
	//
	// If no relevant location is found in source code info, this returns nil.
	OptionExtensionLocation(extensionType protoreflect.ExtensionType, extraPath ...int32) Location

	// PresentExtensionNumbers returns field numbers for all extensions/custom options
	// that have a set value on this descriptor.
	PresentExtensionNumbers() []int32

	// ForEachPresentOption iterates through all options that have a set value on this
	// descriptor, invoking fn for each present option.
	//
	// If fn returns false, the iteration is terminated and ForEachPresentOption
	// immediately returns.
	ForEachPresentOption(fn func(protoreflect.FieldDescriptor, protoreflect.Value) bool)
}

OptionExtensionDescriptor contains option extensions.

type ReservedDescriptor 

type ReservedDescriptor interface {
	ReservedTagRanges() []TagRange
	ReservedNames() []ReservedName
}

ReservedDescriptor has reserved ranges and names.

type ReservedName 

type ReservedName interface {
	LocationDescriptor

	Value() string
}

ReservedName is a reserved name for an enum or message.

type Service 

type Service interface {
	NamedDescriptor
	OptionExtensionDescriptor

	Methods() []Method
	Deprecated() bool
}

Service is a service descriptor.

type Syntax 

type Syntax int

Syntax is the syntax of a file. 

const (
	// SyntaxUnspecified represents no syntax being specified.
	//
	// This is functionally equivalent to SyntaxProto2.
	SyntaxUnspecified Syntax = iota + 1
	// SyntaxProto2 represents the proto2 syntax.
	SyntaxProto2
	// SyntaxProto3 represents the proto3 syntax.
	SyntaxProto3
	// SyntaxEditions represents the editions syntax.
	SyntaxEditions
)

func (Syntax) String 

func (s Syntax) String() string

String returns the string representation of s

type TagRange 

type TagRange interface {
	LocationDescriptor

	// Start is the start of the range.
	Start() int
	// End is the end of the range.
	// Inclusive.
	End() int
	// Max says that the End is the max.
	Max() bool
}

TagRange is a tag range from start to end.

func CheckTagRangeIsSubset added in v1.13.0 

func CheckTagRangeIsSubset(supersetRanges []TagRange, subsetRanges []TagRange) (bool, []TagRange)

CheckTagRangeIsSubset checks if supersetRanges is a superset of subsetRanges. If so, it returns true and nil. If not, it returns false with a slice of failing ranges from subsetRanges.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.