Skip to content

global zip

LuaZip is a lightweight Lua extension library that can be used to read files stored inside zip files. It uses zziplib to do all the hard work.

The API exposed to Lua is very simple and very similiar to the usual file handling functions provided by the I/O Lua standard library. In fact, the API is so similar that parts of this manual are extracted from the Lua manual, copyrighted by Tecgraf, PUC-Rio.

History:

  • keplerproject.org (link not accessible): http://www.keplerproject.org/luazip
  • luaforge.net (link not accessible): http://luaforge.net/projects/luazip
  • Forked from the CVS repository on luaforge.net on Jan. 20, 2010: https://github.com/luaforge/luazip
  • Most active fork: https://github.com/mpeterv/luazip

Project on luarocks: https://luarocks.org/modules/mpeterv/luazip HTML documentation: http://mpeterv.github.io/luazip

😱 Types incomplete or incorrect? 🙏 Please contribute!

methods

zip.type

function zip.type(zfile: ZFile {
    close = function,
    files = function,
    open = function,
}) ->  ("closed zip file"|"zip file")?

Check if a zip file is open or closed.

Reference:

  • Corresponding C source code: (luazip.c#L217-L225)[https://github.com/mpeterv/luazip/blob/e424f667cc5c78dd19bb5eca5a86b3c8698e0ce5/src/luazip.c#L217-L225]

Example:

local z_file = zip.open('test.zip')
assert(z_file)
assert(zip.type(z_file) == "zip file")
z_file:close()
assert(zip.type(z_file) == "closed zip file")

zip.open

function zip.open(filename: string)
 ->  ZFile?
 -> err string?

Open a zip file and return a new zip file handle.

In case of error it returns nil and an error message. Unlike io.open, there is no mode parameter, as the only supported mode is "read".

Example:

local z_file = zip.open('test.zip')
assert(z_file)

Reference:

zip.openfile

function zip.openfile(
  filename: string,
  extensions: (string|string[])?
)
 ->  ZInternalFile?
 -> err string?

Open a file and return a file handle.

In case of error it returns nil and an error message. Unlike io.open, there is no mode parameter, as the only supported mode is read.

This function implements a virtual file system based on optionally compressed files. Instead of simply looking for a file at a given path, this function goes recursively up through all path separators ("/") looking for zip files there. If it finds a zip file, this function use the remaining path to open the requested file. The optional parameter extensions allows the use of file extensions other than .zip during the lookup. It can be a string corresponding to the extension or an indexed table with the lookup extensions sequence.

Example:

-- test.zip: Hello-World.txt
local z_internal_file = zip.openfile('test/Hello-world.txt')
assert(z_internal_file)
local content = z_internal_file:read('*a')
assert(content == 'Hello, World!\n', content)

Reference:

zip.close

function zip.close(zfile: ZFile {
    close = function,
    files = function,
    open = function,
}) -> success boolean

Close a zfile opened by zip.open.

Example:

local z_file = zip.open('test.zip')
local success = zip.close(z_file)
assert(success == true)

Reference: