class SyntaxSuggest::CleanDocument

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

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

算法主要有三个阶段

清理/格式化输入源代码
搜索无效的代码块
将无效的代码块格式化为有意义的内容

这个类处理第一部分。

这个类存在的原因是为了格式化输入源代码，以便更好地/更容易地/更清晰地探索。

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

## 连接尾部斜杠

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

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

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

## 逻辑上连续的行

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

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

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

## Here 文档

Here 文档是一种定义多行字符串的方法。它们可能会导致许多问题。如果将其保留为单行，解析器将尝试将内容解析为 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 行是常量，删除它，并引入语法错误。

通过将整个 Here 文档连接成一行，可以解决所有这些问题。

## 注释和空格

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

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

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

公共类方法

new (source:)

来源

# File lib/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 lib/syntax_suggest/clean_document.rb, line 94
def call
  join_trailing_slash!
  join_consecutive!
  join_heredoc!

  self
end

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

clean_sweep (source:)

来源

# File lib/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

删除注释

替换为空换行符

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)

join_consecutive! ()

来源

# File lib/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

压缩逻辑上“连续”的行

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

join_groups (groups)

来源

# File lib/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

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

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

外层数组保存各个“组”，而内层数组保存代码行。

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

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

join_heredoc! ()

来源

# File lib/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

将所有 Here 文档行压缩成一行

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("")

join_trailing_slash! ()

来源

# File lib/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

连接带有尾部斜杠的行

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("")

lines ()

来源

# File lib/syntax_suggest/clean_document.rb, line 104
def lines
  @document
end

返回文档中 CodeLines 的数组

take_while_including (range = 0..) { |line)| ... }

来源

# File lib/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

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

类似于 'take_while'，除了当它停止迭代时，它还会返回导致它停止的行

to_s ()

来源

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

将文档渲染回字符串