gofile

README

gorepotemplate

Tricky and fun utilities for Go programs.

---

---

Getting Started

Prerequisites

• Go
• Git
• GitHub CLI

Developed with $( go version; ). Go is extremely backwards compatible and semver stable. Nearly any v1.x should work fine.

---

Installation

To use this repo as a template for your own project:

gh repo create -y --public --template "https://github.com/skeptycal/gorepotemplate"

Clone this repo to test and contribute:

# add repo to $GOPATH (xxxxxx is your computer login username)
go get github.com/xxxxxx/gorepotemplate

cd ${GOPATH}/src/github.com/xxxxxx/gorepotemplate

# test results and coverage info
./go.test.sh

# install as a utility package
go install

Use the Issues and PR templates on the GitHub repo page to contribute.

---

Basic Usage

This is a copy of the example script available in the cmd/example/gorepotemplate folder:

package main

import "github.com/skeptycal/gorepotemplate"

func main() {
    gorepotemplate.Example()
}

To try it out:

# change to the sample folder
cd cmd/example/gorepotemplate

# run the main.go program
go run ./main.go

# to compile as an executable
go build

---

Code of Conduct and Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us. Please read the Code of Conduct for details before submitting anything.

---

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

---

Contributors and Inspiration

• Michael Treanor (GitHub / Twitter) - Initial work, updates, maintainer
• Francesc Campoy - Inspiration and great YouTube videos!

See also the list of contributors who participated in this project.

---

License

Licensed under the MIT https://opensource.org/licenses/MIT - see the LICENSE file for details.

Documentation

Overview

Package gofile provides support for file operations.

Package fs defines basic interfaces to a file system. A file system can be provided by the host operating system but also by other packages.

Index

• Constants
• Variables
• func Copy(src, dest string) (int64, error)
• func CopyBuffer(src, dst string, buffersize int) (written int64, err error)
• func CopyUtil(src, dst string) (written int64, err error)
• func Create(name string) (io.ReadWriteCloser, error)
• func CreateSafe(name string) (io.ReadWriteCloser, error)
• func InitialCapacity(capacity int64) int
• func IsDir(name string) bool
• func IsRegular(name string) bool
• func Mode(file string) os.FileMode
• func PWD() string
• func Stat(filename string) (os.FileInfo, error)
• func StatCheck(filename string) (os.FileInfo, error)
• type BasicFile
  • func NewFile(providedName string) (BasicFile, error)
  • func Open(name string) (BasicFile, error)
• type DIR
• type DataFile
• type DirEntry
• type FS
• type File
• type FileInfo
• type FileMode
• type FileModer
• type FileOps
• type GoFile
• type GoFileError
• type PathError
  • func NewGoFileError(op, path string, err error) *PathError
  • func NewPathError(op, path string, err error) *PathError
• type ReadDirFile
• type ReadWriteCloser
• type ReadWriterAt
• type Seeker
• type SortType
  • func (s SortType) String() string
• type StringWriter
• type TimeZone
  • func (tz TimeZone) String() string
• type ToFrom

Constants

const (
	NormalMode        os.FileMode = 0644
	DirMode           os.FileMode = 0755
	MinBufferSize                 = 16
	SmallBufferSize               = 64
	Chunk                         = 512
	DefaultBufferSize             = 1024
	DefaultBufSize                = 4096
	MaxInt                        = int(^uint(0) >> 1)
	MinRead                       = bytes.MinRead
)

const (
	PathSep = os.PathSeparator
	ListSep = os.PathListSeparator
	NewLine = '\n'
)

Variables

var (
	// Log is the default global ErrorLogger. It implements the ErrorLogger interface as well as the logrus.Logger interface, which is compatible with the standard library "log" package gofile
	Log = el.Log

	// Err is the logging function for the global ErrorLogger.
	Err = el.Err
)

errorlogger implements error logging to a logrus log by default. It is completely compatible with the standard library 'log' logger API. It provides an efficient and convenient way to log errors with minimal overhead and to temporarily disable or enable logging.

A global Log and Err with default behaviors are supplied that may be aliased if you wish:

Log = errorlogger.Log // implements the ErrorLogger interface
Err = errorlogger.Err // trigger function

