From 392cc1262df7203a6c8b4f6b692cd69950ccc598 Mon Sep 17 00:00:00 2001 From: Luke Shumaker Date: Tue, 23 Oct 2018 13:31:53 -0400 Subject: Add godoc comments --- backend.go | 38 ++++++++++++++++++++++++++++++++++---- cmd.go | 16 +++++++++++++++- cmd_command.go | 38 ++++++++++++++++++++++++++++++++++++-- cmd_comment.go | 16 +++++++++++++++- cmd_commit.go | 43 ++++++++++++++++++++++++++++++++++++++++++- frontend.go | 33 +++++++++++++++++++++++++++++++-- 6 files changed, 173 insertions(+), 11 deletions(-) diff --git a/backend.go b/backend.go index 9da1b1b..0a95547 100644 --- a/backend.go +++ b/backend.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 @@ -24,7 +24,12 @@ import ( ) // A Backend is something that consumes a fast-import stream; the -// Backend object provides methods for writing to it. +// Backend object provides methods for writing to it. A program that +// reads from a Backend would itself be a frontend. +// +// You may think of a "Backend" object as a "Writer" object, though it was not +// given that name because the GetMark, CatBlob, and Ls methods +// actually provide 2-way communication. type Backend struct { fastImportClose io.Closer fastImportFlush *bufio.Writer @@ -37,6 +42,14 @@ type Backend struct { onErr func(error) error } +// NewBackend creates a new Backend object that writes to the given +// io.WriteCloser. +// +// Optionally, you may also provide an io.Reader that responses to +// "cat-blob", "get-mark", and "ls" commands can be read from. +// +// Optionally, you may also provide an onErr function that can be used +// to handle or transform errors when they are encountered. func NewBackend(fastImport io.WriteCloser, catBlob io.Reader, onErr func(error) error) *Backend { ret := &Backend{} @@ -67,8 +80,10 @@ func NewBackend(fastImport io.WriteCloser, catBlob io.Reader, onErr func(error) return ret } -// will panic if Cmd is a type that may only be used in a commit but -// we aren't in a commit. +// Do tells the Backend to do the given command. +// +// It is an error (panic) if Cmd is a type that may only be used in a +// commit but we aren't in a commit. func (b *Backend) Do(cmd Cmd) error { if b.err == nil { return b.err @@ -103,6 +118,11 @@ func (b *Backend) Do(cmd Cmd) error { return nil } +// GetMark gets the SHA-1 referred to by the given mark from the +// Backend. +// +// It is an error (panic) to call GetMark if NewBackend did not have a +// cat-blob reader passed to it. func (b *Backend) GetMark(cmd CmdGetMark) (sha1 string, err error) { err = b.Do(cmd) if err != nil { @@ -120,6 +140,11 @@ func (b *Backend) GetMark(cmd CmdGetMark) (sha1 string, err error) { return } +// CatBlob gets the SHA-1 and content of the specified blob from the +// Backend. +// +// It is an error (panic) to call CatBlob if NewBackend did not have a +// cat-blob reader passed to it. func (b *Backend) CatBlob(cmd CmdCatBlob) (sha1 string, data string, err error) { err = b.Do(cmd) if err != nil { @@ -137,6 +162,11 @@ func (b *Backend) CatBlob(cmd CmdCatBlob) (sha1 string, data string, err error) return } +// Ls gets information about the file at the specified path from the +// Backend. +// +// It is an error (panic) to call Ls if NewBackend did not have a +// cat-blob reader passed to it. func (b *Backend) Ls(cmd CmdLs) (mode textproto.Mode, dataref string, path textproto.Path, err error) { err = b.Do(cmd) if err != nil { diff --git a/cmd.go b/cmd.go index 6d9e055..1665081 100644 --- a/cmd.go +++ b/cmd.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,19 @@ // You should have received a copy of the GNU Affero General Public License // along with this program. If not, see . +// Package libfastimport implements reading and writing of git +// fast-import streams. +// +// The documentation here focuses on use of the package itself; it +// generally assumes a working understanding of the format. +// Documentation on the format itself can be found in the +// git-fast-import(1) man-page. +// +// A program can write commands to a backend by wrapping the +// appropriate io.Writer with a Backend object. +// +// A program can read commands from a frontend by wrapping the +// appropriate io.Reader with a Frontend object. package libfastimport type fiReader interface { @@ -34,6 +47,7 @@ const ( cmdClassComment cmdClass = cmdClassCommand | cmdClassCommit ) +// Cmd is a command that may be found in a fast-import stream. type Cmd interface { fiCmdRead(fiReader) (Cmd, error) fiCmdWrite(fiWriter) error diff --git a/cmd_command.go b/cmd_command.go index e490a2b..7d65727 100644 --- a/cmd_command.go +++ b/cmd_command.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 @@ -25,6 +25,14 @@ import ( // commit ////////////////////////////////////////////////////////////////////// +// CmdCommit requests that the Backend creates or updates a branch +// with a new commit. +// +// This command may be followed by zero or more "File" or "Note" +// commands to set the content of commit's tree. When reading from a +// Frontend, that sequence of "File" and "Note" commands will be +// terminated by a CmdCommitEnd command. It is not nescessary to +// manually emit a CmdCommitEnd when writing to a Backend. type CmdCommit struct { Ref string Mark int // optional; < 1 for non-use @@ -103,6 +111,13 @@ func (CmdCommit) fiCmdRead(fir fiReader) (cmd Cmd, err error) { return } +// CmdCommitEnd indicates the Frontend will be sending no more "File" +// or "Note" commands that are "part of" the current CmdCommit. +// +// This is a synthesized command to simplify reading from a Frontend; +// it is not really a command in the stream. It is thus not +// nescessary to send a CmdCommitEnd command when writing to a +// Backend. type CmdCommitEnd struct{} func (CmdCommitEnd) fiCmdClass() cmdClass { return cmdClassCommit } @@ -111,6 +126,10 @@ func (CmdCommitEnd) fiCmdRead(fir fiReader) (Cmd, error) { panic("not reached") // tag ///////////////////////////////////////////////////////////////////////// +// CmdTag requests that the Backend creates an *annotated* tag +// referencing a specific commit. +// +// Hint: Use CmdReset to create a *lightweight* tag. type CmdTag struct { RefName string CommitIsh string @@ -160,6 +179,9 @@ func (CmdTag) fiCmdRead(fir fiReader) (cmd Cmd, err error) { // reset /////////////////////////////////////////////////////////////////////// +// CmdReset requests that the Backend creates (or recreates) the named +// ref (usually a branch), optionally starting from a specific +// revision. type CmdReset struct { RefName string CommitIsh string // optional @@ -195,8 +217,12 @@ func (CmdReset) fiCmdRead(fir fiReader) (cmd Cmd, err error) { // blob //////////////////////////////////////////////////////////////////////// +// CmdBlob requests that the Backend write file revision. The blob +// can be later referred to by the specified Mark (if a Mark > 0 is +// given), or by pre-calculating the Git SHA-1 (though this is +// needlessly difficult, just specify a Mark). type CmdBlob struct { - Mark int + Mark int // optional Data string } @@ -236,6 +262,7 @@ func (CmdBlob) fiCmdRead(fir fiReader) (cmd Cmd, err error) { // checkpoint ////////////////////////////////////////////////////////////////// +// CmdCheckpoint requests that the Backend flush already-sent data. type CmdCheckpoint struct{} func (c CmdCheckpoint) fiCmdClass() cmdClass { return cmdClassCommand } @@ -253,6 +280,8 @@ func (CmdCheckpoint) fiCmdRead(fir fiReader) (cmd Cmd, err error) { // progress //////////////////////////////////////////////////////////////////// +// CmdProgress requests that the Backend print the given string to its +// standard output channel. type CmdProgress struct { Str string } @@ -272,6 +301,8 @@ func (CmdProgress) fiCmdRead(fir fiReader) (cmd Cmd, err error) { // feature ///////////////////////////////////////////////////////////////////// +// CmdFeature requests that the Backend immediately aborts with an +// error if it does not support the specified feature. type CmdFeature struct { Feature string Argument string @@ -306,6 +337,7 @@ func (CmdFeature) fiCmdRead(fir fiReader) (cmd Cmd, err error) { // option ////////////////////////////////////////////////////////////////////// +// CmdOption requests that the Backend changes its settings. type CmdOption struct { Option string } @@ -326,6 +358,8 @@ func (CmdOption) fiCmdRead(fir fiReader) (cmd Cmd, err error) { // done //////////////////////////////////////////////////////////////////////// +// CmdDone indicates to the Backend that no more commands will be +// sent. type CmdDone struct{} func (c CmdDone) fiCmdClass() cmdClass { return cmdClassCommand } diff --git a/cmd_comment.go b/cmd_comment.go index 14832da..c640fef 100644 --- a/cmd_comment.go +++ b/cmd_comment.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 @@ -25,6 +25,7 @@ import ( // comment ///////////////////////////////////////////////////////////////////// +// CmdComment is a comment line; not a real command. type CmdComment struct { Comment string } @@ -44,6 +45,9 @@ func (CmdComment) fiCmdRead(fir fiReader) (cmd Cmd, err error) { // get-mark //////////////////////////////////////////////////////////////////// +// CmdGetMark requests that the Backend to report back (over the +// auxiliary cat-blob stream) with the SHA-1 corresponding to the +// given Mark. type CmdGetMark struct { Mark int } @@ -68,6 +72,10 @@ func (CmdGetMark) fiCmdRead(fir fiReader) (cmd Cmd, err error) { // cat-blob //////////////////////////////////////////////////////////////////// +// CmdCatBlob requests that the Backend to report back (over the +// auxiliary cat-blob stream) with the SHA-1 and content of the +// requested blob. The blob can be specified either by a mark +// reference (":") or by a full 40-byte SHA-1. type CmdCatBlob struct { DataRef string } @@ -87,6 +95,12 @@ func (CmdCatBlob) fiCmdRead(fir fiReader) (cmd Cmd, err error) { // ls ////////////////////////////////////////////////////////////////////////// +// CmdLs requests that the Backend to report back (over the auxiliary +// cat-blob stream) with information about the object at a path in the +// specified commit. If inside of a commit, specifying the commit is +// optional, and the ongoing commit is used. The commit can be +// specified either by a mark reference (":") or by a full +// 40-byte SHA-1. type CmdLs struct { DataRef string // optional if inside of a commit Path textproto.Path diff --git a/cmd_commit.go b/cmd_commit.go index 05baac5..83b9815 100644 --- a/cmd_commit.go +++ b/cmd_commit.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 @@ -25,6 +25,13 @@ import ( // M /////////////////////////////////////////////////////////////////////////// +// FileModify appears after a CmdCommit (and before a CmdCommitEnd), +// and causes the CmdCommit to add a new file or change the content of +// an existing file. The content of the file is specified by giving +// either a mark reference (":") or by a full 40-byte SHA-1. +// +// To specify the full content of the file inline, use +// FileModifyInline instead. type FileModify struct { Mode textproto.Mode Path textproto.Path @@ -79,6 +86,13 @@ func (FileModify) fiCmdRead(fir fiReader) (cmd Cmd, err error) { } } +// FileModifyInline appears after a CmdCommit (and before a +// CmdCommitEnd), and causes the CmdCommit to add a new file or change +// the content of an existing file. The full content of the file are +// specified directly +// +// To instead specify the content with a mark reference (":") +// or with a full 40-byte SHA-1, use FileModify instead. type FileModifyInline struct { Mode textproto.Mode Path textproto.Path @@ -96,6 +110,8 @@ func (FileModifyInline) fiCmdRead(fiReader) (Cmd, error) { panic("not reached") // D /////////////////////////////////////////////////////////////////////////// +// FileDelete appears after a CmdCommit (and before a CmdCommitEnd), +// and causes the CmdCommit to recursively remove a file or directory. type FileDelete struct { Path textproto.Path } @@ -115,6 +131,9 @@ func (FileDelete) fiCmdRead(fir fiReader) (cmd Cmd, err error) { // C /////////////////////////////////////////////////////////////////////////// +// FileCopy appears after a CmdCommit (and before a CmdCommitEnd), +// and causes the CmdCommit to recursively copy an existing file or +// subdirectory to a different location. type FileCopy struct { Src textproto.Path Dst textproto.Path @@ -132,6 +151,9 @@ func (FileCopy) fiCmdRead(fir fiReader) (cmd Cmd, err error) { // R /////////////////////////////////////////////////////////////////////////// +// FileRename appears after a CmdCommit (and before a CmdCommitEnd), +// and causes the CmdCommit to rename an existing file or subdirectory +// to a different location. type FileRename struct { Src string Dst string @@ -149,6 +171,9 @@ func (FileRename) fiCmdRead(fir fiReader) (cmd Cmd, err error) { // deleteall /////////////////////////////////////////////////////////////////// +// FileDeleteAll appears after a CmdCommit (and before a +// CmdCommitEnd), and removes all files and directories from the +// CmdCommit. type FileDeleteAll struct{} func (o FileDeleteAll) fiCmdClass() cmdClass { return cmdClassCommit } @@ -166,6 +191,14 @@ func (FileDeleteAll) fiCmdRead(fir fiReader) (cmd Cmd, err error) { // N /////////////////////////////////////////////////////////////////////////// +// NoteModify appears after a CmdCommit (and before a CmdCommitEnd), +// and causes the CmdCommit to add a new note describing CommitIsh or +// change the content of an existing note describing CommitIsh. The +// content of the note is specified by giving either a mark reference +// (":") or by a full 40-byte SHA-1. +// +// To specify the full content of the note inline, use +// NoteModifyInline instead. type NoteModify struct { CommitIsh string DataRef string @@ -212,6 +245,14 @@ func (NoteModify) fiCmdRead(fir fiReader) (cmd Cmd, err error) { } } +// NoteModifyInline appears after a CmdCommit (and before a +// CmdCommitEnd), and causes the CmdCommit to add a new note +// describing CommitIsh or change the content of an existing note +// describing CommitIsh. The full content of the note is specified +// directly. +// +// To instead specify the content with a mark reference (":") +// or with a full 40-byte SHA-1, use NoteModify instead. type NoteModifyInline struct { CommitIsh string Data string diff --git a/frontend.go b/frontend.go index 108a1b1..dc8e771 100644 --- a/frontend.go +++ b/frontend.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 @@ -30,7 +30,13 @@ func (e UnsupportedCommand) Error() string { } // A Frontend is something that produces a fast-import stream; the -// Frontend object provides methods for reading from it. +// Frontend object provides methods for reading from it. A program +// that writes to a Frontend would itself be a backend. +// +// You may think of a "Frontend" object as a "Reader" object, though +// it was not given that name because the RespondGetMark, +// RespondCatBlob, and RespondLs methods actually write information; +// it isn't a read-only object. type Frontend struct { fastImport *parser catBlobWrite *textproto.CatBlobWriter @@ -39,6 +45,14 @@ type Frontend struct { onErr func(error) error } +// NewFrontend creates a new Frontend object that reads from the given +// io.Reader. +// +// Optionally, you may also provide an io.Writer that responses to +// "cat-blob", "get-mark", and "ls" commands can be written to. +// +// Optionally, you may also provide an onErr function that can bue +// used to handle or transform errors when they are encountered. func NewFrontend(fastImport io.Reader, catBlob io.Writer, onErr func(error) error) *Frontend { ret := &Frontend{} @@ -58,6 +72,7 @@ func NewFrontend(fastImport io.Reader, catBlob io.Writer, onErr func(error) erro return ret } +// ReadCmd reads a command from the Frontend. func (f *Frontend) ReadCmd() (Cmd, error) { cmd, err := f.fastImport.ReadCmd() if err != nil { @@ -66,6 +81,11 @@ func (f *Frontend) ReadCmd() (Cmd, error) { return cmd, err } +// RespondGetMark sends to the Frontend a response to a "get-mark" +// command. +// +// It is an error (panic) to call RespondGetMark if NewFrontend did +// not have a cat-blob writer passed to it. func (f *Frontend) RespondGetMark(sha1 string) error { err := f.catBlobWrite.WriteLine(sha1) if err != nil { @@ -74,6 +94,11 @@ func (f *Frontend) RespondGetMark(sha1 string) error { return f.catBlobFlush.Flush() } +// RespondCatBlob sends to the Frontend a response to a "cat-blob" +// command. +// +// It is an error (panic) to call RespondCatBlob if NewFrontend did +// not have a cat-blob writer passed to it. func (f *Frontend) RespondCatBlob(sha1 string, data string) error { err := f.catBlobWrite.WriteBlob(sha1, data) if err != nil { @@ -82,6 +107,10 @@ func (f *Frontend) RespondCatBlob(sha1 string, data string) error { return f.catBlobFlush.Flush() } +// RespondLs sends to the Frontend a response to a "ls" command. +// +// It is an error (panic) to call RespondLs if NewFrontend did not +// have a cat-blob writer passed to it. func (f *Frontend) RespondLs(mode textproto.Mode, dataref string, path textproto.Path) error { var err error if mode == 0 { -- cgit v1.2.3