mirror/protobuf-go
1
0
Fork 0
mirror of https://github.com/protocolbuffers/protobuf-go.git synced 2024-12-29 12:17:48 +00:00
Code Issues Packages Projects Releases Wiki Activity

internal/encoding/pack: replace AST with CST in documentation

Browse Source 
According to linguistics, this is actually a concrete syntax tree, rather
than an abstract syntax tree since it perfectly represents the grammatical
structure of the original raw input.

On the other hand, an abstract syntax tree (AST) loses some
grammatical structure and is only concerned with preserving syntax.

See https://eli.thegreenplace.net/2009/02/16/abstract-vs-concrete-syntax-trees/

Change-Id: Ia3fdb407d2b15c5431984956b7d74921891c2ad9
Reviewed-on: https://go-review.googlesource.com/133995
Reviewed-by: Herbie Ong <herbie@google.com>
This commit is contained in:
Joe Tsai 2018-09-06 18:27:40 -07:00 committed by Joe Tsai
parent 7779e05b0a
commit 8cb9190264
1 changed files with 8 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
internal/encoding/pack/pack.go
View File

@ -52,7 +52,9 @@ const (
type (
// Token is any other type (e.g., Message, Tag, Varint, Float32, etc).
Token token
// Message is a ordered sequence Tokens.
// Message is an ordered sequence of Tokens, where certain tokens may
// contain other tokens. It is functionally a concrete syntax tree that
// losslessly represents any arbitrary wire data (including invalid input).
Message []Token
// Tag is a tuple of the field number and the wire type.
@ -168,7 +170,7 @@ func (m Message) Size() int {
return n
}
// Message encodes an AST into the protobuf wire format.
// Message encodes a syntax tree into the protobuf wire format.
//
// Example message definition:
// message MyMessage {
@ -242,12 +244,12 @@ func (m Message) Marshal() []byte {
return out
}
// Unmarshal parses the input protobuf wire data as a Message AST.
// Unmarshal parses the input protobuf wire data as a syntax tree.
// Any parsing error results in the remainder of the input being
// concatenated to the message as a Raw type.
//
// Each tag (a tuple of the field number and wire type) encountered is
// appended to the AST as a Tag.
// inserted into the syntax tree as a Tag.
//
// The contents of each wire type is mapped to the following Go types:
// VarintType => Uvarint
@ -271,7 +273,7 @@ func (m *Message) Unmarshal(in []byte) {
m.UnmarshalDescriptor(in, nil)
}
// UnmarshalDescriptor parses the input protobuf wire data as a Message AST
// UnmarshalDescriptor parses the input protobuf wire data as a syntax tree
// using the provided message descriptor for more accurate parsing of fields.
// It operates like Unmarshal, but may use a wider range of Go types to
// represent the wire data.
@ -482,7 +484,7 @@ func (p *parser) parseGroup(desc protoreflect.MessageDescriptor) {
}
}
// Format implements a custom formatter to visualize the Message AST.
// Format implements a custom formatter to visualize the syntax tree.
// Using "%#v" formats the Message in Go source code.
func (m Message) Format(s fmt.State, r rune) {
switch r {