protoparse

Documentation

Overview

Package protoparse provides functionality for parsing *.proto source files into descriptors that can be used with other protoreflect packages, like dynamic messages and dynamic GRPC clients.

The file descriptors produced by this package do not include the source_code_info field. As such, comments and location information (like where in the file an element is declared) are not available. This also means that many errors encountered will not have location information. The errors try to be as specific as possible for pinpointing their source. But the only errors that include locations (like line numbers) are those generated during parsing (e.g. syntax errors). Other validation and link errors will instead refer to symbols in the parsed files, not their location/line number.

This package links in various packages that include compiled descriptors for the various "google/protobuf/*.proto" files that are included with protoc. That way, like when invoking protoc, programs need not supply copies of these "builtin" files. Though if copies of the files are provided, they will be used instead of the builtin descriptors.

Index

• type FileAccessor
• type Parser
  • func (p Parser) ParseFiles(filenames ...string) ([]*desc.FileDescriptor, error)

Types

type FileAccessor

type FileAccessor func(filename string) (io.ReadCloser, error)

FileAccessor is an abstraction for opening proto source files. It takes the name of the file to open and returns either the input reader or an error.

type Parser

type Parser struct {
	// The paths used to search for dependencies that are referenced in import
	// statements in proto source files. If no import paths are provided then
	// "." (current directory) is assumed to be the only import path.
	ImportPaths []string

	// If true, the supplied file names/paths need not necessarily match how the
	// files are referenced in import statements. The parser will attempt to
	// match import statements to supplied paths, "guessing" the import paths
	// for the files. Note that this inference is not perfect and link errors
	// could result. It works best when all proto files are organized such that
	// a single import path can be inferred (e.g. all files under a single tree
	// with import statements all being relative to the root of this tree).
	InferImportPaths bool

	// Used to create a reader for a given filename, when loading proto source
	// file contents. If unset, os.Open is used, and relative paths are thus
	// relative to the process's current working directory.
	Accessor FileAccessor
}

Parser parses proto source into descriptors.

func (Parser) ParseFiles

func (p Parser) ParseFiles(filenames ...string) ([]*desc.FileDescriptor, error)

ParseFiles parses the named files into descriptors. The returned slice has the same number of entries as the give filenames, in the same order. So the first returned descriptor corresponds to the first given name, and so on.

All dependencies for all specified files (including transitive dependencies) must be accessible via the parser's Accessor or a link error will occur. The exception to this rule is that files can import standard "google/protobuf/*.proto" files without needing to supply sources for these files. Like protoc, this parser has a built-in version of these files it can use if they aren't explicitly supplied.