Fast

Fast，全称"Find AST"，是一个用于搜索、剪枝和编辑Ruby抽象语法树（AST）的工具。

Ruby是一种灵活的语言，允许我们以多种不同的方式编写代码以达到相同的最终结果。正因如此，如果没有AST，很难验证代码是如何编写的。

查看官方文档：https://jonatas.github.io/fast。

AST中find的标记语法

Fast的当前版本涵盖了以下标记元素：

• () - 表示节点搜索
• {} - 寻找匹配的任意元素，类似于集合包含或Ruby中的any?
• [] - 寻找所有匹配的元素，类似于Ruby中的all?
• $ - 将捕获当前表达式的内容，类似于正则表达式组
• _ - 表示任何非nil值，或某些存在的内容
• nil - 精确匹配nil
• ... - 匹配带有子节点的节点
• ^ - 引用表达式的父节点
• ? - 表示可能存在的元素
• \1 - 表示对先前捕获元素的替换
• %1 - 绑定表达式中的第一个额外参数
• "" - 将匹配带双引号的字面字符串
• #<方法名> - 将以node为参数调用<方法名>，允许你构建自定义规则
• .<方法名> - 将从node调用<方法名>

这种语法的灵感来自RuboCop节点模式。

安装

$ gem install ffast

工作原理

S-表达式

Fast通过使用一系列表示代码的表达式来搜索抽象语法树，这些表达式被称为S-表达式。

S-表达式，或符号表达式，是一种表示嵌套数据的方式。它们起源于LISP编程语言，并经常在其他语言中用于表示AST。

整数字面量

例如，让我们看一个Ruby中的整数：

1

它对应的S-表达式是：

s(:int, 1)

在Fast和Parser中，s是创建Parser::AST::Node的简写。每个这样的节点都有一个#type和包含在其中的#children：

def s(type, *children)
  Parser::AST::Node.new(type, children)
end

变量赋值

现在让我们看一个局部变量赋值：

value = 42

它对应的S-表达式是：

ast = s(:lvasgn, :value, s(:int, 42))

如果我们想在AST中找到这个特定的赋值，我们可以使用Fast来寻找一个名为value且值为42的局部变量：

Fast.match?('(lvasgn value (int 42))', ast) # => true

通配符标记

如果我们想找到一个名为value的变量，它被赋予了任何整数值，我们可以用下划线（_）作为简写来替换查询中的42：

Fast.match?('(lvasgn value (int _))', ast) # => true

集合包含标记

如果我们不确定我们正在赋值的值的类型，我们可以使用之前提到的集合包含标记（{}）来告诉Fast我们期望的是Float或Integer：

Fast.match?('(lvasgn value ({float int} _))', ast) # => true

全部匹配标记

假设我们想说明我们期望值的类型不是什么，我们可以使用全部匹配标记（[]）来表达多个需要为真的条件。在这种情况下，我们不希望值是String、Hash或Array，通过在所有类型前加上!前缀：

Fast.match?('(lvasgn value ([!str !hash !array] _))', ast) # => true

节点子标记

我们可以使用子标记（...）来匹配任何带有子节点的节点：

Fast.match?('(lvasgn value ...)', ast) # => true

我们甚至可以结合使用_和...来匹配任何局部变量赋值：

Fast.match?('(lvasgn _ ...)', ast) # => true

捕获表达式的值

你可以使用$来捕获表达式的内容，以便后续使用：

Fast.match?('(lvasgn value $...)', ast) # => [s(:int, 42)]

捕获可以在任何位置使用，次数不限，以捕获你可能需要的任何信息：

Fast.match?('(lvasgn $_ $...)', ast) # => [:value, s(:int, 42)]

请记住，_表示非nil的内容，而...表示带有子节点的节点。

调用自定义方法

你还可以定义自定义方法来设置更复杂的规则。假设我们要在同一个类中查找重复的方法。我们需要收集方法名并确保它们是唯一的。

def duplicated(method_name)
  @methods ||= []
  already_exists = @methods.include?(method_name)
  @methods << method_name
  already_exists
end

puts Fast.search_file('(def #duplicated)', 'example.rb')

