archive

README

README.md

Status

Installation

As with many Go utilities, a simple

go get github.com/keltia/archive

is enough to fetch, build and install. Most of the time you will not need to do it explicitely, other applications will fetch it automatically as a dependency.

Dependencies

• Go >= 1.10

Only standard Go modules are used. I use Semantic Versioning for all my modules.

Usage

The module currently supports the following "archives":

• plain text
• gzip files (one file per stream, only first stream)
• zip files
• GPG files (either .asc or .gpg)
• Tar files
• Zstd files (one file per stream, only first stream)

SYNOPSIS

    a, err := archive.New("foo.txt")
    content, err := a.Extract(".txt")
    
    a, err := archive.New("bar.zip")
    content, err := a.Extract(".txt")       // extract the first .txt file
    
    a, err := archive.New("baz.txt.gz")
    content, err := a.Extract(".txt")       // extracts baz.txt
    
    // Gpg is a bit special
    a, err := archive.New("xyz.zip.asc")
    unencrypted, err := a.Extract(".zip")   // decrypt into variable
                                            // if you want to use archive.New() there too
                                            // you need to save into a temp file.
    var buf bytes.Buffer
    
    fmt.Fprintf(&buf, "%s", unencrypted)                                        
    fh, err := os.Create("xyz.zip")
    _, err := io.Copy(fh, &buf)
    fh.Close()
    
    a1, err := archive.New("xyz.zip")
    ...
    You can have more verbose output and debug by using these functions:
    
    archive.SetVerbose()
    archive.SetDebug()      // implies verbose
    ...
    archive.Reset()         // both flags are cleared

Limitations

