zfile

README

zfile

Package zfile implements readers and writers which inject de/compression based on file extension.

Install

go get github.com/dshess/zfile

Or just import it and let go guide you.

Requirements

This was developed under go 1.25.5. TBD: Tests work under 1.20.14.

Documentation

https://pkg.go.dev/github.com/dshess/zfile

Usage

This code writes a plain-text file:

path := "file"
contents := "This is a test"
err := os.WriteFile(path, contents, 0644)
if err != nil {
    return err
}

This writes a gzip-compressed file:

path := "file.gz"
contents := "This is a test"
err := zfile.WriteFile(path, contents, 0644)
if err != nil {
    return err
}

Similar wrappers for os.ReadFile(), os.Open(), and os.Create(). This module handles gzip, zstd and xz.

License

Licensed under the MIT License, see LICENSE file.

Documentation

Overview

Package zfile implements readers and writers which inject de/compression based on file extension.

Usage

This code writes a plain-text file:

path := "file"
contents := "This is a test"
err := os.WriteFile(path, contents, 0644)
if err != nil {
    return err
}

This writes a gzip-compressed file:

path := "file.gz"
contents := "This is a test"
err := zfile.WriteFile(path, contents, 0644)
if err != nil {
    return err
}

Similar wrappers for os.ReadFile(), os.Open(), and os.Create(). This module handles gzip, zstd and xz.

What is the motivating use case?

I often find myself writing utility commands which run like this:

go run ./ generate-data ... output.zst

Adding flags to determine the kind of output is error-prone, because you can specify to, say, xz compress data into a file with .zst extension. It is convenient to be able to do things like up-arrow and change the extension and run, without having to make two or three parallel command-line changes.

Index

• func Create(path string) (io.WriteCloser, error)
• func CreateType(path string, ctype Compressor) (io.WriteCloser, error)
• func Open(path string) (io.ReadCloser, error)
• func OpenType(path string, ctype Compressor) (io.ReadCloser, error)
• func ReadFile(path string) ([]byte, error)
• func ReadFileType(path string, ctype Compressor) ([]byte, error)
• func WriteFile(path string, data []byte, perm os.FileMode) error
• func WriteFileType(path string, data []byte, perm os.FileMode, ctype Compressor) error
• type Compressor
  • func CDerive(path string) Compressor

Functions

func Create

func Create(path string) (io.WriteCloser, error)

Opens the named file for writing like os.Create() with automatic compression based on suffix. For instance, Create("file.gz") writes a gzip-compressed file.

func CreateType

func CreateType(path string, ctype Compressor) (io.WriteCloser, error)

Like Create(), but allows passing an explicit compression type. See WriteFileType().

func Open

func Open(path string) (io.ReadCloser, error)

Opens the named file for reading like os.Open() with automatic decompression based on suffix. For instance, Open("file.gz") reads a gzip-compressed file.

func OpenType

func OpenType(path string, ctype Compressor) (io.ReadCloser, error)

Like Open() but allows explicit compression type selection.

func ReadFile

func ReadFile(path string) ([]byte, error)

Reads the contents of the file like os.ReadFile(), with automatic decompression based on suffix. For instance, ReadFile("file.gz") reads a gzip-compressed file.

func ReadFileType

func ReadFileType(path string, ctype Compressor) ([]byte, error)

Like ReadFile() but allows explicit compression type selection.

func WriteFile

func WriteFile(path string, data []byte, perm os.FileMode) error

Writes the contents of the file like os.WriteFile(), with automatic compression based on suffix. For instance, WriteFile("file.gz") writes a gzip-compressed file.

func WriteFileType

func WriteFileType(path string, data []byte, perm os.FileMode, ctype Compressor) error

Like WriteFile(), but allows passing an explicit compression type. This is useful when writing a temporary file which will later be renamed into place. For instance:

tmpPath := path+".tmp"
err := zfile.WriteFileType(tmpPath, data, perm, zfile.CDerive(path))
if err != nil { return err }
return os.Rename(tmpPath, path)

Types

type Compressor

type Compressor int

const (
	CSuffix Compressor = iota
	CGzip
	CZstd
	CXz
	CNone
	CError
)

func CDerive

func CDerive(path string) Compressor

Return a compression type based on extension. Useful for cases like setting the compression when writing to a temporary file which will be renamed into place on completion.