protoparse

package
v1.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 23, 2019 License: Apache-2.0 Imports: 32 Imported by: 223

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.

This package links in other 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

Constants

This section is empty.

Variables

This section is empty.

Functions

func ResolveFilenames added in v1.4.0

func ResolveFilenames(importPaths []string, fileNames ...string) ([]string, error)

ResolveFilenames tries to resolve fileNames into paths that are relative to directories in the given importPaths. The returned slice has the results in the same order as they are supplied in fileNames.

The resulting names should be suitable for passing to Parser.ParseFiles.

If importPaths is empty and any path is absolute, this returns error. If importPaths is empty and all paths are relative, this returns the original fileNames.

Types

type ErrorWithSourcePos

type ErrorWithSourcePos struct {
	Underlying error
	Pos        *SourcePos
}

ErrorWithSourcePos is an error about a proto source file includes information about the location in the file that caused the error.

func (ErrorWithSourcePos) Error

func (e ErrorWithSourcePos) Error() string

Error implements the error interface

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.

func FileContentsFromMap added in v1.2.0

func FileContentsFromMap(files map[string]string) FileAccessor

FileContentsFromMap returns a FileAccessor that uses the given map of file contents. This allows proto source files to be constructed in memory and easily supplied to a parser. The map keys are the paths to the proto source files, and the values are the actual proto source contents.

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.
	//
	// This setting is only used during ParseFiles operations. Since calls to
	// ParseFilesButDoNotLink do not link, there is no need to load and parse
	// dependencies.
	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. If ImportPaths is also empty
	// then relative paths are will be relative to the process's current working
	// directory.
	Accessor FileAccessor

	// If true, the resulting file descriptors will retain source code info,
	// that maps elements to their location in the source files as well as
	// includes comments found during parsing (and attributed to elements of
	// the source file).
	IncludeSourceCodeInfo bool

	// If true, the results from ParseFilesButDoNotLink will be passed through
	// some additional validations. But only constraints that do not require
	// linking can be checked. These include proto2 vs. proto3 language features,
	// looking for incorrect usage of reserved names or tags, and ensuring that
	// fields have unique tags and that enum values have unique numbers (unless
	// the enum allows aliases).
	ValidateUnlinkedFiles bool

	// If true, the results from ParseFilesButDoNotLink will have options
	// interpreted. Any uninterpretable options (including any custom options or
	// options that refer to message and enum types, which can only be
	// interpreted after linking) will be left in uninterpreted_options. Also,
	// the "default" pseudo-option for fields can only be interpreted for scalar
	// fields, excluding enums. (Interpreting default values for enum fields
	// requires resolving enum names, which requires linking.)
	InterpretOptionsInUnlinkedFiles bool
}

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-provided files -- e.g. google/protobuf/*.proto -- 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.

func (p Parser) ParseFilesButDoNotLink(filenames ...string) ([]*dpb.FileDescriptorProto, error)

ParseFilesButDoNotLink parses the named files into descriptor protos. The results are just protos, not fully-linked descriptors. It is possible that descriptors are invalid and still be returned in parsed form without error due to the fact that the linking step is skipped (and thus many validation steps omitted).

There are a few side effects to not linking the descriptors:

  1. No options will be interpreted. Options can refer to extensions or have message and enum types. Without linking, these extension and type references are not resolved, so the options may not be interpretable. So all options will appear in UninterpretedOption fields of the various descriptor options messages.
  2. Type references will not be resolved. This means that the actual type names in the descriptors may be unqualified and even relative to the scope in which the type reference appears. This goes for fields that have message and enum types. It also applies to methods and their references to request and response message types.
  3. Enum fields are not known. Until a field's type reference is resolved (during linking), it is not known whether the type refers to a message or an enum. So all fields with such type references have their Type set to TYPE_MESSAGE.

This method will still validate the syntax of parsed files. If the parser's ValidateUnlinkedFiles field is true, additional checks, beyond syntax will also be performed.

type SourcePos

type SourcePos struct {
	Filename  string
	Line, Col int
	Offset    int
}

SourcePos identifies a location in a proto source file.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL