diff --git a/docs/intro.md b/docs/intro.md index 3a58324..4307a00 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -1,7 +1,7 @@ # Reference -# `ZipEntry` +## `ZipEntry` A single entry (a file or a directory) in a ZIP file, and its properties. ```luau @@ -21,7 +21,7 @@ export type ZipEntry = { children: { ZipEntry }, } ``` -## Properties +### Properties - **name** - File path within ZIP, '/' suffix indicates directory - **versionMadeBy** - Version of software and OS that created the ZIP - **compressedSize** - Compressed size in bytes @@ -36,8 +36,8 @@ export type ZipEntry = { - **parent** - Parent directory entry, `nil` if entry is root - **children** - Children of the entry, if it was a directory, empty array for files -## API -### `new` +### API +#### `new` > [!IMPORTANT] > 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 @@ -54,7 +54,7 @@ ZipEntry.new( ``` [ZipEntry.new]: #new -### `isSymlink` +#### `isSymlink` Returns whether the entry is a symlink. ```luau ZipEntry:isSymlink(): boolean @@ -62,7 +62,7 @@ ZipEntry:isSymlink(): boolean ``` [ZipEntry:isSymlink]: #isSymlink -### `getPath` +#### `getPath` 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. @@ -76,7 +76,7 @@ ZipEntry:getPath(): string ``` [ZipEntry:getPath]: #getPath -### `getSafePath` +#### `getSafePath` 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`. ```luau @@ -85,7 +85,7 @@ ZipEntry:getSafePath(): string? ``` [ZipEntry:getSafePath]: #getSafePath -### `sanitizePath` +#### `sanitizePath` Sanitizes the path of the entry, potentially losing information, but ensuring the path is safe to use for extraction. ```luau @@ -94,7 +94,7 @@ ZipEntry:sanitizePath(): string ``` [ZipEntry:sanitizePath]: #sanitizePath -### `compressionEfficiency` +#### `compressionEfficiency` 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. @@ -104,7 +104,7 @@ ZipEntry:compressionEfficiency(): number? ``` [ZipEntry:compressionEfficiency]: #compressionEfficiency -### `isFile` +#### `isFile` Returns whether the entry is a file, i.e., not a directory or symlink. ```luau ZipEntry:isFile(): boolean @@ -112,7 +112,7 @@ ZipEntry:isFile(): boolean ``` [ZipEntry:isFile]: #isFile -### `unixMode` +#### `unixMode` Parses the entry's attributes to extract a UNIX mode, represented as a [UnixMode]. ```luau ZipEntry:unixMode(): UnixMode? @@ -121,15 +121,15 @@ ZipEntry:unixMode(): UnixMode? [ZipEntry:unixMode]: #unixMode -## Types -### `MadeByOS` +### Types +#### `MadeByOS` The OS that created the ZIP. ```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" ``` [MadeByOS]: #MadeByOS -### `CompressionMethod` +#### `CompressionMethod` The method used to compress the file: - `STORE` - No compression - `DEFLATE` - Compressed raw deflate chunks @@ -138,7 +138,7 @@ export type CompressionMethod = "STORE" | "DEFLATE" ``` [CompressionMethod]: #CompressionMethod -### `ZipEntryProperties` +#### `ZipEntryProperties` > [!IMPORTANT] > 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 @@ -166,7 +166,7 @@ export type ZipEntryProperties = { - **crc** - CRC32 checksum of the uncompressed data [ZipEntryProperties]: #ZipEntryProperties -### `UnixMode` +#### `UnixMode` A object representation of the UNIX mode. ```luau export type UnixMode = { @@ -180,7 +180,7 @@ export type UnixMode = { [UnixMode]: #UnixMode [ZipEntry]: #ZipEntry -# `ZipReader` +## `ZipReader` 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. @@ -193,15 +193,15 @@ export type ZipReader = { root: ZipEntry, } ``` -## Properties +### Properties - **data** - The buffer containing the raw bytes of the ZIP - **comment** - Comment associated with the ZIP - **entries** - The decoded entries present - **directories** - The directories and their respective entries - **root** - The entry of the root directory -## API -### `new` +### API +#### `new` Creates a new ZipReader instance from the raw bytes of a ZIP file. **Errors if the ZIP file is invalid.** @@ -213,7 +213,7 @@ ZipReader.new( ``` [ZipReader.new]: #new -### `parseCentralDirectory` +#### `parseCentralDirectory` > [!IMPORTANT] > 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 @@ -228,7 +228,7 @@ ZipReader:parseCentralDirectory() ``` [ZipReader:parseCentralDirectory]: #parseCentralDirectory -### `buildDirectoryTree` +#### `buildDirectoryTree` > [!IMPORTANT] > 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 @@ -241,7 +241,7 @@ ZipReader:buildDirectoryTree() ``` [ZipReader:buildDirectoryTree]: #buildDirectoryTree -### `findEntry` +#### `findEntry` Finds a [ZipEntry] by its path in the ZIP archive. ```luau ZipReader:findEntry( @@ -251,7 +251,7 @@ ZipReader:findEntry( ``` [ZipReader:findEntry]: #findEntry -### `extract` +#### `extract` Extracts the specified [ZipEntry] from the ZIP archive. See [ZipReader:extractDirectory] for extracting directories. ```luau @@ -263,7 +263,7 @@ ZipReader:extract( ``` [ZipReader:extract]: #extract -### `extractDirectory` +#### `extractDirectory` Extracts all the files in a specified directory, skipping any directory entries. **Errors if [ZipReader:extract] errors on an entry in the directory.** @@ -276,7 +276,7 @@ ZipReader:extractDirectory( ``` [ZipReader:extractDirectory]: #extractDirectory -### `listDirectory` +#### `listDirectory` Lists the entries within a specified directory path. ```luau ZipReader:listDirectory( @@ -286,7 +286,7 @@ ZipReader:listDirectory( ``` [ZipReader:listDirectory]: #listDirectory -### `walk` +#### `walk` Recursively walks through the ZIP file, calling the provided callback for each entry with the current entry and its depth. ```luau @@ -296,7 +296,7 @@ ZipReader:walk( ``` [ZipReader:walk]: #walk -### `getStats` +#### `getStats` Retrieves statistics about the ZIP file. ```luau ZipReader:getStats(): ZipStatistics @@ -305,8 +305,8 @@ ZipReader:getStats(): ZipStatistics [ZipReader:getStats]: #getStats -## Types -### `ZipStatistics` +### Types +#### `ZipStatistics` ```luau export type ZipStatistics = {