同样的原理可以用于节点级别或调试目的。

    require 'pry'
    def debug(node)
      binding.pry
    end

    puts Fast.search_file('#debug', 'example.rb')

如果你只想获取def节点，你也可以用[]来交叉表达式：

puts Fast.search_file('[ def #debug ]', 'example.rb')

方法

让我们看一下方法声明：

def my_method
  call_other_method
end

它对应的s-表达式是：

ast =
  s(:def, :my_method,
    s(:args),
    s(:send, nil, :call_other_method))

注意(args)节点。我们不能用...来匹配它，因为它没有子节点（或者在这种情况下没有参数），但我们可以用通配符_来匹配它，因为它不是nil。

调用链

让我们看几个其他例子。有时你会在一个Object上有一连串的调用，比如a.b.c.d。它对应的s-表达式是：

ast =
  s(:send,
    s(:send,
      s(:send,
        s(:send, nil, :a),
        :b),
      :c),
    :d)

替代语法

你也可以使用嵌套数组与纯值、快捷方式或proc来搜索：

Fast.match? [:send, [:send, '...'], :d], ast  # => true
Fast.match? [:send, [:send, '...'], :c], ast  # => false

像子节点...和通配符_这样的快捷标记只是proc的占位符。如果你愿意，你甚至可以直接使用proc，像这样：

Fast.match?([
  :send, [
    -> (node) { node.type == :send },
    [:send, '...'],
    :c
  ],
  :d
], ast) # => true

这也适用于表达式：

Fast.match?('(send (send (send (send nil $_) $_) $_) $_)', ast) # => [:a, :b, :c, :d]

调试

如果你发现某个特定表达式不起作用，你可以使用debug来查看Fast正在做什么：

Fast.debug { Fast.match?([:int, 1], s(:int, 1)) }

在Fast遍历AST时，每个进行的比较都会被记录到你的控制台（STDOUT）：

int == (int 1) # => true
1 == 1 # => true

将参数绑定到表达式

我们还可以使用插值标记%将参数动态插入到我们的查询中。这类似于使用从1开始的索引的sprintf：

Fast.match? '(lvasgn %1 (int _))', ('a = 1'), :a  # => true

在搜索中使用之前的捕获

假设你正在寻找一个只是将某些东西委托给另一个方法的方法，比如这个name方法：

def name
  person.name
end

这可以表示为以下AST：

(def :name
  (args)
  (send
    (send nil :person) :name))

我们可以创建一个查询来搜索这样的方法：

Fast.match?('(def $_ ... (send (send nil _) \1))', ast) # => [:name]

Fast.search

搜索允许你搜索整个AST，收集匹配给定表达式的节点。然后返回任何匹配的节点：

Fast.search('(int _)', Fast.ast('a = 1')) # => s(:int, 1)

如果你在搜索中使用捕获，匹配的节点和捕获都会被返回：

Fast.search('(int $_)', Fast.ast('a = 1')) # => [s(:int, 1), 1]

你也可以从搜索中绑定外部参数：

Fast.search('(int %1)', Fast.ast('a = 1'), 1) # => [s(:int, 1)]

Fast.capture

要只选择捕获并忽略节点，使用Fast.capture：

Fast.capture('(int $_)', Fast.ast('a = 1')) # => 1

Fast.replace

让我们考虑以下示例：

def name
  person.name
end

我们想用delegate替换表达式中的代码：

delegate :name, to: :person

我们已经在搜索并引用之前的捕获中使用\1定位了这个示例，现在是时候了解如何重写内容了。

Fast.replace会产生一个#{Fast::Rewriter}上下文。 内部的replace方法接受一个范围，每个node都有一个location，包含有关节点表达式范围的元数据。

ast = Fast.ast("def name; person.name end")
# => s(:def, :name, s(:args), s(:send, s(:send, nil, :person), :name))

通常，我们使用location.expression：

ast.location.expression # => #<Parser::Source::Range (string) 0...25>

但location还提供了一些关于特定片段的元数据：

ast.location.instance_variables # => [:@keyword, :@operator, :@name, :@end, :@expression, :@node]

方法定义关键字的范围:

