ArArchiveKit

A simple, 0-dependency Swift package for reading and writing ar archives. Inspired by ar.

Table of Contents

• ArArchiveKit
• Table of Contents
  • ar Variations
  • Installation
    • Swift Package Manager
  • Usage
    • Writing Archives
    • Reading Archives
      • Iteration
      • Subscript
  • Examples
  • Other Platforms
    • Windows
  • Contributing

Created by gh-md-toc

Documentation is available here.

ar Variations

ArArchiveKit supports the "Common", BSD, and SVR4/GNU variations of ar as described in FreeBSD manpages.

Support for symbol tables may come soon.

Installation

Swift Package Manager

Add this to the dependencies array in Package.swift:

.package(url: "https://github.com/LebJe/ArArchiveKit.git", from: "0.3.0")

Also add this to the targets array in the aforementioned file:

.product(name: "ArArchiveKit", package: "ArArchiveKit")

Usage

Writing Archives

To write archives, you'll need a ArArchiveWriter:

var writer = ArArchiveWriter()

Once you have your writer, you must create a Header, that describes the file you wish to add to your archive:

var time: Int = 1615929568

// You can also use date
let date: Date = ...
time = Int(date.timeIntervalSince1970)

let header = Header(
	// `name` will be truncated to 16 characters.
	name: "hello.txt",
	modificationTime: time
)

Once you have your Header, you can write it, along with the contents of your file, to the archive:

// Without Foundation
var contents = [
	UInt8(ascii: "H"),
	UInt8(ascii: "e"),
	UInt8(ascii: "l"),
	UInt8(ascii: "l"),
	UInt8(ascii: "o"),
]

// With Foundation

let myData: Data = "Hello".data(using .utf8)!

contents = Array<UInt8>(myData)

writer.addFile(header: header, contents: contents)

If you have a text file, use the overloaded version of addFile:

writer.addFile(header: header, contents: "Hello")

Once you have added your files, you can get the archive like this:

// Call finalize to get the binary representation (Array<UInt8>) of the archive.
let bytes = writer.finalize()

// You convert it to data like this:
let data = Data(bytes)

// And write it:
try data.write(to: URL(fileURLWithPath: "myArchive.a"))

Reading Archives

To read archives, you need an ArArchiveReader:

// myData is the bytes of the archive.
let myData: Data = ...

let reader = ArArchiveReader(archive: Array<UInt8>(myData))

Once you have your reader, there are several ways you can retrieve the data:

Iteration

You can iterate though all the files in the archive like this:

for (header, data) in reader {
   // `data` is `Array<UInt8>` that contains the raw bytes of the file in the archive.
   // `header` is the `Header` that describes the `data`.

   // if you know `data` is a `String`, then you can use this initializer:
   let str = String(data)
}

Subscript

Accessing data through the subscript is useful when you only need to access a few items in a large archive:

// The subscript provides you with random access to any file in the archive:
let firstFile = reader[0]
let fifthFile = reader[6]

You can also use the version of the subscript that takes a Header - useful for when you have a Header, but not the index of that header.

let header = reader.headers.first(where: { $0.name.contains(".swift") })!
let data = reader[header: header]

Examples

• Exaples/ReaderAndWriter: This example shows how to use ArArchiveKit to read or extract entries from any archive using only Darwin.C (macOS), Glibc (Linux) or ucrt (Windows (not tested)).

Other Platforms

ArArchiveKit doesn't depend on any library, Foundation, or Darwin/Glibc/ucrt - only the Swift standard library. It should compile on any platform where the standard library compiles.

Windows

ArArchiveKit is currently being built on Windows, but not tested, as the Swift Package Manager Resources doesn't seem to work (or isn't available) on Windows.

Contributing

Before committing, please install pre-commit, and swift-format and install the pre-commit hook:

$ brew bundle # install the packages specified in Brewfile
$ pre-commit install

# Commit your changes.

To install pre-commit on other platforms, refer to the documentation.