options

Documentation

Overview

Package options contains the logic for interpreting options. The parse step of compilation stores the options in uninterpreted form, which contains raw identifiers and literal values.

The process of interpreting an option is to resolve identifiers, by examining descriptors for the google.protobuf.*Options types and their available extensions (custom options). As field names are resolved, the values can be type-checked against the types indicated in field descriptors.

On success, the various fields and extensions of the options message are populated and the field holding the uninterpreted form is cleared.

Index

• func InterpretOptions(linked linker.Result, handler *reporter.Handler, opts ...InterpreterOption) (sourceinfo.OptionIndex, error)
• func InterpretOptionsLenient(linked linker.Result, opts ...InterpreterOption) (sourceinfo.OptionIndex, error)
• func InterpretUnlinkedOptions(parsed parser.Result, opts ...InterpreterOption) (sourceinfo.OptionIndex, error)
• func StripSourceRetentionOptionsFromFile(file *descriptorpb.FileDescriptorProto) (*descriptorpb.FileDescriptorProto, error)
• type InterpreterOption
  • func WithOverrideDescriptorProto(f linker.File) InterpreterOption

Functions

func InterpretOptions

func InterpretOptions(linked linker.Result, handler *reporter.Handler, opts ...InterpreterOption) (sourceinfo.OptionIndex, error)

InterpretOptions interprets options in the given linked result, returning an index that can be used to generate source code info. This step mutates the linked result's underlying proto to move option elements out of the "uninterpreted_option" fields and into proper option fields and extensions.

The given handler is used to report errors and warnings. If any errors are reported, this function returns a non-nil error.

func InterpretOptionsLenient

func InterpretOptionsLenient(linked linker.Result, opts ...InterpreterOption) (sourceinfo.OptionIndex, error)

InterpretOptionsLenient interprets options in a lenient/best-effort way in the given linked result, returning an index that can be used to generate source code info. This step mutates the linked result's underlying proto to move option elements out of the "uninterpreted_option" fields and into proper option fields and extensions.

In lenient more, errors resolving option names and type errors are ignored. Any options that are uninterpretable (due to such errors) will remain in the "uninterpreted_option" fields.

func InterpretUnlinkedOptions

func InterpretUnlinkedOptions(parsed parser.Result, opts ...InterpreterOption) (sourceinfo.OptionIndex, error)

InterpretUnlinkedOptions does a best-effort attempt to interpret options in the given parsed result, returning an index that can be used to generate source code info. This step mutates the parsed result's underlying proto to move option elements out of the "uninterpreted_option" fields and into proper option fields and extensions.

This is the same as InterpretOptionsLenient except that it accepts an unlinked result. Because the file is unlinked, custom options cannot be interpreted. Other errors resolving option names or type errors will be effectively ignored. Any options that are uninterpretable (due to such errors) will remain in the "uninterpreted_option" fields.

func StripSourceRetentionOptionsFromFile

func StripSourceRetentionOptionsFromFile(file *descriptorpb.FileDescriptorProto) (*descriptorpb.FileDescriptorProto, error)

StripSourceRetentionOptionsFromFile returns a file descriptor proto that omits any options in file that are defined to be retained only in source. If file has no such options, then it is returned as is. If it does have such options, a copy is made; the given file will not be mutated.

Even when a copy is returned, it is not a deep copy: it may share data with the original file. So callers should not mutate the returned file unless mutating the input file is also safe.

Types

type InterpreterOption

type InterpreterOption func(*interpreter)

InterpreterOption is an option that can be passed to InterpretOptions and its variants.

func WithOverrideDescriptorProto

func WithOverrideDescriptorProto(f linker.File) InterpreterOption

WithOverrideDescriptorProto returns an option that indicates that the given file should be consulted when looking up a definition for an option type. The given file should usually have the path "google/protobuf/descriptor.proto". The given file will only be consulted if the option type is otherwise not visible to the file whose options are being interpreted.