civ3decompress

README

civ3decompress

Civ3Decompress package decompresses Civ III save and bic/bix/biq files.

It is implemented based on the description of PKWare Data Compression Library at https://groups.google.com/forum/#!msg/comp.compression/M5P064or93o/W1ca1-ad6kgJ . However this is only a partial implementation; The Huffman-coded literals of header 0x01 are not implemented here as they are not needed for decompressing Civ3 data files.

It has worked fine on every Civ3 file I've used it on for years, and for one-at-a-time decompressions it seems fast enough. But since I started Lua scripting and batch processing I notice it's a relatively slow decompressor.

So I coded a new function DecompressByteArray() which is much faster.

Exports

• func ReadFile(path string) ([]byte, bool, error) - Most likely what you want. Given a path to a Civ3 data file, it will detect whether or not it's compressed and then return a byte array of the decompressed file contents. It now uses the faster DecompressByteArray behind the scenes.
• func Decompress(file io.Reader) ([]byte, error) - Given an io.Reader for a compressed Civ3 data file, returns a byte array of the decompressed file.
• func DecompressByteArray(bytes []byte) ([]byte, error) - Takes a compressed data file as a byte array and decompresses it. It's much faster than Decompress.
• type FileError struct - If you want to handle errors based on type
• type DecodeError struct - If you want to handle errors based on type
• func (b *BitReader) ReadByte() (byte, error) - I don't recall why this would be exported
• bitstream wrapper - These functions behave exactly like thier bitstream counterparts except they pop the least significant bit first. I'm not sure it makes sense to export them.
  • type BitReader struct
  • func NewReader(r io.Reader) *BitReader
  • func (b *BitReader) ReadBit() (Bit, error)
  • type Bit bool
  • type BitReader struct
  • const Zero Bit = false
  • const One = true

Documentation

Overview

Package civ3decompress is to decompress SAV and BIQ files from the game Civilization III

Package bitstream is a simple wrapper around a io.Reader and io.Writer to provide bit-level access to the stream.

Index

• func Decompress(file io.Reader) ([]byte, error)
• func DecompressByteArray(bytes []byte) ([]byte, error)
• func ReadFile(path string) ([]byte, bool, error)
• type Bit
• type BitReader
  • func NewReader(r io.Reader) *BitReader
  • func (b *BitReader) ReadBit() (Bit, error)
  • func (b *BitReader) ReadBits(nbits uint) (uint, error)
  • func (b *BitReader) ReadByte() (byte, error)
• type DecodeError
  • func (e DecodeError) Error() string
• type FileError
  • func (e FileError) Error() string

Functions

func Decompress

func Decompress(file io.Reader) ([]byte, error)

Decompress is implemented based on the description of PKWare Data Compression Library at https://groups.google.com/forum/#!msg/comp.compression/M5P064or93o/W1ca1-ad6kgJ However this is only a partial implementation; The Huffman-coded literals of header 0x01 are not implemented here as they are not needed for my purpose

func DecompressByteArray

func DecompressByteArray(bytes []byte) ([]byte, error)

DecompressByteArray is a May 2020 attempt at speeding up decompression by eliminating the reader interfaces and frequent function calls TODO: `bytes` is a horrible name for a variable as there is a bytes package. I should probably change it someday.

func ReadFile

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

ReadFile takes a filename and returns the decompressed file data or the raw data if it's not compressed. Also returns true if compressed.

Types

type Bit

type Bit bool

A Bit is a zero or a one

const (
	// Zero is our exported type for '0' bits
	Zero Bit = false
	// One is our exported type for '1' bits
	One = true
)

type BitReader

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

A BitReader reads bits from an io.Reader

func NewReader

func NewReader(r io.Reader) *BitReader

NewReader returns a BitReader that returns a single bit at a time from 'r'

func (*BitReader) ReadBit

func (b *BitReader) ReadBit() (Bit, error)

ReadBit returns the next bit from the stream, reading a new byte from the underlying reader if required.

func (*BitReader) ReadBits

func (b *BitReader) ReadBits(nbits uint) (uint, error)

ReadBits reads nbits from the stream

func (*BitReader) ReadByte

func (b *BitReader) ReadByte() (byte, error)

ReadByte reads a single byte from the stream, regardless of alignment

type DecodeError

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

DecodeError is when the data does not match an expected pattern. Pass it message string.

func (DecodeError) Error

func (e DecodeError) Error() string

type FileError

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

FileError returns errors while trying to open or decompress the file. Pass it the downstream error e.g. return FileError{err}

func (FileError) Error

func (e FileError) Error() string