local

Documentation

Overview

Package local provides functions to operate local files and local file systems.

For better performance, all functions in this package are unsafe for concurrency unless otherwise specified.

Index

• Variables
• func HttpCustomDownload(req *http.Request, filename string, perm filesys.FileMode, ...) error
• func HttpCustomUpdate(req *http.Request, filename string, perm filesys.FileMode, ...) (updated bool, err error)
• func HttpDownload(url, filename string, perm filesys.FileMode, cs ...filesys.Checksum) error
• func HttpUpdate(url, filename string, perm filesys.FileMode, cs ...filesys.Checksum) (updated bool, err error)
• func Read(name string, opts *filesys.ReadOptions) (r filesys.Reader, err error)
• func Tmp(dir, prefix, suffix string, perm fs.FileMode) (f *os.File, err error)
• func TmpDir(dir, prefix, suffix string, perm fs.FileMode) (name string, err error)
• func VerifyChecksum(filename string, cs ...filesys.Checksum) bool
• type WriteOptions
• type Writer
  • func Write(name string, perm filesys.FileMode, opts *WriteOptions, copyTo ...io.Writer) (w Writer, err error)

Variables

var ErrPatternHasPathSeparator = errors.AutoNewCustom("pattern/prefix/suffix contains path separator",
	errors.PrependFullPkgName, 0)

ErrPatternHasPathSeparator is an error indicating that the pattern, prefix, or suffix contains a path separator.

var ErrVerificationFail = errors.AutoNewCustom("file verification failed",
	errors.PrependFullPkgName, 0)

ErrVerificationFail is an error indicating that the file verification failed.

Functions

func HttpCustomDownload

func HttpCustomDownload(req *http.Request, filename string, perm filesys.FileMode, cs ...filesys.Checksum) error

HttpCustomDownload downloads a file from the specified HTTP request req, and saves as a local file specified by filename, with specified permission perm.

The client can create the custom request req using function http.NewRequest.

This function will not create any directory. The client is responsible for creating necessary directories.

The client can specify checksums cs to verify the downloaded file. A damaged file will be removed and ErrVerificationFail will be returned.

It reports an error and downloads nothing if anyone of cs contains a nil HashGen or an empty HexExpSum.

func HttpCustomUpdate

func HttpCustomUpdate(req *http.Request, filename string, perm filesys.FileMode, cs ...filesys.Checksum) (updated bool, err error)

HttpCustomUpdate is the update mode of function HttpCustomDownload.

It verifies the file with specified filename using function VerifyChecksum. If the verification is passed, it does nothing and returns (false, nil). Otherwise, it calls function HttpCustomDownload to download the file.

It returns an indicator updated and any error encountered. updated is true if and only if this function has created or edited the file.

func HttpDownload

func HttpDownload(url, filename string, perm filesys.FileMode, cs ...filesys.Checksum) error

HttpDownload downloads a file from the specified URL via HTTP Get, and saves as a local file specified by filename, with specified permission perm.

This function will not create any directory. The client is responsible for creating necessary directories.

The client can specify checksums cs to verify the downloaded file. A damaged file will be removed and ErrVerificationFail will be returned.

It reports an error and downloads nothing if anyone of cs contains a nil HashGen or an empty HexExpSum.

func HttpUpdate

func HttpUpdate(url, filename string, perm filesys.FileMode, cs ...filesys.Checksum) (updated bool, err error)

HttpUpdate is the update mode of function HttpDownload.

It verifies the file with specified filename using function VerifyChecksum. If the verification is passed, it does nothing and returns (false, nil). Otherwise, it calls function HttpDownload to download the file.

It returns an indicator updated and any error encountered. updated is true if and only if this function has created or edited the file.

func Read

func Read(name string, opts *filesys.ReadOptions) (r filesys.Reader, err error)

Read opens a file with specified name for reading.

The file will be closed when closing the returned reader.

If the file is a symlink, it will be evaluated by filepath.EvalSymlinks.

The file is opened by os.Open; the associated file descriptor has mode syscall.O_RDONLY.

func Tmp

func Tmp(dir, prefix, suffix string, perm fs.FileMode) (f *os.File, err error)

Tmp creates and opens a new temporary file in the directory dir, with specified permission perm (before umask), for reading and writing.

The filename is generated by concatenating prefix, a random string, and suffix. Both prefix and suffix must not contains a path separator. If prefix or suffix contains a path separator, it returns a nil f and an error ErrPatternHasPathSeparator. (To test whether err is ErrPatternHasPathSeparator, use function errors.Is.)

If dir is empty, it will use the default directory for temporary files (as returned by os.TempDir) instead.

Calling this function simultaneously will not choose the same file.

The client can use f.Name() to find the path of the file. The client is responsible for removing the file when no longer needed.

func TmpDir

func TmpDir(dir, prefix, suffix string, perm fs.FileMode) (name string, err error)

TmpDir creates a new temporary directory in the directory dir, with specified permission perm (before umask), and returns the path of the new directory.

