ir

package
v1.5.0 Latest Latest
Warning

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

 Go to latest Published: Feb 10, 2026 License: MIT Imports: 47 Imported by: 0

Documentation

Overview

Package ir defines the intermediate representation used by Protocompile.

This package provides both the IR, and the lowering machinery for that IR. The IR is intended to provide a richer and easier to manipulate structure compared to a FileDescriptorProto. This structure is used for name resolution, type checking, tag number validation, and other semantic operations.

Index

Constants

View Source 
const DescriptorProtoPath = "google/protobuf/descriptor.proto"

Variables

This section is empty.

Functions

func CanonicalizeFilePath 

func CanonicalizeFilePath(path string) string

CanonicalizeFilePath puts a file path into canonical form.

This function is exported so that all code depending on this module can make sure paths are consistently canonicalized.

func DescriptorProtoBytes 

func DescriptorProtoBytes(file *File, options ...DescriptorOption) ([]byte, error)

DescriptorProtoBytes generates a single FileDescriptorProto for file, and returns the result as an encoded byte slice.

The resulting FileDescriptorProto is fully linked: all names are fully-qualified.

func DescriptorSetBytes 

func DescriptorSetBytes(files []*File, options ...DescriptorOption) ([]byte, error)

DescriptorSetBytes generates a FileDescriptorSet for the given files, and returns the result as an encoded byte slice.

The resulting FileDescriptorSet is always fully linked: it contains all dependencies except the WKTs, and all names are fully-qualified.

func GetRef 

func GetRef[T ~id.Node[T, *File, Raw], Raw any](base *File, r Ref[T]) T

Get vets the value that a reference refers to.

func OptionTargets 

func OptionTargets() iter.Seq[OptionTarget]

OptionTargets returns an iterator over all of the possible valid targets, which excludes OptionTargetInvalid.

Types

type DescriptorOption 

type DescriptorOption func(*descGenerator)

DescriptorOption is an option to pass to DescriptorSetBytes or DescriptorProtoBytes.

func ExcludeFiles 

func ExcludeFiles(exclude func(*File) bool) DescriptorOption

ExcludeFiles excludes the given files from the output of DescriptorSetBytes.

func IncludeSourceCodeInfo 

func IncludeSourceCodeInfo(flag bool) DescriptorOption

IncludeDebugInfo sets whether or not to include google.protobuf.SourceCodeInfo in the output.

type Element 

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

Element is an element within a Value.

This exists because array values contain multiple non-array elements; this type provides uniform access to such elements. See Value.Elements.

func (Element) AST 

func (e Element) AST() ast.ExprAny

AST returns the expression this value was evaluated from.

func (Element) AsBool 

func (e Element) AsBool() (value, ok bool)

AsBool returns the bool value of this element.

Returns ok == false if this is not a bool.

func (Element) AsEnum 

func (e Element) AsEnum() Member

AsEnum returns the value of this element as a known enum value.

Returns zero if this is not an enum or if the enum value is out of range.

func (Element) AsFloat 

func (e Element) AsFloat() (float64, bool)

AsFloat returns the value of this element as a floating-point number.

Returns false if this is not a float.

func (Element) AsInt 

func (e Element) AsInt() (int64, bool)

AsInt returns the value of this element as a signed integer.

Returns false if this is not a signed integer (enums are included as signed integers).

func (Element) AsMessage 

func (e Element) AsMessage() MessageValue

AsMessage returns the value of this element as a message literal.

Returns the zero value if this is not a message.

func (Element) AsString 

func (e Element) AsString() (string, bool)

AsString returns the value of this element as a string.

Returns false if this is not a string.

func (Element) AsUInt 

func (e Element) AsUInt() (uint64, bool)

AsUInt returns the value of this element as an unsigned integer.

Returns false if this is not an unsigned integer.

func (Element) Field 

func (e Element) Field() Member

Field returns the field this value sets, which includes the value's type information.

func (Element) IsZeroValue 

func (e Element) IsZeroValue() bool

IsZeroValue returns whether this element contains the zero value for its type.

Always returns false for repeated or message-typed fields.

func (Element) Type 

func (e Element) Type() Type

Type returns the type of this element.

Note that this may be distinct from Member.Element. In the case that this is a google.protobuf.Any-typed field, this function will return the concrete type if known, rather than Any.

func (Element) Value 

func (e Element) Value() Value

Value is the Value this element came from.

func (Element) ValueNodeIndex 

func (e Element) ValueNodeIndex() int

ValueNodeIndex returns the index into Value.ValueASTs for this element's contributing expression. This can be used to obtain other ASTs related to this element, e.g. 

key := e.Value().MessageKeys().At(e.ValueNodeIndex())

If the element is empty, this returns -1.

type ErrCycle 

type ErrCycle = cycle.Error[ast.DeclImport]

ErrCycle is returned by an Importer when encountering an import cycle.

type Extend 

type Extend id.Node[Extend, *File, *rawExtend]

Extend represents an extend block associated with some extension field.

func (Extend) AST 

func (e Extend) AST() ast.DeclDef

AST returns the declaration for this extend block, if known.

func (Extend) Extendee 

func (e Extend) Extendee() Type

Extendee returns the extendee type of this extend block.

func (Extend) Extensions 

func (e Extend) Extensions() seq.Indexer[Member]

Extensions returns the extensions declared in this block.

func (Extend) InternedScope 

func (e Extend) InternedScope() intern.ID

InternedScope returns the intern ID for Extend.Scope.

func (Extend) Parent 

func (e Extend) Parent() Type

Parent returns the type this extend block is declared in.

func (Extend) Scope 

