class SyntaxSuggest::CleanDocument

解析并将源代码清理成一个词法感知的文档

在内部，文档由一个数组表示，每个索引包含一个与源代码中的行相关的 CodeLine。

该算法主要分为三个阶段

  1. 清理/格式化输入源代码

  2. 搜索无效块

  3. 将无效块格式化为有意义的内容

这个类处理第一部分。

这个类存在的原因是为了格式化输入源代码，以便更好/更轻松/更清洁地进行探索。

CodeSearch 类在行级别操作，因此我们必须小心，不要引入本身看起来有效，但删除后会触发语法错误或奇怪行为的行。

## 连接尾随斜杠

带有尾随斜杠的代码在逻辑上被视为单行

1 it "code can be split" \
2    "across multiple lines" do

在这种情况下，删除第 2 行会添加语法错误。我们通过在内部将两行连接成单个“行”对象来解决这个问题

## 逻辑上连续的行

可以跨多行拆分的代码（例如方法调用）位于不同的行上

1 User.
2   where(name: "schneems").
3   first

删除第 2 行可能会引入语法错误。为了解决这个问题，所有行都连接成一行。

## Heredoc

Heredoc 是一种定义多行字符串的方法。它们可能会导致许多问题。如果保留为单行，解析器会尝试将内容解析为 ruby 代码，而不是字符串。即使没有这个问题，我们仍然会遇到缩进问题

1 foo = <<~HEREDOC
2  "Be yourself; everyone else is already taken.""
3    ― Oscar Wilde
4      puts "I look like ruby code" # but i'm still a heredoc
5 HEREDOC

如果我们不连接这些行，那么我们的算法会认为第 4 行与其余部分是分开的，具有更高的缩进，然后先查看它并删除它。

如果代码单独计算第 5 行，它会认为第 5 行是一个常量，删除它，并引入语法错误。

所有这些问题都可以通过将整个 heredoc 连接成一行来解决。

## 注释和空格

注释会干扰词法分析器告诉我们该行在逻辑上属于下一行的方式。这是有效的 ruby 代码，但会导致与之前不同的词法输出

1 User.
2   where(name: "schneems").
3   # Comment here
4   first

为了处理这个问题，我们可以用空行替换注释行，然后重新词法分析源代码。这种删除和重新词法分析保留了行索引和文档大小，但生成了一个更易于使用的文档。

公共类方法

new(source:) 点击切换源代码
# File syntax_suggest/clean_document.rb, line 87
def initialize(source:)
  lines = clean_sweep(source: source)
  @document = CodeLine.from_source(lines.join, lines: lines)
end

公共实例方法

call() 点击切换源代码

调用所有文档“清理器”并返回自身

# File syntax_suggest/clean_document.rb, line 94
def call
  join_trailing_slash!
  join_consecutive!
  join_heredoc!

  self
end
clean_sweep(source:) 点击切换源代码

删除注释

替换为空新行

source = <<~'EOM'
  # Comment 1
  puts "hello"
  # Comment 2
  puts "world"
EOM

