添加新规则

相关源文件

• tests/conftest.py
• tests/rules/test_hostscli.py
• tests/rules/test_sudo.py
• tests/test_corrector.py
• tests/test_types.py
• tests/utils.py
• thefuck/corrector.py
• thefuck/rules/hostscli.py
• thefuck/rules/sudo.py
• thefuck/types.py

本文档提供了在TheFuck中创建新纠正规则的分步指南。规则是决定如何匹配和纠正错误命令的核心机制。有关现有规则以及如何配置它们的更多信息，请参阅规则系统和自定义规则。

1. 理解TheFuck规则

TheFuck中的规则是Python模块，它们定义了如何识别命令错误并提供纠正。每个规则至少包含两个函数：

1. match(command) - 确定规则是否适用于给定命令
2. get_new_command(command) - 生成一个或多个已纠正的命令

来源：thefuck/types.py85-168 thefuck/corrector.py8-19 thefuck/rules/sudo.py31-47

2. 规则结构

2.1 核心组件

每个规则模块必须实现：

组件	类型	描述
match	功能	接受一个Command对象，如果规则适用，则返回True
get_new_command	功能	接受一个Command对象，并返回一个纠正后的命令或命令列表

可选组件包括：

组件	类型	默认	描述
enabled_by_default	布尔值	True	规则是否在没有显式配置的情况下启用
priority	整型	DEFAULT_PRIORITY	规则的优先级级别（数字越大，越先执行）
requires_output	布尔值	True	规则是否需要命令输出才能工作
side_effect	功能	None	执行纠正后的命令时运行的函数

来源：thefuck/types.py85-168 thefuck/corrector.py41-49 thefuck/rules/sudo.py31-47

2.2 Command对象

传递给规则函数的Command对象包含：

属性	描述
script	已执行命令的文本
output	命令的输出（stdout + stderr）
script_parts	已拆分成组件的命令

来源：thefuck/types.py12-82 thefuck/types.py85-168

3. 创建基本规则

3.1 基本规则结构

最简单的规则只需要两个函数。这是一个最小的规则结构：

来源：thefuck/rules/sudo.py31-47

3.2 示例：简单的纠正规则

让我们以sudo规则为例。该规则检测权限错误，并在命令前添加sudo。

1. match函数检查命令输出是否包含指示权限问题的模式。

2. get_new_command函数将sudo添加到命令中。

来源：thefuck/rules/sudo.py31-47 tests/rules/test_sudo.py6-34

4. 规则注册和发现

规则不需要显式注册。TheFuck 会自动从三个位置发现规则：

1. 位于thefuck/rules/中的捆绑规则
2. 位于~/.thefuck/rules/中的用户定义的规则
3. 名为thefuck_contrib_*的Python包中的第三方规则

来源：thefuck/corrector.py22-37 thefuck/corrector.py40-49

5. 高级规则技巧

5.1 返回多个纠正

规则可以通过从get_new_command返回一个列表来建议多个纠正。

这些纠正将按优先级顺序显示。

来源：thefuck/types.py185-198 tests/test_types.py102-113

5.2 使用装饰器

规则可使用几个有用的装饰器：

1. @sudo_support - 使规则能够处理以sudo为前缀的命令
2. @for_app('app_name') - 使规则仅适用于特定应用程序

来自hostscli.py的示例

来源：thefuck/rules/hostscli.py9-16 tests/rules/test_hostscli.py17-20

5.3 设置规则优先级

您可以通过设置priority属性来控制规则的尝试顺序。

默认优先级在DEFAULT_PRIORITY中定义。

来源：thefuck/types.py147-152 tests/test_types.py54-67

6. 测试规则

TheFuck使用pytest进行测试。规则测试应同时验证match和get_new_command函数。

6.1 测试结构

规则的测试通常会：

1. 使用各种输入测试match函数
2. 使用预期的输出测试get_new_command函数

针对sudo规则的示例测试

来源：tests/rules/test_sudo.py6-34 tests/conftest.py21-73

6.2 测试工具

测试工具提供了一些辅助类用于测试：

• Command - 创建用于测试的命令
• Rule - 用于测试的简化规则创建

来源： tests/utils.py5-21 tests/test_corrector.py51-61

7. 规则生命周期与集成

来源： thefuck/corrector.py81-92 thefuck/types.py185-198

8. 规则开发最佳实践

1. 关注范围：每条规则应处理特定类型的命令错误
2. 健壮匹配：考虑错误消息的不同变体
3. 高效处理：保持规则轻量级以便快速执行
4. 充分测试：使用多样化的命令输入和输出来进行测试
5. 文档记录：在测试中包含示例以记录规则行为

遵循这些指南，您可以创建有效的纠正规则，从而增强 TheFuck 的命令纠正能力。

来源： thefuck/rules/sudo.py1-47 thefuck/corrector.py8-19