ErrorLogger is:

 type ErrorLogger interface {
	 Disable()
	 Enable()
	 Err(err error) error
	 SetLoggerFunc(fn func(args ...interface{}))

	// SetErrorType allows ErrorLogger to wrap errors in a
	// specified custom type. For example, if you want all errors
 // returned to be of type *os.PathError
	 SetErrorType(errType error)
}

var (
	FSErr             = errorlogger.Err
	ErrNoAlloc        = errors.New("failed to allocate memory for file")
	ErrNotImplemented = errors.New("not implemented")
	ErrClosed         = fs.ErrClosed
	ErrInvalid        = fs.ErrInvalid
	ErrPermission     = fs.ErrPermission
	ErrExist          = fs.ErrExist
	ErrNotExist       = fs.ErrNotExist
)

var SameFile = os.SameFile

SameFile reports whether fi1 and fi2 describe the same file. For example, on Unix this means that the device and inode fields of the two underlying structures are identical; on other systems the decision may be based on the path names. SameFile only applies to results returned by this package gofile It returns false in other cases.

Functions

func Copy

func Copy(src, dest string) (int64, error)

func CopyBuffer

func CopyBuffer(src, dst string, buffersize int) (written int64, err error)

func CopyUtil

func CopyUtil(src, dst string) (written int64, err error)

func Create

func Create(name string) (io.ReadWriteCloser, error)

Create creates or truncates the named file and returns an opened file as io.ReadWriteCloser.

If the file already exists, it is truncated. If the file does not exist, it is created with mode 0644 (before umask). If successful, methods on the returned File can be used for I/O; the associated file descriptor has mode O_RDWR.

If there is an error, it will be of type *PathError.

func CreateSafe

func CreateSafe(name string) (io.ReadWriteCloser, error)

CreateSafe creates the named file and returns an opened file as io.ReadWriteCloser.

If the file already exists, an error is returned. If the file does not exist, it is created with mode 0644 (before umask). If successful, methods on the returned File can be used for I/O; the associated file descriptor has mode O_RDWR.

If there is an error, it will be of type *PathError.

func InitialCapacity

func InitialCapacity(capacity int64) int

InitialCapacity returns the multiple of 'chunk' one more than needed to accomodate the given capacity.

func IsDir

func IsDir(name string) bool

func IsRegular

func IsRegular(name string) bool

func Mode

func Mode(file string) os.FileMode

Mode returns the filemode of file.

func PWD

func PWD() string

PWD returns a rooted path name corresponding to the current directory. If the current directory can be reached via multiple paths (due to symbolic links), PWD may return any one of them.

If an error occurs, the empty string is returned and the error is logged.

func Stat

func Stat(filename string) (os.FileInfo, error)

Stat returns the os.FileInfo for file if it exists. If the file does not exist, or is not a regular file, nil is returned.

Errors are logged if Err is active.

func StatCheck

func StatCheck(filename string) (os.FileInfo, error)

StatCheck returns file information (after symlink evaluation) using os.Stat(). If the file does not exist, is not a regular file, or if the user lacks adequate permissions, an error is returned.

Types

type BasicFile

type BasicFile = interface {
	File() (f *os.File, err error)

	// Implements fs.File interface:
	Stat() (fs.FileInfo, error)
	io.ReadCloser

	// Implements fs.FileInfo interface:
	Name() string       // base name of the file
	Size() int64        // length in bytes for regular files;
	Mode() FileMode     // file mode bits
	ModTime() time.Time // modification time
	IsDir() bool        // is a directory?
	Sys() interface{}   // underlying data source (can return nil)

	// Additional basic methods:
	IsRegular() bool // is a regular file?
	Abs() string     // absolute path of the file
	String() string  // human-readable representation of the file

}

using File, FileInfo, and FileModer interfaces

Minimum required to implement fs.File interface:

type File interface {
   Stat() (fs.FileInfo, error)
   Read([]byte) (int, error)
   Close() error
}

Implements fs.FileInfo interface:

	// A FileInfo describes a file and is returned by Stat.
 type FileInfo interface {
 	Name() string       // base name of the file
	Size() int64        // length in bytes for regular files; sy stem-dependent for others
 	Mode() FileMode     // file mode bits
 	ModTime() time.Time // modification time
 	IsDir() bool        // abbreviation for Mode().IsDir()
 	Sys() interface{}   // underlying data source (can return nil)
 }

func NewFile

