miniz

Lua bindings for the embedded miniz library

Status

External: Functionality is provided by a third-party library, which may or may not give semantic versioning guarantees

Availability

This module is preloaded. You can simply require it:

local miniz = require("miniz")

Compression Levels

Whenever you compress data, you can optionally pass a compressionLevel, which must be a number value:

The minimum compression level is zero (meaning "no compression")
The highest supported level is nine (meaning "maximum compression")
If you don't pass a compressionLevel, the maximum compression level of nine will be used

If you pass invalid values, you may get an error or the input may silently be clamped to the nearest possible value.

Compressor Flags

Many methods accept an optional flags parameter. By setting a nonzero value, you can control advanced compression options such as "write ZIP archives with a zlib-compatible header". Since they aren't part of the Lua bindings, this page doesn't attempt to list them all.

info

You can find out what flags are currently supported by reading the source comments in the miniz header file.

Deflator

Created by new_deflator. You can use this to compress large amounts of data, or smaller chunks that simply aren't available all at once.

deflate

Applies DEFLATE to the given input and returns the compressed bytes as a Lua string.

info

For advanced use cases, you may control the flushing behavior of the compressor with an additional flushingBehavior flag:

Supported values are "no", "partial", "sync", "full", "finish", and "block"
The default value is "no", i.e., no flushing of the compressor is enforced (useful for stream compression)
For additional details and potential use cases, see this zlib-specific documentation explaining the modes

Most of the time, you'll want to pass "no" or "finish" for asynchronous and synchronous compression, respectively.

Available since: v0.0.5

Arguments
#	Name	Type	Fallback
	self	Deflator
	input	string
	flushingBehavior	string?

Return values
#	Name	Type
	compressedInput	string

Inflator

Created by new_inflator. You can use this to decompress large amounts of data, or smaller chunks that simply aren't available all at once.

inflate

Applies INFLATE to the given (DEFLATE-compressed) input and returns the decompressed bytes as a Lua string.

Available since: v0.0.5

Arguments
#	Name	Type	Fallback
	self	Inflator
	input	string

Return values
#	Name	Type
	decompressedInput	string

ZipFileReader

Created by new_reader or new_reader_memory. You can use this to get information about the files within a ZIP archive or to extract them (in-memory).

extract

Extracts the file referenced by the given fileTableIndex and returns the file contents (or "" on failure). The flags are passed to miniz directly. Since the extraction happens entirely in memory, this method may not be well-suited for extracting very large files.

Available since: v0.0.5

Arguments
#	Name	Type	Fallback
	self	ZipFileReader
	fileTableIndex	number

Return values
#	Name	Type
	decompressedFileContents	string

get_filename

Returns the file name referenced by the given fileTableIndex, or nil and an error message if the given index was invalid.

Available since: v0.0.5

Arguments
#	Name	Type	Fallback
	self	ZipFileReader
	fileTableIndex	number

Return values
#	Name	Type
	filePath	string?
	errorMessage	string?

get_num_files

Returns the total number of files within the ZIP archive. This is the maximum fileTableIndex that you can pass to other functions.

Available since: v0.0.5

Arguments
#	Name	Type	Fallback
	self	ZipFileReader

Return values
#	Name	Type
	fileCount	number?

get_offset

Returns the starting offset (from the beginning of the file) of the ZIP archive.

note

This offset is likely zero for normal archives, but the file format allows storing arbitrary data before the beginning of the ZIP header.

Available since: v0.0.5

Arguments
#	Name	Type	Fallback
	self	ZipFileReader

Return values
#	Name	Type
	startingOffset	number?

is_directory

Returns true if the entry referenced by the given fileTableIndex is a directory entry, and false otherwise.

Available since: v0.0.5

Arguments
#	Name	Type	Fallback
	self	ZipFileReader
	fileTableIndex	number

Return values
#	Name	Type
	isDirectoryEntry	boolean

locate_file

