Documentation
¶
Index ¶
- func ImageToCodeGeneratorRequest(image Image, parameter string, compilerVersion *pluginpb.Version, ...) (*pluginpb.CodeGeneratorRequest, error)
- func ImageToFileDescriptorProtos(image Image) []*descriptorpb.FileDescriptorProto
- func ImageToFileDescriptorSet(image Image) *descriptorpb.FileDescriptorSet
- func ImageToProtoImage(image Image) *imagev1.Image
- func ImagesToCodeGeneratorRequests(images []Image, parameter string, compilerVersion *pluginpb.Version, ...) ([]*pluginpb.CodeGeneratorRequest, error)
- type Image
- func CloneImage(image Image) (Image, error)
- func ImageByDir(image Image) ([]Image, error)
- func ImageWithOnlyPaths(image Image, paths []string, excludePaths []string) (Image, error)
- func ImageWithOnlyPathsAllowNotExist(image Image, paths []string, excludePaths []string) (Image, error)
- func ImageWithoutImports(image Image) Image
- func MergeImages(images ...Image) (Image, error)
- func NewImage(imageFiles []ImageFile) (Image, error)
- func NewImageForCodeGeneratorRequest(request *pluginpb.CodeGeneratorRequest, options ...NewImageForProtoOption) (Image, error)
- func NewImageForProto(protoImage *imagev1.Image, options ...NewImageForProtoOption) (Image, error)
- type ImageFile
- type ImageModuleDependency
- type NewImageForProtoOption
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ImageToCodeGeneratorRequest ¶
func ImageToCodeGeneratorRequest( image Image, parameter string, compilerVersion *pluginpb.Version, includeImports bool, includeWellKnownTypes bool, ) (*pluginpb.CodeGeneratorRequest, error)
ImageToCodeGeneratorRequest returns a new CodeGeneratorRequest for the Image.
All non-imports are added as files to generate. If includeImports is set, all non-well-known-type imports are also added as files to generate. If includeWellKnownTypes is set, well-known-type imports are also added as files to generate. includeWellKnownTypes has no effect if includeImports is not set.
func ImageToFileDescriptorProtos ¶
func ImageToFileDescriptorProtos(image Image) []*descriptorpb.FileDescriptorProto
ImageToFileDescriptorProtos returns the FileDescriptorProtos for the Image.
func ImageToFileDescriptorSet ¶
func ImageToFileDescriptorSet(image Image) *descriptorpb.FileDescriptorSet
ImageToFileDescriptorSet returns a new FileDescriptorSet for the Image.
func ImageToProtoImage ¶
ImageToProtoImage returns a new ProtoImage for the Image.
func ImagesToCodeGeneratorRequests ¶
func ImagesToCodeGeneratorRequests( images []Image, parameter string, compilerVersion *pluginpb.Version, includeImports bool, includeWellKnownTypes bool, ) ([]*pluginpb.CodeGeneratorRequest, error)
ImagesToCodeGeneratorRequests converts the Images to CodeGeneratorRequests.
All non-imports are added as files to generate. If includeImports is set, all non-well-known-type imports are also added as files to generate. If includeImports is set, only one CodeGeneratorRequest will contain any given file as a FileToGenerate. If includeWellKnownTypes is set, well-known-type imports are also added as files to generate. includeWellKnownTypes has no effect if includeImports is not set.
Types ¶
type Image ¶
type Image interface {
// Files are the files that comprise the image.
//
// This contains all files, including imports if available.
// The returned files are in correct DAG order.
//
// All files that have the same ModuleIdentity will also have the same commit, or no commit.
// This is enforced at construction time.
Files() []ImageFile
// GetFile gets the file for the root relative file path.
//
// If the file does not exist, nil is returned.
// The path is expected to be normalized and validated.
// Note that all values of GetDependency() can be used here.
GetFile(path string) ImageFile
// contains filtered or unexported methods
}
Image is a buf image.
func CloneImage ¶ added in v1.30.0
CloneImage returns a deep copy of the given image.
func ImageByDir ¶
ImageByDir returns multiple images that have non-imports split by directory.
That is, each Image will only contain a single directory's files as it's non-imports, along with all required imports for the files in that directory.
func ImageWithOnlyPaths ¶
ImageWithOnlyPaths returns a copy of the Image that only includes the files with the given root relative file paths or directories.
Note that paths can be either files or directories - whether or not a path is included is a result of normalpath.EqualsOrContainsPath.
If a root relative file path does not exist, this errors.
func ImageWithOnlyPathsAllowNotExist ¶
func ImageWithOnlyPathsAllowNotExist( image Image, paths []string, excludePaths []string, ) (Image, error)
ImageWithOnlyPathsAllowNotExist returns a copy of the Image that only includes the files with the given root relative file paths.
Note that paths can be either files or directories - whether or not a path is included is a result of normalpath.EqualsOrContainsPath.
If a root relative file path does not exist, this skips this path.
func ImageWithoutImports ¶
ImageWithoutImports returns a copy of the Image without imports.
The backing Files are not copied.
func MergeImages ¶
MergeImages returns a new Image for the given Images. ImageFiles treated as non-imports in at least one of the given Images will be treated as non-imports in the returned Image. The first non-import version of a file will be used in the result.
Reorders the ImageFiles to be in DAG order. Duplicates can exist across the Images, but only if duplicates are non-imports.
func NewImage ¶
NewImage returns a new Image for the given ImageFiles.
The input ImageFiles are expected to be in correct DAG order! TODO: Consider checking the above, and if not, reordering the Files. If imageFiles is empty, returns error
func NewImageForCodeGeneratorRequest ¶
func NewImageForCodeGeneratorRequest(request *pluginpb.CodeGeneratorRequest, options ...NewImageForProtoOption) (Image, error)
NewImageForCodeGeneratorRequest returns a new Image from a given CodeGeneratorRequest.
The input Files are expected to be in correct DAG order! TODO: Consider checking the above, and if not, reordering the Files.
func NewImageForProto ¶
func NewImageForProto(protoImage *imagev1.Image, options ...NewImageForProtoOption) (Image, error)
NewImageForProto returns a new Image for the given proto Image.
The input Files are expected to be in correct DAG order! TODO: Consider checking the above, and if not, reordering the Files.
TODO: do we want to add the ability to do external path resolution here?
type ImageFile ¶
type ImageFile interface {
bufmoduleref.FileInfo
// FileDescriptorProto is the backing *descriptorpb.FileDescriptorProto for this File.
//
// This will never be nil.
// The value Path() is equal to FileDescriptorProto().GetName() .
FileDescriptorProto() *descriptorpb.FileDescriptorProto
// IsImport returns true if this file is an import.
IsImport() bool
// IsSyntaxUnspecified will be true if the syntax was not explicitly specified.
IsSyntaxUnspecified() bool
// UnusedDependencyIndexes returns the indexes of the unused dependencies within
// FileDescriptor.GetDependency().
//
// All indexes will be valid.
// Will return nil if empty.
UnusedDependencyIndexes() []int32
// contains filtered or unexported methods
}
ImageFile is a Protobuf file within an image.
func CloneImageFile ¶ added in v1.30.0
CloneImageFile returns a deep copy of the given image file.
func ImageFileWithIsImport ¶ added in v1.28.0
ImageFileWithIsImport returns a copy of the ImageFile with the new ImageFile now marked as an import.
If the original ImageFile was already an import, this returns the original ImageFile.
func NewImageFile ¶
func NewImageFile( fileDescriptor protodescriptor.FileDescriptor, moduleIdentity bufmoduleref.ModuleIdentity, commit string, externalPath string, isImport bool, isSyntaxUnspecified bool, unusedDependencyIndexes []int32, ) (ImageFile, error)
NewImageFile returns a new ImageFile.
If externalPath is empty, path is used.
TODO: moduleIdentity and commit should be options since they are optional.
type ImageModuleDependency ¶ added in v1.23.0
type ImageModuleDependency interface {
// String() returns remote/owner/repository[:commit].
fmt.Stringer
// Required. Will never be nil.
ModuleIdentity() bufmoduleref.ModuleIdentity
// Optional. May be empty.
Commit() string
// IsDirect returns true if the dependency is a direct dependency.
//
// A dependency is direct if it is only an import of non-imports in the image.
//
// Example:
//
// a.proto, module buf.build/foo/a, is non-import, imports b.proto
// b.proto, module buf.build/foo/b, is import, imports c.proto
// c.proto, module buf.build/foo/c, is import
//
// In this case, the list would contain only buf.build/foo/b, as buf.build/foo/a
// for a.proto is a non-import, and buf.build/foo/c for c.proto is only imported
// by an import
IsDirect() bool
// contains filtered or unexported methods
}
ImageModuleDependency is a dependency of an image.
This could conceivably be part of ImageFile or bufmoduleref.FileInfo. For ImageFile, this would be a field that is ignored when translated to proto, and is calculated on creation from proto. IsImport would become ImportType. You could go a step further and make this optionally part of the proto definition.
You could even go down to bufmoduleref.FileInfo if you used the AST, but this could be error prone.
However, for simplicity now (and to not rewrite the whole codebase), we make this a separate type that is calculated off of an Image after the fact.
If this became part of ImageFile or bufmoduleref.FileInfo, you would get all the ImageDependencies from the ImageFiles, and then sort | uniq them to get the ImageDependencies for an Image. This would remove the requirement of this associated type to have a ModuleIdentity and commit, so in the IsDirect example below, d.proto would not be "ignored" - it would be an ImageFile like any other, with ImportType DIRECT.
Note that if we ever do this, there is validation in newImage that enforces that all ImageFiles with the same ModuleIdentity have the same commit. This validation will likely have to be moved around.
func ImageModuleDependencies ¶ added in v1.23.0
func ImageModuleDependencies(image Image) []ImageModuleDependency
ImageModuleDependencies returns all ImageModuleDependency values for the Image.
Does not return any ImageModuleDependency values for non-imports, that is the ModuleIdentities and commits represented by non-imports are not represented in this list.
type NewImageForProtoOption ¶ added in v1.10.0
type NewImageForProtoOption func(*newImageForProtoOptions)
NewImageForProtoOption is an option for use with NewImageForProto.
func WithNoReparse ¶ added in v1.10.0
func WithNoReparse() NewImageForProtoOption
WithNoReparse instructs NewImageForProto to skip the reparse step. The reparse step is usually needed when unmarshalling the image from bytes. It reconstitutes custom options, from unrecognized bytes to known extension fields.
func WithUnusedImportsComputation ¶ added in v1.16.0
func WithUnusedImportsComputation() NewImageForProtoOption
WithUnusedImportsComputation instructs NewImageForProto to compute unused imports for the files. These are usually computed by the compiler and stored in the image. But some sources of images may not include this information, so this option can be used to ensure that information is present in the image and accurate.
This option is NOT compatible with WithNoReparse: the image must be re-parsed for there to be adequate information for computing unused imports.
Source Files
Directories