archiver

package module
v3.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 27, 2021 License: Apache-2.0 Imports: 25 Imported by: 4

Documentation

Overview

Package archiver facilitates convenient, cross-platform, high-level archival and compression operations for a variety of formats and compression algorithms.

This package and its dependencies are written in pure Go (not cgo) and have no external dependencies, so they should run on all major platforms. (It also comes with a command for CLI use in the cmd/arc folder.)

Each supported format or algorithm has a unique type definition that implements the interfaces corresponding to the tasks they perform. For example, the Tar type implements Reader, Writer, Archiver, Unarchiver, Walker, and several other interfaces.

The most common functions are implemented at the package level for convenience: Archive, Unarchive, Walk, Extract, CompressFile, and DecompressFile. With these, the format type is chosen implicitly, and a sane default configuration is used.

To customize a format's configuration, create an instance of its struct with its fields set to the desired values. You can also use and customize the handy Default* (replace the wildcard with the format's type name) for a quick, one-off instance of the format's type.

To obtain a new instance of a format's struct with the default config, use the provided New*() functions. This is not required, however. An empty struct of any type, for example &Zip{} is perfectly valid, so you may create the structs manually, too. The examples on this page show how either may be done.

See the examples in this package for an idea of how to wield this package for common tasks. Most of the examples which are specific to a certain format type, for example Zip, can be applied to other types that implement the same interfaces. For example, using Zip is very similar to using Tar or TarGz (etc), and using Gz is very similar to using Sz or Xz (etc).

When creating archives or compressing files using a specific instance of the format's type, the name of the output file MUST match that of the format, to prevent confusion later on. If you absolutely need a different file extension, you may rename the file afterward.

Values in this package are NOT safe for concurrent use. There is no performance benefit of reusing them, and since they may contain important state (especially while walking, reading, or writing), it is NOT recommended to reuse values from this package or change their configuration after they are in use.

Index

Examples

Constants

This section is empty.

Variables

View Source 
var DefaultBrotli = NewBrotli()

DefaultBrotli is a default instance that is conveniently ready to use.

View Source 
var DefaultBz2 = NewBz2()

DefaultBz2 is a default instance that is conveniently ready to use.

View Source 
var DefaultGz = NewGz()

DefaultGz is a default instance that is conveniently ready to use.

View Source 
var DefaultLz4 = NewLz4()

DefaultLz4 is a default instance that is conveniently ready to use.

View Source 
var DefaultRar = NewRar()

DefaultRar is a default instance that is conveniently ready to use.

View Source 
var DefaultSnappy = NewSnappy()

DefaultSnappy is a default instance that is conveniently ready to use.

View Source 
var DefaultTar = NewTar()

DefaultTar is a default instance that is conveniently ready to use.

View Source 
var DefaultTarBrotli = NewTarBrotli()

DefaultTarBrotli is a convenient archiver ready to use.

View Source 
var DefaultTarBz2 = NewTarBz2()

DefaultTarBz2 is a convenient archiver ready to use.

View Source 
var DefaultTarGz = NewTarGz()

DefaultTarGz is a convenient archiver ready to use.

View Source 
var DefaultTarLz4 = NewTarLz4()

DefaultTarLz4 is a convenient archiver ready to use.

View Source 
var DefaultTarSz = NewTarSz()

DefaultTarSz is a convenient archiver ready to use.

View Source 
var DefaultTarXz = NewTarXz()

DefaultTarXz is a convenient archiver ready to use.

View Source 
var DefaultTarZstd = NewTarZstd()

DefaultTarZstd is a convenient archiver ready to use.

View Source 
var DefaultXz = NewXz()

DefaultXz is a default instance that is conveniently ready to use.

View Source 
var DefaultZip = NewZip()

DefaultZip is a default instance that is conveniently ready to use.

View Source 
var DefaultZstd = NewZstd()

DefaultZstd is a default instance that is conveniently ready to use.

View Source 
var ErrFormatNotRecognized = fmt.Errorf("format not recognized")

ErrFormatNotRecognized is an error that will be returned if the file is not a valid archive format.

View Source 
var ErrStopWalk = fmt.Errorf("walk stopped")

ErrStopWalk signals Walk to break without error.

Functions

func Archive 

func Archive(sources []string, destination string) error

Archive creates an archive of the source files to a new file at destination. The archive format is chosen implicitly by file extension.

Example

The simplest use of this package: create an archive file from a list of filenames. This is the recommended way to do so using a default configuration, as it guarantees the file format matches the file extension, because the format to write is determined by the given extension. 

// any files in this list are added
// to the top level of the archive;
// directories are recursively added
files := []string{
	"index.html",
	"photo.jpg",
	"blog", // directory
	"/home/website/copyright.txt",
}

// archive format is determined by file extension
err := Archive(files, "blog_site.zip")
if err != nil {
	log.Fatal(err)
}

Output:

func ByExtension 

func ByExtension(filename string) (interface{}, error)

ByExtension returns an archiver and unarchiver, or compressor and decompressor, based on the extension of the filename.

func CompressFile 

func CompressFile(source, destination string) error

CompressFile is a convenience function to simply compress a file. The compression algorithm is selected implicitly based on the destination's extension.

Example

This example compresses a standard tar file into a tar.gz file. Compression formats are selected by file extension. 

err := CompressFile("example.tar", "example.tar.gz")
if err != nil {
	log.Fatal(err)
}

Output:
Example (Custom)

This example changes the default configuration for the Gz compression format. 

DefaultGz.CompressionLevel = 5
// any calls to DefaultGz now use the modified configuration

