From 970e8578c5326ad236304ecbaba05920c80448bd Mon Sep 17 00:00:00 2001 From: Luke Shumaker Date: Tue, 23 Oct 2018 12:34:16 -0400 Subject: License under the AGPL --- backend.go | 15 +++++++++++++++ 1 file changed, 15 insertions(+) (limited to 'backend.go') diff --git a/backend.go b/backend.go index 52b2441..9da1b1b 100644 --- a/backend.go +++ b/backend.go @@ -1,3 +1,18 @@ +// Copyright (C) 2017 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 +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU Affero General Public License for more details. +// +// You should have received a copy of the GNU Affero General Public License +// along with this program. If not, see . + package libfastimport import ( -- cgit v1.2.3 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 ++++++++++++++++++++++++++++++++++---- 1 file changed, 34 insertions(+), 4 deletions(-) (limited to 'backend.go') 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 { -- cgit v1.2.3