unrar

基于 rarlab 提供的 unrar C 库的高级包装。

此库只能 提取 和 列出 存档，不能 创建 存档。

请查看 示例目录 了解如何使用此库。特别是 lister 示例有很好的文档和高级功能！

基本示例：列出存档条目

use unrar::Archive;

fn main() {
    for entry in Archive::new("archive.rar").open_for_listing().unwrap() {
        println!("{}", entry.unwrap());
    }
}

运行此示例： cargo run --example basic_list path/to/archive.rar. 你可以使用 rar CLI 创建存档： rar a archive.rar .

概述

此crate的主要类型是 Archive，表示文件系统上的存档。 Archive 本身不执行FS操作，除非调用其中一个 open 方法，返回一个 OpenArchive。

存档

Archive 结构提供了两大类方法

1. 不接触FS的方法。这些是基于野外RAR路径约定的实用方法。通常，多部分文件通常具有类似于 .part08.rar 或 .r08.rar 的扩展名。由于提取必须从第一部分开始，因此使用例如 archive.as_first_part() 确定这可能很有帮助
2. 以下方法以指定模式打开底层路径（可能的模式有 List、ListSplit 和 Process）。这些方法中包含单词 open，是可能失败的运算，在 Result 中返回 OpenArchive，如下所示
   • open_for_listing 和 open_for_listing_split：列出存档条目（跳过内容/有效载荷）
   • open_for_processing：处理存档条目以及内容/有效载荷
   • break_open：即使在返回错误的情况下，如果可能，读取存档。必须显式提供 OpenMode。

OpenArchive

存档以以下三种模式之一打开：List、ListSplit 或 Process。此库不提供对存档的随机访问。相反，存档内的文件只能作为流进行处理，单向从前向后，交替进行 ReadHeader 和 ProcessFile 操作（如底层 C++ 库所规定）。

这就是游标背后的思想

OpenArchive: 游标

通过游标，存档跟踪下一个允许的操作

• CursorBeforeHeader -> ReadHeader
• CursorBeforeFile -> ProcessFile

库通过利用 typestate 模式 来强制执行此规则。存档一旦打开，就处于 CursorBeforeHeader 状态，因此必须调用它的 read_header 方法，该方法返回一个新实例的 OpenArchive 在 CursorBeforeFile 状态，只公开映射到内部 ProcessFile 操作的方法。每个步骤中可用的方法取决于存档的当前状态和打开模式。

Open模式/游标位置组合的可用方法

以下是 OpenMode/Cursor 组合公开的方法概述

OpenArchive: 迭代器

以 List 或 ListSplit 模式打开的存档也实现了 Iterator，而以 Process 模式打开的存档则没有（尽管这可能在未来的版本中改变）。这是因为前两种将在读取和返回头部信息的同时强制跳过有效负载，而后者有更复杂的处理可能性，这并不容易通过 Iterator 来表达。

示例

对于更复杂的示例，请查看 examples/ 文件夹。

以下是一个返回文件第一个内容的函数的示例

fn first_file_content<P: AsRef<Path>>(path: P) -> UnrarResult<Vec<u8>> {
    let archive = Archive::new(&path).open_for_processing()?; // cursor: before header
    let archive = archive.read_header()?.expect("empty archive"); // cursor: before file
    dbg!(&archive.entry().filename);
    let (data, _rest) = archive.read()?; // cursor: before header
    Ok(data)
}
# use std::path::Path;
# use unrar::{Archive, UnrarResult};
#
# let data = first_file_content("data/version.rar").unwrap();
# assert_eq!(std::str::from_utf8(&data), Ok("unrar-0.4.0"));

特性

• 多部分文件
• 列出存档
• 提取它们
• 将它们读入内存（不提取）
• 测试它们
• 带密码的加密存档
• 与 unrar 源文件静态链接
• 从源代码构建 unrar C++ 代码
• 基本功能，操作于文件名/路径（不读取存档）
• 文档 / RustDoc
• 测试套件
• 利用类型系统强制正确使用
• 精心设计的错误（计划中）
• TBD

非特性

由于这个库只是一个包装器，以下特性不易实现，因此没有计划

• 创建存档
• 对任意存档条目的随机访问
• 纯 Rust 实现
• 从文件描述符/ fs::File 处理器处理存档
• 从字节流处理存档

贡献

请随时贡献！如果你发现了一个错误，请打开一个问题。

欢迎提交拉取请求！

帮助

如果你需要使用库的帮助，请随时创建一个新的讨论或打开一个问题。

许可证

本库的贡献者编写的部分根据以下任一许可证进行许可

• Apache License，版本 2.0（《LICENSE-APACHE》或http://www.apache.org/licenses/LICENSE-2.0）
• MIT 许可证（《LICENSE-MIT》或http://opensource.org/licenses/MIT）

任选其一。

嵌入的 C/C++ 库 使用自己的许可证。更多信息，请参阅其许可证文件。