archive

package module
v1.3.3 Latest Latest
Warning

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

 Go to latest Published: Oct 11, 2026 License: GPL-3.0 Imports: 32 Imported by: 2

README

Defacto2 / archive

Go Reference

The archive package provides compressed and stored archive file extraction and content listing functions. See the reference documentation for additional usage and examples.

Usage

In your Go project, import the releaser library.

go get github.com/Defacto2/archive

Use the functions.

import "github.com/Defacto2/archive"

func main() {
    src := filepath.Join("path", "to", "archive.zip")
    dst := filepath.Join(os.TempDir(), "extracted")

    // Extract all files from an archive.
    _ = archive.ExtractAll(context.TODO(), src, dst)

    // Extract targets or specific files from an archive.
    x := archive.Extractor{
        Source:       src,
        Destination:  dst,
    }
    _ = x.Extract(context.TODO(), "file1.txt", "file2.txt")

    // List the contents of an archive.
    names, _ := archive.Lists(src)
    for n, name := range names {
        fmt.Println(n, name)
    }

    // Search for a possible readme file within the list of files.
    filename := filepath.Base(src)
    readme := archive.Readme(filename, files...)
    fmt.Println(readme)

    // Compress a file into a new archive.
    srcFile := filepath.Join("path", "to", "textfile.txt")
    dst = filepath.Join(os.TempDir(), "testfile.zip")
    _, _ = rezip.Compress(srcFile, dst)

    // Compress a directory into a new archive.
    srcDir := filepath.Join("path", "to", "compress")
    dst = filepath.Join(os.TempDir(), "testdata.zip")
    _, _ = rezip.CompressDir(srcDir, dst)
}

Documentation

Overview

Package archive provides compressed and stored archive file extraction and content listing.

The file archive formats supported are: 7-Zip, ARC, ARJ, BZip2, Microsoft CAB, GZip, LHA, LZH, NoGate PAK, RAR, TAR, tarballs (compressed TAR), XZ, ZIP, and Zstandard. ZIP support includes the deflate, implode, shrink, and store methods.

The package can use the following terminal programs for legacy file support:

  • 7zz - 7-Zip for Linux: console version
  • arc - arc - pc archive utility
  • arj - (deprecated: on macOS) "Open-source ARJ" v3.10
  • bsdtar - BSD tar that uses the libarchive(3) library
  • lha - Lhasa v0.4 LHA tool found in the jlha-utils or lhasa packages
  • [unar] - The Unarchiver, both "unar" and "lsar"
  • unrar - 6.24 freeware by Alexander Roshal, not the common unrar-free which is feature incomplete

Index

Examples

Constants

View Source 
const (
	// WriteWriteRead is the file mode for read and write access.
	// The file owner and group has read and write access, and others have read access.
	WriteWriteRead   fs.FileMode = 0o664
	DirWriteReadRead fs.FileMode = 0o755
	WriteOnly                    = os.O_CREATE | os.O_WRONLY | os.O_TRUNC
	WriteRead                    = os.O_CREATE | os.O_RDWR | os.O_TRUNC
)

Variables

View Source 
var (
	ErrCorruption     = errors.New("corrupt or unexpected decompression")
	ErrDest           = errors.New("destination is empty")
	ErrHLExt          = errors.New("not a valid extension, it must be in the format, .ext")
	ErrNotArchive     = errors.New("file is not an archive")
	ErrNotImplemented = errors.New("archive format is not implemented")
	ErrRead           = errors.New("could not read the file archive")
	ErrProg           = errors.New("program error")
	ErrFile           = errors.New("path is a directory")
	ErrPath           = errors.New("path is a file")
	ErrSize           = errors.New("size cannot be a negative value")
	ErrTooMany        = errors.New("will not decompress this archive as it is very large")
)
View Source 
var (
	// ErrContext Deprecated: Unused.
	ErrContext = errors.New("context cannot be nil")
	// ErrExt Deprecated: Retired.
	ErrExt = errors.New("extension is not a supported archive format")
	// ErrPanic Deprecated: Unused.
	ErrPanic = errors.New("extract panic")
	// ErrMissing Deprecated: Unused.
	ErrMissing = errors.New("path does not exist")
)

Functions

func ExtractAll 

func ExtractAll(ctx context.Context, src, dst string) error

