扩展

可以使用自定义（第三方）cop 和格式化程序扩展 RuboCop。

加载扩展

除了 --require 命令行选项外，您还可以在 .rubocop.yml 文件中使用可选的 require 指令指定要加载的 ruby 文件。

require:
 - ../my/custom/file.rb
 - rubocop-extension
这些路径将直接传递给 Kernel.require。如果您的扩展文件不在 $LOAD_PATH 中，您需要显式地指定路径作为以 ./ 为前缀的相对路径或绝对路径。以 . 开头的路径相对于 .rubocop.yml 解析。如果给定包含 - 的路径，它将按原样使用，但如果我们找不到要加载的文件，我们将用 / 替换 - 并再次尝试，就像 Bundler 加载 gem 时一样。

扩展建议

根据您在捆绑包中拥有的 gem，RuboCop 可能会建议可以添加的扩展以提供更多功能。例如，如果您使用 rspec 但没有相应的 rubocop-rspec 扩展，RuboCop 会建议启用它。

可以通过在配置中添加以下内容来禁用此消息

AllCops:
  SuggestExtensions: false

如果 SuggestExtensions: true，则建议默认扩展。

您也可以选择退出对特定扩展库的建议，如下所示（未指定的扩展将继续根据需要发出通知）

AllCops:
  SuggestExtensions:
    rubocop-rake: false

自定义 Cop

您可以在 .rubocop.yml 中配置自定义 cop，就像任何其他 cop 一样。

编写自己的 Cop

如果您想创建一个扩展 gem，可以使用 rubocop-extension-generator。

请参阅 开发 了解如何实现 cop。

Cop 扩展

主要的 RuboCop gem 侧重于核心 Ruby 语言，不包括与任何外部 Ruby 库/框架相关的功能。但是，有许多专门针对这些库/框架的 RuboCop 扩展，其中一些由 RuboCop 的核心团队维护。

官方扩展

第三方扩展

有任何缺少的扩展？向我们发送 Pull Request！

配置扩展

如果您正在编写扩展，您可以将部分配置绑定到 RuboCop。

配置弃用

当已发布的规则后来被重命名或删除，或其参数之一被更改时，RuboCop 可以输出错误消息，让用户知道将他们的配置更新为最新值。如果遇到任何过时的配置，RuboCop 将输出错误消息并退出。

您可以通过创建自己的 obsoletions.yml 文件并让 RuboCop 知道在哪里找到它来将您的扩展绑定到此系统

RuboCop::ConfigObsoletion.files << File.expand_path(filename)

目前有三种类型的弃用可以为规则定义

  • renamed: 规则已更改为具有新名称，或移动到不同的部门。

  • removed: 规则已删除（通常这配置有 alternatives 或 reason 说明为什么它被删除）。

  • split: 规则已删除并被多个其他规则替换。

还有两种类型可用于定义参数更改。这些配置可以同时应用于多个规则和多个参数（因此在 YAML 中以哈希数组的形式表示）

  • changed_parameters: 参数已重命名。

  • changed_enforced_styles: 之前接受的 EnforcedStyle 值已更改或删除。

参数弃用可以通过 severity: warning 设置，以弃用旧参数，但仍接受它。RuboCop 将输出警告，但继续运行。

弃用配置示例

有关更多示例，请参阅 config/obsoletion.yml。

所有复数键（例如 cops、parameters、alternatives 等）可以取单个值或数组。 
renamed:
  Layout/AlignArguments: Layout/ArgumentAlignment
  Lint/BlockAlignment: Layout/BlockAlignment

removed:
  Layout/SpaceAfterControlKeyword:
    alternatives: Layout/SpaceAroundKeyword
  Lint/InvalidCharacterLiteral:
    reason: it was never being actually triggered

split:
  Style/MethodMissing:
    alternatives:
      - Style/MethodMissingSuper
      - Style/MissingRespondToMissing

changed_parameters: # must be an array of hashes
  - cops:
      - Metrics/BlockLength
      - Metrics/MethodLength
    parameters: ExcludedMethods
    alternative: IgnoredMethods
    severity: warning

changed_enforced_styles: # must be an array of hashes
  - cops: Layout/IndentationConsistency
    parameters: EnforcedStyle
    value: rails
    reason: >
      `EnforcedStyle: rails` has been renamed to
      `EnforcedStyle: indented_internal_methods`

自定义格式化程序

您可以使用自定义格式化程序来自定义 RuboCop 的输出格式。

创建自定义格式化程序

要实现自定义格式化程序，您需要子类化 RuboCop::Formatter::BaseFormatter 并覆盖一些方法，或者通过鸭子类型实现所有格式化程序 API 方法。

有关更多格式化程序 API 详细信息，请参阅以下文档。

从命令行使用自定义格式化程序

您可以通过结合使用 --format 和 --require 选项来告诉 RuboCop 使用您的自定义格式化程序。例如，当您在 ./path/to/my_custom_formatter.rb 中定义了 MyCustomFormatter 时，您将键入以下命令

$ rubocop --require ./path/to/my_custom_formatter --format MyCustomFormatter

模板支持

RuboCop 具有 API，用于扩展以支持 ERB、Haml、Slim 等模板。

通常，RuboCop 从一个 Ruby 文件中提取一个 Ruby 代码，但是一个模板文件中有多个嵌入式 Ruby 代码。为了解决这个问题，RuboCop 具有一个称为 RuboCop::Runner.ruby_extractors 的机制，任何 Ruby 提取器都可以添加到扩展端。

Ruby 提取器必须是一个可调用对象，它接受一个 RuboCop::ProcessedSource 并返回一个包含 Ruby 源代码及其从原始源代码的偏移量的 Hash 的 Array，或者对于不相关的文件返回 nil。

ruby_extractor.call(processed_source)

Ruby 提取器返回的示例值如下所示

[
  {
    offset: 2,
    processed_source: #<RuboCop::ProcessedSource>
  },
  {
    offset: 10,
    processed_source: #<RuboCop::ProcessedSource>
  }
]

在扩展端，代码将类似于以下内容

RuboCop::Runner.ruby_extractors.unshift(ruby_extractor)

RuboCop::Runners.ruby_extractors 从头开始处理，并在其中一个返回非空值时结束。默认情况下，有一个 Ruby 提取器返回给定的 Ruby 源代码，偏移量为 0，因此您可以在它之前添加任何 Ruby 提取器。

这仍然是一个实验性功能，将来可能会更改。