RuboCop AST

This gem introduces two core classes of RuboCop:

  • RuboCop::AST::Node - this is an extension of the parser gem’s Node class, which adds a simpler and more powerful object-oriented API to make it easier to work with nodes.

  • RuboCop::AST::NodePattern - a regular expression-style method to traverse and match nodes in an Abstract Syntax Tree. See "Node Pattern" to get yourself familiar with NodePattern's capabilities.

This gem may be used independently from the main RuboCop gem. It was extracted from RuboCop in version 0.84 and its only dependency is the parser gem, which rubocop-ast extends.

Rationale

While working with parser's AST representation is fairly easy (especially when compared to the AST of Ruby’s built-in ripper library), there’s still areas we felt could be improved:

  • the canonical way to work with an AST node is to deconstruct the node in array-like fashion, which results in code that’s hard to read

  • looking for complex AST node patterns requires a lot of boilerplate code

  • there’s no easy way to tell apart AST nodes of certain types - e.g. prefix vs postfix conditionals

  • there’s no easy way to grab the parent node of some node

Enter rubocop-ast, which aims to solve those problems. This library evolved for years as part of RuboCop and was eventually spun off in the hope that it might be useful for other projects built on top of parser.

RuboCop::AST::Node provides a wrapper around parser's Node class (in other words, RuboCop::AST::Node < Parser::AST::Node). In addition to a number of methods to make it easier to work with, the wrapper class also provides ways to inspect the parents of nodes, which the parser nodes do not support.

Here are a few examples using parser and rubocop-ast:

parser

rubocop-ast

 
# type = :if
is_if = node.loc.keyword == 'if'
if_branch = node.children[1]
else_branch = node.children[2]
has_elsif_branch = node.children[2].type == :if && node.children[2].keyword == 'elsif'
 
# type = :if
is_if = node.if?
if_branch = node.if_branch
else_branch = node.else_branch
has_elsif_branch = node.elsif_conditional?
 
# type = :hash
pairs = node.children
pairs.each do |pair_node|
  key = pair_node.children[0]
  value = pair_node.children[1]
  do_something(key, value)
end
 
# type = :hash
node.each_pair do |pair_node|
  do_something(pair_node.key, pair_node.value)
end

Sample usage:

class MyRule < Parser::AST::Processor
  include RuboCop::AST::Traversal

  def on_sym(node)
    puts "I found a symbol! #{node.value}"
  end
end

source = RuboCop::AST::ProcessedSource.new(code, 2.7)
rule = MyRule.new
source.ast.each_node { |n| rule.process(n) }

If you have already parsed the Ruby code with prism, you can pass an instance of Prism::ParseLexResult to the :prism_result keyword argument. This is a useful API for Ruby LSP, where Prism::ParseLexResult has already been obtained externally from RuboCop. A Prism::ParseLexResult instance is a value that can be obtained, for example, as the return value of Prism.parse_lex(source). The bypass occurs only when the source is processed by prism and an instance of Prism::ParseLexResult is specified for the :prism_result keyword argument. Otherwise, the source code is parsed.

# `parser_prism` is chosen automatically for `ruby_version >= 3.4` but you can also request
# it explicitly starting from `ruby_version` 3.3. Requesting `parser_prism` for an earlier version
# will raise an error.
ProcessedSource.new(@options[:stdin], ruby_version, file, parser_engine: :parser_prism, prism_result: parse_lex_result)
The Parser gem supports syntax up to Ruby 3.3, but it does not support syntax in Ruby 3.4, such as it block parameters. Additionally, there are no plans to support Ruby 3.5 or later. For Ruby 3.4 and later, parser_engine: parser_prism is chosen automatically.