ExtractAll extracts all files from the src archive file to the destination directory.

func ExtractSource deprecated 

func ExtractSource(ctx context.Context, src, _ string) (string, error)

ExtractSource extracts the source file to a temporary directory, to function as a pseudo cache. The named file is used as part of the extracted directory path. The src is the source file to extract.

If a target temporary directory already exists, and it contains two or more entries (directories, files, etc). Then ExtractSource will stop, assuming the src file has already been extracted.

If the source archive is larger then 157_286_400 bytes, then an error is returned.

The returned string is the absolute path to the temporary directory holding the extracted archive.

Deprecated: Use ExtractTemp as the name argument is unused.

func ExtractTemp added in v1.2.0 

func ExtractTemp(ctx context.Context, src string) (path string, aErr error)

ExtractTemp extracts the source file to a temporary directory to act as a pseudo cache.

If a target temporary directory already exists and contains two or more entries (directories, files, etc). Then the extraction will abort as it is assumed the source file has previously been extracted.

If the source archive is larger than 157,286,400 bytes, then an error is returned.

The returned string is the absolute path to the extracted temporary directory. 

func HardLink(require, src string) (string, error)

HardLink is used to create a hard link to the source file when the filename does not have the required file extension.

This is a workaround for archive programs such as arj which demands the file extension but when the source filename does not have one. The hardlink needs to be removed after usage.

Returns:

  • The absolute path of the hardlink is returned if it is created.
  • An empty string is returned if the source file already has the file extension.
  • An error is returned if the source file cannot be linked.

func List deprecated 

func List(ctx context.Context, src, _ string) ([]string, error)

List returns the files within the src archive.

The optional filename gets used as a extraction pattern name. For example, where the src archive is named as a UUID and the original name is something else such as a tarball.

Deprecated: Use Lists as the filename argument is unused.

func Lists added in v1.2.0 

func Lists(ctx context.Context, src string) ([]string, error)

func MagicExt deprecated 

func MagicExt(ctx context.Context, src string) (string, error)

MagicExt uses the Linux file program to determine the src archive file type. The returned string will be a file separator and extension.

Note both bzip2 and gzip archives now do not return the .tar extension prefix. The detection of tar.gz archives requires the src filename to end with .tar.gz, otherwise the file will be treated as a gzip archive.

Deprecated: This func is now unused, it is frozen and no new functionality will be added.

func Readme 

func Readme(filename string, files ...string) string

Readme returns the best matching scene text README or NFO file from a collection of files. The filename is the name of the archive file, and the files are the list of files in the archive. Note the filename matches are case-insensitive as many handled file archives are created on Windows FAT32, NTFS or MS-DOS FAT16 file systems.

Example 
package main

import (
	"fmt"

	"github.com/Defacto2/archive"
)

func main() {
	name := archive.Readme("APP.ZIP", "APP.EXE", "APP.TXT",
		"APP.BIN", "APP.DAT", "STUFF.DAT")
	fmt.Println(name)
}

Output:
APP.TXT

Types

type Content 

type Content struct {
	Ext   string   // Ext returns file extension of the archive.
	Files []string // Files returns list of files within the archive.
}

Content are the result of using system programs to read the file archives. 

func ListARJ() {
    var c archive.Content
    ctx := context.TODO()
    err := c.ARJ(ctx, "archive.arj")
    if err != nil {
        fmt.Fprintf(os.Stderr, "error: %v\n", err)
        return
    }
    for name := range slices.Values(c.Files) {
        fmt.Println(name)
    }
}

func (*Content) ARC added in v1.1.0 

func (c *Content) ARC(ctx context.Context, src string) error

ARC returns the content of the src ARC archive. The format once credited to System Enhancement Associates, but now using the arc program by Howard Chu.

func (*Content) ARJ 

func (c *Content) ARJ(ctx context.Context, src string) (err error)

ARJ returns the content of the src ARJ archive. The format credited to Robert Jung using the arj program.

func (*Content) BSDTar added in v1.2.0 

func (c *Content) BSDTar(ctx context.Context, src string) error

BSDTar returns the content of the archive using the bsdtar program.

func (*Content) Bz2 added in v1.2.0 

func (c *Content) Bz2(ctx context.Context, src string) error

Bz2 returns the uncompressed filename of the bz2 archive.

func (*Content) Bz2Tar added in v1.2.0 

