archive

README

Defacto2 / archive

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() {
    // Extract all files from an archive.
    if err := archive.Extract("path/to/archive.zip", "path/to/extract"); err != nil {
        fmt.Println(err)
    }

    // Extract a specific files from an archive.
    x := archive.Extractor{
        Source: "path/to/archive.zip",
        Destination: "path/to/extract",
    }
    if err := x.Extract("file1.txt", "file2.txt"); err != nil {
        fmt.Println(err)
    }

    // Extract all files to a temporary directory.
    path, err := archive.ExtractSource("path/to/archive.zip", "tempsubdir")
    if err != nil {
        fmt.Println(err)
    }
    fmt.Println("Extracted to:", path)

    // List the contents of an archive.
    files, err := archive.List("path/to/archive.zip", "archive.zip")
    if err != nil {
        fmt.Println(err)
    }
    for _, f := range files {
        fmt.Println(f)
    }

    // Search for a possible readme file within the list of files.
    name := archive.Readme("archive.zip", cont.Files)
    fmt.Println(name)

    // Compress a file into a new archive.
    if _, err := rezip.Compress("file1.txt", "path/to/new.zip"); err != nil {
        fmt.Println(err)
    }
    // Compress a directory into a new archive.
    if _, err = rezip.CompressDir("path/to/directory", "path/to/new.zip"); err != nil {
        fmt.Println(err)
    }
}

Documentation

Overview

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

The file archive formats supported are 7Zip, ARC, ARJ, LHA, LZH, RAR, TAR, and ZIP, including the deflate, implode, and shrink compression methods.

The package uses following Linux terminal programs for legacy file support.

1. 7zz - 7-Zip for Linux: console version
2. arc - arc - pc archive utility
2. arj - "Open-source ARJ" v3.10
3. lha - Lhasa v0.4 LHA tool found in the jlha-utils or lhasa packages
4. hwzip - hwzip for BBS era ZIP file that uses obsolete compression methods
5. tar - GNU tar
6. unrar - 6.24 freeware by Alexander Roshal, not the common unrar-free which is feature incomplete
7. zipinfo - ZipInfo v3 by the Info-ZIP workgroup

Index

• Constants
• Variables
• func ExtractAll(src, dst string) error
• func ExtractSource(src, name string) (string, error)
• func List(src, filename string) ([]string, error)
• func MagicExt(src string) (string, error)
• func Readme(filename string, files ...string) string
• type Content
  • func (c *Content) ARJ(src string) error
  • func (c *Content) LHA(src string) error
  • func (c *Content) Rar(src string) error
  • func (c *Content) Read(src string) error
  • func (c *Content) Zip(src string) error
• type Extractor
  • func (x Extractor) ARC(targets ...string) error
  • func (x Extractor) ARJ(targets ...string) error
  • func (x Extractor) Bsdtar(targets ...string) error
  • func (x Extractor) Extract(targets ...string) error
  • func (x Extractor) Gzip() error
  • func (x Extractor) LHA(targets ...string) error
  • func (x Extractor) Rar(targets ...string) error
  • func (x Extractor) Zip(targets ...string) error
  • func (x Extractor) Zip7(targets ...string) error
  • func (x Extractor) ZipHW(targets ...string) error
• type Finds
  • func (f Finds) BestMatch() string
• type Usability

Examples

• Readme

Constants

const (
	TimeoutExtract = 15 * time.Second // TimeoutExtract is the maximum time allowed for the archive extraction.
	TimeoutDefunct = 5 * time.Second  // TimeoutDefunct is the maximum time allowed for the defunct file extraction.
	TimeoutLookup  = 2 * time.Second  // TimeoutLookup is the maximum time allowed for the program list content.
)

Variables

var (
	ErrDest           = errors.New("destination is empty")
	ErrExt            = errors.New("extension is not a supported archive format")
	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")
	ErrPanic          = errors.New("extract panic")
	ErrMissing        = errors.New("path does not exist")
)

Functions

func ExtractAll

func ExtractAll(src, dst string) error

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

func ExtractSource

func ExtractSource(src, name string) (string, error)

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

func List

func List(src, filename string) ([]string, error)

List returns the files within an rar, tar, lha, or zip archive. This filename extension is used to determine the archive format.

func MagicExt

func MagicExt(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. For example a file with the magic string "gzip compressed data" will return ".tar.gz".

Note both bzip2 and gzip archives return the .tar extension prefix.

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
    err := c.ARJ("archive.arj")
    if err != nil {
        fmt.Fprintf(os.Stderr, "error: %v\n", err)
        return
    }
    for i, f := range c.Files {
        fmt.Printf("%d %s\n", i+1, f)
    }
}

func (*Content) ARJ

func (c *Content) ARJ(src string) error

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

func (*Content) LHA

func (c *Content) LHA(src string) error

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

func (*Content) Rar

func (c *Content) Rar(src string) error

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

func (*Content) Read

func (c *Content) Read(src string) error

Read returns the content of the src file archive using the system archiver programs. The filename is used to determine the archive format.

Supported formats are ARJ, LHA, LZH, RAR, and ZIP.

func (*Content) Zip

func (c *Content) Zip(src string) error

Zip returns the content of the src ZIP archive, credited to Phil Katz, using the zipinfo program.

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(targets ...string) error

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

ARC is a DOS era archive format that is not widely supported. It also does not support extracting to a target directory. To work around this, this 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) ARJ

func (x Extractor) ARJ(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

func (x Extractor) Bsdtar(targets ...string) error

Bsdtar extracts the targets from the source archive to the destination directory using the bsdtar program. If the targets are empty then all files are extracted. bsdtar uses the performant libarchive library for archive extraction and is the recommended program for extracting the following formats:

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

func (Extractor) Extract

func (x Extractor) Extract(targets ...string) 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.

The required Filename string is used to determine the archive format.

Some archive formats that could be impelmented if needed in the future, "freearc", "zoo".

func (Extractor) Gzip

func (x Extractor) Gzip() error

Gzip decompresses the source archive file to the destination directory. The source file is expected to be a gzip compressed file. Unlike the other container formats, gzip only compresses a single file.

func (Extractor) LHA

func (x Extractor) LHA(targets ...string) error

LHA extracts the targets from the source LHA/LZH archive to the destination directory using an 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(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) Zip

func (x Extractor) Zip(targets ...string) error

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

func (Extractor) Zip7

func (x Extractor) Zip7(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) ZipHW

func (x Extractor) ZipHW(targets ...string) error

ZipHW extracts the targets from the source zip archive to the destination directory using the [hwzip program]. If the targets are empty then all files are extracted.

hwzip is used to handle DOS era, zip archive compression methods that are not widely supported. It also does not support extracting to a target directory. To work around this, this 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.

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 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.
)