miniz
Lua bindings for the embedded miniz library
Status
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.
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.
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.
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.
ZipFileReader
Created by new_reader. 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.
get_filename
Returns the file name referenced by the given fileTableIndex, or nil and an error message if the given index was invalid.
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.
get_offset
Returns the starting offset (from the beginning of the file) of the ZIP archive.
This offset is likely zero for normal archives, but the file format allows storing arbitrary data before the beginning of the ZIP header.
is_directory
Returns true if the entry referenced by the given fileTableIndex is a directory entry, and false otherwise.
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.
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.
| 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.
add_from_zip
Adds (in-memory) the contents of the entry referenced by the given fileTableIndex from another ZIP archive to the archive.
finalize
Finishes the current archive, adding the necessary structures to make it a valid and complete ZIP file. Then, returns the file contents.
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.
Functions
adler32
Returns the Adler-32 checksum for the given input. Supplying an initialValue allows processing multiple chunks as they arrive.
crc32
Returns the CRC-32 checksum for the given input. Supplying an initialValue allows processing multiple chunks as they arrive.
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.
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.
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.
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.
last_error
Returns the last compression or decompression error (as a human-readable string) if any was encountered, or nil otherwise.
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).
new_inflator
Creates a new Inflator object and returns a userdata reference to it.
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.
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.
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.
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.
version
Returns the version number of the embedded miniz library as a Lua string.
Changelog
| Version | What happened? |
|---|---|
| v0.0.5 | Initial release |