ast.location.keyword # => #<Parser::Source::Range (string) 0...3>

你总是可以获取源码范围的源代码:

ast.location.keyword.source # => "def"

或者只获取方法名:

ast.location.name # => #<Parser::Source::Range (string) 4...8>
ast.location.name.source # => "name"

在重写器的上下文中,目标是删除方法并插入新的委托内容。因此,范围是node.location.expression:

Fast.replace '(def $_ ... (send (send nil $_) \1))', ast do |node, captures|
  attribute, object = captures

  replace(
    node.location.expression,
    "delegate :#{attribute}, to: :#{object}"
  )
end

替换文件

现在假设我们有一个名为sample.rb的文件,其中包含以下代码:

def good_bye
  message = ["good", "bye"]
  puts message.join(' ')
end

我们决定将message变量的内容内联到后面

def good_bye
  puts ["good", "bye"].join(' ')
end

要重构并达到建议的示例,请遵循以下步骤:

1. 删除局部变量赋值
2. 存储已删除变量的值
3. 在之前使用变量的地方替换为该值

完整示例

assignment = nil
Fast.replace_file '({ lvasgn lvar } message )', 'sample.rb' do |node, _|
  # 查找变量赋值
  if node.type == :lvasgn
    assignment = node.children.last
    # 删除负责赋值的节点
    remove(node.location.expression)
  # 查找正在使用的变量
  elsif node.type == :lvar
    # 用变量的内容替换变量
    replace(
      node.location.expression,
      assignment.location.expression.source
    )
  end
end 

请注意,当前示例返回内容输出,但不重写文件。

其他实用函数

要操作Ruby文件,有时你需要一些额外的任务。

Fast.ast_from_file(file)

此方法从文件解析代码并将其加载到AST表示中。

Fast.ast_from_file('sample.rb')

Fast.search_file

你可以使用search_file在文件中搜索表达式。

Fast.search_file(expression, 'file.rb')

它是Fast.ast_from_file和Fast.search的组合。

Fast.capture_file

你可以使用Fast.capture_file只返回捕获:

Fast.capture_file('(class (const nil $_))', 'lib/fast.rb')
# => [:Rewriter, :ExpressionParser, :Find, :FindString, ...]

Fast.ruby_files_from(arguments)

Fast.ruby_files_from(arguments)可以从文件列表或文件夹中获取所有Ruby文件:

Fast.ruby_files_from('lib') 
# => ["lib/fast/experiment.rb", "lib/fast/cli.rb", "lib/fast/version.rb", "lib/fast.rb"]

注意:它不支持像*.rb或**/*这样的glob特殊选择器,因为它会递归查找给定参数中的Ruby文件。

命令行中的fast

Fast还附带一个名为fast的命令行工具。你可以使用它来搜索和查找代码,就像库版本一样:

fast '(def match?)' lib/fast.rb

CLI工具接受以下标志

• 使用-d或--debug启用调试模式。
• 使用--ast输出AST而不是原始代码
• 使用--pry使用pry调试第一个结果
• 使用-c从代码示例中搜索
• 使用-s搜索相似代码
• 使用-p或--parallel并行化搜索

定义你的Fastfile

当你以.开始模式时,会加载Fastfile。

你还可以在主目录中定义额外的Fastfile,或者通过设置FAST_FILE_DIR来指定目录。

你可以在任何项目中定义一个Fastfile,其中包含你的自定义快捷方式。

Fast.shortcut(:version, '(casgn nil VERSION (str _))', 'lib/fast/version.rb')

假设你想显示库的版本。你的普通命令行会像这样:

$ fast '(casgn nil VERSION)' lib/*/version.rb

或者概括为搜索版本文件中的所有常量:

