GithubHelp home page GithubHelp logo

lebje / cpioarchivekit Goto Github PK

View Code? Open in Web Editor NEW
3.0 2.0 0.0 15.87 MB

A simple, 0-dependency Swift package for reading and writing cpio archives.

Home Page: https://lebje.github.io/CPIOArchiveKit/

License: MIT License

Ruby 0.16% Swift 99.84%
macos linux windows swift swift5 cpio cpio-archives swift-library

cpioarchivekit's Introduction

CPIOArchiveKit

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

Swift 5.3 SPM Compatible Build and Test

Table of Contents

Created by gh-md-toc

Documentation is available here.

Installation

Swift Package Manager

Add this to the dependencies array in Package.swift:

.package(url: "https://github.com/LebJe/CPIOArchiveKit.git", from: "0.0.2")

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

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

Usage

Writing Archives

To write archives, you'll need a CPIOArchiveWriter:

var writer = CPIOArchiveWriter()

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)

// File
let header = Header(
   name: "hello.txt",
   mode: FileMode(0o644, modes: [.regular]),
   modificationTime: time
)

// Directory
let header = Header(
   name: "dir/",
   mode: FileMode(0o644, modes: [.directory]),
   modificationTime: time
)

Checksums

If you would like to provide a cpio checksum with the Header you created above, there are two ways to do so.

Computed Checksum
// Compute the checksum.
let fileContents: [UInt8] = ...
let checksum = Checksum(bytes: fileContents)
Pre-computed Checksum
let preComputedChecksum = 123
let checksum = Checksum(sum: preComputedChecksum)
l

Once you have a checksum, add it to the checksum parameter of your Header:

Header(..., checksum: checksum, ...)

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

// Without Foundation
var contents = Array("Hello".utf8)

// 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")

For directories, omit the contents parameter in addFile. For symlinks, set the contents parameter to the file or directory the link points to.

Once you have added your files, you must call finalize() to create the archive and return the data:

// The binary representation (Array<UInt8>) of the created 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.cpio"))

if you want to reuse writer, call finalize(clear: true) instead, which will clear the state inside writer.

Reading Archives

To read archives, you need an CPIOArchiveReader:

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

let reader = CPIOArchiveReader(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]

FileMode

Once you have retrived a FileMode from a Header in a CPIOArchiveReader, you can access the file's type and UNIX permissions.

File Type

let type = header.mode.type

switch type {
	case .regular: // Regular file.
	case .directory: // Directory.
	case .symlink: // Symbolic link.
	...
}

Permissions

To access the UNIX permissions, use the permissions variable in FileMode.

Examples

  • Examples/CreateReadWrite: This example shows how to use CPIOArchiveKit to read, create, or extract an archive; or compute a checksum for an archive using only Darwin.C (macOS), Glibc (Linux) or ucrt (Windows (not tested)).

Other Platforms

CPIOArchiveKit 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

CPIOArchiveKit 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, swift-format, and Prettier, then 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.

cpioarchivekit's People

Contributors

lebje avatar

Stargazers

 avatar  avatar  avatar

Watchers

 avatar  avatar

cpioarchivekit's Issues

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.