A pure MoonBit implementation of ZIP archive extraction

Download zip

Author

wangmingfa

Version

0.1.3

License

Apache-2.0

Repository

github.com/wangmingfa/zipx

Last updated

3 months ago

Downloads

moonbitlang/async0.19.4

#wangmingfa/zipx

A pure MoonBit implementation of ZIP archive extraction, without FFI or system commands.

#Features

Pure MoonBit implementation (no FFI, no system calls)
DEFLATE decompression support
Store (no compression) support
CLI tool for extracting and listing ZIP files
Async file I/O support

#Installation

moon add wangmingfa/zipx

#Usage

#As a Library

#Simple Usage (Async)

import { unzip_file_path } from "wangmingfa/zipx"

async fn {
  // Extract all files to memory (no output directory)
  let extracted = unzip_file_path("/path/to/archive.zip")
  for entry in extracted.iter() {
    let (filename, data) = entry
    // Process extracted file...
  }

  // Extract files to a directory
  let extracted = unzip_file_path("/path/to/archive.zip", output_dir="./output")
  // Files are written to ./output directory
}

#Advanced Usage (Sync)

import { unzip_file, zip_file_open, zip_file_list } from "wangmingfa/zipx"

// Extract all files from a ZIP archive (requires pre-loaded data)
let extracted : Array[(String, Bytes)] = unzip_file(zip_data)
for entry in extracted.iter() {
  let (filename, data) = entry
  // Process extracted file...
}

// Or use lower-level API
let zip = zip_file_open(zip_data)
let files = zip_file_list(zip)  // Get list of filenames
let (filename, data) = zip_file_extract(zip, 0)  // Extract by index

#CLI Tool

# Build the CLI tool
moon build cmd/main/

# List files in a ZIP archive
moon run cmd/main/ list /path/to/archive.zip

# Extract files from a ZIP archive
moon run cmd/main/ unzip /path/to/archive.zip ./output_dir

# Enable debug logging (timing & internal diagnostics)
moon run cmd/main/ --debug unzip /path/to/archive.zip ./output_dir
moon run cmd/main/ list /path/to/archive.zip --debug

#API Reference

#unzip_file_path (Async)

pub async fn unzip_file_path(path : String, output_dir? : String) -> Array[(String, Bytes)] raise

Extracts all files from a ZIP archive specified by file path. This is an async function that reads the file from disk.

Parameters:

path: The path to the ZIP file
output_dir: Optional output directory to extract files to. If not provided, files are returned in memory.

Returns: An array of (filename, data) tuples for all extracted files

Behavior:

Without output_dir: Returns extracted files in memory
With output_dir: Writes files to the specified directory AND returns them in memory

Example:

async fn {
  // Extract to memory only
  let extracted = unzip_file_path("/path/to/archive.zip")

  // Extract to directory
  let extracted = unzip_file_path("/path/to/archive.zip", output_dir="./output")
}

#unzip_file

pub fn unzip_file(data : Bytes) -> Array[(String, Bytes)] raise

Extracts all files from a ZIP archive. Returns an array of (filename, data) tuples.

#zip_file_open

pub fn zip_file_open(data : Bytes) -> ZipFile raise

Opens a ZIP archive for reading. Returns a ZipFile handle.

#zip_file_list

pub fn zip_file_list(zip : ZipFile) -> Array[String]

Returns a list of all filenames in the ZIP archive.

#zip_file_extract

pub fn zip_file_extract(zip : ZipFile, index : Int) -> (String, Bytes) raise

Extracts a single file by index. Returns (filename, data) tuple.

#inflate

pub fn inflate(data : Bytes) -> Bytes

Low-level DEFLATE decompression function.

#CompressionMethod

///|
pub enum CompressionMethod {
  Stored // No compression
  Deflated // DEFLATE compression
  Unsupported(UInt16) // Unsupported method
}

The compression method used in a ZIP file entry.

#Supported Compression Methods

Method	Description
Store (0)	No compression
Deflate (8)	DEFLATE compression

#License

Apache-2.0

BitReader

source

pub struct BitReader {
  data : Bytes
  pos : Int
  buf : UInt64
  bits : Int
}

CentralDirectoryFileHeader

source

pub struct CentralDirectoryFileHeader {
  signature : UInt
  version_made_by : UInt16
  version_needed : UInt16
  flags : UInt16
  compression_method : CompressionMethod
  last_mod_time : UInt16
  last_mod_date : UInt16
  crc32 : UInt
  compressed_size : UInt
  uncompressed_size : UInt
  filename_length : UInt16
  extra_field_length : UInt16
  comment_length : UInt16
  disk_number_start : UInt16
  internal_file_attrs : UInt16
  external_file_attrs : UInt
  local_header_offset : UInt
  filename : String
  extra_field : Bytes
  comment : String
}

Central Directory File Header

Represents a file entry in the ZIP archive's central directory. Contains metadata about each file in the archive.

CompressionMethod

source

pub enum CompressionMethod {
  Stored
  Deflated
  Unsupported(UInt16)
}

Compression Method

The compression method used in a ZIP file entry.

Stored: No compression (stored as-is)
Deflated: DEFLATE compression
Unsupported(UInt16): Unsupported compression method

EndOfCentralDirectoryRecord

source

pub struct EndOfCentralDirectoryRecord {
  signature : UInt
  disk_number : UInt16
  cd_start_disk : UInt16
  cd_entries_on_disk : UInt16
  cd_entries_total : UInt16
  cd_size : UInt
  cd_offset : UInt
  comment_length : UInt16
  comment : String
}

