classDocs / Zip

Zip

classsharedsource

Object → Zip

The zip (.zip) archive.

Parses stored, deflated and LZMA files (ZIP64 too), builds archives with deflated or LZMA files, the files of a parsed archive are copied without recompression.

lua

local zip = Zip()
zip:addFile( "docs/readme.txt", "hello" )

local data = zip:compile()
print( Zip( data ):readFile( "docs/readme.txt" ) ) -- hello

Constructor

Zip(data: string?): Zip

Fields

Name	Type	Description
`comment`	`string`	The comment of the archive.
`files`	`Zip.File[]`	The files of the archive.
`file_count`	`integer`	The number of files.
`file_indexes`	`table<string, integer>`	The indexes of files in `files` by their paths.
`data`	`string \| nil`	The parsed archive data, the content of not yet read files.
`Signature`	`integer`	`PK\3\4` as little endian uint32.

Methods

`addDirectory`	Adds the directory to the archive, replaces the existing entry with the same path.
`addFile`	Adds the file to the archive, replaces the existing file with the same path.
`compile`	Builds the .zip data of the archive.
`getFile`	Returns the file of the archive.
`parse`	Replaces the archive with the parsed .zip data.
`readFile`	Returns the uncompressed content of the file of the archive.
`removeFile`	Removes the file from the archive.
`verify`	Decompresses all files and checks their CRC-32 checksums.

#Zip:addDirectory

sharedsource

function Zip:addDirectory(directory_path: string): Zip.File

Adds the directory to the archive, replaces the existing entry with the same path.

Directories don't have to be added for their files, but some tools show empty directories only this way.

Parameters

Name	Type	Description
`directory_path`	`string`	The path of the directory inside of the archive, `/` is appended if missing.

Returns

Type	Name	Description
`Zip.File`	`file`	The added directory entry.

#Zip:addFile

sharedasyncsource

async function Zip:addFile(file_path: string, content: string, level?: integer, method?: Zip.Method): Zip.File

Adds the file to the archive, replaces the existing file with the same path.

The content is compressed right away, it is stored as is if compression doesn't make it smaller.

LZMA uses lzma.compress, so it runs on a separate thread when HolyLib is installed and the call is made from a coroutine.

Throws an error if method is not STORED, DEFLATE or LZMA.

Parameters

Name	Type	Description
`file_path`	`string`	The path of the file inside of the archive, e.g. `docs/readme.txt`.
`content`	`string`	The file content.
`level`optional	`integer`	The compression level ( 0 - 9 ), `0` stores the content without compression, `6` by default for deflate, `5` for LZMA.
`method`optional	`Zip.Method`	The compression method, `0` (stored), `8` (deflate) or `14` (LZMA), `8` by default.

Returns

Type	Name	Description
`Zip.File`	`file`	The added file.

#Zip:compile

sharednodiscardsource

function Zip:compile(): string

Builds the .zip data of the archive.

Files are written with the extended timestamp, ZIP64 records are added only for more than 65534 files.

Returns

Type	Name	Description
`string`	`data`	The `.zip` data.

#Zip:getFile

sharednodiscardsource

function Zip:getFile(file_path: string): Zip.File | nil

Returns the file of the archive.

Parameters

Name	Type	Description
`file_path`	`string`	The path of the file inside of the archive.

Returns

Type	Name	Description
`Zip.File \| nil`	`file`	The file, `nil` if there is no such file.

#Zip:parse

sharedsource

function Zip:parse(data: string)

Replaces the archive with the parsed .zip data.

File contents are not copied, they are read from the data on demand by readFile.

Multi-disk archives are not supported.

Parameters

Name	Type	Description
`data`	`string`	The `.zip` data.

#Zip:readFile

sharednodiscardsource

function Zip:readFile(file_path: string): string | nil

Returns the uncompressed content of the file of the archive.

Throws an error if the file is encrypted, uses an unsupported compression method or its data is malformed.

Parameters

Name	Type	Description
`file_path`	`string`	The path of the file inside of the archive.

Returns

Type	Name	Description
`string \| nil`	`content`	The file content, `nil` if there is no such file.

#Zip:removeFile

sharedsource

function Zip:removeFile(file_path: string): boolean

Removes the file from the archive.

Parameters

Name	Type	Description
`file_path`	`string`	The path of the file inside of the archive.

Returns

Type	Name	Description
`boolean`	`removed`	`true` if the file was removed, `false` if there is no such file.

#Zip:verify

sharednodiscardsource

function Zip:verify(): boolean, string | nil

Decompresses all files and checks their CRC-32 checksums.

Encrypted files and files with unsupported compression methods are reported as damaged.

Returns

Type	Name	Description
`boolean`	`is_valid`	`true` if all files are fine.
`string \| nil`	`file_path`	The path of the first damaged file.