Output:

func DecompressFile 

func DecompressFile(source, destination string) error

DecompressFile is a convenience function to simply decompress a file. The decompression algorithm is selected implicitly based on the source's extension.

Example

This example decompresses a gzipped tarball and writes it to an adjacent file. 

err := DecompressFile("example.tar.gz", "example.tar")
if err != nil {
	log.Fatal(err)
}

Output:

func Extract 

func Extract(source, target, destination string) error

Extract extracts a single file from the given source archive. If the target is a directory, the entire folder will be extracted into destination. The archive format is chosen implicitly.

Example

This example extracts target.txt from inside example.rar and puts it into a folder on disk called output/dir. 

err := Extract("example.rar", "target.txt", "output/dir")
if err != nil {
	log.Fatal(err)
}

Output:

func IsIllegalPathError 

func IsIllegalPathError(err error) bool

IsIllegalPathError returns true if the provided error is of the type IllegalPathError.

func NameInArchive 

func NameInArchive(sourceInfo os.FileInfo, source, fpath string) (string, error)

NameInArchive returns a name for the file at fpath suitable for the inside of an archive. The source and its associated sourceInfo is the path where walking a directory started, and if no directory was walked, source may == fpath. The returned name is essentially the components of the path between source and fpath, preserving the internal directory structure.

func Unarchive 

func Unarchive(source, destination string) error

Unarchive unarchives the given archive file into the destination folder. The archive format is selected implicitly.

Example

The simplest use of this package: extract all of an archive's contents to a folder on disk using the default configuration. The archive format is determined automatically. 

err := Unarchive("blog_site.zip", "extracted/mysite")
if err != nil {
	log.Fatal(err)
}

Output:

func Walk 

func Walk(archive string, walkFn WalkFunc) error

Walk calls walkFn for each file within the given archive file. The archive format is chosen implicitly.

Example

It's easy to list the items in an archive. This example prints the name and size of each file in the archive. Like other top-level functions in this package, the format is inferred automatically for you. 

err := Walk("example.tar.gz", func(f File) error {
	fmt.Println(f.Name(), f.Size())
	// you could also read the contents; f is an io.Reader!
	return nil
})
if err != nil {
	log.Fatal(err)
}

Output:

Types

type Archiver 

type Archiver interface {
	ExtensionChecker

	// Archive adds all the files or folders in sources
	// to an archive to be created at destination. Files
	// are added to the root of the archive, and directories
	// are walked and recursively added, preserving folder
	// structure.
	Archive(sources []string, destination string) error
}

Archiver is a type that can create an archive file from a list of source file names.

type Brotli 

type Brotli struct {
	Quality int
}

Brotli facilitates brotli compression.

func NewBrotli 

func NewBrotli() *Brotli

NewBrotli returns a new, default instance ready to be customized and used.

func (*Brotli) CheckExt 

func (br *Brotli) CheckExt(filename string) error

CheckExt ensures the file extension matches the format.

func (*Brotli) Compress 

func (br *Brotli) Compress(in io.Reader, out io.Writer) error

Compress reads in, compresses it, and writes it to out.

func (*Brotli) Decompress 

func (br *Brotli) Decompress(in io.Reader, out io.Writer) error

Decompress reads in, decompresses it, and writes it to out.

func (*Brotli) String 

func (br *Brotli) String() string

type Bz2 

type Bz2 struct {
	CompressionLevel int
}

Bz2 facilitates bzip2 compression.

func NewBz2 

func NewBz2() *Bz2

NewBz2 returns a new, default instance ready to be customized and used.

func (*Bz2) CheckExt 

func (bz *Bz2) CheckExt(filename string) error

CheckExt ensures the file extension matches the format.

func (*Bz2) Compress 

func (bz *Bz2) Compress(in io.Reader, out io.Writer) error

Compress reads in, compresses it, and writes it to out.

func (*Bz2) Decompress 

func (bz *Bz2) Decompress(in io.Reader, out io.Writer) error

Decompress reads in, decompresses it, and writes it to out.

func (*Bz2) String 

func (bz *Bz2) String() string

type Compressor 

type Compressor interface {
	ExtensionChecker
	Compress(in io.Reader, out io.Writer) error
}

Compressor compresses to out what it reads from in. It also ensures a compatible or matching file extension.

type Decompressor 

type Decompressor interface {
	Decompress(in io.Reader, out io.Writer) error
}

Decompressor decompresses to out what it reads from in.

type ExtensionChecker 

type ExtensionChecker interface {
	CheckExt(name string) error
}

ExtensionChecker validates file extensions

type Extractor 

type Extractor interface {
	Extract(source, target, destination string) error
}

Extractor can extract a specific file from a source archive to a specific destination folder on disk.

type File 

type File struct {
	os.FileInfo

	// OriginalPath is the original full path to file
	OriginalPath string

	// The original header info; depends on
	// type of archive -- could be nil, too.
	Header interface{}

	// Allow the file contents to be read (and closed)
	io.ReadCloser
}

File provides methods for accessing information about or contents of a file within an archive.

type FileCompressor 

type FileCompressor struct {
	Compressor
	Decompressor

	// Whether to overwrite existing files when creating files.
	OverwriteExisting bool
}

FileCompressor can compress and decompress single files.

func (FileCompressor) CompressFile 

func (fc FileCompressor) CompressFile(source, destination string) error

CompressFile reads the source file and compresses it to destination. The destination must have a matching extension.

func (FileCompressor) DecompressFile 

func (fc FileCompressor) DecompressFile(source, destination string) error

