From 8cb9190264f0774cfc6521794ac506756060048f Mon Sep 17 00:00:00 2001 From: Joe Tsai Date: Thu, 6 Sep 2018 18:27:40 -0700 Subject: [PATCH] internal/encoding/pack: replace AST with CST in documentation 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 --- internal/encoding/pack/pack.go | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/internal/encoding/pack/pack.go b/internal/encoding/pack/pack.go index 89601ba3..aeb33906 100644 --- a/internal/encoding/pack/pack.go +++ b/internal/encoding/pack/pack.go @@ -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 {