editions

Documentation

Overview

Package editions contains helpers related to resolving features for Protobuf editions. These are lower-level helpers. Higher-level helpers (which use this package under the hood) can be found in the exported protoutil package.

Index

• Constants
• Variables
• func GetEdition(d protoreflect.Descriptor) descriptorpb.Edition
• func GetEditionDefaults(edition descriptorpb.Edition) *descriptorpb.FeatureSet
• func GetFeatureDefault(edition descriptorpb.Edition, container protoreflect.MessageType, ...) (protoreflect.Value, error)
• func ResolveFeature(element protoreflect.Descriptor, fields ...protoreflect.FieldDescriptor) (protoreflect.Value, error)
• type HasEdition
• type HasFeatures

Constants

const (
	// MinSupportedEdition is the earliest edition supported by this module.
	// It should be 2023 (the first edition) for the indefinite future.
	MinSupportedEdition = descriptorpb.Edition_EDITION_2023

	// MaxSupportedEdition is the most recent edition supported by this module.
	MaxSupportedEdition = descriptorpb.Edition_EDITION_2023
)

Variables

var (
	// SupportedEditions is the exhaustive set of editions that protocompile
	// can support. We don't allow it to compile future/unknown editions, to
	// make sure we don't generate incorrect descriptors, in the event that
	// a future edition introduces a change or new feature that requires
	// new logic in the compiler.
	SupportedEditions = computeSupportedEditions(MinSupportedEdition, MaxSupportedEdition)

	// FeatureSetDescriptor is the message descriptor for the compiled-in
	// version (in the descriptorpb package) of the google.protobuf.FeatureSet
	// message type.
	FeatureSetDescriptor = (*descriptorpb.FeatureSet)(nil).ProtoReflect().Descriptor()
	// FeatureSetType is the message type for the compiled-in version (in
	// the descriptorpb package) of google.protobuf.FeatureSet.
	FeatureSetType = (*descriptorpb.FeatureSet)(nil).ProtoReflect().Type()
)

Functions

func GetEdition

func GetEdition(d protoreflect.Descriptor) descriptorpb.Edition

GetEdition returns the edition for a given element. It returns EDITION_PROTO2 or EDITION_PROTO3 if the element is in a file that uses proto2 or proto3 syntax, respectively. It returns EDITION_UNKNOWN if the syntax of the given element is not recognized or if the edition cannot be ascertained from the element's protoreflect.FileDescriptor.

func GetEditionDefaults

func GetEditionDefaults(edition descriptorpb.Edition) *descriptorpb.FeatureSet

GetEditionDefaults returns the default feature values for the given edition. It returns nil if the given edition is not known.

This only populates known features, those that are fields of *descriptorpb.FeatureSet. It does not populate any extension fields.

The returned value must not be mutated as it references shared package state.

func GetFeatureDefault

func GetFeatureDefault(edition descriptorpb.Edition, container protoreflect.MessageType, feature protoreflect.FieldDescriptor) (protoreflect.Value, error)

GetFeatureDefault computes the default value for a feature. The given container is the message type that contains the field. This should usually be the descriptor for google.protobuf.FeatureSet, but can be a different message for computing the default value of custom features.

Note that this always re-computes the default. For known fields of FeatureSet, it is more efficient to query from the statically computed default messages, like so:

editions.GetEditionDefaults(edition).ProtoReflect().Get(feature)

func ResolveFeature

func ResolveFeature(
	element protoreflect.Descriptor,
	fields ...protoreflect.FieldDescriptor,
) (protoreflect.Value, error)

ResolveFeature resolves a feature for the given descriptor. This simple helper examines the given element and its ancestors, searching for an override. If there is no overridden value, it returns a zero value.

Types

type HasEdition

type HasEdition interface {
	// Edition returns the numeric value of a google.protobuf.Edition enum
	// value that corresponds to the edition of this file. If the file does
	// not use editions, it should return the enum value that corresponds
	// to the syntax level, EDITION_PROTO2 or EDITION_PROTO3.
	Edition() int32
}

HasEdition should be implemented by values that implement protoreflect.FileDescriptor, to provide access to the file's edition when its syntax is protoreflect.Editions.

type HasFeatures

type HasFeatures interface {
	GetFeatures() *descriptorpb.FeatureSet
}

HasFeatures is implemented by all options messages and provides a nil-receiver-safe way of accessing the features explicitly configured in those options.