0x5eal/luau-unzip
1
1
Fork 0
mirror of https://github.com/0x5eal/luau-unzip.git synced 2025-04-06 23:30:55 +01:00
Code Issues Projects Releases Packages Wiki Activity

merge: origin/main->main

Browse source
This commit is contained in:
Erica Marigold 2025-02-23 18:55:24 +00:00
commit d198f7f038
Signed by: DevComp
SSH key fingerprint: SHA256:jD3oMT4WL3WHPJQbrjC3l5feNCnkv7ndW8nYaHX5wFw
1 changed files with 30 additions and 30 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

60
docs/intro.md
View file

@ -1,7 +1,7 @@
<!-- This file was @generated by `lune run docsgen`, please do not edit this manually, changes will be overwritten. --> <!-- This file was @generated by `lune run docsgen`, please do not edit this manually, changes will be overwritten. -->
# Reference # Reference
# `ZipEntry` ## `ZipEntry`
A single entry (a file or a directory) in a ZIP file, and its properties. A single entry (a file or a directory) in a ZIP file, and its properties.
```luau ```luau
@ -21,7 +21,7 @@ export type ZipEntry = {
children: { ZipEntry }, children: { ZipEntry },
} }
``` ```
## Properties ### Properties
- **name** - File path within ZIP, '/' suffix indicates directory - **name** - File path within ZIP, '/' suffix indicates directory
- **versionMadeBy** - Version of software and OS that created the ZIP - **versionMadeBy** - Version of software and OS that created the ZIP
- **compressedSize** - Compressed size in bytes - **compressedSize** - Compressed size in bytes
@ -36,8 +36,8 @@ export type ZipEntry = {
- **parent** - Parent directory entry, `nil` if entry is root - **parent** - Parent directory entry, `nil` if entry is root
- **children** - Children of the entry, if it was a directory, empty array for files - **children** - Children of the entry, if it was a directory, empty array for files
## API ### API
### `new` #### `new`
> [!IMPORTANT] > [!IMPORTANT]
> This is a private API. It may be exported publicly, but try to avoid > This is a private API. It may be exported publicly, but try to avoid
> using this API, since it can have breaking changes at any time without > using this API, since it can have breaking changes at any time without
@ -54,7 +54,7 @@ ZipEntry.new(
``` ```
[ZipEntry.new]: #new [ZipEntry.new]: #new
### `isSymlink` #### `isSymlink`
Returns whether the entry is a symlink. Returns whether the entry is a symlink.
```luau ```luau
ZipEntry:isSymlink(): boolean ZipEntry:isSymlink(): boolean
@ -62,7 +62,7 @@ ZipEntry:isSymlink(): boolean
``` ```
[ZipEntry:isSymlink]: #isSymlink [ZipEntry:isSymlink]: #isSymlink
### `getPath` #### `getPath`
Resolves the path of the entry based on its relationship with other entries. It is recommended to use this Resolves the path of the entry based on its relationship with other entries. It is recommended to use this
method instead of accessing the `name` property directly, although they should be equivalent. method instead of accessing the `name` property directly, although they should be equivalent.
@ -76,7 +76,7 @@ ZipEntry:getPath(): string
``` ```
[ZipEntry:getPath]: #getPath [ZipEntry:getPath]: #getPath
### `getSafePath` #### `getSafePath`
Resolves the path of the entry based on its relationship with other entries and returns it Resolves the path of the entry based on its relationship with other entries and returns it
only if it is safe to use for extraction, otherwise returns `nil`. only if it is safe to use for extraction, otherwise returns `nil`.
```luau ```luau
@ -85,7 +85,7 @@ ZipEntry:getSafePath(): string?
``` ```
[ZipEntry:getSafePath]: #getSafePath [ZipEntry:getSafePath]: #getSafePath
### `sanitizePath` #### `sanitizePath`
Sanitizes the path of the entry, potentially losing information, but ensuring the path is Sanitizes the path of the entry, potentially losing information, but ensuring the path is
safe to use for extraction. safe to use for extraction.
```luau ```luau
@ -94,7 +94,7 @@ ZipEntry:sanitizePath(): string
``` ```
[ZipEntry:sanitizePath]: #sanitizePath [ZipEntry:sanitizePath]: #sanitizePath
### `compressionEfficiency` #### `compressionEfficiency`
Calculates the compression efficiency of the entry, or `nil` if the entry is a directory. Calculates the compression efficiency of the entry, or `nil` if the entry is a directory.
Uses the formula: `round((1 - compressedSize / size) * 100)` and outputs a percentage. Uses the formula: `round((1 - compressedSize / size) * 100)` and outputs a percentage.
@ -104,7 +104,7 @@ ZipEntry:compressionEfficiency(): number?
``` ```
[ZipEntry:compressionEfficiency]: #compressionEfficiency [ZipEntry:compressionEfficiency]: #compressionEfficiency
### `isFile` #### `isFile`
Returns whether the entry is a file, i.e., not a directory or symlink. Returns whether the entry is a file, i.e., not a directory or symlink.
```luau ```luau
ZipEntry:isFile(): boolean ZipEntry:isFile(): boolean
@ -112,7 +112,7 @@ ZipEntry:isFile(): boolean
``` ```
[ZipEntry:isFile]: #isFile [ZipEntry:isFile]: #isFile
### `unixMode` #### `unixMode`
Parses the entry's attributes to extract a UNIX mode, represented as a [UnixMode]. Parses the entry's attributes to extract a UNIX mode, represented as a [UnixMode].
```luau ```luau
ZipEntry:unixMode(): UnixMode? ZipEntry:unixMode(): UnixMode?
@ -121,15 +121,15 @@ ZipEntry:unixMode(): UnixMode?
[ZipEntry:unixMode]: #unixMode [ZipEntry:unixMode]: #unixMode
## Types ### Types
### `MadeByOS` #### `MadeByOS`
The OS that created the ZIP. The OS that created the ZIP.
```luau ```luau
export type MadeByOS = "FAT" | "AMIGA" | "VMS" | "UNIX" | "VM/CMS" | "Atari ST" | "OS/2" | "MAC" | "Z-System" | "CP/M" | "NTFS" | "MVS" | "VSE" | "Acorn RISCOS" | "VFAT" | "Alternate MVS" | "BeOS" | "TANDEM" | "OS/400" | "OS/X" | "Unknown" export type MadeByOS = "FAT" | "AMIGA" | "VMS" | "UNIX" | "VM/CMS" | "Atari ST" | "OS/2" | "MAC" | "Z-System" | "CP/M" | "NTFS" | "MVS" | "VSE" | "Acorn RISCOS" | "VFAT" | "Alternate MVS" | "BeOS" | "TANDEM" | "OS/400" | "OS/X" | "Unknown"
``` ```
[MadeByOS]: #MadeByOS [MadeByOS]: #MadeByOS
### `CompressionMethod` #### `CompressionMethod`
The method used to compress the file: The method used to compress the file:
- `STORE` - No compression - `STORE` - No compression
- `DEFLATE` - Compressed raw deflate chunks - `DEFLATE` - Compressed raw deflate chunks
@ -138,7 +138,7 @@ export type CompressionMethod = "STORE" | "DEFLATE"
``` ```
[CompressionMethod]: #CompressionMethod [CompressionMethod]: #CompressionMethod
### `ZipEntryProperties` #### `ZipEntryProperties`
> [!IMPORTANT] > [!IMPORTANT]
> This is a private type. It may be exported publicly, but try to avoid > This is a private type. It may be exported publicly, but try to avoid
> using it, since its definition can have a breaking change at any time > using it, since its definition can have a breaking change at any time
@ -166,7 +166,7 @@ export type ZipEntryProperties = {
- **crc** - CRC32 checksum of the uncompressed data - **crc** - CRC32 checksum of the uncompressed data
[ZipEntryProperties]: #ZipEntryProperties [ZipEntryProperties]: #ZipEntryProperties
### `UnixMode` #### `UnixMode`
A object representation of the UNIX mode. A object representation of the UNIX mode.
```luau ```luau
export type UnixMode = { export type UnixMode = {
@ -180,7 +180,7 @@ export type UnixMode = {
[UnixMode]: #UnixMode [UnixMode]: #UnixMode
[ZipEntry]: #ZipEntry [ZipEntry]: #ZipEntry
# `ZipReader` ## `ZipReader`
The main class which represents a decoded state of a ZIP file, holding references The main class which represents a decoded state of a ZIP file, holding references
to its entries. This is the primary point of interaction with the ZIP file's contents. to its entries. This is the primary point of interaction with the ZIP file's contents.
@ -193,15 +193,15 @@ export type ZipReader = {
root: ZipEntry, root: ZipEntry,
} }
``` ```
## Properties ### Properties
- **data** - The buffer containing the raw bytes of the ZIP - **data** - The buffer containing the raw bytes of the ZIP
- **comment** - Comment associated with the ZIP - **comment** - Comment associated with the ZIP
- **entries** - The decoded entries present - **entries** - The decoded entries present
- **directories** - The directories and their respective entries - **directories** - The directories and their respective entries
- **root** - The entry of the root directory - **root** - The entry of the root directory
## API ### API
### `new` #### `new`
Creates a new ZipReader instance from the raw bytes of a ZIP file. Creates a new ZipReader instance from the raw bytes of a ZIP file.
**Errors if the ZIP file is invalid.** **Errors if the ZIP file is invalid.**
@ -213,7 +213,7 @@ ZipReader.new(
``` ```
[ZipReader.new]: #new [ZipReader.new]: #new
### `parseCentralDirectory` #### `parseCentralDirectory`
> [!IMPORTANT] > [!IMPORTANT]
> This is a private API. It may be exported publicly, but try to avoid > This is a private API. It may be exported publicly, but try to avoid
> using this API, since it can have breaking changes at any time without > using this API, since it can have breaking changes at any time without
@ -228,7 +228,7 @@ ZipReader:parseCentralDirectory()
``` ```
[ZipReader:parseCentralDirectory]: #parseCentralDirectory [ZipReader:parseCentralDirectory]: #parseCentralDirectory
### `buildDirectoryTree` #### `buildDirectoryTree`
> [!IMPORTANT] > [!IMPORTANT]
> This is a private API. It may be exported publicly, but try to avoid > This is a private API. It may be exported publicly, but try to avoid
> using this API, since it can have breaking changes at any time without > using this API, since it can have breaking changes at any time without
@ -241,7 +241,7 @@ ZipReader:buildDirectoryTree()
``` ```
[ZipReader:buildDirectoryTree]: #buildDirectoryTree [ZipReader:buildDirectoryTree]: #buildDirectoryTree
### `findEntry` #### `findEntry`
Finds a [ZipEntry] by its path in the ZIP archive. Finds a [ZipEntry] by its path in the ZIP archive.
```luau ```luau
ZipReader:findEntry( ZipReader:findEntry(
@ -251,7 +251,7 @@ ZipReader:findEntry(
``` ```
[ZipReader:findEntry]: #findEntry [ZipReader:findEntry]: #findEntry
### `extract` #### `extract`
Extracts the specified [ZipEntry] from the ZIP archive. See [ZipReader:extractDirectory] for Extracts the specified [ZipEntry] from the ZIP archive. See [ZipReader:extractDirectory] for
extracting directories. extracting directories.
```luau ```luau
@ -263,7 +263,7 @@ ZipReader:extract(
``` ```
[ZipReader:extract]: #extract [ZipReader:extract]: #extract
### `extractDirectory` #### `extractDirectory`
Extracts all the files in a specified directory, skipping any directory entries. Extracts all the files in a specified directory, skipping any directory entries.
**Errors if [ZipReader:extract] errors on an entry in the directory.** **Errors if [ZipReader:extract] errors on an entry in the directory.**
@ -276,7 +276,7 @@ ZipReader:extractDirectory(
``` ```
[ZipReader:extractDirectory]: #extractDirectory [ZipReader:extractDirectory]: #extractDirectory
### `listDirectory` #### `listDirectory`
Lists the entries within a specified directory path. Lists the entries within a specified directory path.
```luau ```luau
ZipReader:listDirectory( ZipReader:listDirectory(
@ -286,7 +286,7 @@ ZipReader:listDirectory(
``` ```
[ZipReader:listDirectory]: #listDirectory [ZipReader:listDirectory]: #listDirectory
### `walk` #### `walk`
Recursively walks through the ZIP file, calling the provided callback for each entry Recursively walks through the ZIP file, calling the provided callback for each entry
with the current entry and its depth. with the current entry and its depth.
```luau ```luau
@ -296,7 +296,7 @@ ZipReader:walk(
``` ```
[ZipReader:walk]: #walk [ZipReader:walk]: #walk
### `getStats` #### `getStats`
Retrieves statistics about the ZIP file. Retrieves statistics about the ZIP file.
```luau ```luau
ZipReader:getStats(): ZipStatistics ZipReader:getStats(): ZipStatistics
@ -305,8 +305,8 @@ ZipReader:getStats(): ZipStatistics
[ZipReader:getStats]: #getStats [ZipReader:getStats]: #getStats
## Types ### Types
### `ZipStatistics` #### `ZipStatistics`
```luau ```luau
export type ZipStatistics = { export type ZipStatistics = {