func (e Extend) Scope() FullName

Scope returns the scope that symbol lookups in this block should be performed against.

type Feature 

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

Feature is a feature setting retrieved from a FeatureSet.

func (Feature) Field 

func (f Feature) Field() Member

Field returns the field corresponding to this feature value.

func (Feature) IsCustom 

func (f Feature) IsCustom() bool

IsCustom returns whether this is a custom feature.

func (Feature) IsDefault 

func (f Feature) IsDefault() bool

IsDefault returns whether this feature was inherited from edition defaults. An explicit setting to the default will return false for this method.

func (Feature) IsExplicit 

func (f Feature) IsExplicit() bool

IsExplicit returns whether this feature was set explicitly.

func (Feature) IsInherited 

func (f Feature) IsInherited() bool

IsInherited returns whether this feature value was inherited from its parent.

func (Feature) Type 

func (f Feature) Type() Type

Type returns the type of this feature. May be zero if there is no specified default value for this feature in the current edition.

func (Feature) Value 

func (f Feature) Value() Value

Value returns the value of this feature. May be zero if there is no specified value for this feature, given the current edition.

type FeatureInfo 

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

FeatureInfo represents information about a message field being used as a feature. This corresponds to the edition_defaults and feature_support options on a field.

func (FeatureInfo) Default 

func (f FeatureInfo) Default(edition syntax.Syntax) Value

Default returns the default value for this feature.

func (FeatureInfo) Deprecated 

func (f FeatureInfo) Deprecated() syntax.Syntax

Deprecated returns whether this feature has been deprecated, and in which edition.

func (FeatureInfo) DeprecationWarning 

func (f FeatureInfo) DeprecationWarning() string

DeprecationWarning returns the literal text of the deprecation warning for this feature, if it has been deprecated.

func (FeatureInfo) Introduced 

func (f FeatureInfo) Introduced() syntax.Syntax

Introduced returns which edition this feature is first allowed in.

func (FeatureInfo) IsDeprecated 

func (f FeatureInfo) IsDeprecated(in syntax.Syntax) bool

IsDeprecated returns whether this feature has been deprecated yet.

func (FeatureInfo) IsIntroduced 

func (f FeatureInfo) IsIntroduced(in syntax.Syntax) bool

IsIntroduced returns whether this feature has been introduced yet.

func (FeatureInfo) IsRemoved 

func (f FeatureInfo) IsRemoved(in syntax.Syntax) bool

IsRemoved returns whether this feature has been removed yet.

func (FeatureInfo) Removed 

func (f FeatureInfo) Removed() syntax.Syntax

Removed returns whether this feature has been removed, and in which edition.

type FeatureSet 

type FeatureSet id.Node[FeatureSet, *File, *rawFeatureSet]

FeatureSet represents the Editions-mediated features of a particular declaration.

func (FeatureSet) Lookup 

func (fs FeatureSet) Lookup(field Member) Feature

Lookup looks up a feature with the given google.protobuf.FeatureSet member.

func (FeatureSet) LookupCustom 

func (fs FeatureSet) LookupCustom(extension, field Member) Feature

LookupCustom looks up a custom feature in the given extension's field.

func (FeatureSet) Options 

func (fs FeatureSet) Options() MessageValue

Options returns the value of the google.protobuf.FeatureSet message that this FeatureSet is built from.

func (FeatureSet) Parent 

func (fs FeatureSet) Parent() FeatureSet

Parent returns the feature set of the parent scope for this feature.

Returns zero if this is the feature set for the file.

type File 

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

File is an IR file, which provides access to the top-level declarations of a Protobuf *File.

func (*File) AST 

func (f *File) AST() *ast.File

AST returns the AST this file was parsed from.

func (*File) AllExtends 

func (f *File) AllExtends() seq.Indexer[Extend]

AllExtends returns all extend blocks in this file.

func (*File) AllExtensions 

func (f *File) AllExtensions() seq.Indexer[Member]

AllExtensions returns all extensions defined in this file.

func (*File) AllMembers 

func (f *File) AllMembers() iter.Seq[Member]

AllMembers returns all fields defined in this file, including extensions and enum values.

func (*File) AllTypes 

func (f *File) AllTypes() seq.Indexer[Type]

AllTypes returns all types defined in this file.

func (*File) Deprecated 

func (f *File) Deprecated() Value

Deprecated returns whether this file is deprecated, by returning the relevant option value for setting deprecation.

func (*File) Extends 

func (f *File) Extends() seq.Indexer[Extend]

Extends returns the top level extend blocks in this file.

func (*File) Extensions 

func (f *File) Extensions() seq.Indexer[Member]

Extensions returns the top level extensions defined in this file (i.e., the contents of any top-level `extends` blocks).

func (*File) FeatureSet 

func (f *File) FeatureSet() FeatureSet

FeatureSet returns the Editions features associated with this file.

func (*File) FindSymbol 

func (f *File) FindSymbol(fqn FullName) Symbol

FindSymbol finds a symbol among File.Symbols with the given fully-qualified name.

func (*File) FromID 

func (f *File) FromID(id uint64, want any) any

func (*File) ImportFor 

func (f *File) ImportFor(that *File) Import

ImportFor returns import metadata for a given file, if this file imports it.

func (*File) Imports 

func (f *File) Imports() seq.Indexer[Import]

Imports returns an indexer over the imports declared in this file.

func (*File) InternedPackage 

func (f *File) InternedPackage() intern.ID

InternedPackage returns the intern ID for the value of File.Package.

func (*File) InternedPath 

func (f *File) InternedPath() intern.ID