DecompressFile reads the source file and decompresses it to destination.

type FileInfo 

type FileInfo struct {
	os.FileInfo
	CustomName string
}

FileInfo is an os.FileInfo but optionally with a custom name, useful if dealing with files that are not actual files on disk, or which have a different name in an archive than on disk.

func (FileInfo) Name 

func (fi FileInfo) Name() string

Name returns fi.CustomName if not empty; otherwise it returns fi.FileInfo.Name().

type FilenameChecker 

type FilenameChecker interface {
	CheckPath(to, filename string) error
}

FilenameChecker validates filenames to prevent path traversal attacks

type Gz 

type Gz struct {
	CompressionLevel int
	SingleThreaded   bool
}

Gz facilitates gzip compression.

func NewGz 

func NewGz() *Gz

NewGz returns a new, default instance ready to be customized and used.

func (*Gz) CheckExt 

func (gz *Gz) CheckExt(filename string) error

CheckExt ensures the file extension matches the format.

func (*Gz) Compress 

func (gz *Gz) Compress(in io.Reader, out io.Writer) error

Compress reads in, compresses it, and writes it to out.

Example (Custom)

This example creates a new Gz instance and uses it to compress a stream, writing to another stream. This is sometimes preferable over modifying the DefaultGz. 

gz := &Gz{CompressionLevel: 5}
err := gz.Compress(os.Stdin, os.Stdout)
if err != nil {
	log.Fatal(err)
}

Output:

func (*Gz) Decompress 

func (gz *Gz) Decompress(in io.Reader, out io.Writer) error

Decompress reads in, decompresses it, and writes it to out.

func (*Gz) String 

func (gz *Gz) String() string

type IllegalPathError 

type IllegalPathError struct {
	AbsolutePath string
	Filename     string
}

IllegalPathError is an error returned when an illegal path is detected during the archival process.

By default, only the Filename is showed on error, but you might also get the absolute value of the invalid path on the AbsolutePath field.

func (*IllegalPathError) Error 

func (err *IllegalPathError) Error() string

type Lz4 

type Lz4 struct {
	CompressionLevel int
}

Lz4 facilitates LZ4 compression.

func NewLz4 

func NewLz4() *Lz4

NewLz4 returns a new, default instance ready to be customized and used.

func (*Lz4) CheckExt 

func (lz *Lz4) CheckExt(filename string) error

CheckExt ensures the file extension matches the format.

func (*Lz4) Compress 

func (lz *Lz4) Compress(in io.Reader, out io.Writer) error

Compress reads in, compresses it, and writes it to out.

func (*Lz4) Decompress 

func (lz *Lz4) Decompress(in io.Reader, out io.Writer) error

Decompress reads in, decompresses it, and writes it to out.

func (*Lz4) String 

func (lz *Lz4) String() string

type Matcher 

type Matcher interface {
	Match(io.ReadSeeker) (bool, error)
}

Matcher is a type that can return whether the given file appears to match the implementation's format. Implementations should return the file's read position to where it was when the method was called.

type Rar 

type Rar struct {
	// Whether to overwrite existing files; if false,
	// an error is returned if the file exists.
	OverwriteExisting bool

	// Whether to make all the directories necessary
	// to create a rar archive in the desired path.
	MkdirAll bool

	// A single top-level folder can be implicitly
	// created by the Unarchive method if the files
	// to be extracted from the archive do not all
	// have a common root. This roughly mimics the
	// behavior of archival tools integrated into OS
	// file browsers which create a subfolder to
	// avoid unexpectedly littering the destination
	// folder with potentially many files, causing a
	// problematic cleanup/organization situation.
	// This feature is available for both creation
	// and extraction of archives, but may be slightly
	// inefficient with lots and lots of files,
	// especially on extraction.
	ImplicitTopLevelFolder bool

	// Strip number of leading paths. This feature is available
	// only during unpacking of the entire archive.
	StripComponents int

	// If true, errors encountered during reading
	// or writing a single file will be logged and
	// the operation will continue on remaining files.
	ContinueOnError bool

	// The password to open archives (optional).
	Password string
	// contains filtered or unexported fields
}

Rar provides facilities for reading RAR archives. See https://www.rarlab.com/technote.htm.

func NewRar 

func NewRar() *Rar

NewRar returns a new, default instance ready to be customized and used.

func (*Rar) CheckExt 

func (*Rar) CheckExt(filename string) error

CheckExt ensures the file extension matches the format.

func (*Rar) CheckPath 

func (*Rar) CheckPath(to, filename string) error

CheckPath ensures that the filename has not been crafted to perform path traversal attacks

func (*Rar) Close 

func (r *Rar) Close() error

Close closes the rar archive(s) opened by Create and Open.

func (*Rar) Extract 

func (r *Rar) Extract(source, target, destination string) error

Extract extracts a single file from the rar archive. If the target is a directory, the entire folder will be extracted into destination.

func (*Rar) Match 

func (*Rar) Match(file io.ReadSeeker) (bool, error)

Match returns true if the format of file matches this type's format. It should not affect reader position.

func (*Rar) Open 

func (r *Rar) Open(in io.Reader, size int64) error

Open opens t for reading an archive from in. The size parameter is not used.

func (*Rar) OpenFile 

func (r *Rar) OpenFile(filename string) error

OpenFile opens filename for reading. This method supports multi-volume archives, whereas Open does not (but Open supports any stream, not just files).

func (*Rar) Read 

func (r *Rar) Read() (File, error)