func NewFile(providedName string) (BasicFile, error)

func Open

func Open(name string) (BasicFile, error)

Open opens the named file for reading as an in memory object. If successful, methods on the returned file can be used for reading; the associated file descriptor has mode O_RDONLY. If there is an error, it will be of type *os.PathError.

type DIR

type DIR interface {
	Len() int
	Path() string
	List() ([]DataFile, error)
	SetOpts(opts dirOpts)
}

type DataFile

type DataFile = BasicFile // todo - finish DataFile implementation

type DirEntry

type DirEntry = fs.DirEntry

A DirEntry is an entry read from a directory (using the ReadDir function or a ReadDirFile's ReadDir method).

type DirEntry interface {
	// Name returns the name of the file (or subdirectory) described by the entry.
	// This name is only the final element of the path (the base name), not the entire path.
	// For example, Name would return "hello.go" not "/home/gopher/hello.go".
	Name() string

 	// IsDir reports whether the entry describes a directory.
	IsDir() bool

 	// Type returns the type bits for the entry.
	// The type bits are a subset of the usual FileMode bits, those returned by the FileMode.Type method.
	Type() FileMode

 	// Info returns the FileInfo for the file or subdirectory described by the entry.
	// The returned FileInfo may be from the time of the original directory read
	// or from the time of the call to Info. If the file has been removed or renamed
	// since the directory read, Info may return an error satisfying errors.Is(err, ErrNotExist).
	// If the entry denotes a symbolic link, Info reports the information about the link itself,
	// not the link's target.
	Info() (FileInfo, error)
}

Reference: standard library fs.go

type FS

type FS = fs.FS

An FS provides access to a hierarchical file system.

The FS interface is the minimum implementation required of the file system. A file system may implement additional interfaces, such as ReadFileFS, to provide additional or optimized functionality.

type FS interface {
	// Open opens the named file.
	//
	// When Open returns an error, it should be of type *PathError
	// with the Op field set to "open", the Path field set to name,
	// and the Err field describing the problem.
	//
	// Open should reject attempts to open names that do not satisfy
	// ValidPath(name), returning a *PathError with Err set to
	// ErrInvalid or ErrNotExist.
	Open(name string) (File, error)
}

Reference: standard library fs.go

type File

type File = fs.File

A File provides access to a single file. The File interface is the minimum implementation required of the file. A file may implement additional interfaces, such as ReadDirFile, ReaderAt, or Seeker, to provide additional or optimized functionality.

type File interface {
	Stat() (fs.FileInfo, error)
	Read([]byte) (int, error)
	Close() error
}

Reference: standard library fs.go

type FileInfo

type FileInfo = fs.FileInfo

A FileInfo describes a file and is returned by Stat.

type FileInfo interface {
	Name() string       // base name of the file
	Size() int64        // length in bytes for regular files; system-dependent for others
	Mode() FileMode     // file mode bits
	ModTime() time.Time // modification time
	IsDir() bool        // abbreviation for Mode().IsDir()
	Sys() interface{}   // underlying data source (can return nil)
}

Reference: standard library fs.go

type FileMode

type FileMode = fs.FileMode

A FileMode represents a file's mode and permission bits. The bits have the same definition on all systems, so that information about files can be moved from one system to another portably. Not all bits apply to all systems. The only required bit is ModeDir for directories.

type FileMode uint32

Reference: standard library fs.go

type FileModer

type FileModer interface {
	String() string
	IsDir() bool
	IsRegular() bool
	Perm() FileMode
	Type() FileMode
}

FileModer implements fs.FileMode functionality ... yes, I hate the name, too

type FileOps

type FileOps interface {
	Chmod(mode os.FileMode) error
	Move(path string) error
	Abs() (string, error)
	Split(path string) (dir, file string)
	Base(path string) string
	Dir(path string) string
	Ext(path string) string
}

type GoFile

type GoFile interface {
	ReadWriteCloser
	ToFrom

	Name() string
	Open(name string) (http.File, error)
	Readdir(count int) ([]os.FileInfo, error)
	Stat() (os.FileInfo, error)
}

type GoFileError

type GoFileError = os.PathError

type PathError

type PathError = os.PathError

func NewGoFileError

func NewGoFileError(op, path string, err error) *PathError

NewPathError records an error and the operation / path involved. The error will be of type *os.PathError

type PathError struct {
	Op   string
	Path string
	Err  error
}

func NewPathError

func NewPathError(op, path string, err error) *PathError

NewPathError records an error and the operation / path involved. The error will be of type *os.PathError

type PathError struct {
	Op   string
	Path string
	Err  error
}

type ReadDirFile

type ReadDirFile = fs.ReadDirFile

A ReadDirFile is a directory file whose entries can be read with the ReadDir method. Every directory file should implement this interface. (It is permissible for any file to implement this interface, but if so ReadDir should return an error for non-directories.)

  type ReadDirFile interface {
  	File
		// ReadDir reads the contents of the directory and returns
		// a slice of up to n DirEntry values in directory order.
		// Subsequent calls on the same file will yield further DirEntry values.
		//
		// If n > 0, ReadDir returns at most n DirEntry structures.
		// In this case, if ReadDir returns an empty slice, it will return
		// a non-nil error explaining why.
		// At the end of a directory, the error is io.EOF.
		//
		// If n <= 0, ReadDir returns all the DirEntry values from the directory
		// in a single slice. In this case, if ReadDir succeeds (reads all the way
		// to the end of the directory), it returns the slice and a nil error.
		// If it encounters an error before the end of the directory,
		// ReadDir returns the DirEntry list read until that point and a non-nil error.
  	ReadDir(n int) ([]DirEntry, error)
  }

Reference: standard library fs.go

type ReadWriteCloser

type ReadWriteCloser interface {
	Read(p []byte) (n int, err error)
	Write(p []byte) (n int, err error)
	Close() error
}

type ReadWriterAt

type ReadWriterAt interface {
	// ReaderAt is the interface that wraps the basic ReadAt method.
	//
	// ReadAt reads len(p) bytes into p starting at offset off in the
	// underlying input source. It returns the number of bytes
	// read (0 <= n <= len(p)) and any error encountered.
	//
	// When ReadAt returns n < len(p), it returns a non-nil error
	// explaining why more bytes were not returned. In this respect,
	// ReadAt is stricter than Read.
	//
	// Even if ReadAt returns n < len(p), it may use all of p as scratch
	// space during the call. If some data is available but not len(p) bytes,
	// ReadAt blocks until either all the data is available or an error occurs.
	// In this respect ReadAt is different from Read.
	//
	// If the n = len(p) bytes returned by ReadAt are at the end of the
	// input source, ReadAt may return either err == EOF or err == nil.
	//
	// If ReadAt is reading from an input source with a seek offset,
	// ReadAt should not affect nor be affected by the underlying
	// seek offset.
	//
	// Clients of ReadAt can execute parallel ReadAt calls on the
	// same input source.
	//
	// Implementations must not retain p.
	ReadAt(p []byte, off int64) (n int, err error)

	// WriterAt is the interface that wraps the basic WriteAt method.
	//
	// WriteAt writes len(p) bytes from p to the underlying data stream
	// at offset off. It returns the number of bytes written from p (0 <= n <= len(p))
	// and any error encountered that caused the write to stop early.
	// WriteAt must return a non-nil error if it returns n < len(p).
	//
	// If WriteAt is writing to a destination with a seek offset,
	// WriteAt should not affect nor be affected by the underlying
	// seek offset.
	//
	// Clients of WriteAt can execute parallel WriteAt calls on the same
	// destination if the ranges do not overlap.
	//
	// Implementations must not retain p.
	WriteAt(p []byte, off int64) (n int, err error)
}

ReadWriteAt implements io.ReaderAt and io.WriterAt for concurrent, non-overlapping reads and writes.

type Seeker

type Seeker interface {
	Seek(offset int64, whence int) (int64, error)
}

type SortType

type SortType int

SortType is a list of constants representing sort methods for directory listings.

const (
	Alpha SortType = iota + 1
	Size
	Version
	Extension
	Atime
	Ctime
)

func (SortType) String

func (s SortType) String() string

type StringWriter

type StringWriter interface {
	ReadWriteCloser
	io.StringWriter
}

type TimeZone

type TimeZone int

const (
	EST TimeZone = -(5 + iota)
	CST
	MST
	PST
)

American Time Zones

func (TimeZone) String

func (tz TimeZone) String() string

type ToFrom

type ToFrom interface {
	io.ReaderFrom
	io.WriterTo
}