InternedPath returns the intern ID for the value of File.Path.

func (*File) IsDescriptorProto 

func (f *File) IsDescriptorProto() bool

IsDescriptorProto returns whether this is the special file google/protobuf/descriptor.proto, which is given special treatment in the language.

func (*File) Options 

func (f *File) Options() MessageValue

Options returns the top level options applied to this file.

func (*File) Package 

func (f *File) Package() FullName

Package returns the package name for this file.

The name will not include a leading dot. It will be empty for the empty package.

func (*File) Path 

func (f *File) Path() string

Path returns the canonical path for this file.

This need not be the same as File.AST().Span().Path().

func (*File) Services 

func (f *File) Services() seq.Indexer[Service]

Services returns all services defined in this file.

func (*File) Symbols 

func (f *File) Symbols() seq.Indexer[Symbol]

Symbols returns this file's symbol table.

The symbol table includes both symbols defined in this file, and symbols imported by the file. The symbols are returned in an arbitrary but fixed order.

func (*File) Syntax 

func (f *File) Syntax() syntax.Syntax

Syntax returns the syntax pragma that applies to this file.

func (*File) TransitiveImports 

func (f *File) TransitiveImports() seq.Indexer[Import]

TransitiveImports returns an indexer over the transitive imports for this file.

This function does not report whether those imports are weak or not.

func (*File) Types 

func (f *File) Types() seq.Indexer[Type]

Types returns the top level types of this file.

type FullName 

type FullName string

FullName is a fully-qualified Protobuf name, which is a dot-separated list of identifiers, with an optional dot prefix.

This is a helper type for common operations on such names. This is essentially protoreflect.FullName, without depending on protoreflect. Unlike protoreflect, we do not provide validation methods.

func (FullName) Absolute 

func (n FullName) Absolute() bool

Absolute returns whether this is an absolute name, i.e., has a leading dot.

func (FullName) Append 

func (n FullName) Append(names ...string) FullName

Append returns a name with the given component(s) appended.

If this is an empty name, the resulting name will not be absolute.

func (FullName) Components 

func (n FullName) Components() iter.Seq[string]

Components returns an iterator over the components of this name.

If there are adjacent dots, e.g. foo..bar, this will yield an empty string within the name.

func (FullName) First 

func (n FullName) First() string

First returns the first component of this name.

func (FullName) IsIdent 

func (n FullName) IsIdent() bool

IsIdent returns whether this name is a single identifier.

func (FullName) Name 

func (n FullName) Name() string

Name returns the last component of this name.

func (FullName) Parent 

func (n FullName) Parent() FullName

Parent returns the name of the parent entity for this name.

If the name only has one component, returns the zero value. In particular, the parent of ".foo" is "".

func (FullName) ToAbsolute 

func (n FullName) ToAbsolute() FullName

ToAbsolute returns this name with a leading dot.

func (FullName) ToRelative 

func (n FullName) ToRelative() FullName

ToRelative returns this name without a leading dot.

type Import 

type Import struct {
	*File // The file that is imported.

	// The kind of import this is.
	Public, Weak, Option bool

	Direct  bool           // Whether this is a direct or transitive import.
	Visible bool           // Whether this import's symbols are visible in the current file.
	Used    bool           // Whether this import has been marked as used.
	Decl    ast.DeclImport // The import declaration.
}

Import is an import in a File.

type Importer 

type Importer func(n int, path string, decl ast.DeclImport) (*File, error)

Importer is a callback to resolve the imports of an ast.File being lowered.

If a cycle is encountered, should return an *[incremental.ErrCycle], starting from decl and ending when the currently lowered file is imported.

Session.Lower may not call this function on all imports; only those for which it needs the caller to resolve a File for it.

This function will also be called with DescriptorProtoPath if it isn't transitively imported by the lowered file, with an index value of -1. Returning an error or a zero file will trigger an ICE.

type Member 

type Member id.Node[Member, *File, *rawMember]

Member is a Protobuf message field, enum value, or extension field.

A member has three types associated with it. The English language struggles to give these succinct names, so we review them here.

  1. Its _element_, i.e. the type it contains. This is the type that a member is declared to be _of_. Not present for enum values.

  2. Its _parent_, i.e., the type it is syntactically defined within. Extensions appear syntactically within their parent.

  3. Its _container_, i.e., the type which it is part of for the purposes of serialization. Extensions are fields of their container, but are declared within their parent.

func (Member) AST 

func (m Member) AST() ast.DeclDef

AST returns the declaration for this member, if known.

func (Member) AsTagRange 

func (m Member) AsTagRange() TagRange

AsTagRange wraps this member in a TagRange.

func (Member) CanTarget 

func (m Member) CanTarget(target OptionTarget) bool

CanTarget returns whether this message field can be set as an option for the given option target type.

This is mediated by the option FieldOptions.targets, which controls whether this field can be set (transitively) on the options of a given entity type. This is useful for options which re-use the same message type for different option types, such as FeatureSet.

func (Member) Container 

func (m Member) Container() Type

Container returns the type which contains this member: this is either Member.Parent, or the extendee if this is an extension. This is the type it is declared to be *part of*.

func (Member) Deprecated 

func (m Member) Deprecated() Value

Deprecated returns whether this member is deprecated, by returning the relevant option value for setting deprecation.

func (Member) Element 

func (m Member) Element() Type

Element returns the this member's element type. This is the type it is declared to be *of*, such as in the phrase "a string field's type is string".

This does not include the member's presence: for example, a repeated int32 member will report the type as being the int32 primitive, not an int32 array.

This is zero for enum values.

func (Member) Extend 

func (m Member) Extend() Extend

