Tarscape

关于

Tarscape 是一个 Swift 包，用于在 macOS 和 iOS 上读取和写入 Tar 归档文件。

安装

在 Xcode 的包管理器中搜索 https://github.com/kayembi/Tarscape.git。 或者，下载 Tarscape 包文件夹并将其拖到您的 Xcode 项目中。

请记住在使用 Tarscape 的 Swift 文件顶部添加 import Tarscape。

使用方法

基本用法

创建和提取 Tar 归档文件最简单的方法是使用 FileManager 扩展。

要创建 Tar 归档文件

// let folderURL = <folder from which to create archive>
// let tarURL = <location at which to create Tar file>
try FileManager.default.createTar(at: tarURL, from: folderURL)

要提取 Tar 归档文件

// let tarURL = <location of the Tar file>
// let dirURL = <location at which the extracted directory should be created>
try FileManager.default.extractTar(at: tarURL, to: dirURL)

FileManager 方法也可以从 Objective-C 代码中调用。

自定义选项

您可以使用 KBTarArchiver 和 KBTarUnarchiver 并更改某些选项来增加或减少归档和提取时间。

例如，设置 .convertAliasFiles 可确保别名文件正确存储在归档文件中，但会减慢归档过程。

// If the folder contains or might contain aliases, we should tell 
// the archiver to convert them to symbolic links.
let tarArchiver = KBTarArchiver(directoryURL: dirURL, options: .convertAliasFiles)
try tarArchiver.archive(to: tarURL) { (progressFraction, progressCount) in
    // Update progress here.
}

您还可以设置一些选项来加快解档速度

// 1. File attributes such as permissions and modification dates 
//    have to be set using FileManager's setAttributes(_:ofItemAtPath:) 
//    and this is *slow*. If you don't care about such attributes being 
//    restored and can live with default attributes being applied to 
//    extracted files, telling the unarchiver not to restore file attributes
//    can significantly improve extraction speeds. Do this by setting the
//    options parameter and *not* including .restoreFileAttributes.
// 2. Constructing file URLs can be done much faster if we don't have to 
//    worry about special characters and spaces etc that have to be escaped.
//    If you know that most subpaths in the archive don't use special characters
//    or spaces, you can speed up unarchiving by telling the unarchiver as much.
//    Only set this flag if you're sure, though - unarchiving can be slower if
//    you set this flag but it turns out that a lot of subpaths contain spaces
//    or special characters.
let tarUnarchiver = try KBTarUnarchiver(tarURL: tarURL, options: [.mostSubpathsCanBeUnescaped])
try tarUnarchiver.extract(to: dirURL) { (progressFraction, progressCount) in
    // Update progress here.
}

访问单个归档条目

如果您不想提取整个 Tar 文件，而只是查找其中的某个或某些文件，则可以使用 KBTarEntry 查询它。

示例

let tarUnarchiver = try KBTarUnarchiver(tarURL: tarURL)

// Get a single file:
let fileEntry = try tarUnarchiver.entry(atSubpath: "path/to/file.txt")
let data = fileEntry.regularFileContents()

// Get a directory:
let folderEntry = try tarUnarchiver.entry(atSubpath: "path/to/folder")
for childEntry in folderEntry.descendants {
    // ...
}

请注意，每次调用 entry(atSubpath:) 时，Tarscape 都必须解析整个 Tar 文件，直到找到该条目。 因此，如果您需要查找多个条目，则应告诉解档器首先解析 Tar 文件以构建条目列表

let tarUnarchiver = try KBTarUnarchiver(tarURL: tarURL)

// Tell the unarchiver to gather a list of entries. By passing in the "lazily" 
// flag, we tell the unarchiver not to load any data into memory but only the 
// list of entries. The data for each entry will not be read into memory until 
// we call regularFileContents() on a specific entry.
try tarUnarchiver.loadAllEntries(lazily: true)

// Enumerate through root entries (note that rootEntries is nil until 
// loadAllEntries() is called):
for entry in tarUnarchiver.rootEntries {
    // do something...
}

// Find an entry using subscript syntax:
let fileEntry = tarUnarchiver["path/to/file.txt"]
// Load the data for the entry - if "lazily" was set to "true", only now does 
// the data get read from the archive:
let data = fileEntry.regularFileContents()

文档

所有 Tarscape 方法都使用 Swift 文档注释进行记录。 在 Xcode 中 Opt-click 方法名称以获取快速帮助。

局限性

请注意，由于 Tarscape 专注于快速 Tar 创建和提取，因此它不支持压缩（它读取和写入 .tar 文件，而不是 tar.gz 文件）。 要添加对 tar.gz 的支持，您需要一个第三方压缩库，例如 DataCompression。

为什么选择 Tarscape？

我们需要一种快速的方法将文件包（即文件夹）归档为单个文件格式以进行同步，最好用 Swift 编写。 存在几个出色的 Swift 和 Objective-C 开源 Tar 项目（请参见下面的参考）。 但是，没有一个完全符合我们的要求

参考

Tarscape 构建并使用了以下项目中的代码