func (c *Content) Bz2Tar(ctx context.Context, src string) error

func (*Content) Cab added in v1.1.0 

func (c *Content) Cab(ctx context.Context, src string) error

Cab returns the content of the src Cabinet archive. The format is credited to Microsoft. On Linux the format is handled with the gcab program by Marc-André Lureau.

func (*Content) Gzip added in v1.1.0 

func (c *Content) Gzip(ctx context.Context, src string) error

Gzip returns the uncompressed filename of the gzip archive.

func (*Content) GzipTar added in v1.2.0 

func (c *Content) GzipTar(ctx context.Context, src string) error

GzipTar returns the content of a TAR archive compressed with gzip. This process is slower as the gzip file must first be decompressed to a temporary directory before the TAR archive can be accessed.

func (*Content) LHA 

func (c *Content) LHA(ctx context.Context, src string) error

LHA returns the content of the src LHA or LZH archive. The format credited to Haruyasu Yoshizaki (Yoshi) using the lha program.

On Linux either the jlha-utils or lhasa work.

func (*Content) Lsar added in v1.1.8 

func (c *Content) Lsar(ctx context.Context, src string) error

Lsar extracts the targets from the source of multiple archive types.

More information:

func (*Content) Rar 

func (c *Content) Rar(ctx context.Context, src string) error

Rar returns the content of the src RAR archive. The format is credited to Alexander Roshal using the unrar program.

On Linux there are two versions of the unrar program, the freeware version by Alexander Roshal and the feature incomplete unrar-free. The freeware version is the recommended program for extracting RAR archives.

func (*Content) Read 

func (c *Content) Read(ctx context.Context, src string) error

Read returns the content of the src file archive with the archive format being detected using magic bytes. However, tarballs (compressed tar archives) must have a proper file extension:

  • bzip2 ".tar.bz2", ".tar.bz", ".tbz2" ".tbz"
  • Gzip ".tar.gz", ".tgz"
  • XZ Utils ".tar.xz", ".txz"
  • Zstandard ".tar.zst" ".tzst"

Supported formats are:

7-zip, arc, arj, bzip2, Microsoft cabinet, gzip, lha, lzh, Nogate pak, rar, tar, tarball, zip, zstandard.

func (*Content) Run added in v1.2.0 

func (c *Content) Run(ctx context.Context, file, prog string, arg ...string) ([]byte, error)

Run executes a content list command, capturing output, stderr, and context timeouts.

func (*Content) Tar added in v1.1.0 

func (c *Content) Tar(ctx context.Context, src string) error

Tar returns the content of a TAR archive.

func (*Content) Zip 

func (c *Content) Zip(ctx context.Context, src string) error

Zip returns the content of the src ZIP archive. The format is credited to Phil Katz.

func (*Content) Zip7 added in v1.1.0 

func (c *Content) Zip7(ctx context.Context, src string) error

Zip7 returns the content of the src 7-zip archive. The format credited to Igor Pavlov and using the 7z program.

On some Linux distributions the 7z program is named 7zz. The legacy version of the 7z program, the p7zip package should not be used!

type Extractor 

type Extractor struct {
	Source      string // The source archive file.
	Destination string // The extraction destination directory.
}

Extractor uses system archiver programs to extract the targets from the src file archive. 

func Extract() {
    x := archive.Extractor{
        Source:      "archive.arj",
        Destination: os.TempDir(),
    }
    err := x.Extract("README.TXT", "INFO.DOC")
    if err != nil {
        fmt.Fprintf(os.Stderr, "error: %v\n", err)
        return
    }
}

func (Extractor) ARC 

func (x Extractor) ARC(ctx context.Context, targets ...string) error

ARC extracts the content of the ARC archive. The format once credited to System Enhancement Associates, but now using the arc program by Howard Chu. If the targets are empty then all files are extracted.

func (Extractor) ARJ 

func (x Extractor) ARJ(ctx context.Context, targets ...string) error

ARJ extracts the targets from the source ARJ archive to the destination directory using the arj program. If the targets are empty then all files are extracted.

func (Extractor) BSDTar added in v1.2.0 

func (x Extractor) BSDTar(ctx context.Context, targets ...string) error

BSDTar extracts the content of the Tar archive using the bsdtar program. If the targets are empty then all files are extracted.