Read reads the next file from t, which must have already been opened for reading. If there are no more files, the error is io.EOF. The File must be closed when finished reading from it.

func (*Rar) String 

func (r *Rar) String() string

func (*Rar) Unarchive 

func (r *Rar) Unarchive(source, destination string) error

Unarchive unpacks the .rar file at source to destination. Destination will be treated as a folder name. It supports multi-volume archives.

func (*Rar) Walk 

func (r *Rar) Walk(archive string, walkFn WalkFunc) error

Walk calls walkFn for each visited item in archive.

type ReadFakeCloser 

type ReadFakeCloser struct {
	io.Reader
}

ReadFakeCloser is an io.Reader that has a no-op close method to satisfy the io.ReadCloser interface.

func (ReadFakeCloser) Close 

func (rfc ReadFakeCloser) Close() error

Close implements io.Closer.

type Reader 

type Reader interface {
	Open(in io.Reader, size int64) error
	Read() (File, error)
	Close() error
}

Reader can read discrete byte streams of files from an input stream.

type Snappy 

type Snappy struct{}

Snappy facilitates Snappy compression.

func NewSnappy 

func NewSnappy() *Snappy

NewSnappy returns a new, default instance ready to be customized and used.

func (*Snappy) CheckExt 

func (s *Snappy) CheckExt(filename string) error

CheckExt ensures the file extension matches the format.

func (*Snappy) Compress 

func (s *Snappy) Compress(in io.Reader, out io.Writer) error

Compress reads in, compresses it, and writes it to out.

func (*Snappy) Decompress 

func (s *Snappy) Decompress(in io.Reader, out io.Writer) error

Decompress reads in, decompresses it, and writes it to out.

func (*Snappy) String 

func (s *Snappy) String() string

type Tar 

type Tar struct {
	// Whether to overwrite existing files; if false,
	// an error is returned if the file exists.
	OverwriteExisting bool

	// Whether to make all the directories necessary
	// to create a tar archive in the desired path.
	MkdirAll bool

	// Whether to preserve the file path in the archive
	PreservePath bool

	// A single top-level folder can be implicitly
	// created by the Archive or Unarchive methods
	// if the files to be added to the archive
	// or the files to be extracted from the archive
	// do not all have a common root. This roughly
	// mimics the behavior of archival tools integrated
	// into OS file browsers which create a subfolder
	// to avoid unexpectedly littering the destination
	// folder with potentially many files, causing a
	// problematic cleanup/organization situation.
	// This feature is available for both creation
	// and extraction of archives, but may be slightly
	// inefficient with lots and lots of files,
	// especially on extraction.
	ImplicitTopLevelFolder bool

	// Strip number of leading paths. This feature is available
	// only during unpacking of the entire archive.
	StripComponents int

	// If true, errors encountered during reading
	// or writing a single file will be logged and
	// the operation will continue on remaining files.
	ContinueOnError bool
	// contains filtered or unexported fields
}

Tar provides facilities for operating TAR archives. See http://www.gnu.org/software/tar/manual/html_node/Standard.html.

func NewTar 

func NewTar() *Tar

NewTar returns a new, default instance ready to be customized and used.

func (*Tar) Archive 

func (t *Tar) Archive(sources []string, destination string) error

Archive creates a tarball file at destination containing the files listed in sources. The destination must end with ".tar". File paths can be those of regular files or directories; directories will be recursively added.

func (*Tar) CheckExt 

func (*Tar) CheckExt(filename string) error

CheckExt ensures the file extension matches the format.

func (*Tar) CheckPath 

func (*Tar) CheckPath(to, filename string) error

CheckPath ensures that the filename has not been crafted to perform path traversal attacks

func (*Tar) Close 

func (t *Tar) Close() error

Close closes the tar archive(s) opened by Create and Open.

func (*Tar) Create 

func (t *Tar) Create(out io.Writer) error

Create opens t for writing a tar archive to out.

func (*Tar) Extract 

func (t *Tar) Extract(source, target, destination string) error

Extract extracts a single file from the tar archive. If the target is a directory, the entire folder will be extracted into destination.

func (*Tar) Match 

func (*Tar) Match(file io.ReadSeeker) (bool, error)

Match returns true if the format of file matches this type's format. It should not affect reader position.

func (*Tar) Open 

func (t *Tar) Open(in io.Reader, size int64) error

Open opens t for reading an archive from in. The size parameter is not used.

func (*Tar) Read 

func (t *Tar) Read() (File, error)

Read reads the next file from t, which must have already been opened for reading. If there are no more files, the error is io.EOF. The File must be closed when finished reading from it.

func (*Tar) String 

func (t *Tar) String() string

func (*Tar) Unarchive 

func (t *Tar) Unarchive(source, destination string) error

Unarchive unpacks the .tar file at source to destination. Destination will be treated as a folder name.

func (*Tar) Walk 

func (t *Tar) Walk(archive string, walkFn WalkFunc) error

Walk calls walkFn for each visited item in archive.

func (*Tar) Write 

func (t *Tar) Write(f File) error

Write writes f to t, which must have been opened for writing first.

type TarBrotli 

type TarBrotli struct {
	*Tar
	Quality int
}

TarBrotli facilitates brotli compression of tarball archives.

func NewTarBrotli 

func NewTarBrotli() *TarBrotli

NewTarBrotli returns a new, default instance ready to be customized and used.

func (*TarBrotli) Archive 

func (tbr *TarBrotli) Archive(sources []string, destination string) error

Archive creates a compressed tar file at destination containing the files listed in sources. The destination must end with ".tar.br" or ".tbr". File paths can be those of regular files or directories; directories will be recursively added.

