Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clean up comments to match standard Go comment conventions for exported names. #13

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Clean up comments to match standard Go comment conventions for exported names. #13

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 3 additions & 4 deletions cmd/protoscope/main.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,13 +54,13 @@ var (
)

func main() {
if err := Main(); err != nil {
if err := realMain(); err != nil {
fmt.Fprintln(os.Stderr, "protoscope:", err)
os.Exit(1)
}
}

func Main() error {
func realMain() error {
flag.Usage = func() {
fmt.Fprintf(os.Stderr, "Usage: %s [-s] [OPTION...] [INPUT]\n", os.Args[0])
fmt.Fprintf(os.Stderr, "Assemble a Protoscope file to binary, or inspect binary data as Protoscope text.\n")
Expand Down Expand Up @@ -154,8 +154,7 @@ func Main() error {

outBytes, err = scanner.Exec()
if err != nil {
return fmt.Errorf("syntax error: %s\n", err)
os.Exit(1)
return fmt.Errorf("syntax error: %s", err)
}
} else {
outBytes = []byte(protoscope.Write(inBytes, protoscope.WriterOptions{
Expand Down
28 changes: 16 additions & 12 deletions internal/print/print.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ func (s *Stack[T]) Pop() T {
return popped
}

// Pop pops the top n elements off the stack and returns a slice containing
// PopN pops the top n elements off the stack and returns a slice containing
// copies. Panics if the stack is too small
func (s *Stack[T]) PopN(n int) []T {
popped := make([]T, n)
Expand All @@ -58,7 +58,7 @@ func (s *Stack[T]) Peek() *T {
return &s.PeekN(1)[0]
}

// Peek returns the top n elements of the stack as another stack.
// PeekN returns the top n elements of the stack as another stack.
//
// Returns nil if the stack is too small.
func (s *Stack[T]) PeekN(n int) Stack[T] {
Expand Down Expand Up @@ -96,19 +96,22 @@ func (p *Printer) Current() *Line {
return p.Prev(0)
}

// Discards the current line
// DiscardLine discards the current line
func (p *Printer) DiscardLine() {
p.lines.Pop()
}

// A Mark is a mark in a Printer that can be used to discard all lines that follow it.
//
// See Printer.Reset().
type Mark int

// Makes a mark on the line buffer.
// Mark returns a mark on the line buffer.
func (p *Printer) Mark() Mark {
return Mark(len(p.lines))
}

// Discards all lines after the mark.
// Reset discards all lines after the mark.
func (p *Printer) Reset(m Mark) {
p.lines = p.lines[:m]
}
Expand All @@ -130,18 +133,18 @@ func (p *Printer) Write(args ...any) {
fmt.Fprint(p.Current(), args...)
}

// Writes to the current line's buffer with Fprintf.
// Writef writes to the current line's buffer with Fprintf.
func (p *Printer) Writef(f string, args ...any) {
fmt.Fprintf(p.Current(), f, args...)
}

// Adds a new remark made from stringifying args.
// Remark adds a new remark made by calling Fprint.
func (p *Printer) Remark(args ...any) {
l := p.Current()
l.remarks = append(l.remarks, fmt.Sprint(args...))
}

// Adds a new remark made from stringifying args.
// Remarkf adds a new remark made by calling Fprintf.
func (p *Printer) Remarkf(f string, args ...any) {
l := p.Current()
l.remarks = append(l.remarks, fmt.Sprintf(f, args...))
Expand Down Expand Up @@ -214,6 +217,7 @@ func (p *Printer) Finish() []byte {
return out.Bytes()
}

// A BlockInfo is configuration options for a block.
type BlockInfo struct {
// Whether this block will start and end with delimiters that do not need to
// have spaces placed before/after them, allowing for output like {x} instead
Expand All @@ -229,7 +233,7 @@ type BlockInfo struct {
start int
}

// Starts a new indentation block.
// StartBlock starts a new indentation block.
func (p *Printer) StartBlock(bi BlockInfo) {
if p.Current().indent != 0 {
panic("called StartBlock() too many times; this is a bug")
Expand All @@ -239,15 +243,15 @@ func (p *Printer) StartBlock(bi BlockInfo) {
p.Current().indent++
}

// Discards the current block and undoes its indentation.
// DropBlock discards the current block and undoes its indentation.
func (p *Printer) DropBlock() *Line {
bi := p.blocks.Pop()
start := &p.lines[bi.start]
start.indent--
return start
}

// Finishes an indentation block; a call to this function must match up to
// EndBlock finishes an indentation block; a call to this function must match up to
// a corresponding previous StartBlock() call. Returns the starting line for the
// block.
//
Expand Down Expand Up @@ -308,7 +312,7 @@ func (p *Printer) EndBlock() *Line {
return start
}

// Folds the last count lines into lines with `cols` columns each.
// FoldIntoColumns folds the last count lines into lines with `cols` columns each.
func (p *Printer) FoldIntoColumns(cols, count int) {
toFold := p.lines.PopN(count)
widths := make([]int, cols)
Expand Down
17 changes: 14 additions & 3 deletions scanner.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,17 @@
// See the License for the specific language governing permissions and
// limitations under the License.

// package protoscope ...
// package protoscope implements an assembler and disassembler for the Protoscope language.
// This language is specified in language.txt.
//
// The assembler consumes a string containing Protoscope tokens and outputs a Protobuf-encoded
// binary blob based on those tokens. The entry point for the assembler is the Scanner type.
//
// The disassembler consumes a binary blob and attempts to produce reasonable Protoscope tokens that
// can be reassembled into the original binary. It uses a number of heuristics to accomplish this,
// optionally incorporating a message descriptor to aid with disassembly. The entry point for the
// disassembler is the Write function.

package protoscope

import (
Expand All @@ -28,7 +38,7 @@ import (
_ "embed"
)

// The contents of language.text.
// LanguageTxt contains the contents of language.txt, which specifies the Protoscope language.
//
//go:embed language.txt
var LanguageTxt string
Expand Down Expand Up @@ -116,6 +126,7 @@ var (
// 3: The wire type, including the colon, if this is a tag.
// 4: The wire type expression, which may be empty if it is inferred.
regexpIntOrTag = regexp.MustCompile(`^-?([0-9]+|0x[0-9a-fA-F]+)(z|i32|i64)?(:(\w*))?$`)

regexpDecFp = regexp.MustCompile(`^(-?[0-9]+\.[0-9]+(?:[eE]-?[0-9]+)?)(i32|i64)?$`)
regexpHexFp = regexp.MustCompile(`^(-?0x[0-9a-fA-F]+\.[0-9a-fA-F]+(?:[pP]-?[0-9]+)?)(i32|i64)?$`)
regexpLongForm = regexp.MustCompile(`^long-form:([0-9]+)$`)
Expand Down Expand Up @@ -421,7 +432,7 @@ loop:
}

if value>>61 != 0 && value>>61 != -1 {
return token{}, &ParseError{start, errors.New("field number too large for three extra bits for the wire type.")}
return token{}, &ParseError{start, errors.New("field number too large for three extra bits for the wire type")}
}
fieldNumber = value

Expand Down