Extend returns the extend block this member is declared in, if any.

func (Member) FeatureInfo 

func (m Member) FeatureInfo() FeatureInfo

FeatureInfo returns feature definition information relating to this field (for when using this field as a feature).

Returns a zero value if this information does not exist.

func (Member) FeatureSet 

func (m Member) FeatureSet() FeatureSet

FeatureSet returns the Editions features associated with this member.

func (Member) FullName 

func (m Member) FullName() FullName

FullName returns this member's fully-qualified name.

func (Member) InternedFullName 

func (m Member) InternedFullName() intern.ID

InternedFullName returns the intern ID for Member.FullName.

func (Member) InternedJSONName 

func (m Member) InternedJSONName() intern.ID

InternedJSONName returns the intern ID for Member.JSONName.

func (Member) InternedName 

func (m Member) InternedName() intern.ID

InternedName returns the intern ID for Member.FullName().Name().

func (Member) InternedScope 

func (m Member) InternedScope() intern.ID

InternedScope returns the intern ID for Member.Scope.

func (Member) IsEnumValue 

func (m Member) IsEnumValue() bool

IsEnumValue returns whether this is an enum value.

func (Member) IsExtension 

func (m Member) IsExtension() bool

IsExtension returns whether this is a extension message field.

func (Member) IsGroup 

func (m Member) IsGroup() bool

IsGroup returns whether this is a group-encoded field.

func (Member) IsMap 

func (m Member) IsMap() bool

IsMap returns whether this is a map field.

func (Member) IsMessageField 

func (m Member) IsMessageField() bool

IsMessageField returns whether this is a non-extension message field.

func (Member) IsPacked 

func (m Member) IsPacked() bool

IsPacked returns whether this is a packed message field.

func (Member) IsRepeated 

func (m Member) IsRepeated() bool

IsRepeated returns whether this is a repeated field; this includes map fields.

func (Member) IsSingular 

func (m Member) IsSingular() bool

IsSingular returns whether this is a singular field; this includes oneof members.

func (Member) IsSynthetic 

func (m Member) IsSynthetic() bool

IsSynthetic returns whether or not this is a synthetic field, such as the fields of a map entry.

func (Member) IsUnicode 

func (m Member) IsUnicode() bool

IsUnicode returns whether this is a string-typed message field that must contain UTF-8 bytes.

func (Member) JSONName 

func (m Member) JSONName() string

JSONName returns this member's JSON name, either the default-generated one or the one set via the json_name pseudo-option.

func (Member) Name 

func (m Member) Name() string

Name returns this member's name.

func (Member) Number 

func (m Member) Number() int32

Number returns the number for this member after expression evaluation.

Defaults to zero if the number is not specified.

func (Member) Oneof 

func (m Member) Oneof() Oneof

Oneof returns the oneof that this member is a member of.

Returns the zero value if this member does not have presence.Shared.

func (Member) Options 

func (m Member) Options() MessageValue

Options returns the options applied to this member.

func (Member) Parent 

func (m Member) Parent() Type

Parent returns the type this member is syntactically located in. This is the type it is declared *in*, but which it is not necessarily part of.

May be zero for extensions declared at the top level.

func (Member) Presence 

func (m Member) Presence() presence.Kind

Presence returns this member's presence kind.

Returns presence.Unknown for enum values.

func (Member) PseudoOptions 

func (m Member) PseudoOptions() PseudoFields

PseudoOptions returns this member's pseudo options.

func (Member) Scope 

func (m Member) Scope() FullName

Scope returns the scope in which this member is defined.

func (Member) Targets 

func (m Member) Targets() iter.Seq[OptionTarget]

Targets returns an iterator over the valid option targets for this member.

func (Member) TypeAST 

func (m Member) TypeAST() ast.TypeAny

TypeAST returns the type AST node for this member, if known.

type MessageValue 

type MessageValue id.Node[MessageValue, *File, *rawMessageValue]

MessageValue is a message literal, represented as a list of ordered key-value pairs.

func (MessageValue) AsValue 

func (v MessageValue) AsValue() Value

AsValue returns the Value corresponding to this message.

This value can be used to retrieve the associated Member and from it the message's declared Type.

func (MessageValue) Concrete 

func (v MessageValue) Concrete() MessageValue

Concrete returns the concrete version of this value if it is an Any.

If it isn't an Any, or a .Raw()" Any (one not specified with the special type URL syntax), this returns v.

func (MessageValue) Field 

func (v MessageValue) Field(field Member) Value

Field returns the field corresponding with the given member, if it is set.

func (MessageValue) Fields 

func (v MessageValue) Fields() iter.Seq[Value]

Fields yields the fields within this message literal, in insertion order.

func (MessageValue) Marshal 

func (v MessageValue) Marshal(buf []byte, r *report.Report) []byte

Marshal serializes this message as wire format and appends it to buf.

If r is not nil, it will be used to record diagnostics generated during the marshal operation.

func (MessageValue) Type 

func (v MessageValue) Type() Type

Type returns this value's message type.

If v was returned from MessageValue.Concrete, its type need not be the same as v.AsValue()'s (although it can be, in the case of pathological Any-within-an-Any messages).

func (MessageValue) TypeURL 

func (v MessageValue) TypeURL() string

TypeURL returns this value's type URL, if it is the concrete value of an Any.

type Method 

type Method id.Node[Method, *File, *rawMethod]

Method is a Protobuf service method.

func (Method) AST 

func (m Method) AST() ast.DeclDef

AST returns the declaration for this method, if known.

func (Method) Deprecated 

func (m Method) Deprecated() Value