func (*TarBrotli) CheckExt 

func (*TarBrotli) CheckExt(filename string) error

CheckExt ensures the file extension matches the format.

func (*TarBrotli) Create 

func (tbr *TarBrotli) Create(out io.Writer) error

Create opens txz for writing a compressed tar archive to out.

func (*TarBrotli) Extract 

func (tbr *TarBrotli) Extract(source, target, destination string) error

Extract extracts a single file from the tar archive. If the target is a directory, the entire folder will be extracted into destination.

func (*TarBrotli) Open 

func (tbr *TarBrotli) Open(in io.Reader, size int64) error

Open opens t for reading a compressed archive from in. The size parameter is not used.

func (*TarBrotli) String 

func (tbr *TarBrotli) String() string

func (*TarBrotli) Unarchive 

func (tbr *TarBrotli) Unarchive(source, destination string) error

Unarchive unpacks the compressed tarball at source to destination. Destination will be treated as a folder name.

func (*TarBrotli) Walk 

func (tbr *TarBrotli) Walk(archive string, walkFn WalkFunc) error

Walk calls walkFn for each visited item in archive.

type TarBz2 

type TarBz2 struct {
	*Tar

	CompressionLevel int
}

TarBz2 facilitates bzip2 compression (https://github.com/dsnet/compress/blob/master/doc/bzip2-format.pdf) of tarball archives.

func NewTarBz2 

func NewTarBz2() *TarBz2

NewTarBz2 returns a new, default instance ready to be customized and used.

func (*TarBz2) Archive 

func (tbz2 *TarBz2) Archive(sources []string, destination string) error

Archive creates a compressed tar file at destination containing the files listed in sources. The destination must end with ".tar.bz2" or ".tbz2". File paths can be those of regular files or directories; directories will be recursively added.

func (*TarBz2) CheckExt 

func (*TarBz2) CheckExt(filename string) error

CheckExt ensures the file extension matches the format.

func (*TarBz2) Create 

func (tbz2 *TarBz2) Create(out io.Writer) error

Create opens tbz2 for writing a compressed tar archive to out.

func (*TarBz2) Extract 

func (tbz2 *TarBz2) Extract(source, target, destination string) error

Extract extracts a single file from the tar archive. If the target is a directory, the entire folder will be extracted into destination.

func (*TarBz2) Open 

func (tbz2 *TarBz2) Open(in io.Reader, size int64) error

Open opens t for reading a compressed archive from in. The size parameter is not used.

func (*TarBz2) String 

func (tbz2 *TarBz2) String() string

func (*TarBz2) Unarchive 

func (tbz2 *TarBz2) Unarchive(source, destination string) error

Unarchive unpacks the compressed tarball at source to destination. Destination will be treated as a folder name.

func (*TarBz2) Walk 

func (tbz2 *TarBz2) Walk(archive string, walkFn WalkFunc) error

Walk calls walkFn for each visited item in archive.

type TarGz 

type TarGz struct {
	*Tar

	// The compression level to use, as described
	// in the compress/gzip package.
	CompressionLevel int

	// Disables parallel gzip.
	SingleThreaded bool
}

TarGz facilitates gzip compression (RFC 1952) of tarball archives.

func NewTarGz 

func NewTarGz() *TarGz

NewTarGz returns a new, default instance ready to be customized and used.

func (*TarGz) Archive 

func (tgz *TarGz) Archive(sources []string, destination string) error

Archive creates a compressed tar file at destination containing the files listed in sources. The destination must end with ".tar.gz" or ".tgz". File paths can be those of regular files or directories; directories will be recursively added.

func (*TarGz) CheckExt 

func (*TarGz) CheckExt(filename string) error

CheckExt ensures the file extension matches the format.

func (*TarGz) Create 

func (tgz *TarGz) Create(out io.Writer) error

Create opens txz for writing a compressed tar archive to out.

func (*TarGz) Extract 

func (tgz *TarGz) Extract(source, target, destination string) error

Extract extracts a single file from the tar archive. If the target is a directory, the entire folder will be extracted into destination.

func (*TarGz) Open 

func (tgz *TarGz) Open(in io.Reader, size int64) error

Open opens t for reading a compressed archive from in. The size parameter is not used.

func (*TarGz) String 

func (tgz *TarGz) String() string

func (*TarGz) Unarchive 

func (tgz *TarGz) Unarchive(source, destination string) error

Unarchive unpacks the compressed tarball at source to destination. Destination will be treated as a folder name.

func (*TarGz) Walk 

func (tgz *TarGz) Walk(archive string, walkFn WalkFunc) error

Walk calls walkFn for each visited item in archive.

type TarLz4 

type TarLz4 struct {
	*Tar

	// The compression level to use when writing.
	// Minimum 0 (fast compression), maximum 12
	// (most space savings).
	CompressionLevel int
}

TarLz4 facilitates lz4 compression (https://github.com/lz4/lz4/tree/master/doc) of tarball archives.

func NewTarLz4 

func NewTarLz4() *TarLz4

NewTarLz4 returns a new, default instance ready to be customized and used.

func (*TarLz4) Archive 

func (tlz4 *TarLz4) Archive(sources []string, destination string) error

Archive creates a compressed tar file at destination containing the files listed in sources. The destination must end with ".tar.lz4" or ".tlz4". File paths can be those of regular files or directories; directories will be recursively added.

func (*TarLz4) CheckExt 

func (*TarLz4) CheckExt(filename string) error

CheckExt ensures the file extension matches the format.

func (*TarLz4) Create 

func (tlz4 *TarLz4) Create(out io.Writer) error

Create opens tlz4 for writing a compressed tar archive to out.

func (*TarLz4) Extract 

func (tlz4 *TarLz4) Extract(source, target, destination string) error

Extract extracts a single file from the tar archive. If the target is a directory, the entire folder will be extracted into destination.

func (*TarLz4) Open 

func (tlz4 *TarLz4) Open(in io.Reader, size int64) error

Open opens t for reading a compressed archive from in. The size parameter is not used.

func (*TarLz4) String 

func (tlz4 *TarLz4) String() string

func (*TarLz4) Unarchive 

func (tlz4 *TarLz4) Unarchive(source, destination string) error

Unarchive unpacks the compressed tarball at source to destination. Destination will be treated as a folder name.

func (*TarLz4) Walk 

func (tlz4 *TarLz4) Walk(archive string, walkFn WalkFunc) error

Walk calls walkFn for each visited item in archive.

type TarSz 

type TarSz struct {
	*Tar
}

TarSz facilitates Snappy compression (https://github.com/google/snappy) of tarball archives.

func NewTarSz 

func NewTarSz() *TarSz

NewTarSz returns a new, default instance ready to be customized and used.

func (*TarSz) Archive 

func (tsz *TarSz) Archive(sources []string, destination string) error

Archive creates a compressed tar file at destination containing the files listed in sources. The destination must end with ".tar.sz" or ".tsz". File paths can be those of regular files or directories; directories will be recursively added.

func (*TarSz) CheckExt 

func (*TarSz) CheckExt(filename string) error

CheckExt ensures the file extension matches the format.

func (*TarSz) Create 

func (tsz *TarSz) Create(out io.Writer) error

Create opens tsz for writing a compressed tar archive to out.

func (*TarSz) Extract 

func (tsz *TarSz) Extract(source, target, destination string) error

Extract extracts a single file from the tar archive. If the target is a directory, the entire folder will be extracted into destination.

func (*TarSz) Open 

func (tsz *TarSz) Open(in io.Reader, size int64) error

Open opens t for reading a compressed archive from in. The size parameter is not used.

func (*TarSz) String 

func (tsz *TarSz) String() string

func (*TarSz) Unarchive 

func (tsz *TarSz) Unarchive(source, destination string) error

Unarchive unpacks the compressed tarball at source to destination. Destination will be treated as a folder name.

func (*TarSz) Walk 

func (tsz *TarSz) Walk(archive string, walkFn WalkFunc) error

Walk calls walkFn for each visited item in archive.

type TarXz 

type TarXz struct {
	*Tar
}

TarXz facilitates xz compression (https://tukaani.org/xz/format.html) of tarball archives.

func NewTarXz 

func NewTarXz() *TarXz

NewTarXz returns a new, default instance ready to be customized and used.

func (*TarXz) Archive 

func (txz *TarXz) Archive(sources []string, destination string) error

Archive creates a compressed tar file at destination containing the files listed in sources. The destination must end with ".tar.xz" or ".txz". File paths can be those of regular files or directories; directories will be recursively added.

func (*TarXz) CheckExt 

func (*TarXz) CheckExt(filename string) error

CheckExt ensures the file extension matches the format.

func (*TarXz) Create 

func (txz *TarXz) Create(out io.Writer) error

Create opens txz for writing a compressed tar archive to out.

func (*TarXz) Extract 

func (txz *TarXz) Extract(source, target, destination string) error

Extract extracts a single file from the tar archive. If the target is a directory, the entire folder will be extracted into destination.

func (*TarXz) Open 

func (txz *TarXz) Open(in io.Reader, size int64) error

Open opens t for reading a compressed archive from in. The size parameter is not used.

func (*TarXz) String 

func (txz *TarXz) String() string

func (*TarXz) Unarchive 

func (txz *TarXz) Unarchive(source, destination string) error

Unarchive unpacks the compressed tarball at source to destination. Destination will be treated as a folder name.

func (*TarXz) Walk 

func (txz *TarXz) Walk(archive string, walkFn WalkFunc) error

Walk calls walkFn for each visited item in archive.

type TarZstd 

type TarZstd struct {
	*Tar
}

TarZstd facilitates Zstandard compression (RFC 8478) of tarball archives.

func NewTarZstd 

func NewTarZstd() *TarZstd

NewTarZstd returns a new, default instance ready to be customized and used.

func (*TarZstd) Archive 

func (tzst *TarZstd) Archive(sources []string, destination string) error

Archive creates a compressed tar file at destination containing the files listed in sources. The destination must end with ".tar.zst" or ".tzst". File paths can be those of regular files or directories; directories will be recursively added.

func (*TarZstd) CheckExt 

func (*TarZstd) CheckExt(filename string) error

CheckExt ensures the file extension matches the format.

func (*TarZstd) Create 

func (tzst *TarZstd) Create(out io.Writer) error

Create opens txz for writing a compressed tar archive to out.

func (*TarZstd) Extract 

func (tzst *TarZstd) Extract(source, target, destination string) error

Extract extracts a single file from the tar archive. If the target is a directory, the entire folder will be extracted into destination.

func (*TarZstd) Open 

func (tzst *TarZstd) Open(in io.Reader, size int64) error

Open opens t for reading a compressed archive from in. The size parameter is not used.

func (*TarZstd) String 

func (tzst *TarZstd) String() string

func (*TarZstd) Unarchive 

func (tzst *TarZstd) Unarchive(source, destination string) error

Unarchive unpacks the compressed tarball at source to destination. Destination will be treated as a folder name.

func (*TarZstd) Walk 

func (tzst *TarZstd) Walk(archive string, walkFn WalkFunc) error

Walk calls walkFn for each visited item in archive.

type Unarchiver 

type Unarchiver interface {
	Unarchive(source, destination string) error
}

Unarchiver is a type that can extract archive files into a folder.

func ByHeader 

func ByHeader(input io.ReadSeeker) (Unarchiver, error)

ByHeader returns the unarchiver value that matches the input's file header. It does not affect the current read position. If the file's header is not a recognized archive format, then ErrFormatNotRecognized will be returned.

type WalkFunc 

type WalkFunc func(f File) error

WalkFunc is called at each item visited by Walk. If an error is returned, the walk may continue if the Walker is configured to continue on error. The sole exception is the error value ErrStopWalk, which stops the walk without an actual error.

type Walker 

type Walker interface {
	Walk(archive string, walkFn WalkFunc) error
}

Walker can walk an archive file and return information about each item in the archive.

type Writer 

type Writer interface {
	Create(out io.Writer) error
	Write(f File) error
	Close() error
}

Writer can write discrete byte streams of files to an output stream.

type Xz 

type Xz struct{}

Xz facilitates XZ compression.

func NewXz 

func NewXz() *Xz

NewXz returns a new, default instance ready to be customized and used.

func (*Xz) CheckExt 

func (x *Xz) CheckExt(filename string) error

CheckExt ensures the file extension matches the format.

func (*Xz) Compress 

func (x *Xz) Compress(in io.Reader, out io.Writer) error

Compress reads in, compresses it, and writes it to out.

func (*Xz) Decompress 

func (x *Xz) Decompress(in io.Reader, out io.Writer) error

Decompress reads in, decompresses it, and writes it to out.

func (*Xz) String 

func (x *Xz) String() string

type Zip 

type Zip struct {
	// The compression level to use, as described
	// in the compress/flate package.
	CompressionLevel int

	// Whether to overwrite existing files; if false,
	// an error is returned if the file exists.
	OverwriteExisting bool

	// Whether to make all the directories necessary
	// to create a zip archive in the desired path.
	MkdirAll bool

	// If enabled, selective compression will only
	// compress files which are not already in a
	// compressed format; this is decided based
	// simply on file extension.
	SelectiveCompression bool

	// A single top-level folder can be implicitly
	// created by the Archive or Unarchive methods
	// if the files to be added to the archive
	// or the files to be extracted from the archive
	// do not all have a common root. This roughly
	// mimics the behavior of archival tools integrated
	// into OS file browsers which create a subfolder
	// to avoid unexpectedly littering the destination
	// folder with potentially many files, causing a
	// problematic cleanup/organization situation.
	// This feature is available for both creation
	// and extraction of archives, but may be slightly
	// inefficient with lots and lots of files,
	// especially on extraction.
	ImplicitTopLevelFolder bool

	// Strip number of leading paths. This feature is available
	// only during unpacking of the entire archive.
	StripComponents int

	// If true, errors encountered during reading
	// or writing a single file will be logged and
	// the operation will continue on remaining files.
	ContinueOnError bool

	// Compression algorithm
	FileMethod ZipCompressionMethod
	// contains filtered or unexported fields
}

Zip provides facilities for operating ZIP archives. See https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT.

Example (Custom)

Here we create our own instance of the Zip format. No need to use the constructor function (NewZip) or the default instance (DefaultZip) if we do not want to. Instantiating the type like this allows us to easily be very explicit about our configuration. 

z := &Zip{
	CompressionLevel:       3,
	OverwriteExisting:      false,
	MkdirAll:               true,
	SelectiveCompression:   true,
	ImplicitTopLevelFolder: true,
	ContinueOnError:        false,
}
// z is now ready to use for whatever (this is a dumb example)
fmt.Println(z.CheckExt("test.zip"))

Output:
Example (Default)

In this example, the DefaultZip is being customized so that all calls to its methods will use that configuration. 

DefaultZip.OverwriteExisting = true
DefaultZip.ImplicitTopLevelFolder = true
// any subsequent use of DefaultZip uses
// this modified configuration

Output:
Example (StreamingRead)

This example demonstrates how to read an archive in a streaming fashion. The idea is that you can stream the bytes of an archive from a stream, regardless of whether it is an actual file on disk. This means that you can read a huge archive file-by-file rather than having to store it all on disk first. In this example, we read a hypothetical archive from a (fake) HTTP request body and print its file names and sizes. The files can be read, of course, but they do not have to be. 

// for the sake of the example compiling, pretend we have an HTTP request
req := new(http.Request)
contentLen, err := strconv.Atoi(req.Header.Get("Content-Length"))
if err != nil {
	log.Fatal(err)
}

// the Zip format requires knowing the length of the stream,
// but other formats don't generally require it, so it
// could be left as 0 when using those
err = DefaultZip.Open(req.Body, int64(contentLen))
if err != nil {
	log.Fatal(err)
}
defer DefaultZip.Close()

// Note that DefaultZip now contains some state that
// is critical to reading the stream until it is closed,
// so do not reuse it until then.

// iterate each file in the archive until EOF
for {
	f, err := DefaultZip.Read()
	if err == io.EOF {
		break
	}
	if err != nil {
		log.Fatal(err)
	}

	// f is an io.ReadCloser, so you can read its contents
	// if you wish; or you can access its header info through
	// f.Header or the embedded os.FileInfo
	fmt.Println("File name:", f.Name(), "File size:", f.Size())

	// be sure to close f before moving on!!
	err = f.Close()
	if err != nil {
		log.Fatal(err)
	}
}

Output:
Example (StreamingWrite)

This example demonstrates how to write an archive in a streaming fashion. The idea is that you can stream the bytes of a new archive that is created on-the-fly from generic streams. Those streams could be actual files on disk, or they could be over a network, or standard output, or any other io.Reader/io.Writer. This example only adds one file to the archive and writes the resulting archive to standard output, but you could add as many files as needed with a loop. 

err := DefaultZip.Create(os.Stdout)
if err != nil {
	log.Fatal(err)
}
defer DefaultZip.Close()

// Note that DefaultZip now contains state
// critical to a successful write until it
// is closed, so don't reuse it for anything
// else until then.

// At this point, you can open an actual file
// to add to the archive, or the "file" could
// come from any io.ReadCloser stream. If you
// only have an io.Reader, you can use
// ReadFakeCloser to make it into an
// io.ReadCloser.

// The next part is a little tricky if you
// don't have an actual file because you will
// need an os.FileInfo. Fortunately, that's an
// interface! So go ahead and implement it in
// whatever way makes the most sense to you.
// You'll also need to give the file a name
// for within the archive. In this example,
// we'll open a real file.

file, err := os.Open("foo.txt")
if err != nil {
	log.Fatal(err)
}
defer file.Close()
fileInfo, err := file.Stat()
if err != nil {
	log.Fatal(err)
}

err = DefaultZip.Write(File{
	FileInfo: FileInfo{
		FileInfo:   fileInfo,
		CustomName: "name/in/archive.txt",
	},
	ReadCloser: file, // does not have to be an actual file
})
if err != nil {
	log.Fatal(err)
}

Output:

func NewZip 

func NewZip() *Zip

NewZip returns a new, default instance ready to be customized and used.

func (*Zip) Archive 

func (z *Zip) Archive(sources []string, destination string) error

Archive creates a .zip file at destination containing the files listed in sources. The destination must end with ".zip". File paths can be those of regular files or directories. Regular files are stored at the 'root' of the archive, and directories are recursively added.

Example

Much like the package-level Archive function, this creates an archive using the configuration of the Zip instance it is called on. The output filename must match the format's recognized file extension(s). 

err := DefaultZip.Archive([]string{"..."}, "example.zip")
if err != nil {
	log.Fatal(err)
}

Output:

func (*Zip) CheckExt 

func (*Zip) CheckExt(filename string) error

CheckExt ensures the file extension matches the format.

func (*Zip) CheckPath 

func (*Zip) CheckPath(to, filename string) error

CheckPath ensures the file extension matches the format.

func (*Zip) Close 

func (z *Zip) Close() error

Close closes the zip archive(s) opened by Create and Open.

func (*Zip) Create 

func (z *Zip) Create(out io.Writer) error

Create opens z for writing a ZIP archive to out.

func (*Zip) Extract 

func (z *Zip) Extract(source, target, destination string) error

Extract extracts a single file from the zip archive. If the target is a directory, the entire folder will be extracted into destination.

func (*Zip) Match 

func (*Zip) Match(file io.ReadSeeker) (bool, error)

Match returns true if the format of file matches this type's format. It should not affect reader position.

func (*Zip) Open 

func (z *Zip) Open(in io.Reader, size int64) error

Open opens z for reading an archive from in, which is expected to have the given size and which must be an io.ReaderAt.

func (*Zip) Read 

func (z *Zip) Read() (File, error)

Read reads the next file from z, which must have already been opened for reading. If there are no more files, the error is io.EOF. The File must be closed when finished reading from it.

func (*Zip) String 

func (z *Zip) String() string

func (*Zip) Unarchive 

func (z *Zip) Unarchive(source, destination string) error

Unarchive unpacks the .zip file at source to destination. Destination will be treated as a folder name.

func (*Zip) Walk 

func (z *Zip) Walk(archive string, walkFn WalkFunc) error

Walk calls walkFn for each visited item in archive.

func (*Zip) Write 

func (z *Zip) Write(f File) error

Write writes f to z, which must have been opened for writing first.

type ZipCompressionMethod 

type ZipCompressionMethod uint16

ZipCompressionMethod Compression type 

const (
	Store   ZipCompressionMethod = 0
	Deflate ZipCompressionMethod = 8
	BZIP2   ZipCompressionMethod = 12
	LZMA    ZipCompressionMethod = 14
	ZSTD    ZipCompressionMethod = 93
	XZ      ZipCompressionMethod = 95
)

Compression methods. see https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT. Note LZMA: Disabled - because 7z isn't able to unpack ZIP+LZMA ZIP+LZMA2 archives made this way - and vice versa.

type Zstd 

type Zstd struct {
	EncoderOptions []zstd.EOption
	DecoderOptions []zstd.DOption
}

Zstd facilitates Zstandard compression.

func NewZstd 

func NewZstd() *Zstd

NewZstd returns a new, default instance ready to be customized and used.

func (*Zstd) CheckExt 

func (zs *Zstd) CheckExt(filename string) error

CheckExt ensures the file extension matches the format.

func (*Zstd) Compress 

func (zs *Zstd) Compress(in io.Reader, out io.Writer) error

Compress reads in, compresses it, and writes it to out.

func (*Zstd) Decompress 

func (zs *Zstd) Decompress(in io.Reader, out io.Writer) error

Decompress reads in, decompresses it, and writes it to out.

func (*Zstd) String 

func (zs *Zstd) String() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.