$ opm get hamishforbes/lua-ffi-zlib

lua-ffi-zlib

A Lua module using LuaJIT's FFI feature to access zlib. Intended primarily for use within OpenResty to allow manipulation of gzip encoded HTTP responses.

Methods

Basic methods allowing for simple compression or decompression of gzip data

inflateGzip

Syntax: ok, err = inflateGzip(input, output, chunk?, windowBits?)

• input should be a function that accepts a chunksize as its only argument and return that many bytes of the gzip stream

• output will receive a string of decompressed data as its only argument, do with it as you will!

• chunk is the size of the input and output buffers, optional and defaults to 16KB

• windowBits is passed to inflateInit2(), should be left as default for most cases. See zlib manual for details

On error returns false and the error message, otherwise true and the last status message

deflateGzip

Syntax: ok, err = deflateGzip(input, output, chunk?, options?)

• input should be a function that accepts a chunksize as its only argument and return that many bytes of uncompressed data.

• output will receive a string of compressed data as its only argument, do with it as you will!

• chunk is the size of the input and output buffers, optional and defaults to 16KB

• options is a table of options to pass to deflateInit2() Valid options are level, memLevel, strategy and windowBits, see zlib manual for details

On error returns false and the error message, otherwise true and the last status message

Example

Reads a file and output the decompressed version.

Roughly equivalent to running gzip -dc file.gz > out_file | tee

    local table_insert = table.insert
    local table_concat = table.concat
    local zlib = require('lib.ffi-zlib')
    
    local f = io.open(arg[1], "rb")
    local out_f = io.open(arg[2], "w")
    
    local input = function(bufsize)
        -- Read the next chunk
        local d = f:read(bufsize)
        if d == nil then
            return nil
        end
        return d
    end
    
    local output_table = {}
    local output = function(data)
        table_insert(output_table, data)
        local ok, err = out_f:write(data)
        if not ok then
            -- abort decompression when error occurs
            return nil, err
        end
    end
    
    -- Decompress the data
    local ok, err = zlib.inflateGzip(input, output)
    if not ok then
        print(err)
        return
    end
    
    local decompressed = table_concat(output_table,'')
    
    print(decompressed)

Advanced Usage

Several other methods are available for advanced usage. Some of these map directly to functions in the zlib library itself, see the manual for full details. Others are lower level utility functions.

createStream

Synax: stream, inbuf, outbuf = createStream(bufsize)

Returns a z_stream struct, input buffer and output buffer of length bufsize

initInflate

Syntax: ok = initInflate(stream, windowBits?)

Calls zlib's inflateInit2 with given stream, defaults to automatic header detection.

initDeflate

Syntax: ok = initDeflate(stream, options?)

Calls zlib's deflateInit2 with the given stream. options is an optional table that can set level, memLevel, strategy and windowBits

deflate

Syntax: ok, err = deflate(input, output, bufsize, stream, inbuf, outbuf)

• input is a function that takes a chunk size argument and returns at most that many input bytes

• output is a function that takes a string argument of output data

• bufsize is the length of the output buffer

• inbuf cdata input buffer

• outpuf ccdata output buffer

This function will loop until all input data is consumed (input returns nil) or an error occurs. It will then clean up the stream and return an error code

inflate

Syntax: ok, err = inflate(input, output, bufsize, stream, inbuf, outbuf)

• input is a function that takes a chunk size argument and returns at most that many input bytes

• output is a function that takes a string argument of output data

• bufsize is the length of the output buffer

• inbuf cdata input buffer

• outpuf ccdata output buffer

This function will loop until all input data is consumed (input returns nil) or an error occurs. It will then clean up the stream and return an error code

adler

Syntax: chksum = adler(str, chksum?)

Computes an adler32 checksum for a string, updates an existing checksum if provided

crc

Syntax: chksum = crc(str, chksum?)

Computes an crc32 checksum for a string, updates an existing checksum if provided

zlib_err

Syntax: err = zlib_err(code)

Returns the string representation of a zlib error code