summaryrefslogtreecommitdiff
path: root/textproto
diff options
context:
space:
mode:
authorLuke Shumaker <lukeshu@lukeshu.com>2018-10-23 12:40:03 -0400
committerLuke Shumaker <lukeshu@lukeshu.com>2018-10-23 12:41:00 -0400
commitaab6e690da587d54301225705ea5ee97512a49e0 (patch)
tree561a7b138c83bb906d7e5c103c1256ff67c52414 /textproto
parent07ee7b5f3c46c5db69ecb3fda71ab33a59f9a8dd (diff)
textproton: Add godoc comments
Diffstat (limited to 'textproto')
-rw-r--r--textproto/io.go34
-rw-r--r--textproto/types.go38
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 <lukeshu@lukeshu.com>
+// Copyright (C) 2017-2018 Luke Shumaker <lukeshu@lukeshu.com>
//
// 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 <https://www.gnu.org/licenses/>.
+// 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 <lukeshu@lukeshu.com>
+// Copyright (C) 2017-2018 Luke Shumaker <lukeshu@lukeshu.com>
//
// 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
+//
+// <name> SP LT <email> GT SP <time> SP <offutc>
+//
+// Where <name> may contain a space, but not "<" or ">"; <time> is an
+// integer number of seconds since the UNIX epoch (UTC); <offutc> is
+// positive or negative 4-digit offset from UTC (for example, EST
+// would be "-0500").
func ParseIdent(str string) (Ident, error) {
ret := Ident{}
lt := strings.IndexAny(str, "<>")
@@ -85,14 +98,15 @@ func ParseIdent(str string) (Ident, error) {
return ret, nil
}
+// Mode is a file mode as seen by git.
type Mode uint32 // 18 bits
var (
- ModeFil = Mode(0100644)
- ModeExe = Mode(0100755)
- ModeSym = Mode(0120000)
- ModeGit = Mode(0160000)
- ModeDir = Mode(0040000)
+ ModeFil = Mode(0100644) // A regular file
+ ModeExe = Mode(0100755) // An executable file
+ ModeSym = Mode(0120000) // A symbolic link
+ ModeGit = Mode(0160000) // A nested git repository (e.g. submodule)
+ ModeDir = Mode(0040000) // A directory
)
func (m Mode) String() string {
@@ -103,6 +117,10 @@ func (m Mode) GoString() string {
return fmt.Sprintf("%07o", m)
}
+// Path is a string storing a git path.
+type Path string
+
+// PathEscape escapes a path in case it contains special characters.
func PathEscape(path Path) string {
if strings.HasPrefix(string(path), "\"") || strings.ContainsRune(string(path), '\n') {
return "\"" + strings.Replace(strings.Replace(strings.Replace(string(path), "\\", "\\\\", -1), "\"", "\\\"", -1), "\n", "\\n", -1) + "\""
@@ -111,6 +129,7 @@ func PathEscape(path Path) string {
}
}
+// PathUnescape unescapes a quoted path.
func PathUnescape(epath string) Path {
if strings.HasPrefix(epath, "\"") {
return Path(strings.Replace(strings.Replace(strings.Replace(epath[1:len(epath)-1], "\\n", "\n", -1), "\\\"", "\"", -1), "\\\\", "\\", -1))
@@ -119,8 +138,7 @@ func PathUnescape(epath string) Path {
}
}
-type Path string
-
+// String calls PathEscape on the Path.
func (p Path) String() string {
return PathEscape(p)
}