From aab6e690da587d54301225705ea5ee97512a49e0 Mon Sep 17 00:00:00 2001 From: Luke Shumaker Date: Tue, 23 Oct 2018 12:40:03 -0400 Subject: textproton: Add godoc comments --- textproto/io.go | 34 +++++++++++++++++++++++++++++++++- textproto/types.go | 38 ++++++++++++++++++++++++++++---------- 2 files changed, 61 insertions(+), 11 deletions(-) diff --git a/textproto/io.go b/textproto/io.go index da73db9..dde5470 100644 --- a/textproto/io.go +++ b/textproto/io.go @@ -1,4 +1,4 @@ -// Copyright (C) 2017 Luke Shumaker +// Copyright (C) 2017-2018 Luke Shumaker // // This program is free software: you can redistribute it and/or modify // it under the terms of the GNU Affero General Public License as published by @@ -13,6 +13,14 @@ // You should have received a copy of the GNU Affero General Public License // along with this program. If not, see . +// Package textproto implements low-level details of the fast-import +// format. +// +// This package deals with parsing and marshalling idiosyncratic +// datatypes used by the format (Ident tuples, 18-bit Mode numbers, +// oddly-quoted Path strings), and abstracting over special-case +// commands that break the "line-based" nature of the format (the +// "data" command, responses to the "cat-blob" command). package textproto import ( @@ -23,6 +31,7 @@ import ( "strings" ) +// FIReader is a low-level parser of a fast-import stream. type FIReader struct { r *bufio.Reader @@ -30,12 +39,16 @@ type FIReader struct { err error } +// NewFIReader creates a new FIReader parser. func NewFIReader(r io.Reader) *FIReader { return &FIReader{ r: bufio.NewReader(r), } } +// ReadLine reads a "line" from the stream; with special handling for +// the "data" command, which isn't really a single line, but rather +// contains arbitrary binary data. func (fir *FIReader) ReadLine() (line string, err error) { for len(line) <= 1 { line, err = fir.r.ReadString('\n') @@ -73,21 +86,26 @@ func (fir *FIReader) ReadLine() (line string, err error) { return } +// FIWriter is a low-level marshaller of a fast-import stream. type FIWriter struct { w io.Writer } +// NewFIWriter creates a new FIWriter marshaller. func NewFIWriter(w io.Writer) *FIWriter { return &FIWriter{ w: w, } } +// WriteLine writes an ordinary line to the stream; arguments are +// handled similarly to fmt.Println. func (fiw *FIWriter) WriteLine(a ...interface{}) error { _, err := fmt.Fprintln(fiw.w, a...) return err } +// WriteData writes a 'data' command to the stream. func (fiw *FIWriter) WriteData(data string) error { err := fiw.WriteLine("data", len(data)) if err != nil { @@ -97,16 +115,22 @@ func (fiw *FIWriter) WriteData(data string) error { return err } +// CatBlobReader is a low-level parser of an fast-import auxiliary +// "cat-blob" stream. type CatBlobReader struct { r *bufio.Reader } +// NewCatBlobReader creates a new CatBlobReader parser. func NewCatBlobReader(r io.Reader) *CatBlobReader { return &CatBlobReader{ r: bufio.NewReader(r), } } +// ReadLine reads a response from the stream; with special handling +// for responses to "cat-blob" commands, which contain multiple +// newline characters. func (cbr *CatBlobReader) ReadLine() (line string, err error) { for len(line) <= 1 { line, err = cbr.r.ReadString('\n') @@ -141,21 +165,29 @@ func (cbr *CatBlobReader) ReadLine() (line string, err error) { return } +// CatBlobWriter is a low-level marshaller for an auxiliary cat-blob +// stream. type CatBlobWriter struct { w io.Writer } +// NewCatBlobWriter creates a new CatBlobWriter marshaller. func NewCatBlobWriter(w io.Writer) *CatBlobWriter { return &CatBlobWriter{ w: w, } } +// WriteLine writes a response (to a command OTHER THAN "cat-blob") to +// the stream; arguments are handled similarly to fmt.Println. +// +// Use WriteBlob instead to write responses to "cat-blob" commands. func (cbw *CatBlobWriter) WriteLine(a ...interface{}) error { _, err := fmt.Fprintln(cbw.w, a...) return err } +// WriteBlob writes a response to a "cat-blob" command to the stream. func (cbw *CatBlobWriter) WriteBlob(sha1 string, data string) error { err := cbw.WriteLine(sha1, "blob", len(data)) if err != nil { diff --git a/textproto/types.go b/textproto/types.go index fb5aa5f..20aa3e5 100644 --- a/textproto/types.go +++ b/textproto/types.go @@ -1,4 +1,4 @@ -// Copyright (C) 2017 Luke Shumaker +// Copyright (C) 2017-2018 Luke Shumaker // // This program is free software: you can redistribute it and/or modify // it under the terms of the GNU Affero General Public License as published by @@ -22,8 +22,11 @@ import ( "time" ) -// BUG(lukeshu): Only supports the "raw" date format (not "rfc2822" or -// "now") +// Ident is a tuple of a commiter's (or author's) name, email, and a +// timestamp with timezone. +// +// BUG(lukeshu): Ident (and ParseIdent) only supports the "raw" date +// format (not "rfc2822" or "now") type Ident struct { Name string Email string @@ -46,6 +49,16 @@ func (ut Ident) String() string { } } +// ParseIdent parses a string containing an Ident. +// +// The format of this string is +// +// SP LT GT SP