Deprecated returns whether this service is deprecated, by returning the relevant option value for setting deprecation.

func (Method) FeatureSet 

func (m Method) FeatureSet() FeatureSet

FeatureSet returns the Editions features associated with this method.

func (Method) FullName 

func (m Method) FullName() FullName

FullName returns this method's fully-qualified name.

func (Method) Input 

func (m Method) Input() (ty Type, stream bool)

Input returns the input type for this method, and whether it is a streaming input.

func (Method) InternedFullName 

func (m Method) InternedFullName() intern.ID

InternedFullName returns the intern ID for Method.FullName.

func (Method) InternedName 

func (m Method) InternedName() intern.ID

InternedName returns the intern ID for Method.FullName().Name().

func (Method) Name 

func (m Method) Name() string

Name returns this method's declared name, i.e. the last component of its full name.

func (Method) Options 

func (m Method) Options() MessageValue

Options returns the options applied to this method.

func (Method) Output 

func (m Method) Output() (ty Type, stream bool)

Output returns the output type for this method, and whether it is a streaming output.

func (Method) Service 

func (m Method) Service() Service

Service returns the service this method is part of.

type Oneof 

type Oneof id.Node[Oneof, *File, *rawOneof]

Oneof represents a oneof within a message definition.

func (Oneof) AST 

func (o Oneof) AST() ast.DeclDef

AST returns the declaration for this oneof, if known.

func (Oneof) Container 

func (o Oneof) Container() Type

Container returns the message type which contains it.

func (Oneof) FeatureSet 

func (o Oneof) FeatureSet() FeatureSet

FeatureSet returns the Editions features associated with this oneof.

func (Oneof) FullName 

func (o Oneof) FullName() FullName

FullName returns this oneof's fully-qualified name.

func (Oneof) Index 

func (o Oneof) Index() int

Index returns this oneof's index in its containing message.

func (Oneof) InternedFullName 

func (o Oneof) InternedFullName() intern.ID

InternedFullName returns the intern ID for Oneof.FullName.

func (Oneof) InternedName 

func (o Oneof) InternedName() intern.ID

InternedName returns the intern ID for Oneof.FullName().Name().

func (Oneof) Members 

func (o Oneof) Members() seq.Indexer[Member]

Members returns this oneof's member fields.

func (Oneof) Name 

func (o Oneof) Name() string

Name returns this oneof's declared name.

func (Oneof) Options 

func (o Oneof) Options() MessageValue

Options returns the options applied to this oneof.

func (Oneof) Parent 

func (o Oneof) Parent() Type

Parent returns the type that this oneof is declared within,.

type OptionTarget 

type OptionTarget int32

OptionTarget is target for an Editions feature, corresponding to google.protobuf.FieldOptions.OptionTargetType. The values of this enum match those in descriptor.proto one-to-one. 

const (
	OptionTargetInvalid OptionTarget = iota
	OptionTargetFile
	OptionTargetRange
	OptionTargetMessage
	OptionTargetField
	OptionTargetOneof
	OptionTargetEnum
	OptionTargetEnumValue
	OptionTargetService
	OptionTargetMethod
)

func (OptionTarget) GoString 

func (v OptionTarget) GoString() string

GoString implements fmt.GoStringer.

func (OptionTarget) String 

func (v OptionTarget) String() string

String implements fmt.Stringer.

type PseudoFields 

type PseudoFields struct {
	Default  Value
	JSONName Value
}

PseudoFields contains pseudo options, which are special option-like syntax for fields which are not real options. They can be accessed via [Message.PseudoFields].

type Ref 

type Ref[T any] struct {
	// contains filtered or unexported fields
}

Ref is a reference in a Protobuf file: an id.ID along with information for retrieving which file that ID is for, relative to the referencing file's context.

The context needed for resolving a ref is called its "base context", which the user is expected to keep track of.

func (Ref[T]) ChangeContext 

func (r Ref[T]) ChangeContext(base, next *File) Ref[T]

ChangeContext changes the implicit context for this ref to be with respect to the new one given.

func (Ref[T]) Context 

func (r Ref[T]) Context(base *File) *File

Context returns the context for this reference relative to a base context.

func (Ref[T]) IsZero 

func (r Ref[T]) IsZero() bool

IsZero returns whether this is the zero ID.

type ReservedName 

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

ReservedName is a name for a field or enum value that has been reserved for future use.

func (ReservedName) AST 

func (r ReservedName) AST() ast.ExprAny

AST returns the expression that this name was evaluated from, if known.

func (ReservedName) InternedName 

func (r ReservedName) InternedName() intern.ID

InternedName returns the intern ID for ReservedName.Name.

func (ReservedName) Name 

func (r ReservedName) Name() string

Name returns the name (i.e., an identifier) that was reserved.

type ReservedRange 

type ReservedRange id.Node[ReservedRange, *File, *rawReservedRange]

ReservedRange is a range of reserved field or enum numbers, either from a reserved or extensions declaration.

func (ReservedRange) AST 

func (r ReservedRange) AST() ast.ExprAny

AST returns the expression that this range was evaluated from, if known.

func (ReservedRange) AsTagRange 

func (r ReservedRange) AsTagRange() TagRange

AsTagRange wraps this range in a TagRange.

func (ReservedRange) DeclAST 

func (r ReservedRange) DeclAST() ast.DeclRange

DeclAST returns the declaration this range came from. Multiple ranges may have the same declaration.

func (ReservedRange) FeatureSet 

func (r ReservedRange) FeatureSet() FeatureSet

FeatureSet returns the Editions features associated with this file.

func (ReservedRange) ForExtensions 