The new directory's name is generated by concatenating prefix, a random string, and suffix. Both prefix and suffix must not contains a path separator. If prefix or suffix contains a path separator, it returns an empty name and an error ErrPatternHasPathSeparator. (To test whether err is ErrPatternHasPathSeparator, use function errors.Is.)

If dir is empty, it will use the default directory for temporary files (as returned by os.TempDir) instead.

Calling this function simultaneously will not choose the same directory.

The client is responsible for removing the directory when no longer needed.

func VerifyChecksum

func VerifyChecksum(filename string, cs ...filesys.Checksum) bool

VerifyChecksum verifies a local file by checksum.

It returns true if and only if the file can be read and matches all checksums.

Note that it returns false if anyone of cs contains a nil HashGen or an empty HexExpSum. And it returns true if len(cs) is 0 and the file can be opened for reading.

Types

type WriteOptions

type WriteOptions struct {
	// Only take effect when the target file already exists.
	// If true, it will append data to the file.
	// Otherwise, it will truncate the file.
	Append bool

	// True if not to compress the file with gzip and not to archive the file
	// with tar (i.e., tape archive) according to the filename.
	Raw bool

	// Size of the buffer for writing the file at least.
	// Non-positive values for using default value.
	BufSize int

	// If true, a buffer will be created when open the file. Otherwise,
	// a buffer won't be created until calling methods that need a buffer.
	BufOpen bool

	// Let the writer write data to a temporary file. After calling method
	// Close, the writer move the temporary file to the target file. If any
	// error occurs during writing, the temporary file will be discarded, and
	// the original target file won't be changed.
	Backup bool

	// Only take effect when the option Backup is disabled.
	// Let the writer preserve the written file when encountering an error.
	// If false (the default), the written file will be removed
	// by the method Close if any error occurs during writing.
	PreserveOnFail bool

	// Make parent directories before creating the file.
	MkDirs bool

	// A verify function to report whether the data written to the file is
	// correct. The function will be called in our writer's method Close.
	// If the function returns true, our writer will finish writing.
	// Otherwise, our writer will return ErrVerificationFail, and discard
	// the file if Backup is true.
	VerifyFn func() bool

	// The compression level for GNU zip. Note that the zero value (0) stands
	// for no compression other than the default value. Remember setting it to
	// gzip.DefaultCompression if you want to use the default.
	GzipLv int
}

WriteOptions are options for function Write.

type Writer

type Writer interface {
	inout.Closer
	inout.BufferedWriter

	// TarEnabled returns true if the file is archived by tar
	// (i.e., tape archive) and is not opened in raw mode.
	TarEnabled() bool

	// TarWriteHeader writes hdr and prepares to accept the file's contents.
	//
	// The tar.Header.Size determines how many bytes can be written
	// for the next file.
	// If the current file is not fully written, it will return an error.
	// It implicitly flushes any padding necessary before writing the header.
	//
	// If the file is not archived by tar, or the file is opened in raw mode,
	// it does nothing and returns ErrNotTar.
	// (To test whether the error is ErrNotTar, use function errors.Is.)
	TarWriteHeader(hdr *tar.Header) error

	// Options returns a copy of options used by this writer.
	Options() *WriteOptions

	// Filename returns the filename as presented to function Write.
	Filename() string

	// TmpFilename returns the name of the temporary file created by
	// function Write if the option Backup enabled.
	// Otherwise, it returns an empty string.
	TmpFilename() string
}

Writer is a device to write data to a file.

Its method Close closes all closable objects opened by this writer, including the file, and processes the temporary file used by this writer. After successfully closing this writer, its method Close will do nothing and return nil.

The written file will be removed by its method Close if any error occurs during writing and the option PreserveOnFail is disabled.

func Write

func Write(name string, perm filesys.FileMode, opts *WriteOptions, copyTo ...io.Writer) (w Writer, err error)

Write creates (if necessary) and opens a file with specified name for writing.

If name is empty, it does nothing and returns an error. If opts is nil, it will use the default write options instead. The default write options are shown as follows:

Append: false,
Raw: false,
BufSize: 0,
BufOpen: false,
Backup: true,
MkDirs: true,
VerifyFn: nil,
GzipLv: gzip.DefaultCompression,

Data ultimately written to the file will also be written to copyTo. (Due to possible compression, data written to the file may be different from data provided to the writer when the option Raw is disabled.) The client can use copyTo to monitor the data, such as calculating the checksum to verify the file.

But note that: 1. The client is responsible for managing copyTo, including flushing or closing them after use. 2. If an error occurs when writing to copyTo, other writing will also stop and the writer will fall into the error state. 3. During one write operation, data will be written to the file first, and then to copyTo sequentially. If an error occurs when writing to copyTo, the data of current write operation has already been written to the file.

As for the write options, notice that when options Append and Backup are both enabled and the specified file already exists, this function will copy the specified file to a temporary file, which may cost a lot of time and space resource. Data copied from the specified file won't be written to copyTo.