Documentation
¶
Overview ¶
Package parser contains the logic for parsing protobuf source code into an AST (abstract syntax tree) and also for converting an AST into a descriptor proto.
A FileDescriptorProto is very similar to an AST, but the AST this package uses is more useful because it contains more information about the source code, including details about whitespace and comments, that cannot be represented by a descriptor proto. This makes it ideal for things like code formatters, which may want to preserve things like whitespace and comment format.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrNoSyntax = errors.New("no syntax specified; defaulting to proto2 syntax")
ErrNoSyntax is a sentinel error that may be passed to a warning reporter. The error the reporter receives will be wrapped with source position that indicates the file that had no syntax statement.
Functions ¶
func Parse ¶
Parse parses the given source code info and returns an AST. The given filename is used to construct error messages and position information. The given reader supplies the source code. The given handler is used to report errors and warnings encountered while parsing. If any errors are reported, this function returns a non-nil error.
Types ¶
type Result ¶
type Result interface {
// AST returns the parsed abstract syntax tree. This returns nil if the
// Result was created without an AST.
AST() *ast.FileNode
// Proto returns the file descriptor proto.
Proto() *descriptorpb.FileDescriptorProto
// FileNode returns the root of the AST. If this result has no AST then a
// placeholder node is returned.
FileNode() ast.FileDeclNode
// Node returns the AST node from which the given message was created. This
// can return nil, such as if the given message is not part of the
// FileDescriptorProto hierarchy. If this result has no AST, this returns a
// placeholder node.
Node(proto.Message) ast.Node
// OptionNode returns the AST node corresponding to the given uninterpreted
// option. This can return nil, such as if the given option is not part of
// the FileDescriptorProto hierarchy. If this result has no AST, this
// returns a placeholder node.
OptionNode(*descriptorpb.UninterpretedOption) ast.OptionDeclNode
// OptionNamePartNode returns the AST node corresponding to the given name
// part for an uninterpreted option. This can return nil, such as if the
// given name part is not part of the FileDescriptorProto hierarchy. If this
// result has no AST, this returns a placeholder node.
OptionNamePartNode(*descriptorpb.UninterpretedOption_NamePart) ast.Node
// MessageNode returns the AST node corresponding to the given message. This
// can return nil, such as if the given message is not part of the
// FileDescriptorProto hierarchy. If this result has no AST, this returns a
// placeholder node.
MessageNode(*descriptorpb.DescriptorProto) ast.MessageDeclNode
// FieldNode returns the AST node corresponding to the given field. This can
// return nil, such as if the given field is not part of the
// FileDescriptorProto hierarchy. If this result has no AST, this returns a
// placeholder node.
FieldNode(*descriptorpb.FieldDescriptorProto) ast.FieldDeclNode
// OneOfNode returns the AST node corresponding to the given oneof. This can
// return nil, such as if the given oneof is not part of the
// FileDescriptorProto hierarchy. If this result has no AST, this returns a
// placeholder node.
OneOfNode(*descriptorpb.OneofDescriptorProto) ast.Node
// ExtensionRangeNode returns the AST node corresponding to the given
// extension range. This can return nil, such as if the given range is not
// part of the FileDescriptorProto hierarchy. If this result has no AST,
// this returns a placeholder node.
ExtensionRangeNode(*descriptorpb.DescriptorProto_ExtensionRange) ast.RangeDeclNode
// MessageReservedRangeNode returns the AST node corresponding to the given
// reserved range. This can return nil, such as if the given range is not
// part of the FileDescriptorProto hierarchy. If this result has no AST,
// this returns a placeholder node.
MessageReservedRangeNode(*descriptorpb.DescriptorProto_ReservedRange) ast.RangeDeclNode
// EnumNode returns the AST node corresponding to the given enum. This can
// return nil, such as if the given enum is not part of the
// FileDescriptorProto hierarchy. If this result has no AST, this returns a
// placeholder node.
EnumNode(*descriptorpb.EnumDescriptorProto) ast.Node
// EnumValueNode returns the AST node corresponding to the given enum. This
// can return nil, such as if the given enum value is not part of the
// FileDescriptorProto hierarchy. If this result has no AST, this returns a
// placeholder node.
EnumValueNode(*descriptorpb.EnumValueDescriptorProto) ast.EnumValueDeclNode
// EnumReservedRangeNode returns the AST node corresponding to the given
// reserved range. This can return nil, such as if the given range is not
// part of the FileDescriptorProto hierarchy. If this result has no AST,
// this returns a placeholder node.
EnumReservedRangeNode(*descriptorpb.EnumDescriptorProto_EnumReservedRange) ast.RangeDeclNode
// ServiceNode returns the AST node corresponding to the given service. This
// can return nil, such as if the given service is not part of the
// FileDescriptorProto hierarchy. If this result has no AST, this returns a
// placeholder node.
ServiceNode(*descriptorpb.ServiceDescriptorProto) ast.Node
// MethodNode returns the AST node corresponding to the given method. This
// can return nil, such as if the given method is not part of the
// FileDescriptorProto hierarchy. If this result has no AST, this returns a
// placeholder node.
MethodNode(*descriptorpb.MethodDescriptorProto) ast.RPCDeclNode
}
Result is the result of constructing a descriptor proto from a parsed AST. From this result, the AST and the file descriptor proto can be had. This also contains numerous lookup functions, for looking up AST nodes that correspond to various elements of the descriptor hierarchy.
Results can be created without AST information, using the ResultWithoutAST() function. All functions other than AST() will still return non-nil values, allowing compile operations to work with files that have only intermediate descriptor protos and no source code. For such results, the function that return AST nodes will return placeholder nodes. The position information for placeholder nodes contains only the filename.
func ResultFromAST ¶
ResultFromAST constructs a descriptor proto from the given AST. The returned result includes the descriptor proto and also contains an index that can be used to lookup AST node information for elements in the descriptor proto hierarchy.
If validate is true, some basic validation is performed, to make sure the resulting descriptor proto is valid per protobuf rules and semantics. Only some language elements can be validated since some rules and semantics can only be checked after all symbols are all resolved, which happens in the linking step.
The given handler is used to report any errors or warnings encountered. If any errors are reported, this function returns a non-nil error.
func ResultWithoutAST ¶
func ResultWithoutAST(proto *descriptorpb.FileDescriptorProto) Result
ResultWithoutAST returns a parse result that has no AST. All methods for looking up AST nodes return a placeholder node that contains only the filename in position information.
Source Files