unrar_wrapper 1.0.0

# UnRAR包装器

[](https://travis-ci.org/openSUSE/unrar#_wrapper)

UnRAR包装器（`unrar_wrapper.py`）是一个Python包装脚本，它将基本的UnRAR命令转换为unar和lsar调用，以提供向后兼容性。

## 包装器的原因
[UnRAR](https://www.rarlab.com)是免费软件命令行应用程序，用于提取RAR文件存档。遗憾的是，这个软件是非自由的，因此在许多发行版中，它被LGPL [the Unarchiver (unar/lsar)](https://theunarchiver.com/command-line)所取代。

总的来说，Unarchiver似乎是非自由unrar的良好替代品。它支持基本上相同的格式（除了UUE和JAR以及有限的ARJ（无多部分）和ACE（不支持Ace 2.0）支持）并且也支持RAR5。

遗憾的是，UnRAR和Unarchiver在CLI上完全不兼容，它们有不同的选项集。Unrar支持相当大的选项集（有时相当晦涩和没有必要）而Unarchiver仅支持它的一小部分。Unarchiver还将此功能分布在`unar`（解包）和`lsar`（列出和测试）实用工具之间。


## 支持的功能
正如之前所写的，UnRAR提供了一套庞大的命令和选项，而Unarchiver仅提供了其中相对较小的一部分。由于本包装程序的主要目的是保留基本的向后兼容性，因此只支持必要的命令和选项。

### 概述
`unrar 命令 [选项1] [选项N] 归档 [文件...] [@文件列表...] [提取路径/]`

`unar [选项]... 归档 [文件]...`

`lsar [选项]... 归档...`

如您所见，即使UnRAR和Unarchiver的概述也不同。包装程序仅支持UnRAR的概述，仅用于提取（`x`）命令。对于列表（`l`）和测试（`t`）命令，它既不支持`files`、`@文件列表`，也不支持`path_to_extract/`，因为Unarchiver不提供此功能。

| UnRAR | unar | 包装程序实现 |
|--|--|--|
| `[files...]` | `[FILE]` | 直接 |
| `[@listfiles...]` | 不支持 | 通过多个 `[FILE]` |
| `[path_to_extract/]` | `unar -output-directory` | 直接 |


### 命令
#### 提取
| UnRAR 命令 | unar 命令 | 包装程序实现 |
|--|--|--|
| `e` | 不支持 | 未实现 |
| `x` | `unar` | 直接 |

UnRAR命令`e`提取没有归档路径的文件。Unarchiver不支持这种行为，因此需要通过此包装程序来模拟。不幸的是，这将是相当复杂的功能，例如当文件冲突出现时的交互性，因此此包装程序中没有实现此功能。

#### 列表
UnRAR支持许多列出归档信息变体的功能。`l[t[a],b]`用于列出归档`[技术[所有]，裸]`和`v[t[a],b]`用于详细列出归档。实际上，这意味着以下组合：`l`、`lt`、`lta`、`lb`（以及`v`选项的相反）。然而，`lsar`仅支持基本列表，并支持选项`l`和`L`来打印归档中每个文件的更多/全部信息。

根据我的测试，`l`和`v`命令的输出没有区别，除了简单的`unrar l`和`unrar v`，其中`unrar v`在输出中添加了`packed`和`ratio`列。由于此包装程序的目的不是精确地模拟输出，因此使用了以下简化的投影

| UnRAR 命令 | lsar 命令 |
|--|--|
| `lb`，`vb` | `lsar` |
| `l`，`v` | `lsar -l` |
| `lt`，`lta`，`vt`，`vta` | `lsar -L` |

#### 测试
| UnRAR 命令 | lsar 命令 | 包装程序实现 |
|--|--|--|
| `t` | `-t` | 直接 |

#### 打印
| UnRAR 命令 | unar 命令 | 包装程序实现 |
|--|--|--|
| `p` | 不支持 | 未实现 |

UnRAR的`p`命令简单地打印文件到标准输出。它在unar中不受支持，由于我认为此命令不是关键的，因此我没有实现它。

### 选项
UnRAR包含许多选项，但只有以下选项在Unarchiver中直接支持。其他选项的模拟超出了此包装程序的范畴。

| UnRAR 选项 | unar/lsar 选项 | 包装程序实现 |
|--|--|--|
| `-o+` | `unar-force-overwrite` | 直接 |
| `-o-` | `unar -force-skip` | 直接 |
| `-or` | `unar -force-rename` | 直接 |
| `-p[密码]` | `p 密码` | 直接 |

对于UnRAR，所有这些选项都可以与所有命令一起使用，即使它没有任何意义。在这种情况下，它将被忽略（例如，当使用`-o+`与`l`命令时）。基于`unar`支持的选项，我决定仅支持提取命令的这些选项，但`-p`选项除外，该选项支持所有命令。

#### 默认选项

如果归档没有目录（即文件直接存在于归档中），则UnRAR按原样解包它们。但unar默认创建一个包含目录，如果有多个顶级文件或文件夹。因此，我们需要使用`-D`，`-no-directory` unar选项作为默认选项。此选项表示永远不为解包归档的内容创建额外的包含目录。

### 返回代码

UnRAR 支持许多返回代码，用以指示错误类型（例如，密码错误、写入错误、文件创建错误等）。然而，Unarchiver 只使用两种基本返回代码 - 0（成功）和 1（错误）。由于无法将返回代码 1 翻译为更具体的错误描述，因此此包装器只支持这两个代码，并额外增加了表示包装器参数错误的代码 2。

## 测试

该项目包含两种类型的测试 - 单元测试和功能测试。单元测试测试特定 Python 函数的基本功能。功能测试则对位于 `tests/testdata` 目录中的真实 RAR 存档进行测试。

如果您想运行单元测试，请从主目录运行 `python3 -m unittest tests.test_unrar_wrapper`。

如果您想运行功能测试，请从主目录运行 `./tests/functional_tests.sh tests/testdata/functional/ unrar_wrapper.py`。