tar2go

README

tar2go

tar2go implements are go fs.FS for tar files.

Tars are not indexed so by themselves don't really have support for random access. When a request to open/stat a file is made tar2go will scan through the tar, indexing each entry along the way, until the file is found in the tar. A tar file is only ever scanned 1 time and scanning is done lazily (as needed to index the requested entry).

tar2go does not support modifying a tar file, however there is support for modifying the in-memory representation of the tar which will show up in the fs.FS. You can also write a new tar file with requested modifications.

Usage

  f, _ := os.Open(p)
  defer f.Close()
  
  // Entrypoint into this library
  idx := NewIndex(f)
  
  // Get the `fs.FS` implementation
  goFS := idx.FS()
  // Do stuff with your fs
  // ...
  
  
  // Add or replace a file in the index
  _ := idx.Replace("foo", strings.NewReader("random stuff")
  data, _ := fs.ReadFile(goFS, "foo")
  if string(data) != "random stuff") {
    panic("unexpected data")
  }
  
  // Delete a file in the index
  _ := idx.Replace("foo", nil)
  if _, err := fs.ReadFile(goFS, "foo"); !errors.Is(err, fs.ErrNotExist) {
    panic(err)
  }
  
  // Create a new tar with updated content
  // First we need to create an `io.Writer`, which is where the updated tar stream will be written to.
  f, _ := os.CreateTemp("", "updated")
  idx.Update(f, func(name string, rdr ReaderAtSized) (ReaderAtSized, bool, error) {
    // Update calls this function for every file in the tar
    // The returned `ReaderAtSized` is used instead of the content passed in (rdr).
    // To make no changes just return the same rdr back.
    // Return true for the bool value if the content is changed.
  })

Documentation

Index

• Variables
• type Index
  • func NewIndex(rdr io.ReaderAt) *Index
  • func (i *Index) FS() fs.FS
  • func (i *Index) Reader() *io.SectionReader
  • func (i *Index) Replace(name string, rdr ReaderAtSized) error
  • func (i *Index) Update(w io.Writer, updater UpdaterFn) error
• type ReaderAtSized
• type UpdaterFn

Variables

var (
	// ErrDelete should be returned by an UpdaterFn when the file should be deleted.
	ErrDelete = errors.New("delete")
)

Types

type Index

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

Index is a tar index that can be used to read files from a tar.

func NewIndex

func NewIndex(rdr io.ReaderAt) *Index

NewIndex creates a new Index from the passed in io.ReaderAt.

func (*Index) FS

func (i *Index) FS() fs.FS

FS returns an fs.FS that can be used to read the files in the tar.

func (*Index) Reader

func (i *Index) Reader() *io.SectionReader

Reader returns an io.ReaderAt that can be used to read the entire tar.

func (*Index) Replace

func (i *Index) Replace(name string, rdr ReaderAtSized) error

Replace replaces the file with the passed in name with the passed in ReaderAtSized. If the passed in ReaderAtSized is nil, the file will be deleted. If the file does not exist, it will be added.

This function does not update the actual tar file, it only updates the index.

func (*Index) Update

func (i *Index) Update(w io.Writer, updater UpdaterFn) error

Update creates a new tar with the files updated by the passed in updater function. The output tar is written to the passed in io.Writer

type ReaderAtSized

type ReaderAtSized interface {
	io.ReaderAt
	Size() int64
}

ReaderAtSized is an io.ReaderAt that also implements a Size method.

type UpdaterFn

type UpdaterFn func(string, ReaderAtSized) (ReaderAtSized, bool, error)

UpdaterFn is a function that is passed the name of the file and a ReaderAtSized