I wrote this both to simplify and my own code in dmarc-cat (that's also how sandbox got created) and to play with interfaces. It is currently only trying to extract one file at a time matching the extension provided. It will probably evolve into a more general code later.

Tests

I'm trying to get to 100% coverage but some error cases are more difficult to create.

License

This is released under the BSD 2-Clause license. See LICENSE.md.

Contributing

This project is an open Open Source project, please read CONTRIBUTING.md.

Feedback

We welcome pull requests, bug fixes and issue reports.

Before proposing a large change, first please discuss your change by raising an issue.

I use Git Flow for this package so please use something similar or the usual github workflow.

1. Fork it ( https://github.com/keltia/archive/fork )
2. Checkout the develop branch (git checkout develop)
3. Create your feature branch (git checkout -b my-new-feature)
4. Commit your changes (git commit -am 'Add some feature')
5. Push to the branch (git push origin my-new-feature)
6. Create a new Pull Request

Documentation

Index

• Constants
• Variables
• func Ext2Type(typ string) int
• func Reset()
• func SetDebug()
• func SetVerbose()
• func TestGpg_Close(t *testing.T)
• func TestGpg_Decrypt(t *testing.T)
• func TestGpg_Extract(t *testing.T)
• func TestGpg_Extract2(t *testing.T)
• func TestGpg_Extract3(t *testing.T)
• func TestGpg_Extract4(t *testing.T)
• func TestGpg_Extract4_Debug(t *testing.T)
• func TestNullGPGError_Decrypt(t *testing.T)
• func TestNullGPG_Decrypt(t *testing.T)
• func Version() string
• type Decrypter
• type ExtractCloser
  • func New(fn string) (ExtractCloser, error)
  • func NewFromReader(r io.Reader, t int) (ExtractCloser, error)
• type Extracter
• type Gpg
  • func NewGpgfile(fn string) (*Gpg, error)
  • func (a Gpg) Close() error
  • func (a Gpg) Extract(t string) ([]byte, error)
  • func (a *Gpg) Type() int
• type Gpgme
  • func (Gpgme) Decrypt(r io.Reader) (*gpgme.Data, error)
• type Gzip
  • func NewGzipfile(fn string) (*Gzip, error)
  • func (a Gzip) Close() error
  • func (a Gzip) Extract(t string) ([]byte, error)
  • func (a Gzip) Type() int
• type NullGPG
  • func (NullGPG) Decrypt(r io.Reader) (*gpgme.Data, error)
• type NullGPGError
  • func (NullGPGError) Decrypt(r io.Reader) (*gpgme.Data, error)
• type Plain
  • func NewPlainfile(fn string) (*Plain, error)
  • func (a Plain) Close() error
  • func (a Plain) Extract(t string) ([]byte, error)
  • func (a Plain) Type() int
• type Tar
  • func NewTarfile(fn string) (*Tar, error)
  • func (a Tar) Close() error
  • func (a Tar) Extract(t string) ([]byte, error)
  • func (a *Tar) Type() int
• type Zip
  • func NewZipfile(fn string) (*Zip, error)
  • func (a Zip) Close() error
  • func (a Zip) Extract(t string) ([]byte, error)
  • func (a Zip) Type() int
• type Zstd
  • func NewZstdfile(fn string) (*Zstd, error)
  • func (a Zstd) Close() error
  • func (a Zstd) Extract(t string) ([]byte, error)
  • func (a Zstd) Type() int

Constants

const (
	// ArchivePlain starts the different types
	ArchivePlain = 1 << iota
	// ArchiveGzip is for gzip archives
	ArchiveGzip
	// ArchiveZip is for zip archives
	ArchiveZip
	// ArchiveTar describes the tar ones
	ArchiveTar
	// ArchiveGpg is for openpgp archives
	ArchiveGpg
	// ArchiveZstd is for Zstd archives
	ArchiveZstd
)

Variables

var ErrFakeGPGError = fmt.Errorf("fake error")

Functions

func Ext2Type

func Ext2Type(typ string) int

Ext2Type converts from string to archive type (int)

func Reset

func Reset()

Reset is for the two flags

func SetDebug

func SetDebug()

SetDebug sets the mode too

func SetVerbose

func SetVerbose()

SetVerbose sets the mode

func TestGpg_Close

func TestGpg_Close(t *testing.T)

func TestGpg_Decrypt

func TestGpg_Decrypt(t *testing.T)

func TestGpg_Extract

func TestGpg_Extract(t *testing.T)

func TestGpg_Extract2

func TestGpg_Extract2(t *testing.T)

func TestGpg_Extract3

func TestGpg_Extract3(t *testing.T)

func TestGpg_Extract4

func TestGpg_Extract4(t *testing.T)

func TestGpg_Extract4_Debug

func TestGpg_Extract4_Debug(t *testing.T)

func TestNullGPGError_Decrypt

func TestNullGPGError_Decrypt(t *testing.T)

func TestNullGPG_Decrypt

func TestNullGPG_Decrypt(t *testing.T)

func Version

func Version() string

Version reports it

Types

type Decrypter

type Decrypter interface {
	Decrypt(r io.Reader) (*gpgme.Data, error)
}

Decrypter is the gpgme interface

type ExtractCloser

type ExtractCloser interface {
	Extracter
	Close() error
	Type() int
}

ExtractCloser is the same with Close()

func New

func New(fn string) (ExtractCloser, error)

New is the main creator

func NewFromReader

func NewFromReader(r io.Reader, t int) (ExtractCloser, error)

NewFromReader uses an io.Reader instead of a file

type Extracter

type Extracter interface {
	Extract(t string) ([]byte, error)
}

Extracter is the main interface we have

type Gpg

type Gpg struct {
	// contains filtered or unexported fields
}

Gpg is how we use/mock decryption stuff

func NewGpgfile

func NewGpgfile(fn string) (*Gpg, error)

NewGpgfile initializes the struct and check filename

func (Gpg) Close

func (a Gpg) Close() error

Close is part of the Closer interface

func (Gpg) Extract

func (a Gpg) Extract(t string) ([]byte, error)

Extract binds it to the Archiver interface

func (*Gpg) Type

func (a *Gpg) Type() int

Type returns the archive type obviously.

type Gpgme

type Gpgme struct{}

Gpgme is for real gpgme stuff

func (Gpgme) Decrypt

func (Gpgme) Decrypt(r io.Reader) (*gpgme.Data, error)

Decrypt does the obvious

type Gzip

type Gzip struct {
	// contains filtered or unexported fields
}

Gzip is a gzip-compressed file

func NewGzipfile

func NewGzipfile(fn string) (*Gzip, error)

NewGzipfile stores the uncompressed file name

func (Gzip) Close

func (a Gzip) Close() error

Close is a no-op

func (Gzip) Extract

func (a Gzip) Extract(t string) ([]byte, error)

Extract returns the content of the file

func (Gzip) Type

func (a Gzip) Type() int

Type returns the archive type obviously.

type NullGPG

type NullGPG struct{}

NullGPG is for testing

func (NullGPG) Decrypt

func (NullGPG) Decrypt(r io.Reader) (*gpgme.Data, error)

Decrypt does the obvious

type NullGPGError

type NullGPGError struct{}

func (NullGPGError) Decrypt

func (NullGPGError) Decrypt(r io.Reader) (*gpgme.Data, error)

type Plain

type Plain struct {
	Name string
	// contains filtered or unexported fields
}

Plain is for plain text

func NewPlainfile

func NewPlainfile(fn string) (*Plain, error)

func (Plain) Close

func (a Plain) Close() error

Close is a no-op

func (Plain) Extract

func (a Plain) Extract(t string) ([]byte, error)

Extract returns the content of the file

func (Plain) Type

func (a Plain) Type() int

Type returns the archive type obviously.

type Tar

type Tar struct {
	// contains filtered or unexported fields
}

Tar is a tar archive :)

func NewTarfile

func NewTarfile(fn string) (*Tar, error)

func (Tar) Close

func (a Tar) Close() error

Close does something here

func (Tar) Extract

func (a Tar) Extract(t string) ([]byte, error)

func (*Tar) Type

func (a *Tar) Type() int

Type returns the archive type obviously.

type Zip

type Zip struct {
	// contains filtered or unexported fields
}

Zip is for pkzip/infozip files

func NewZipfile

func NewZipfile(fn string) (*Zip, error)

NewZipfile open the zip file

func (Zip) Close

func (a Zip) Close() error

Close does something here

func (Zip) Extract

func (a Zip) Extract(t string) ([]byte, error)

Extract returns the content of the file

func (Zip) Type

func (a Zip) Type() int

Type returns the archive type obviously.

type Zstd

type Zstd struct {
	// contains filtered or unexported fields
}

Zstd is a gzip-compressed file

func NewZstdfile

func NewZstdfile(fn string) (*Zstd, error)

NewZstdfile stores the uncompressed file name

func (Zstd) Close

func (a Zstd) Close() error

Close is a no-op

func (Zstd) Extract

func (a Zstd) Extract(t string) ([]byte, error)

Extract returns the content of the file

func (Zstd) Type

func (a Zstd) Type() int

Type returns the archive type obviously.