lines = CleanDocument.new(source: source).lines
expect(lines[0].to_s).to eq("\n")
expect(lines[1].to_s).to eq("puts "hello")
expect(lines[2].to_s).to eq("\n")
expect(lines[3].to_s).to eq("puts "world")

重要提示：必须在词法分析之前完成此操作。

在此更改后，我们对文档进行词法分析，因为删除注释会更改文档的解析方式。

例如

values = LexAll.new(source: <<~EOM))
  User.
    # comment
    where(name: 'schneems')
EOM
expect(
  values.count {|v| v.type == :on_ignored_nl}
).to eq(1)

删除注释后

 values = LexAll.new(source: <<~EOM))
   User.

     where(name: 'schneems')
 EOM
 expect(
  values.count {|v| v.type == :on_ignored_nl}
).to eq(2)
# File syntax_suggest/clean_document.rb, line 157
def clean_sweep(source:)
  # Match comments, but not HEREDOC strings with #{variable} interpolation
  # https://rubular.com/r/HPwtW9OYxKUHXQ
  source.lines.map do |line|
    if line.match?(/^\s*#([^{].*|)$/)
      $/
    else
      line
    end
  end
end
join_consecutive!() 点击切换源代码

将逻辑上“连续”的行合并

source = <<~'EOM'
  User.
    where(name: 'schneems').
    first
EOM

lines = CleanDocument.new(source: source).join_consecutive!.lines
expect(lines[0].to_s).to eq(source)
expect(lines[1].to_s).to eq("")

已知此方法无法处理的情况是

Ripper.lex <<~EOM
  a &&
   b ||
   c
EOM

由于某种原因，这引入了 `on_ignore_newline`，但类型为 BEG

# File syntax_suggest/clean_document.rb, line 225
def join_consecutive!
  consecutive_groups = @document.select(&:ignore_newline_not_beg?).map do |code_line|
    take_while_including(code_line.index..) do |line|
      line.ignore_newline_not_beg?
    end
  end

  join_groups(consecutive_groups)
  self
end
join_groups(groups) 点击切换源代码

用于连接行“组”的辅助方法

输入应为 Array<Array<CodeLine>> 类型

外部数组保存各种“组”，而内部数组保存代码行。

所有代码行都“连接”到其组中的第一行。

为了保留文档大小，空行放置在“连接”的行的位置

# File syntax_suggest/clean_document.rb, line 266
def join_groups(groups)
  groups.each do |lines|
    line = lines.first

    # Handle the case of multiple groups in a row
    # if one is already replaced, move on
    next if @document[line.index].empty?

    # Join group into the first line
    @document[line.index] = CodeLine.new(
      lex: lines.map(&:lex).flatten,
      line: lines.join,
      index: line.index
    )

    # Hide the rest of the lines
    lines[1..].each do |line|
      # The above lines already have newlines in them, if add more
      # then there will be double newline, use an empty line instead
      @document[line.index] = CodeLine.new(line: "", index: line.index, lex: [])
    end
  end
  self
end
join_heredoc!() 点击切换源代码

将所有 heredoc 行合并为一行

source = <<~'EOM'
  foo = <<~HEREDOC
     lol
     hehehe
  HEREDOC
EOM

lines = CleanDocument.new(source: source).join_heredoc!.lines
expect(lines[0].to_s).to eq(source)
expect(lines[1].to_s).to eq("")

# File syntax_suggest/clean_document.rb, line 181
def join_heredoc!
  start_index_stack = []
  heredoc_beg_end_index = []
  lines.each do |line|
    line.lex.each do |lex_value|
      case lex_value.type
      when :on_heredoc_beg
        start_index_stack << line.index
      when :on_heredoc_end
        start_index = start_index_stack.pop
        end_index = line.index
        heredoc_beg_end_index << [start_index, end_index]
      end
    end
  end

  heredoc_groups = heredoc_beg_end_index.map { |start_index, end_index| @document[start_index..end_index] }

  join_groups(heredoc_groups)
  self
end
join_trailing_slash!() 点击切换源代码

连接带有尾随斜杠的行

source = <<~'EOM'
  it "code can be split" \
     "across multiple lines" do
EOM

lines = CleanDocument.new(source: source).join_consecutive!.lines
expect(lines[0].to_s).to eq(source)
expect(lines[1].to_s).to eq("")

# File syntax_suggest/clean_document.rb, line 246
def join_trailing_slash!
  trailing_groups = @document.select(&:trailing_slash?).map do |code_line|
    take_while_including(code_line.index..) { |x| x.trailing_slash? }
  end
  join_groups(trailing_groups)
  self
end
lines() 点击切换源代码

返回文档中 CodeLine 的数组

# File syntax_suggest/clean_document.rb, line 104
def lines
  @document
end
take_while_including(range = 0..) { |line)| ... } 点击切换源代码

用于从文档中获取元素的辅助方法

类似于 `take_while`，只是当它停止迭代时，它还会返回导致其停止的行

# File syntax_suggest/clean_document.rb, line 296
def take_while_including(range = 0..)
  take_next_and_stop = false
  @document[range].take_while do |line|
    next if take_next_and_stop

    take_next_and_stop = !(yield line)
    true
  end
end
to_s() 点击切换源代码

将文档渲染回字符串

# File syntax_suggest/clean_document.rb, line 109
def to_s
  @document.join
end