Searches the internal file system table of the given ZIP archive for an entry that matches fileSystemPath and returns the corresponding fileTableIndex, or nil and an error message if no match was found. It uses a simple linear search method that might have to iterate over the entire table, which is slow for very large files. The flags passed to miniz can control the way that the search is performed.

Available since: v0.0.5

Arguments
#	Name	Type	Fallback
	fileSystemPath	string
	flags	number?

Return values
#	Name	Type
	fileTableIndex	number

stat

Returns a list of attributes for the entry referenced by the given fileTableIndex, or nil and an error message if the index was invalid.

Available since: v0.0.5

Arguments
#	Name	Type	Fallback
	self	ZipFileReader
	fileTableIndex	number

Return values
#	Name	Type
	stats	ZipArchiveFileStatistics?
	errorMessage	string?

ZipArchiveFileStatistics
Field	Type
index	number
version_made_by	number
version_needed	number
bit_flag	number
method	number
time	number
crc32	number
comp_size	number
uncomp_size	number
internal_attr	number
external_attr	number
filename	string
comment	string

ZipFileWriter

Created by new_writer. You can use this to add files to a ZIP archive or to save the in-memory data to disk.

add

Adds (in-memory) a new file entry referenced by fileSystemPath with the given fileContents to the archive. The flags passed to miniz control the compression level and settings for this specific entry; it's a bitfield with the level being stored in the lowest byte.

Available since: v0.0.5

add_from_zip

Adds (in-memory) the contents of the entry referenced by the given fileTableIndex from another ZIP archive to the archive.

Available since: v0.0.5

finalize

Finishes the current archive, adding the necessary structures to make it a valid and complete ZIP file. Then, returns the file contents.

note

Once the archive has been finalized, you can no longer add new entries to it. You'd usually do this before saving the file to disk.

Available since: v0.0.5

Arguments
#	Name	Type	Fallback
	self	ZipFileWriter

Return values
#	Name	Type
	zipFileContents	string

Functions

adler32

Returns the Adler-32 checksum for the given input. Supplying an initialValue allows processing multiple chunks as they arrive.

Available since: v0.0.5

Arguments
#	Name	Type	Fallback
	input	string
	initialValue	string?

Return values
#	Name	Type
	checksum	string

crc32

Returns the CRC-32 checksum for the given input. Supplying an initialValue allows processing multiple chunks as they arrive.

Available since: v0.0.5

Arguments
#	Name	Type	Fallback
	input	string
	initialValue	string?

Return values
#	Name	Type
	checksum	string

compress

Applies DEFLATE to the given input and returns the compressed bytes as a Lua string, or nil and an error message in case of failure. This method is identical to Deflator.deflate in principle, but cannot be used to compress data in chunks.

info

As a general guideline, you would use the different compression methods as follows:

For maximum ease of use, simply call compress for "one and done" synchronous compression (blocking)
If you want to control the behavior of the compressor by passing flags to miniz, use deflate instead (blocking)
Using an Deflator allows compressing chunks as they come in, i.e., work asynchronously (non-blocking)

While you don't need to worry about buffer allocation with either of these, the performance characteristics may still differ.

Available since: v0.0.5

Arguments
#	Name	Type	Fallback
	input	string
	compressionLevel	number?

Return values
#	Name	Type
	compressedInput	string

deflate

Applies DEFLATE to the given input and returns the decompressed bytes, or "" in case of failure.

The flags passed to miniz control the behavior of the compressor.

Available since: v0.0.5

Arguments
#	Name	Type	Fallback
	input	string
	flags	number?

Return values
#	Name	Type
	decompressedInput	string

inflate

Applies INFLATE to the given (DEFLATE-compressed) input and returns the decompressed bytes, or "" in case of failure.

The flags passed to miniz control the behavior of the decompressor.

Available since: v0.0.5

Arguments
#	Name	Type	Fallback
	input	string
	flags	number?

Return values
#	Name	Type
	decompressedInput	string

last_error

Returns the last compression or decompression error (as a human-readable string) if any was encountered, or nil otherwise.

Available since: v0.0.5

new_deflator