func (r ReservedRange) ForExtensions() bool

ForExtensions returns whether this is an extension range.

func (ReservedRange) Options 

func (r ReservedRange) Options() MessageValue

Options returns the options applied to this range.

Reserved ranges cannot carry options; only extension ranges do.

func (ReservedRange) Range 

func (r ReservedRange) Range() (start, end int32)

Range returns the start and end of the range.

type Service 

type Service id.Node[Service, *File, *rawService]

Service is a Protobuf service definition.

func (Service) AST 

func (s Service) AST() ast.DeclDef

AST returns the declaration for this service, if known.

func (Service) Deprecated 

func (s Service) Deprecated() Value

Deprecated returns whether this service is deprecated, by returning the relevant option value for setting deprecation.

func (Service) FeatureSet 

func (s Service) FeatureSet() FeatureSet

FeatureSet returns the Editions features associated with this service.

func (Service) FullName 

func (s Service) FullName() FullName

FullName returns this service's fully-qualified name.

func (Service) InternedFullName 

func (s Service) InternedFullName() intern.ID

InternedFullName returns the intern ID for Service.FullName.

func (Service) InternedName 

func (s Service) InternedName() intern.ID

InternedName returns the intern ID for Service.FullName().Name().

func (Service) Methods 

func (s Service) Methods() seq.Indexer[Method]

Methods returns the methods of this service.

func (Service) Name 

func (s Service) Name() string

Name returns this service's declared name, i.e. the last component of its full name.

func (Service) Options 

func (s Service) Options() MessageValue

Options returns the options applied to this service.

type Session 

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

Session is shared global configuration and state for all IR values that are being used together.

It is used to track shared book-keeping.

A zero Session is ready to use.

func (*Session) Lower 

func (s *Session) Lower(source *ast.File, errs *report.Report, importer Importer) (file *File, ok bool)

Lower lowers an AST into an IR module.

The ir package does not provide a mechanism for resolving imports; instead, they must be provided as an argument to this function.

type Symbol 

type Symbol id.Node[Symbol, *File, *rawSymbol]

Symbol is an entry in a File's symbol table.

[Symbol.Context] returns the context for the file which imported this symbol. To map this to the context in which the symbol was defined, use [Symbol.InDefFile].

func (Symbol) AsMember 

func (s Symbol) AsMember() Member

AsMember returns the member this symbol refers to, if it is one.

func (Symbol) AsMethod 

func (s Symbol) AsMethod() Method

AsMethod returns the method this symbol refers to, if it is one.

func (Symbol) AsOneof 

func (s Symbol) AsOneof() Oneof

AsOneof returns the oneof this symbol refers to, if it is one.

func (Symbol) AsService 

func (s Symbol) AsService() Service

AsService returns the service this symbol refers to, if it is one.

func (Symbol) AsType 

func (s Symbol) AsType() Type

AsType returns the type this symbol refers to, if it is one.

func (Symbol) Definition 

func (s Symbol) Definition() source.Span

Definition returns a span for the definition site of this symbol; specifically, this is (typically) just an identifier.

func (Symbol) Deprecated 

func (s Symbol) Deprecated() Value

Deprecated returns whether this symbol is deprecated, but returning the relevant option value for setting deprecation.

Note that although files can be marked as deprecated, packages cannot, so package symbols never show up as deprecated.

func (Symbol) FeatureSet 

func (s Symbol) FeatureSet() FeatureSet

FeatureSet returns the features associated with this symbol.

func (Symbol) FullName 

func (s Symbol) FullName() FullName

FullName returns this symbol's fully-qualified name.

func (Symbol) Import 

func (s Symbol) Import(in *File) Import

Import returns the import declaration that brought this symbol into scope in the given file.

Returns zero if s is defined in the current file or if s is not imported by in.

func (Symbol) InternedFullName 

func (s Symbol) InternedFullName() intern.ID

InternedFullName returns the intern ID for Symbol.FullName.

func (Symbol) Kind 

func (s Symbol) Kind() SymbolKind

Kind returns which kind of symbol this is.

func (Symbol) Visible 

func (s Symbol) Visible(in *File, allowOptions bool) bool

Visible returns whether or not this symbol is visible according to Protobuf's import semantics, within the given file.

If allowOptions is true, symbols that were pulled in via import option are accepted.

type SymbolKind 

type SymbolKind int8

SymbolKind is a kind of symbol, i.e. an IR entity that defines a fully-qualified name. 

const (
	SymbolKindInvalid SymbolKind = iota
	SymbolKindPackage
	SymbolKindScalar
	SymbolKindMessage
	SymbolKindEnum
	SymbolKindField
	SymbolKindEnumValue
	SymbolKindExtension
	SymbolKindOneof
	SymbolKindService
	SymbolKindMethod
)

func (SymbolKind) GoString 

func (v SymbolKind) GoString() string

GoString implements fmt.GoStringer.

func (SymbolKind) IsMember 

func (k SymbolKind) IsMember() bool

IsMember returns whether this is a field's symbol kind. This includes enum values, which the ir package treats as fields of enum types.

func (SymbolKind) IsMessageField 

func (k SymbolKind) IsMessageField() bool

IsMessageField returns whether this is a field's symbol kind.

func (SymbolKind) IsScope 

func (k SymbolKind) IsScope() bool

IsScope returns whether this is a symbol that defines a scope, for the purposes of name lookup.

func (SymbolKind) IsType 

func (k SymbolKind) IsType() bool

IsType returns whether this is a type's symbol kind.

func (SymbolKind) OptionTarget 

func (k SymbolKind) OptionTarget() OptionTarget

