extract

Documentation

Overview

Extract implements the extraction of files from various file archive or compression formats.

The entrypoint for the package is ExtractFile which is meant to call the appropriate handlers for the file at the given path based on the filename extensions. OpenArchive may also be used. The resulting Archive struct has methods which handle common archive types.

Index

• func ExtractFile(filePath string, filterStrings []string, overwrite bool) error
• func NewFile(path string, mode fs.FileMode, overwrite bool) (*os.File, error)
• func NormalizeFilePath(path string) string
• type Archive
  • func OpenArchive(filePath string) (*Archive, error)
  • func (a *Archive) Bunzip2() error
  • func (a *Archive) Close()
  • func (a *Archive) Gunzip() error
  • func (a *Archive) Untar(outputDir string, filters FilterSet, overwrite bool) []string
  • func (a *Archive) Unxz() error
  • func (a *Archive) Unzip(outputDir string, filters FilterSet, overwrite bool) []string
  • func (a *Archive) WriteSingleton(outputPath string, mode fs.FileMode, overwrite bool) error
• type FilterSet

Functions

func ExtractFile

func ExtractFile(filePath string, filterStrings []string, overwrite bool) error

ExtractFile extracts the contents of the file archive at the given filePath. The filterStrings argument accepts a slice of strings (which will be compiled into regexp.Regexp objects) to filter what will be extracted from the file archive.

func NewFile

func NewFile(path string, mode fs.FileMode, overwrite bool) (*os.File, error)

NewFile wraps os.OpenFile to standardize the way the package creates output files. The path argument accepts the file path to the given output file, the mode argument accepts an fs.FileMode which the file will be created with, and overwrite determines whether existing files should be overwritten or and error produced.

func NormalizeFilePath

func NormalizeFilePath(path string) string

NormalizeFilePath is a utility function that rewrites file paths specified to ensure that they are relative to the current working directory and don't have names that are potentially a nuisence for users (such as names composed only of whitespace characters, only dots, etc.)

Types

type Archive

type Archive struct {
	Path         string        // full path to the archive file
	PathNoExt    string        // full path to the archive file with any recognized filename extensions removed
	FileHandle   *os.File      // file handle for the archive file
	FileStats    fs.FileInfo   // file statistics for the archive file
	StreamHandle io.ReadCloser // handle for optional decompression reader
}

Archive is a handle for optionally-compressed file archives which contain one or more files.

func OpenArchive

func OpenArchive(filePath string) (*Archive, error)

OpenArchive opens the archive file at the given path and returns a handle suitable for file extraction operations on that archive

func (*Archive) Bunzip2

func (a *Archive) Bunzip2() error

Bunzip2 enables bzip2 decompression of the Archive data. It creates a bzip2 stream reader for Archive.FileHandle on Archive.StreamHandle. Any errors creating the reader will be returned.

func (*Archive) Close

func (a *Archive) Close()

Close handles closing the resources contained in an Archive handle

func (*Archive) Gunzip

func (a *Archive) Gunzip() error

Gunzip enables gzip decompression of the Archive data. It creates a gzip stream reader for Archive.FileHandle on Archive.StreamHandle. Any errors creating the reader will be returned.

func (*Archive) Untar

func (a *Archive) Untar(outputDir string, filters FilterSet, overwrite bool) []string

Untar extracts the Archive's contents into the given output directory using a tar file reader. If there are any filters in the given FilterSet then files are only extracted if they match one of the given filters. If the files to be created conflict with existing files in the outputDir then extraction will stop unless the overwrite argument is set to true.

func (*Archive) Unxz

func (a *Archive) Unxz() error

Unxz enables xz decompression of the Archive data. It creates an xz stream reader for Archive.FileHandle on Archive.StreamHandle. Any errors creating the reader will be returned.

func (*Archive) Unzip

func (a *Archive) Unzip(outputDir string, filters FilterSet, overwrite bool) []string

Unzip extracts the Archive's contents into the given output directory using the a zip file reader. If there are any filters in the given FilterSet then files are only extracted if they match one of the given filters. If the files to be created conflict with existing files in the outputDir then extraction will stop unless the overwrite argument is set to true.

func (*Archive) WriteSingleton

func (a *Archive) WriteSingleton(outputPath string, mode fs.FileMode, overwrite bool) error

WriteSingleton extracts the Archive's solitary file into the given output directory using io.Copy. This is typically applied when a single file is compressed with a utility like gzip. If the file to be written conflicts with an existing file in the outputDir then extraction will stop unless the overwrite argument is set to true.

type FilterSet

type FilterSet []*regexp.Regexp

FilterSet contains compiled regular expressions which identify files to be included during an extraction process. If the FilterSet is empty all files will be extracted.