Documentation
¶
Overview ¶
Package protocompile -- build_link.go contains the core descriptor building functions that construct FileDescriptor and MessageDescriptor trees from resolved AST files.
Package protocompile -- build_resolve.go contains field, oneof, enum, service, and method descriptor building functions, along with type resolution helpers that link field types to their built descriptors.
Package protocompile -- build_validate.go contains the build context definition, syntax mapping helpers, cardinality conversion, and packed encoding computation used during descriptor building.
Package protocompile transforms parsed .proto AST files into fully linked, validated descriptor sets. It resolves imports, links type references to descriptors, validates field numbers and types, applies default values, and produces an immutable descriptor tree ready for code generation or runtime use.
The core type is Compiler, constructed via NewCompiler with a FileAccessor that abstracts file loading. The Compile method accepts one or more .proto file paths and returns a Result containing linked FileDescriptor values in topological order (dependencies before dependents).
A typical usage looks like:
accessor := &protocompile.OSFileAccessor{}
compiler := protocompile.NewCompiler(accessor)
result, err := compiler.Compile("api/messages.proto", "api/service.proto")
if err != nil {
log.Fatal(err)
}
for _, fd := range result.Files() {
fmt.Println(fd.Path(), fd.Package())
}
The Compiler holds internal caches (parsed files, symbol table) and is not safe for concurrent use. Callers must not call Compile concurrently on the same Compiler instance.
The package follows a split error convention. Programmer errors cause panics prefixed with "protocompile: " for easy identification (e.g., passing a nil accessor to NewCompiler or calling Compile with no file arguments). Data-driven failures such as parse errors, unresolved type references, and validation failures are returned as errors from Compile. When multiple errors are encountered during compilation, they are collected into an ErrorList and returned together.
All error messages use the "protocompile: " prefix. Errors that have source position information include the file path, line, and column in the format "protocompile: file.proto:10:5: message".
This package depends on protoparse, descriptor, scalar, and the standard library. It has zero external dependencies.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type CompileError ¶
type CompileError struct {
// Pos is the source location where the error occurred.
Pos protoparse.Position
// Detail is a human-readable description of the failure.
Detail string
// Cause is the underlying error, if any.
Cause error
}
CompileError is a typed error returned when proto compilation encounters a semantic error at a known source location. It includes file, line, and column context and wraps an optional underlying cause.
func (*CompileError) Error ¶
func (e *CompileError) Error() string
Error returns a human-readable message with the source location prefix.
func (*CompileError) Unwrap ¶
func (e *CompileError) Unwrap() error
Unwrap returns the underlying cause so that errors.Is and errors.As work.
type Compiler ¶
type Compiler struct {
// contains filtered or unexported fields
}
Compiler transforms parsed .proto AST files into fully linked, validated descriptor sets. It holds internal caches for parsed files and a symbol table for type resolution. A Compiler is not safe for concurrent use.
func NewCompiler ¶
func NewCompiler(accessor FileAccessor) *Compiler
NewCompiler creates a Compiler that loads files through the given accessor. It panics if accessor is nil.
type ErrorList ¶
type ErrorList []error
ErrorList collects multiple compilation errors encountered during a single compilation. It implements the error interface; its Error method joins all contained messages with newlines. The Unwrap method returns the underlying slice for use with errors.As and errors.Is.
type FileAccessor ¶
type FileAccessor interface {
// Open reads the file at path and returns its contents. It returns an
// error if the file cannot be read.
Open(path string) ([]byte, error)
}
FileAccessor abstracts file loading so that callers can supply custom file systems, in-memory sources, or overlay file systems. The compiler never calls os.ReadFile directly; all file I/O goes through a FileAccessor.
type OSFileAccessor ¶
type OSFileAccessor struct{}
OSFileAccessor is a FileAccessor that reads files from the real filesystem using os.ReadFile.
type Result ¶
type Result struct {
// contains filtered or unexported fields
}
Result holds the output of a successful compilation. It provides both ordered and keyed access to the compiled file descriptors. A Result is immutable and safe for concurrent read access after creation.
func (*Result) File ¶
func (r *Result) File(path string) *descriptor.FileDescriptor
File returns the file descriptor for the given path, or nil if no file with that path was compiled.
func (*Result) Files ¶
func (r *Result) Files() []*descriptor.FileDescriptor
Files returns the compiled file descriptors in topological order (dependencies before dependents). The returned slice must not be modified.
Source Files