libarchive

libarchive bindings for reading and writing archive formats in Kit

Files

Dependencies

No Kit package dependencies.

Installation

kit add gitlab.com/kit-lang/packages/kit-libarchive.git

System Requirements

This package links against libarchive. Install the system library before running interpreter or native builds.

Usage

import Kit.LibArchive as LibArchive

main = fn =>
  # List entries in an archive
  match LibArchive.list "project.tar.gz"
    | Ok entries ->
      println ("Found " ++ (show (List.length entries)) ++ " entries:")
      List.map (fn(e) => println ("  " ++ e)) entries
      no-op
    | Err e -> println ("Error: " ++ e)

  # Extract a single file from an archive
  match LibArchive.extract-file "project.tar.gz" "README.md"
    | Ok contents -> println ("Contents: " ++ contents)
    | Err e -> println ("Error: " ++ e)

  # Extract entire archive to a directory
  match LibArchive.extract "project.tar.gz" "/tmp/output"
    | Ok _ -> println "Archive extracted"
    | Err e -> println ("Error: " ++ e)

  # Create a tar.gz archive from files
  match LibArchive.create-tar-gz "/tmp/output.tar.gz" ["kit.toml", "README.md"]
    | Ok _ -> println "Archive created"
    | Err e -> println ("Error: " ++ e)

main

Developer Notes

The public Kit API returns Result values and keeps raw FFI details private to src/libarchive.kit.

The C wrapper exposes result-returning entry points and prefixes errors with __KIT_ARCHIVE_ERROR__: before the Kit layer converts them to Err values. Successful operations return normal strings, with empty strings used for operations that do not produce payload data.

The local native library is named kit_libarchive_ffi so development builds can coexist with an installed @kit/libarchive package without linking against the wrong wrapper.

Development

Running Examples

Run examples with the interpreter:

kit run examples/basic.kit

Compile examples to a native binary:

kit build examples/basic.kit && ./basic

Running Tests

Run the test suite:

kit test

Run the test suite with coverage:

kit test --coverage

Running Parity

Compare interpreter and native output:

kit parity --no-spinner --failures-only

Run parity after changing src/libarchive.kit, c/kit_libarchive_ffi.c, c/kit_archive.h, or native linking settings in kit.toml.

Running kit dev

Run the standard development workflow (format, check, test):

kit dev

This will:

1. Format and check source files in src/
2. Run tests in tests/ with coverage

Generating Documentation

Generate API documentation from doc comments:

kit doc

Note: Kit sources with doc comments (##) will generate HTML documents in docs/*.html

Cleaning Build Artifacts

Remove generated files, caches, and build artifacts:

kit task clean

Note: Defined in kit.toml.

Local Installation

To install this package locally for development:

kit install

This installs the package to ~/.kit/packages/@kit/libarchive/, making it available for import as Kit.LibArchive in other projects.

License

This package is released under the MIT License - see LICENSE for details.

libarchive is released under the BSD 3-Clause License.

Exported Functions & Types

list

List all entry names in an archive file.

Supports tar, zip, 7z, gzip, xz, and many other formats. Format is auto-detected from the file contents.

Parameters:

Returns:

NonEmptyString -> Result [String] String

match list "data.tar.gz"
  | Ok entries ->
    println ("Found " ++ (show (List.length entries)) ++ " entries")
    List.map (fn(e) => println ("  " ++ e)) entries
  | Err e -> println "Error: ${e}"

extract

Extract all entries from an archive to a directory.

The destination directory must already exist. Supports tar, zip, 7z, and many other formats with automatic detection.

Parameters:

Returns:

NonEmptyString -> NonEmptyString -> Result Unit String

match extract "data.tar.gz" "/tmp/output"
  | Ok _ -> println "Extracted successfully!"
  | Err e -> println "Extraction failed: ${e}"

extract-file

Extract a single file from an archive and return its contents as a string.

Parameters:

Returns:

NonEmptyString -> NonEmptyString -> Result String String

match extract-file "data.tar.gz" "README.md"
  | Ok contents -> println contents
  | Err e -> println "Error: ${e}"

create-tar-gz

Create a .tar.gz archive from a list of file paths.

Parameters:

Returns:

NonEmptyString -> [String] -> Result Unit String

files = ["src/main.kit", "src/util.kit", "kit.toml"]
match create-tar-gz "release.tar.gz" files
  | Ok _ -> println "Archive created!"
  | Err e -> println "Error: ${e}"