Documentation
¶
Overview ¶
Package file provides functions to operate files.
Index ¶
- Variables
- func HttpCustomDownload(req *http.Request, filename string, perm os.FileMode, cs ...Checksum) error
- func HttpCustomUpdate(req *http.Request, filename string, perm os.FileMode, cs ...Checksum) (updated bool, err error)
- func HttpDownload(url, filename string, perm os.FileMode, cs ...Checksum) error
- func HttpUpdate(url, filename string, perm os.FileMode, cs ...Checksum) (updated bool, err error)
- func Tmp(dir, prefix, suffix string, perm os.FileMode) (f *os.File, err error)
- func TmpDir(dir, prefix, suffix string, perm os.FileMode) (name string, err error)
- func VerifyChecksum(filename string, cs ...Checksum) bool
- type Checksum
- type ReadOptions
- type Reader
- type WriteOptions
- type Writer
Constants ¶
This section is empty.
Variables ¶
var ErrNotTar = errors.AutoNewWithStrategy("file is not archived by tar, or is opened in raw mode", errors.PrefixFullPkgName, 0)
ErrNotTar is an error indicating that the file is not archived by tar, or is opened in raw mode.
The client should use errors.Is to test whether an error is ErrNotTar.
var ErrPatternHasPathSeparator = errors.AutoNewWithStrategy("pattern/prefix/suffix contains path separator", errors.PrefixFullPkgName, 0)
ErrPatternHasPathSeparator is an error indicating that the pattern, prefix, or suffix contains a path separator.
var ErrVerificationFail = errors.AutoNewWithStrategy("file verification failed", errors.PrefixFullPkgName, 0)
ErrVerificationFail is an error indicating that the file verification failed.
Functions ¶
func HttpCustomDownload ¶ added in v0.2.0
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 ¶ added in v0.2.0
func HttpCustomUpdate(req *http.Request, filename string, perm os.FileMode, cs ...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 ¶ added in v0.1.7
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 ¶ added in v0.2.0
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 Tmp ¶ added in v0.1.7
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 ¶ added in v0.1.7
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 ¶ added in v0.2.0
VerifyChecksum verifies a 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 Checksum ¶ added in v0.1.7
type Checksum struct {
// A function to generate a hash function. E.g. crypto/sha256.New.
HashGen func() hash.Hash
// Expected checksum, in hexadecimal representation.
HexExpSum string
}
Checksum is a combination of a hash function generator and an expected checksum.
type ReadOptions ¶ added in v0.2.0
type ReadOptions struct {
// Offset of the file to read, in bytes,
// relative to the origin of the file for positive values,
// and relative to the end of the file for negative values.
Offset int64
// Limit of the file to read, in bytes. Non-positive values for no limit.
Limit int64
// True if not to decompress when the file is compressed by gzip or bzip2,
// and not to restore when the file is archived by tar (i.e., tape archive).
Raw bool
// Size of the buffer for reading 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
}
ReadOptions are options for function Read.
type Reader ¶
type Reader interface {
myio.Closer
myio.BufferedReader
// TarEnabled returns true if the file is archived by tar
// (i.e., tape archive) and is not opened in raw mode.
TarEnabled() bool
// TarNext advances to the next entry in the tar archive.
//
// The tar.Header.Size determines how many bytes can be read
// for the next file.
// Any remaining data in current file is automatically discarded.
//
// io.EOF is returned at the end of the input.
//
// 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 err is ErrNotTar, use function errors.Is.)
TarNext() (header *tar.Header, err error)
// Options returns a copy of options used by this reader.
Options() *ReadOptions
// Filename returns the filename as presented to function Read.
Filename() string
// FileInfo returns the information of the file.
FileInfo() (info os.FileInfo, err error)
}
Reader is a device to read data from a file.
Its method Close closes all closable objects opened by this reader, including the file. After successfully closing this reader, its method Close will do nothing and return nil.
func Read ¶ added in v0.1.7
func Read(name string, options *ReadOptions) (r Reader, err error)
Read opens a file with specified name for reading.
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.
type WriteOptions ¶ added in v0.2.0
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 ¶ added in v0.1.7
type Writer interface {
myio.Closer
myio.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 ¶ added in v0.2.0
func Write(name string, perm os.FileMode, options *WriteOptions, copies ...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 options 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 copies. (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 copies to monitor the data, such as calculating the checksum to verify the file.
But note that: 1. The client is responsible for managing copies, including flushing or closing them after use. 2. If an error occurs when writing to copies, 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 copies sequentially. If an error occurs when writing to copies, 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 copies.
Source Files