$ fast casgn lib/*/version.rb

它会输出结果,但命令不太方便。为了只需输入fast .version,你可以在Fastfile中使用前面的片段。

它会输出类似这样的内容:

# lib/fast/version.rb:4
VERSION = '0.1.2'

创建带有块的快捷方式,能够在Fast模块的作用域内引入自定义代码

例如,要为你的库提升新版本,你可以输入fast .bump_version,并将片段添加到你的库中,修复文件名。

Fast.shortcut :bump_version do
  rewrite_file('(casgn nil VERSION (str _)', 'lib/fast/version.rb') do |node|
    target = node.children.last.loc.expression
    pieces = target.source.split(".").map(&:to_i)
    pieces.reverse.each_with_index do |fragment,i|
      if fragment < 9
        pieces[-(i+1)] = fragment +1
        break
      else
        pieces[-(i+1)] = 0
      end
    end
    replace(target, "'#{pieces.join(".")}'")
  end
end

你可以在Fastfile中找到更多示例。

Fast与Pry

你可以使用 --pry 在特定的源节点停止，并在该位置运行 Pry：

fast '(block (send nil it))' spec --pry

在 pry 会话中，你可以访问 result 获取找到的第一个结果，或者使用 results 获取所有找到的匹配项。

让我们看看 results：

results.map { |e| e.children[0].children[2] }
# => [s(:str, "将 ... 解析为 Find"),
# s(:str, "将 $ 解析为 Capture"),
# s(:str, "将引号值解析为字符串"),
# s(:str, "将 {} 解析为 Any"),
# s(:str, "将 [] 解析为 All"), ...]

Fast 与 RSpec

假设我们想获取 RSpec 代码中当前没有描述的所有 it 块：

fast '(block (send nil it (nil)) (args) (!str)) ) )' spec

这将返回以下内容：

# spec/fast_spec.rb:166
it { expect(described_class).to be_match(s(:int, 1), '(...)') }
# spec/fast_spec.rb:167
it { expect(described_class).to be_match(s(:int, 1), '(_ _)') }
# spec/fast_spec.rb:168
it { expect(described_class).to be_match(code['"string"'], '(str "string")') }

实验

实验可以用来以自动化的方式对你的代码进行测试。这些实验可以用来测试性能增强的效果，或者替代代码是否真正有效。

让我们创建一个实验，尝试从我们的规格中移除所有 before 和 after 块。

如果规格仍然通过，我们可以自信地说这个钩子是无用的。

Fast.experiment("RSpec/RemoveUselessBeforeAfterHook") do
  # 查找我们的规格文件
  lookup 'spec'

  # 查找每个以 before 或 after 开头的块
  search "(block (send nil {before after}))"

  # 移除这些块
  edit { |node| remove(node.loc.expression) }

  # 创建一个新文件，并对该新文件运行 RSpec
  policy { |new_file| system("bin/spring rspec --fail-fast #{new_file}") }
end

• lookup 可用于传入文件或文件夹。
• search 包含你想匹配的表达式
• edit 用于应用代码更改
• policy 是我们执行的内容，用于验证当前更改是否仍然通过

每个 before 和 after 块的移除都会独立进行，以单独验证每一个。每次成功的移除都会保存在次要更改中，直到我们移除完所有块。

你可以在 experiments 文件夹中看到更多示例。

运行多个实验

要运行多个实验，请使用 fast-experiment 运行器：

fast-experiment <实验名称> <文件或文件夹>

你可以限制实验的范围：

fast-experiment RSpec/RemoveUselessBeforeAfterHook spec/models/**/*_spec.rb

开发

检出仓库后，运行 bin/setup 安装依赖项。然后，运行 rake spec 执行测试。你还可以运行 bin/console 进入交互式提示符，允许你进行实验。

在控制台中，我们有一些函数如 s 和 code 来简化操作 ;)

bin/console

code("a = 1") # => s(:lvasgn, s(:int, 1))

要将此 gem 安装到本地机器上，运行 bundle exec rake install。要发布新版本，请更新 version.rb 中的版本号，然后运行 bundle exec rake release，这将为该版本创建一个 git 标签，推送 git 提交和标签，并将 .gem 文件推送到 rubygems.org。

贡献

欢迎在 GitHub 上提交错误报告和拉取请求：https://github.com/jonatas/fast。本项目旨在成为一个安全、友好的协作空间，贡献者应遵守 贡献者公约 行为准则。

许可证

该 gem 在 MIT 许可证 条款下作为开源软件提供。

更多信息请参见 官方文档。