Creates a new Deflator object and returns a userdata reference to it. If you set compressionLevel, it must be a valid value (0 to 9).

Available since: v0.0.5

Arguments
#	Name	Type	Fallback
	compressionLevel	number?

Return values
#	Name	Type
	deflator	Deflator

new_inflator

Creates a new Inflator object and returns a userdata reference to it.

Available since: v0.0.5

new_reader

Creates a new ZIP file reader for the given fileSystemPath. The flags passed to miniz can control the way that the archive is read. This method will automatically load the ZIP file from disk and attempt to decode it.

info

This function is suitable if loading the entire file into memory is acceptable. Use a deflator for streaming.

Returns nil and an error message in case of failure. Otherwise the ZIP reader should be ready to use.

Available since: v0.0.5

Arguments
#	Name	Type	Fallback
	fileSystemPath	string
	flags	number?

Return values
#	Name	Type
	reader	ZipFileReader?
	errorMessage	string?

new_reader_memory

Creates a new ZIP file reader for the given fileContents. The flags passed to miniz can control the way that the archive is read. You must handle reading the file from disk yourself, however you see fit.

info

This function is suitable if loading the entire file into memory is acceptable. Use a deflator for streaming.

Returns nil and an error message in case of failure. Otherwise the ZIP reader should be ready to use.

Available since: v0.0.20

Arguments
#	Name	Type	Fallback
	fileContents	string
	flags	number?

Return values
#	Name	Type
	reader	ZipFileReader?
	errorMessage	string?

new_writer

Creates a new ZIP file writer for the given fileSystemPath. The flags passed to miniz can control the way that the archive is written.

Available since: v0.0.5

Arguments
#	Name	Type	Fallback
	fileSystemPath	string
	flags	number?

Return values
#	Name	Type
	writer	ZipFileWriter

uncompress

Applies INFLATE to the given (DEFLATE-compressed) input and returns the decompressed bytes as a Lua string, or nil and an error message in case of failure. This method is identical to Inflator.inflate in principle, but cannot be used to decompress data in chunks.

For optimization purposes, you can configure an initialOutputBufferSize (in bytes). The decompressor will otherwise double the buffer whenever it needs more space, until decompression has finished or the maximum integer size of the platform has been reached.

info

As a general guideline, you would use the different decompression methods as follows:

For maximum ease of use, simply call uncompress for "one and done" synchronous decompression (blocking)
If you want to control the behavior of the decompressor by passing flags to miniz, use inflate instead (blocking)
Using an Inflator allows compressing chunks as they come in, i.e., work asynchronously (non-blocking)

While you don't need to worry about buffer allocation with either of these, the performance characteristics may still differ.

Available since: v0.0.5

Arguments
#	Name	Type	Fallback
	input	string
	initialOutputBufferSize	number?

Return values
#	Name	Type
	decompressedInput	string

version

Returns the version number of the embedded miniz library as a Lua string.

Available since: v0.0.5

Changelog

Version	What happened?
v0.0.20	Added `new_reader_memory`
v0.0.5	Initial release

miniz

Status​

Availability​

Compression Levels​

Compressor Flags​

Deflator​

deflate​

Inflator​

inflate​

ZipFileReader​

extract​

get_filename​

get_num_files​

get_offset​

is_directory​

locate_file​

stat​

ZipFileWriter​

add​

add_from_zip​

finalize​

Functions​

adler32​

crc32​

compress​

deflate​

inflate​

last_error​

new_deflator​

new_inflator​

new_reader​

new_reader_memory​

new_writer​

uncompress​

version​

Changelog​

Status

Availability

Compression Levels

Compressor Flags

Deflator

deflate

Inflator

inflate

ZipFileReader

extract

get_filename

get_num_files

get_offset

is_directory

locate_file

stat

ZipFileWriter

add

add_from_zip

finalize

Functions

adler32

crc32

compress

deflate

inflate

last_error

new_deflator

new_inflator

new_reader

new_reader_memory

new_writer

uncompress

version

Changelog