flop

README

flop

---

flop aims to make copying files easier in Go, and is modeled after GNU cp. Most administrators and engineers interact with GNU utilities every day, so it makes sense to utilize that knowledge and expectations for a library that does the same operation in code.

flop strategically diverges from cp where it is advantageous for the programmer to explicitly define the behavior, like cp assuming that copying from a file path to a directory path means the file should be created inside the directory. This behavior must be explicitly defined in flop by passing the option AppendNameToPath, otherwise an error will be returned.

go get -u github.com/homedepot/flop

Usage

Basic file copy.

err := flop.SimpleCopy("src_path", "dst_path")
handle(err)

Advanced file copy with options.

options := flop.Options{
    Recursive: true,
    MkdirAll:  true,
}
err := flop.Copy("src_path", "dst_path", options)
handle(err)

Logging

flop won't throw logs at you for no reason, but if you want to follow along with what's going on giving it a logger can help expose the behavior, or aid in debugging if you are generous enough to contribute.

// the logger just takes a string so format your favorite logger to accept one
import (
	"github.com/homedepot/flop"
	"github.com/rs/zerolog"
	zlog "github.com/rs/zerolog/log"
	llog "github.com/sirupsen/logrus"
)

func logDebug(msg string) {
	llog.WithFields(llog.Fields{
		"application": "stuffcopy",
	}).Info(msg)
}

func main() {
	zlog.Logger = zlog.Output(zerolog.ConsoleWriter{Out: os.Stderr})
	err := flop.Copy(src.Name(), dst.Name(), flop.Options{
		InfoLogFunc: zlog.Info().Msg,  // Msg already accepts a string so we can just pass it directly
		DebugLogFunc: logDebug,        // logrus Debug takes ...interface{} so we need to wrap it
	})
	handle(err)
}

Documentation

Overview

Package flop implements file operations, taking most queues from GNU cp while trying to be more programmatically friendly.

Index

• Variables
• func Copy(src, dst string, opts Options) (err error)
• func SimpleCopy(src, dst string) error
• type File
  • func NewFile(path string) *File
• type Options

Variables

var (
	// ErrFileNotExist occurs when a file is given that does not exist when its existence is required.
	ErrFileNotExist = errors.New("no such file or directory")
	// ErrCannotOpenSrc occurs when a src file cannot be opened with os.Open().
	ErrCannotOpenSrc = errors.New("source file cannot be opened")
	// ErrCannotStatFile occurs when a file receives an error from get os.Stat().
	ErrCannotStatFile = errors.New("cannot stat file, check that file path is accessible")
	// ErrCannotChmodFile occurs when an error is received trying to change permissions on a file.
	ErrCannotChmodFile = errors.New("cannot change permissions on file")
	// ErrCannotCreateTmpFile occurs when an error is received attempting to create a temporary file for atomic copy.
	ErrCannotCreateTmpFile = errors.New("temp file cannot be created")
	// ErrCannotOpenOrCreateDstFile occurs when an error is received attempting to open or create destination file during non-atomic copy.
	ErrCannotOpenOrCreateDstFile = errors.New("destination file cannot be created")
	// ErrCannotRenameTempFile occurs when an error is received trying to rename the temporary copy file to the destination.
	ErrCannotRenameTempFile = errors.New("cannot rename temp file, check file or directory permissions")
	// ErrOmittingDir occurs when attempting to copy a directory but Options.Recursive is not set to true.
	ErrOmittingDir = errors.New("Options.Recursive is not true, omitting directory")
	// ErrWithParentsDstMustBeDir occurs when the destination is expected to be an existing directory but is not
	// present or accessible.
	ErrWithParentsDstMustBeDir = errors.New("with Options.Parents, the destination must be a directory")
	// ErrCannotOverwriteNonDir occurs when attempting to copy a directory to a non-directory.
	ErrCannotOverwriteNonDir = errors.New("cannot overwrite non-directory")
	// ErrReadingSrcDir occurs when attempting to read contents of the source directory fails
	ErrReadingSrcDir = errors.New("cannot read source directory, check source directory permissions")
	// ErrWritingFileToExistingDir occurs when attempting to write a file to an existing directory.
	// See AppendNameToPath option for a more dynamic approach.
	ErrWritingFileToExistingDir = errors.New("cannot overwrite existing directory with file")
	// ErrInvalidBackupControlValue occurs when a control value is given to the Backup option, but the value is invalid.
	ErrInvalidBackupControlValue = errors.New("invalid backup value, valid values are 'off', 'simple', 'existing', 'numbered'")
)

Functions

func Copy

func Copy(src, dst string, opts Options) (err error)

Copy will copy src to dst. Behavior is determined by the given Options.

func SimpleCopy

func SimpleCopy(src, dst string) error

SimpleCopy will src to dst with default Options.

Types

type File

type File struct {
	// Path is the path to the src file.
	Path string
	// contains filtered or unexported fields
}

File describes a file on the filesystem.

func NewFile

func NewFile(path string) *File

NewFile creates a new File.

type Options

type Options struct {
	// AppendNameToPath will, when attempting to copy a file to an existing directory, automatically
	// create the file with the same name in the destination directory.  While CP uses this behavior
	// by default it is an assumption better left to the client in a programmatic setting.
	AppendNameToPath bool
	// Atomic will copy contents to a temporary file in the destination's parent directory first, then
	// rename the file to ensure the operation is atomic.
	Atomic bool
	// Backup makes a backup of each existing destination file. The backup suffix is '~'. Acceptable
	// control values are:
	//   - "off"       no backup will be made (default)
	//   - "simple"    always make simple backups
	//   - "numbered"  make numbered backups
	//   - "existing"  numbered if numbered backups exist, simple otherwise
	Backup string
	// Link creates hard links to files instead of copying them.
	Link bool
	// MkdirAll will use os.MkdirAll to create the destination directory if it does not exist, along with
	// any necessary parents.
	MkdirAll bool

	// NoClobber will not let an existing file be overwritten.
	NoClobber bool
	// Parents will create source directories in dst if they do not already exist. ErrWithParentsDstMustBeDir
	// is returned if destination is not a directory.
	Parents bool
	// Recursive will recurse through sub directories if set true.
	Recursive bool
	// InfoLogFunc will, if defined, handle logging info messages.
	InfoLogFunc func(string)
	// DebugLogFunc will, if defined, handle logging debug messages.
	DebugLogFunc func(string)
	// contains filtered or unexported fields
}

Options directly represent command line flags associated with GNU file operations.