OptionTarget returns the OptionTarget type for a symbol of this kind.

Returns OptionTargetInvalid if there is no corresponding target for this type of symbol.

func (SymbolKind) String 

func (v SymbolKind) String() string

String implements fmt.Stringer.

type TagRange 

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

TagRange is a range of tag numbers in a Type.

This can represent either a Member or a ReservedRange.

func (TagRange) AsMember 

func (r TagRange) AsMember() Member

AsMember returns the Member this range points to, or zero if it isn't a member.

func (TagRange) AsReserved 

func (r TagRange) AsReserved() ReservedRange

AsReserved returns the ReservedRange this range points to, or zero if it isn't a member.

type Type 

type Type id.Node[Type, *File, *rawType]

Type is a Protobuf message field type.

func PredeclaredType 

func PredeclaredType(n predeclared.Name) Type

PredeclaredType returns the type corresponding to a predeclared name.

Returns the zero value if !n.IsScalar().

func (Type) AST 

func (t Type) AST() ast.DeclDef

AST returns the declaration for this type, if known.

This need not be an ast.DefMessage or ast.DefEnum; it may be something else in the case of e.g. a map field's entry type.

func (Type) AbsoluteRange 

func (t Type) AbsoluteRange() (start, end int32)

AbsoluteRange returns the smallest and largest number a member of this type can have.

This range is inclusive.

func (Type) AllRanges 

func (t Type) AllRanges() seq.Indexer[ReservedRange]

AllRanges returns all reserved/extension ranges declared in this type.

This does not include reserved field names; see Type.ReservedNames.

func (Type) AllowsAlias 

func (t Type) AllowsAlias() bool

AllowsAlias returns whether this is an enum type with the allow_alias option set.

func (Type) Deprecated 

func (t Type) Deprecated() Value

Deprecated returns whether this type is deprecated, by returning the relevant option value for setting deprecation.

func (Type) EntryFields 

func (t Type) EntryFields() (key, value Member)

EntryFields returns the key and value fields for this map entry type.

func (Type) Extends 

func (t Type) Extends() seq.Indexer[Extend]

Extends returns the options applied to this type.

func (Type) ExtensionRanges 

func (t Type) ExtensionRanges() seq.Indexer[ReservedRange]

ExtensionRanges returns the extension ranges declared in this type.

func (Type) Extensions 

func (t Type) Extensions() seq.Indexer[Member]

Extensions returns any extensions nested within this type.

func (Type) FeatureSet 

func (t Type) FeatureSet() FeatureSet

FeatureSet returns the Editions features associated with this type.

func (Type) FullName 

func (t Type) FullName() FullName

FullName returns this type's fully-qualified name.

If t is zero, returns "". Otherwise, the returned name will be absolute unless this is a primitive type.

func (Type) InternedFullName 

func (t Type) InternedFullName() intern.ID

InternedName returns the intern ID for Type.FullName

Predeclared types do not have an interned name.

func (Type) InternedName 

func (t Type) InternedName() intern.ID

InternedName returns the intern ID for Type.FullName().Name()

Predeclared types do not have an interned name.

func (Type) InternedScope 

func (t Type) InternedScope() intern.ID

InternedScope returns the intern ID for Type.Scope

Predeclared types do not have an interned name.

func (Type) IsAny 

func (t Type) IsAny() bool

IsAny returns whether this is the type google.protobuf.Any, which gets special treatment in the language.

func (Type) IsClosedEnum 

func (t Type) IsClosedEnum() bool

func (Type) IsEnum 

func (t Type) IsEnum() bool

IsEnum returns whether this is an enum type.

func (Type) IsExported 

func (t Type) IsExported() (exported, explicit bool)

IsExported returns whether this type is exported for the purposes of visibility in other files.

Returns whether this was set explicitly via the export or local keywords.

func (Type) IsMapEntry 

func (t Type) IsMapEntry() bool

IsMapEntry returns whether this is a map type's entry.

func (Type) IsMessage 

func (t Type) IsMessage() bool

IsMessage returns whether this is a message type.

func (Type) IsMessageSet 

func (t Type) IsMessageSet() bool

IsMessageSet returns whether this is a message type using the message set encoding.

func (Type) IsPackable 

func (t Type) IsPackable() bool

IsPackable returns whether this type can be the element of a packed repeated field.

func (Type) IsPredeclared 

func (t Type) IsPredeclared() bool

IsPredeclared returns whether this is a predeclared type.

func (Type) MapField 

func (t Type) MapField() Member

MapField returns the map field that generated this type, if any.

func (Type) MemberByInternedName 

func (t Type) MemberByInternedName(name intern.ID) Member

MemberByInternedName is like Type.MemberByName, but takes an interned string.

func (Type) MemberByName 

func (t Type) MemberByName(name string) Member

MemberByName looks up a member with the given name.

Returns a zero member if there is no such member.

func (Type) MemberByNumber 

func (t Type) MemberByNumber(number int32) Member

MemberByNumber looks up a member with the given number.

Returns a zero member if there is no such member.

func (Type) Members 

func (t Type) Members() seq.Indexer[Member]

Members returns the members of this type.

Predeclared types have no members; message and enum types do.

func (Type) Name 

func (t Type) Name() string

Name returns this type's declared name, i.e. the last component of its full name.

func (Type) Nested 

func (t Type) Nested() seq.Indexer[Type]

Nested returns those types which are nested within this one.

Only message types have nested types.

func (Type) OccupiedRanges 

func (t Type) OccupiedRanges() iter.Seq2[[2]int32, seq.Indexer[TagRange]]