bsdtar uses the performant libarchive library for archive extraction:

gzip, bzip2, compress, xz, lzip, lzma, tar, iso9660, zip, ar, xar, lha/lzh, rar, rar v5, Microsoft Cabinet, 7-zip.

func (Extractor) Bz2 added in v1.2.0 

func (x Extractor) Bz2(ctx context.Context) error

func (Extractor) Cab added in v1.1.0 

func (x Extractor) Cab(ctx context.Context) error

Cab decompresses the source archive file to the destination directory. The format is credited to Microsoft. On Linux the format is handled with the gcab program by Marc-André Lureau which does not support targets for extraction.

func (Extractor) Extract 

func (x Extractor) Extract(ctx context.Context, targets ...string) (err error)

Extract the targets from the source file archive to the destination directory a system archive program. If the targets are empty then all files are extracted.

Some archive formats do not support targets and will always extract the whole archive:

  • Bzip2
  • Microsoft CAB

func (Extractor) Generic added in v1.1.0 

func (x Extractor) Generic(ctx context.Context, run Run, targets ...string) (err error)

Generic extracts the targets from the source archive to the destination directory using the specified archive program. If the targets are empty then all files are extracted.

It is used for archive formats that are not widely supported or have a limited feature set including ARC, and others.

These DOS era archive formats are not widely supported. They also does not support extracting to a target directory. To work around this, Generic copies the source archive to the destination directory, uses that as the working directory and extracts the files. The copied source archive is then removed.

func (Extractor) Gzip added in v1.0.6 

func (x Extractor) Gzip(ctx context.Context, targets ...string) error

Gzip extracts the compressed file from a gzip archive. If the compressed file is a supported TAR archive, that too is extracted. These combined files often use the ".tgz" and ".tar.gz" filename extensions.

The targets are only for TAR archives and are otherwise ignored.

func (Extractor) LHA 

func (x Extractor) LHA(ctx context.Context, targets ...string) error

LHA extracts the targets from the source LHA/LZH archive. The format credited to Haruyasu Yoshizaki (Yoshi) using the lha program. If the targets are empty then all files are extracted.

On Linux either the jlha-utils or lhasa work.

func (Extractor) Rar 

func (x Extractor) Rar(ctx context.Context, targets ...string) error

Rar extracts the targets from the source RAR archive to the destination directory using the unrar program. If the targets are empty then all files are extracted.

On Linux there are two versions of the unrar program, the freeware version by Alexander Roshal and the feature incomplete unrar-free. The freeware version is the recommended program for extracting RAR archives.

func (Extractor) RarWithoutPaths added in v1.2.0 

func (x Extractor) RarWithoutPaths(ctx context.Context, targets ...string) error

RarWithoutPaths extracts the targets from the source RAR archive to the destination directory using the unrar program. If the targets are empty then all files are extracted.

It uses the "extract files without archived paths" and the "exclude paths from names" flags.

func (Extractor) Run added in v1.2.0 

func (x Extractor) Run(ctx context.Context, file, prog string, arg ...string) error

Run executes an extraction command, capturing stderr and context timeouts.

func (Extractor) Tar added in v1.1.0 

func (x Extractor) Tar(ctx context.Context, targets ...string) error

Tar extracts the content of the Tar archive. If the targets are empty then all files are extracted. Any errors with the archive or its content are ignored.

func (Extractor) TarWithLogger added in v1.2.0 

func (x Extractor) TarWithLogger(ctx context.Context, logger *slog.Logger, targets ...string) error

TarWithLogger extracts the content of the Tar archive and reports any archive or extraction errors to the logger. If the targets are empty then all files are extracted.

func (Extractor) Unar added in v1.1.7 

func (x Extractor) Unar(ctx context.Context, targets ...string) error

Unar extracts the targets from the source of multiple archive types. If the targets are empty then all files are extracted.

Support includes:

  • ARJ, ARC, PAK, Zoo, LHZ, LZX, Squeeze, Crunch
  • PackIt, RAR, CAB, MSI
  • ISO, BIN, MDF, NRG, CDI

More information:

func (Extractor) Zip 

func (x Extractor) Zip(ctx context.Context, targets ...string) error

Zip extracts the content of the src ZIP archive. The format is credited to Phil Katz. If the targets are empty then all files are extracted.

