Lua bindings for the embedded miniz library
This module is preloaded. You can simply require it:
local miniz = require("miniz")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.
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.
:::
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.
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.
:::
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.
Applies INFLATE to the given (DEFLATE-compressed) input and returns the decompressed bytes as a Lua string.
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).
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.
Returns the file name referenced by the given fileTableIndex, or nil and an error message if the given index was invalid.
Returns the total number of files within the ZIP archive. This is the maximum fileTableIndex that you can pass to other functions.
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.
:::
Returns true if the entry referenced by the given fileTableIndex is a directory entry, and false otherwise.
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.
Returns a list of attributes for the entry referenced by the given fileTableIndex, or nil and an error message if the index was invalid.
Created by new_writer. You can use this to add files to a ZIP archive or to save the in-memory data to disk.
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.
Adds (in-memory) the contents of the entry referenced by the given fileTableIndex from another ZIP archive to the archive.
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.
:::
Returns the Adler-32 checksum for the given input. Supplying an initialValue allows processing multiple chunks as they arrive.
Returns the CRC-32 checksum for the given input. Supplying an initialValue allows processing multiple chunks as they arrive.
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.
:::
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.
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.
Returns the last compression or decompression error (as a human-readable string) if any was encountered, or nil otherwise.
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).
Creates a new Inflator object and returns a userdata reference to it.
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.
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.
Creates a new ZIP file writer for the given fileSystemPath. The flags passed to miniz can control the way that the archive is written.
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.
:::
Returns the version number of the embedded miniz library as a Lua string.
| Version | What happened? |
|---|---|
| v0.0.20 | Added new_reader_memory |
| v0.0.5 | Initial release |