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 ImageFilteredByTypesWithOptions(image bufimage.Image, types []string, opts ...ImageFilterOption) (bufimage.Image, error)
- func NewInputFiles(imageFiles []bufimage.ImageFile) []protosource.InputFile
- func StripSourceRetentionOptions(image bufimage.Image) (bufimage.Image, error)
- type ImageFilterOption
Constants ¶
This section is empty.
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 ¶ added in v1.1.0
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. So 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 following 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 ImageFilteredByTypesWithOptions ¶ added in v1.10.0
func ImageFilteredByTypesWithOptions(image bufimage.Image, types []string, opts ...ImageFilterOption) (bufimage.Image, error)
ImageFilteredByTypesWithOptions returns a minimal image containing only the descriptors required to define those types. See ImageFilteredByTypes for more details. This version allows for customizing the behavior with options.
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.
func StripSourceRetentionOptions ¶ added in v1.30.0
StripSourceRetentionOptions strips any options with a retention of "source" from the descriptors in the given image. The image is not mutated but instead a new image is returned. The returned image may share state with the original.
Types ¶
type ImageFilterOption ¶ added in v1.10.0
type ImageFilterOption func(*imageFilterOptions)
ImageFilterOption is an option that can be passed to ImageFilteredByTypesWithOptions.
func WithAllowFilterByImportedType ¶ added in v1.10.0
func WithAllowFilterByImportedType() ImageFilterOption
WithAllowFilterByImportedType returns an option for ImageFilteredByTypesWithOptions that allows a named filter type to be in an imported file or module. Without this option, only types defined directly in the image to be filtered are allowed.
func WithExcludeCustomOptions ¶ added in v1.10.0
func WithExcludeCustomOptions() ImageFilterOption
WithExcludeCustomOptions returns an option that will cause an image filtered via ImageFilteredByTypesWithOptions to *not* include custom options unless they are explicitly named in the list of filter types.
func WithExcludeKnownExtensions ¶ added in v1.10.0
func WithExcludeKnownExtensions() ImageFilterOption
WithExcludeKnownExtensions returns an option that will cause an image filtered via ImageFilteredByTypesWithOptions to *not* include the known extensions for included extendable messages unless they are explicitly named in the list of filter types.
Source Files