Individual file extraction errors are ignored, instead use Extractor.ZipWithLogger.

func (Extractor) Zip7 

func (x Extractor) Zip7(ctx context.Context, targets ...string) error

Zip7 extracts the targets from the source 7z archive to the destination directory using the 7z program. If the targets are empty then all files are extracted.

On some Linux distributions the 7z program is named 7zz. The legacy version of the 7z program, the p7zip package should not be used!

func (Extractor) ZipStrict added in v1.2.0 

func (x Extractor) ZipStrict(ctx context.Context, targets ...string) error

ZipStrict extracts the content of the src ZIP archive. The format is credited to Phil Katz. If the targets are empty then all files are extracted.

The process is aborted and an error is returned for any file extraction errors and CRC32 validation checks.

func (Extractor) ZipUnzip added in v1.2.0 

func (x Extractor) ZipUnzip(ctx context.Context, targets ...string) error

ZipUnzip extracts the content of the src ZIP archive using the unzip program. The format is credited to Phil Katz. If the targets are empty then all files are extracted.

The use of Extractor.Zip is preferred over this method.

func (Extractor) ZipWithLogger added in v1.2.0 

func (x Extractor) ZipWithLogger(ctx context.Context, logger *slog.Logger, targets ...string) error

ZipWithLogger extracts the content of the src ZIP archive. The format is credited to Phil Katz. If the targets are empty then all files are extracted.

Individual file extraction errors are logged by the logger.

type Finds 

type Finds map[string]Usability

Finds are a collection of matched filenames and their usability ranking.

func (Finds) BestMatch 

func (f Finds) BestMatch() string

BestMatch returns the most usable filename from a collection of finds.

type ProgInfo added in v1.3.0 

type ProgInfo struct {
	Prog    string      // Prog is the basename of the program
	Abs     string      // Abs is the absolute path of the program
	Regular bool        // Regular is false when the program is a symlink
	Perm    os.FileMode // Perm bits of the program or symlink
	Size    int64       // Size of the program or symlink
	Output  string      // Output string when running the program
}

func ProgInfos added in v1.3.0 

func ProgInfos(ctx context.Context) [n]ProgInfo

ProgInfos returns the program versions of the various commands referenced by this archive package.

func (*ProgInfo) Lookup added in v1.3.0 

func (pi *ProgInfo) Lookup(ctx context.Context, name, arg string,
	progOutput func(name string, b []byte) string,
) error

Lookup the named program version and using an optional argument. The output will be parsed and stored as a string to ProgInfo.Output.

The progOutput is a func to parse the output bytes and return a version string. The progOutput name should match the Lookup name and gets used to identify where the version information is located.

type Run added in v1.1.0 

type Run struct {
	Program string // Program is the archiver program to run, but not the full path.
	Extract string // Extract is the program command to extract files from the archive.
}

Run holds the program and extract command for use with the generic extractor.

type Usability 

type Usability uint

Usability of search, filename pattern matches. 

const (
	// Lvl1 is the highest usability.
	Lvl1 Usability = iota + 1
	Lvl2
	Lvl3
	Lvl4
	Lvl5
	Lvl6
	Lvl7
	Lvl8
	Lvl9 // Lvl9 is the least usable.
)

type ZipMethod added in v1.2.0 

type ZipMethod uint16
const (
	Store ZipMethod = iota
	Shrink
	Reduce1
	Reduce2
	Reduce3
	Reduce4
	Implode
	Unused
	Deflate
)

func (ZipMethod) String added in v1.2.0 

func (z ZipMethod) String() string

Source Files

View all Source files

Directories

Path Synopsis
Package command lists the known archiving and decompression application names.
 Package command lists the known archiving and decompression application names.
Package expand is for use with the archive/zip package.
 Package expand is for use with the archive/zip package.
Package explode is for use with the archive/zip package.
 Package explode is for use with the archive/zip package.
Package pkzip provides constants and functions for working with PKZip files to determine the compression methods used.
 Package pkzip provides constants and functions for working with PKZip files to determine the compression methods used.
Package rezip provides compression for files and directories to create zip archives using the universal Store and Deflate compression methods.
 Package rezip provides compression for files and directories to create zip archives using the universal Store and Deflate compression methods.
Package unshrink is for use with the archive/zip package.
 Package unshrink is for use with the archive/zip package.

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.