OccupiedRanges returns ranges of member numbers currently in use in this type. The pairs of numbers are inclusive ranges.

func (Type) Oneofs 

func (t Type) Oneofs() seq.Indexer[Oneof]

Oneofs returns the options applied to this type.

func (Type) Options 

func (t Type) Options() MessageValue

Options returns the options applied to this type.

func (Type) Parent 

func (t Type) Parent() Type

Parent returns the type that this type is declared inside of, if it isn't at the top level.

func (Type) Predeclared 

func (t Type) Predeclared() predeclared.Name

Predeclared returns the predeclared type that this Type corresponds to, if any.

Returns either predeclared.Unknown or a value such that predeclared.Name.IsScalar returns true. For example, this will *not* return predeclared.Map for map fields.

func (Type) Ranges 

func (t Type) Ranges(number int32) iter.Seq[TagRange]

Ranges returns an iterator over [TagRange]s that contain number.

func (Type) ReservedNames 

func (t Type) ReservedNames() seq.Indexer[ReservedName]

ReservedNames returns the reserved named declared in this type.

func (Type) ReservedRanges 

func (t Type) ReservedRanges() seq.Indexer[ReservedRange]

ReservedRanges returns the reserved ranges declared in this type.

This does not include reserved field names; see Type.ReservedNames.

func (Type) Scope 

func (t Type) Scope() FullName

Scope returns the scope in which this type is defined.

type Value 

type Value id.Node[Value, *File, *rawValue]

Value is an evaluated expression, corresponding to an option in a Protobuf file.

func (Value) AsBool 

func (v Value) AsBool() (value, ok bool)

AsBool is a shortcut for Element.AsBool, if this value is singular.

func (Value) AsEnum 

func (v Value) AsEnum() Member

AsEnum is a shortcut for Element.AsEnum, if this value is singular.

func (Value) AsFloat 

func (v Value) AsFloat() (float64, bool)

AsFloat is a shortcut for Element.AsFloat, if this value is singular.

func (Value) AsInt 

func (v Value) AsInt() (int64, bool)

AsInt is a shortcut for Element.AsInt, if this value is singular.

func (Value) AsMessage 

func (v Value) AsMessage() MessageValue

AsMessage is a shortcut for Element.AsMessage, if this value is singular.

func (Value) AsString 

func (v Value) AsString() (string, bool)

AsString is a shortcut for Element.AsString, if this value is singular.

func (Value) AsUInt 

func (v Value) AsUInt() (uint64, bool)

AsUInt is a shortcut for Element.AsUInt, if this value is singular.

func (Value) Container 

func (v Value) Container() MessageValue

Container returns the message value which contains this value, assuming it is not a top-level value.

This function is analogous to Member.Container, which returns the type that contains a member; in particular, for extensions, it returns an extendee.

func (Value) Elements 

func (v Value) Elements() seq.Indexer[Element]

Elements returns an indexer over the elements within this value.

If the value is not an array, it contains the singular element within; otherwise, it returns the elements of the array.

The indexer will be nonempty except for the zero Value. That is to say, unset fields of [MessageValue]s are not represented as a distinct "empty" Value.

func (Value) Field 

func (v Value) Field() Member

Field returns the field this value sets, which includes the value's type information.

NOTE: Member.Element returns google.protobuf.Any, the concrete type of the values in Value.Elements may be distinct from it.

func (Value) IsZeroValue 

func (v Value) IsZeroValue() bool

IsZeroValue is a shortcut for Element.IsZeroValue.

func (Value) KeyAST 

func (v Value) KeyAST() ast.ExprAny

KeyAST returns a representative AST node for the message key that evaluated from this value.

func (Value) KeyASTs 

func (v Value) KeyASTs() seq.Indexer[ast.ExprAny]

KeyASTs returns the AST nodes for each key associated with a value in Value.ValueASTs.

This will either be the key value from an ast.FieldExpr (which need not be an ast.PathExpr, in the case of an extension) or the ast.PathExpr associated with the left-hand-side of an option setting.

func (Value) Marshal 

func (v Value) Marshal(buf []byte, r *report.Report) []byte

Marshal converts this value into a wire format record and appends it to buf.

If r is not nil, it will be used to record diagnostics generated during the marshal operation.

func (Value) OptionPaths 

func (v Value) OptionPaths() seq.Indexer[ast.Path]

OptionPaths returns the AST nodes for option paths that set this node.

There will be one path per value returned from Value.ValueASTs. Generally, you'll want to use Value.KeyASTs instead.

func (Value) OptionSpan 

func (v Value) OptionSpan() source.Spanner

OptionSpan returns a representative span for the option that set this value.

The Spanner will be an ast.ExprField, if it is set in an ast.ExprDict.

func (Value) OptionSpans 

func (v Value) OptionSpans() seq.Indexer[source.Spanner]

OptionSpans returns an indexer over spans for the option that set this value.

The Spanner will be an ast.ExprField, if it is set in an ast.ExprDict.

func (Value) ValueAST 

func (v Value) ValueAST() ast.ExprAny

ValueAST returns a representative expression that evaluated to this value.

For complicated options (such as repeated fields), there may be more than one contributing expression; this will just return *one* of them.

func (Value) ValueASTs 

func (v Value) ValueASTs() seq.Indexer[ast.ExprAny]

ValueASTs returns all expressions that contributed to evaluating this value.

There may be more than one such expression, for repeated fields set more than once.

Source Files

View all Source files

Directories

Path Synopsis
Package presence provides Kind, which denotes the way in which a field can be present in a Protobuf message.
 Package presence provides Kind, which denotes the way in which a field can be present in a Protobuf message.

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.