bufimageutil

Documentation

Index

• Variables
• func FreeMessageRangeStrings(ctx context.Context, filePaths []string, image bufimage.Image) ([]string, error)
• func ImageFilteredByTypes(image bufimage.Image, types ...string) (bufimage.Image, error)
• func NewInputFiles(imageFiles []bufimage.ImageFile) []protosource.InputFile

Variables

var (
	// ErrImageFilterTypeNotFound is returned from ImageFilteredByTypes when
	// a specified type cannot be found in an image.
	ErrImageFilterTypeNotFound = errors.New("not found")

	// ErrImageFilterTypeIsImport is returned from ImageFilteredByTypes when
	// a specified type name is declared in a module dependency.
	ErrImageFilterTypeIsImport = errors.New("type declared in imported module")
)

Functions

func FreeMessageRangeStrings

func FreeMessageRangeStrings(
	ctx context.Context,
	filePaths []string,
	image bufimage.Image,
) ([]string, error)

FreeMessageRangeStrings gets the free MessageRange strings for the target files.

Recursive.

func ImageFilteredByTypes

func ImageFilteredByTypes(image bufimage.Image, types ...string) (bufimage.Image, error)

ImageFilteredByTypes returns a minimal image containing only the descriptors required to define those types. The resulting contains only files in which those descriptors and their transitive closure of required descriptors, with each file only contains the minimal required types and imports.

Although this returns a new bufimage.Image, it mutates the original image's underlying file's `descriptorpb.FileDescriptorProto` and the old image should not continue to be used.

A descriptor is said to require another descriptor if the dependent descriptor is needed to accurately and completely describe that descriptor. For the follwing types that includes:

Messages
 - messages & enums referenced in fields
 - proto2 extension declarations for this field
 - custom options for the message, its fields, and the file in which the
   message is defined
 - the parent message if this message is a nested definition

Enums
 - Custom options used in the enum, enum values, and the file
   in which the message is defined
 - the parent message if this message is a nested definition

Services
 - request & response types referenced in methods
 - custom options for the service, its methods, and the file
   in which the message is defined

As an example, consider the following proto structure:

--- foo.proto ---
package pkg;
message Foo {
  optional Bar bar = 1;
  extensions 2 to 3;
}
message Bar { ... }
message Baz {
  other.Qux qux = 1 [(other.my_option).field = "buf"];
}
--- baz.proto ---
package other;
extend Foo {
  optional Qux baz = 2;
}
message Qux{ ... }
message Quux{ ... }
extend google.protobuf.FieldOptions {
  optional Quux my_option = 51234;
}

A filtered image for type `pkg.Foo` would include

files:      [foo.proto, bar.proto]
messages:   [pkg.Foo, pkg.Bar, other.Qux]
extensions: [other.baz]

A filtered image for type `pkg.Bar` would include

 files:      [foo.proto]
 messages:   [pkg.Bar]

A filtered image for type `pkg.Baz` would include
 files:      [foo.proto, bar.proto]
 messages:   [pkg.Baz, other.Quux, other.Qux]
 extensions: [other.my_option]

func NewInputFiles

func NewInputFiles(imageFiles []bufimage.ImageFile) []protosource.InputFile

NewInputFiles converts the ImageFiles to InputFiles.

Since protosource is a pkg package, it cannot depend on bufmoduleref, which has the definition for bufmoduleref.ModuleIdentity, so we have our own interfaces for this in protosource. Given Go's type system, we need to do a conversion here.