HuffmanTree

source

pub struct HuffmanTree {
  table : Array[Int]
  table_lens : Array[Int]
  table_bits : Int
  first_code : Array[Int]
  first_symbol : Array[Int]
  sorted_symbols : Array[Int]
  bl_count : Array[Int]
  max_code_len : Int
}

InflateResult

source

pub enum InflateResult {
  Continue
  Done
  Error(String)
}

LocalFileHeader

source

pub struct LocalFileHeader {
  signature : UInt
  version_needed : UInt16
  flags : UInt16
  compression_method : CompressionMethod
  last_mod_time : UInt16
  last_mod_date : UInt16
  crc32 : UInt
  compressed_size : UInt
  uncompressed_size : UInt
  filename_length : UInt16
  extra_field_length : UInt16
  filename : String
  extra_field : Bytes
}

ZipFile

source

pub struct ZipFile {
  data : Bytes
  eocd : EndOfCentralDirectoryRecord
  cd_entries : Array[CentralDirectoryFileHeader]
}

ZipFile

Represents an open ZIP archive file. Use zip_file_open to create an instance.

inflate

source

fn inflate(data : Bytes, uncompressed_size : Int) -> Bytes raise

DEFLATE Decompression

Decompresses DEFLATE-compressed data using the inflate algorithm.

Parameters

data: The compressed data bytes

Returns

The decompressed data as Bytes

Example

let decompressed = inflate(compressed_data)

unzip_file

source

fn unzip_file(data : Bytes) -> Array[(String, Bytes)] raise

Unzip All Files

Extracts all files from a ZIP archive at once.

Parameters

data: The raw bytes of the ZIP file

Returns

An array of tuples (filename, data) for all extracted files

Throws

If the ZIP file is invalid or corrupted
If decompression fails for any file

Example

let extracted = unzip_file(zip_data)
for entry in extracted.iter() {
  let (filename, data) = entry
  println("Extracted: " + filename)
}

unzip_file_path

source

async fn unzip_file_path(path : String, output_dir? : String) -> Array[(String, Bytes)]

Unzip from File Path

Extracts all files from a ZIP archive specified by file path. This is an async function that reads the file from disk.

If output_dir is provided, files will be written to that directory. Otherwise, the extracted files are returned as an array.

Parameters

path: The path to the ZIP file
output_dir: Optional output directory to extract files to

Returns

An array of tuples (filename, data) for all extracted files

Throws

If the file cannot be read
If the ZIP file is invalid or corrupted
If decompression fails for any file

Example

async fn {
  // Just get the files in memory
  let extracted = unzip_file_path("/path/to/archive.zip")

  // Extract to a directory
  let extracted = unzip_file_path("/path/to/archive.zip", output_dir="./output")
}

zip_file_extract

source

fn zip_file_extract(zip : ZipFile, index : Int) -> (String, Bytes) raise

Extract a Single File

Extracts a single file from the ZIP archive by index.

Parameters

zip: The open ZIP file handle
index: The zero-based index of the file to extract

Returns

A tuple of (filename, data) containing the extracted file

Throws

If the index is out of bounds
If the local file header cannot be found
If decompression fails

Example

let (filename, data) = zip_file_extract(zip, 0)

zip_file_list

source

fn zip_file_list(zip : ZipFile) -> Array[String]

List Files in ZIP

Returns a list of all filenames in the ZIP archive.

Parameters

zip: The open ZIP file handle

Returns

An array of filenames in the order they appear in the archive

Example

let files = zip_file_list(zip)
for filename in files.iter() {
  println(filename)
}

zip_file_open

source

fn zip_file_open(data : Bytes) -> ZipFile raise

Open a ZIP File

Opens a ZIP archive from byte data and returns a ZipFile handle.

Parameters

data: The raw bytes of the ZIP file

Returns

A ZipFile handle for reading the archive

Throws

If the end of central directory record cannot be found
If the central directory is corrupted

Example

let zip = zip_file_open(zip_data)

let files = zip_file_list(zip)

Source Files

Site source Report issue Packages Build queue Skills Statistics

zipx

#wangmingfa/zipx

#Features

#Installation

#Usage

#As a Library

#Simple Usage (Async)

#Advanced Usage (Sync)

#CLI Tool

#API Reference

#unzip_file_path (Async)

#unzip_file

#zip_file_open

#zip_file_list

#zip_file_extract

#inflate

#CompressionMethod

#Supported Compression Methods

#License

#BitReader

#CentralDirectoryFileHeader

Central Directory File Header

#CompressionMethod

Compression Method

#EndOfCentralDirectoryRecord

#HuffmanTree

#InflateResult

#LocalFileHeader

#ZipFile

ZipFile

#inflate

DEFLATE Decompression

Parameters

Returns

Example

#unzip_file

Unzip All Files

Parameters

Returns

Throws

Example

#unzip_file_path

Unzip from File Path

Parameters

Returns

Throws

Example

#zip_file_extract

Extract a Single File

Parameters

Returns

Throws

Example

#zip_file_list

List Files in ZIP

Parameters

Returns

Example

#zip_file_open

Open a ZIP File

Parameters

Returns

Throws

Example

Source Files

BitReader

CentralDirectoryFileHeader

CompressionMethod

EndOfCentralDirectoryRecord

HuffmanTree

InflateResult

LocalFileHeader

ZipFile

inflate

unzip_file

unzip_file_path

zip_file_extract

zip_file_list

zip_file_open