class RuboCop::AST::Node

`RuboCop::AST::Node` is a subclass of `Parser::AST::Node`. It provides access to parent nodes and an object-oriented way to traverse an AST with the power of `Enumerable`.

It has predicate methods for every node type, like this:

@example

node.send_type?    # Equivalent to: `node.type == :send`
node.op_asgn_type? # Equivalent to: `node.type == :op_asgn`

# Non-word characters (other than a-zA-Z0-9_) in type names are omitted.
node.defined_type? # Equivalent to: `node.type == :defined?`

# Find the first lvar node under the receiver node.
lvar_node = node.each_descendant.find(&:lvar_type?)

Constants

ARGUMENT_TYPES

@api private

ASSIGNMENTS

@api private

BASIC_CONDITIONALS

@api private

BASIC_LITERALS

@api private

COMPARISON_OPERATORS

@api private <=> isn't included here, because it doesn't return a boolean.

COMPOSITE_LITERALS

@api private

CONDITIONALS

@api private

EQUALS_ASSIGNMENTS

@api private

FALSEY_LITERALS

@api private

IMMUTABLE_LITERALS

@api private

KEYWORDS

@api private

LITERALS

@api private

LITERAL_RECURSIVE_METHODS
LITERAL_RECURSIVE_TYPES
LOOP_TYPES

@api private

MUTABLE_LITERALS

@api private

OPERATOR_KEYWORDS

@api private

POST_CONDITION_LOOP_TYPES

@api private

REFERENCES

@api private

SHORTHAND_ASSIGNMENTS

@api private

SPECIAL_KEYWORDS

@api private

TRUTHY_LITERALS

@api private

VARIABLES

@api private

Public Class Methods

new(type, children = [], properties = {}) click to toggle source

@see www.rubydoc.info/gems/ast/AST/Node:initialize

Calls superclass method
# File lib/rubocop/ast/node.rb, line 88
def initialize(type, children = [], properties = {})
  @mutable_attributes = {}

  # ::AST::Node#initialize freezes itself.
  super

  # #parent= may be invoked multiple times for a node because there are
  # pending nodes while constructing AST and they are replaced later.
  # For example, `lvar` and `send` type nodes are initially created as an
  # `ident` type node and fixed to the appropriate type later.
  # So, the #parent attribute needs to be mutable.
  each_child_node do |child_node|
    child_node.parent = self unless child_node.complete?
  end
end

Public Instance Methods

ancestors() click to toggle source

Returns an array of ancestor nodes. This is a shorthand for `node.each_ancestor.to_a`.

@return [Array<Node>] an array of ancestor nodes

# File lib/rubocop/ast/node.rb, line 237
def ancestors
  each_ancestor.to_a
end
argument?() click to toggle source
# File lib/rubocop/ast/node.rb, line 454
def argument?
  parent&.send_type? && parent.arguments.include?(self)
end
argument_type?() click to toggle source
# File lib/rubocop/ast/node.rb, line 458
def argument_type?
  ARGUMENT_TYPES.include?(type)
end
assignment?() click to toggle source
# File lib/rubocop/ast/node.rb, line 406
def assignment?
  ASSIGNMENTS.include?(type)
end
basic_conditional?() click to toggle source
# File lib/rubocop/ast/node.rb, line 410
def basic_conditional?
  BASIC_CONDITIONALS.include?(type)
end
basic_literal?() click to toggle source
# File lib/rubocop/ast/node.rb, line 353
def basic_literal?
  BASIC_LITERALS.include?(type)
end
boolean_type?() click to toggle source
# File lib/rubocop/ast/node.rb, line 462
def boolean_type?
  true_type? || false_type?
end
call_type?() click to toggle source
# File lib/rubocop/ast/node.rb, line 446
def call_type?
  send_type? || csend_type?
end
chained?() click to toggle source
# File lib/rubocop/ast/node.rb, line 450
def chained?
  parent&.call_type? && eql?(parent.receiver)
end
complete!() click to toggle source
# File lib/rubocop/ast/node.rb, line 132
def complete!
  @mutable_attributes.freeze
  each_child_node(&:complete!)
end
complete?() click to toggle source
# File lib/rubocop/ast/node.rb, line 137
def complete?
  @mutable_attributes.frozen?
end
conditional?() click to toggle source
# File lib/rubocop/ast/node.rb, line 414
def conditional?
  CONDITIONALS.include?(type)
end
const_name() click to toggle source
# File lib/rubocop/ast/node.rb, line 283
def const_name
  return unless const_type?

  namespace, name = *self
  if namespace && !namespace.cbase_type?
    "#{namespace.const_name}::#{name}"
  else
    name.to_s
  end
end
defined_module() click to toggle source
# File lib/rubocop/ast/node.rb, line 304
def defined_module
  namespace, name = *defined_module0
  s(:const, namespace, name) if name
end
defined_module_name() click to toggle source
# File lib/rubocop/ast/node.rb, line 309
def defined_module_name
  (const = defined_module) && const.const_name
end
each_ancestor(*types, &block) click to toggle source

Calls the given block for each ancestor node from parent to root. If no block is given, an `Enumerator` is returned.

@overload each_ancestor

Yield all nodes.

@overload each_ancestor(type)

Yield only nodes matching the type.
@param [Symbol] type a node type

@overload each_ancestor(type_a, type_b, …)

Yield only nodes matching any of the types.
@param [Symbol] type_a a node type
@param [Symbol] type_b a node type

@yieldparam [Node] node each ancestor node @return [self] if a block is given @return [Enumerator] if no block is given

# File lib/rubocop/ast/node.rb, line 225
def each_ancestor(*types, &block)
  return to_enum(__method__, *types) unless block

  visit_ancestors(types, &block)

  self
end
empty_source?() click to toggle source
# File lib/rubocop/ast/node.rb, line 339
def empty_source?
  source_length.zero?
end
equals_asgn?() click to toggle source
# File lib/rubocop/ast/node.rb, line 398
def equals_asgn?
  EQUALS_ASSIGNMENTS.include?(type)
end
falsey_literal?() click to toggle source
# File lib/rubocop/ast/node.rb, line 361
def falsey_literal?
  FALSEY_LITERALS.include?(type)
end
first_line() click to toggle source
# File lib/rubocop/ast/node.rb, line 251
def first_line
  loc.line
end
guard_clause?() click to toggle source
# File lib/rubocop/ast/node.rb, line 474
def guard_clause?
  node = and_type? || or_type? ? rhs : self

  node.match_guard_clause?
end
immutable_literal?() click to toggle source
# File lib/rubocop/ast/node.rb, line 369
def immutable_literal?
  IMMUTABLE_LITERALS.include?(type)
end
keyword?() click to toggle source
# File lib/rubocop/ast/node.rb, line 427
def keyword?
  return true if special_keyword? || send_type? && prefix_not?
  return false unless KEYWORDS.include?(type)

  !OPERATOR_KEYWORDS.include?(type) || loc.operator.is?(type.to_s)
end
last_line() click to toggle source
# File lib/rubocop/ast/node.rb, line 255
def last_line
  loc.last_line
end
left_sibling() click to toggle source

Use is discouraged, this is a potentially slow method and can lead to even slower algorithms @return [Node, nil] the left (aka previous) sibling

# File lib/rubocop/ast/node.rb, line 175
def left_sibling
  i = sibling_index
  return if i.nil? || i.zero?

  parent.children[i - 1].freeze
end
left_siblings() click to toggle source

Use is discouraged, this is a potentially slow method and can lead to even slower algorithms @return [Array<Node>] the left (aka previous) siblings

# File lib/rubocop/ast/node.rb, line 185
def left_siblings
  return [].freeze unless parent

  parent.children[0...sibling_index].freeze
end
line_count() click to toggle source
# File lib/rubocop/ast/node.rb, line 259
def line_count
  return 0 unless source_range

  source_range.last_line - source_range.first_line + 1
end
literal?() click to toggle source
# File lib/rubocop/ast/node.rb, line 349
def literal?
  LITERALS.include?(type)
end
loop_keyword?() click to toggle source

NOTE: `loop { }` is a normal method call and thus not a loop keyword.

# File lib/rubocop/ast/node.rb, line 423
def loop_keyword?
  LOOP_TYPES.include?(type)
end
multiline?() click to toggle source

Predicates

# File lib/rubocop/ast/node.rb, line 331
def multiline?
  line_count > 1
end
mutable_literal?() click to toggle source
# File lib/rubocop/ast/node.rb, line 365
def mutable_literal?
  MUTABLE_LITERALS.include?(type)
end
node_parts() click to toggle source

Common destructuring method. This can be used to normalize destructuring for different variations of the node. Some node types override this with their own custom destructuring method.

@return [Array<Node>] the different parts of the ndde

# File lib/rubocop/ast/node.rb, line 206
def node_parts
  to_a
end
nonempty_line_count() click to toggle source
# File lib/rubocop/ast/node.rb, line 265
def nonempty_line_count
  source.lines.grep(/\S/).size
end
numeric_type?() click to toggle source
# File lib/rubocop/ast/node.rb, line 466
def numeric_type?
  int_type? || float_type?
end
operator_keyword?() click to toggle source
# File lib/rubocop/ast/node.rb, line 438
def operator_keyword?
  OPERATOR_KEYWORDS.include?(type)
end
parent() click to toggle source

Returns the parent node, or `nil` if the receiver is a root node.

@return [Node, nil] the parent node or `nil`

# File lib/rubocop/ast/node.rb, line 114
def parent
  @mutable_attributes[:parent]
end
parent?() click to toggle source

@return [Boolean]

# File lib/rubocop/ast/node.rb, line 123
def parent?
  !!parent
end
parent_module_name() click to toggle source

Searching the AST

# File lib/rubocop/ast/node.rb, line 315
def parent_module_name
  # what class or module is this method/constant/etc definition in?
  # returns nil if answer cannot be determined
  ancestors = each_ancestor(:class, :module, :sclass, :casgn, :block)
  result    = ancestors.map do |ancestor|
    parent_module_name_part(ancestor) do |full_name|
      return nil unless full_name

      full_name
    end
  end.compact.reverse.join('::')
  result.empty? ? 'Object' : result
end
parenthesized_call?() click to toggle source
# File lib/rubocop/ast/node.rb, line 442
def parenthesized_call?
  loc.respond_to?(:begin) && loc.begin && loc.begin.is?('(')
end
post_condition_loop?() click to toggle source
# File lib/rubocop/ast/node.rb, line 418
def post_condition_loop?
  POST_CONDITION_LOOP_TYPES.include?(type)
end
pure?() click to toggle source

Some expressions are evaluated for their value, some for their side effects, and some for both. If we know that expressions are useful only for their return values, and have no side effects, that means we can reorder them, change the number of times they are evaluated, or replace them with other expressions which are equivalent in value. So, is evaluation of this node free of side effects?

# File lib/rubocop/ast/node.rb, line 566
def pure?
  # Be conservative and return false if we're not sure
  case type
  when :__FILE__, :__LINE__, :const, :cvar, :defined?, :false, :float,
       :gvar, :int, :ivar, :lvar, :nil, :str, :sym, :true, :regopt
    true
  when :and, :array, :begin, :case, :dstr, :dsym, :eflipflop, :ensure,
       :erange, :for, :hash, :if, :iflipflop, :irange, :kwbegin, :not,
       :or, :pair, :regexp, :until, :until_post, :when, :while,
       :while_post
    child_nodes.all?(&:pure?)
  else
    false
  end
end
range_type?() click to toggle source
# File lib/rubocop/ast/node.rb, line 470
def range_type?
  irange_type? || erange_type?
end
reference?() click to toggle source
# File lib/rubocop/ast/node.rb, line 394
def reference?
  REFERENCES.include?(type)
end
right_sibling() click to toggle source

Use is discouraged, this is a potentially slow method and can lead to even slower algorithms @return [Node, nil] the right (aka next) sibling

# File lib/rubocop/ast/node.rb, line 166
def right_sibling
  return unless parent

  parent.children[sibling_index + 1].freeze
end
right_siblings() click to toggle source

Use is discouraged, this is a potentially slow method and can lead to even slower algorithms @return [Array<Node>] the right (aka next) siblings

# File lib/rubocop/ast/node.rb, line 194
def right_siblings
  return [].freeze unless parent

  parent.children[sibling_index + 1..-1].freeze
end
root?() click to toggle source

@return [Boolean]

# File lib/rubocop/ast/node.rb, line 128
def root?
  !parent
end
shorthand_asgn?() click to toggle source
# File lib/rubocop/ast/node.rb, line 402
def shorthand_asgn?
  SHORTHAND_ASSIGNMENTS.include?(type)
end
sibling_index() click to toggle source

Returns the index of the receiver node in its siblings. (Sibling index uses zero based numbering.) Use is discouraged, this is a potentially slow method.

@return [Integer, nil] the index of the receiver node in its siblings

# File lib/rubocop/ast/node.rb, line 159
def sibling_index
  parent&.children&.index { |sibling| sibling.equal?(self) }
end
single_line?() click to toggle source
# File lib/rubocop/ast/node.rb, line 335
def single_line?
  line_count == 1
end
source() click to toggle source

NOTE: Some rare nodes may have no source, like `s(:args)` in `foo {}` @return [String, nil]

# File lib/rubocop/ast/node.rb, line 243
def source
  loc.expression&.source
end
source_length() click to toggle source
# File lib/rubocop/ast/node.rb, line 269
def source_length
  source_range ? source_range.size : 0
end
source_range() click to toggle source
# File lib/rubocop/ast/node.rb, line 247
def source_range
  loc.expression
end
special_keyword?() click to toggle source
# File lib/rubocop/ast/node.rb, line 434
def special_keyword?
  SPECIAL_KEYWORDS.include?(source)
end
truthy_literal?() click to toggle source
# File lib/rubocop/ast/node.rb, line 357
def truthy_literal?
  TRUTHY_LITERALS.include?(type)
end
updated(type = nil, children = nil, properties = {}) click to toggle source

Override `AST::Node#updated` so that `AST::Processor` does not try to mutate our ASTs. Since we keep references from children to parents and not just the other way around, we cannot update an AST and share identical subtrees. Rather, the entire AST must be copied any time any part of it is changed.

# File lib/rubocop/ast/node.rb, line 148
def updated(type = nil, children = nil, properties = {})
  properties[:location] ||= @location
  klass = RuboCop::AST::Builder::NODE_MAP[type || @type] || Node
  klass.new(type || @type, children || @children, properties)
end
value_used?() click to toggle source

Some expressions are evaluated for their value, some for their side effects, and some for both If we know that an expression is useful only for its side effects, that means we can transform it in ways which preserve the side effects, but change the return value So, does the return value of this node matter? If we changed it to `(…; nil)`, might that affect anything?

rubocop:disable Metrics/MethodLength

# File lib/rubocop/ast/node.rb, line 535
def value_used?
  # Be conservative and return true if we're not sure.
  return false if parent.nil?

  case parent.type
  when :array, :defined?, :dstr, :dsym, :eflipflop, :erange, :float,
       :hash, :iflipflop, :irange, :not, :pair, :regexp, :str, :sym,
       :when, :xstr
    parent.value_used?
  when :begin, :kwbegin
    begin_value_used?
  when :for
    for_value_used?
  when :case, :if
    case_if_value_used?
  when :while, :until, :while_post, :until_post
    while_until_value_used?
  else
    true
  end
end
variable?() click to toggle source
# File lib/rubocop/ast/node.rb, line 390
def variable?
  VARIABLES.include?(type)
end

Protected Instance Methods

parent=(node) click to toggle source
# File lib/rubocop/ast/node.rb, line 118
def parent=(node)
  @mutable_attributes[:parent] = node
end

Private Instance Methods

begin_value_used?() click to toggle source
# File lib/rubocop/ast/node.rb, line 594
def begin_value_used?
  # the last child node determines the value of the parent
  sibling_index == parent.children.size - 1 ? parent.value_used? : false
end
case_if_value_used?() click to toggle source
# File lib/rubocop/ast/node.rb, line 605
def case_if_value_used?
  # (case <condition> <when...>)
  # (if <condition> <truebranch> <falsebranch>)
  sibling_index.zero? ? true : parent.value_used?
end
for_value_used?() click to toggle source
# File lib/rubocop/ast/node.rb, line 599
def for_value_used?
  # `for var in enum; body; end`
  # (for <var> <enum> <body>)
  sibling_index == 2 ? parent.value_used? : true
end
parent_module_name_for_block(ancestor) { || ... } click to toggle source
# File lib/rubocop/ast/node.rb, line 641
def parent_module_name_for_block(ancestor)
  if ancestor.method?(:class_eval)
    # `class_eval` with no receiver applies to whatever module or class
    # we are currently in
    return unless (receiver = ancestor.receiver)

    yield unless receiver.const_type?
    receiver.const_name
  elsif !new_class_or_module_block?(ancestor)
    yield
  end
end
parent_module_name_for_sclass(sclass_node) click to toggle source
# File lib/rubocop/ast/node.rb, line 629
def parent_module_name_for_sclass(sclass_node)
  # TODO: look for constant definition and see if it is nested
  # inside a class or module
  subject = sclass_node.children[0]

  if subject.const_type?
    "#<Class:#{subject.const_name}>"
  elsif subject.self_type?
    "#<Class:#{sclass_node.parent_module_name}>"
  end
end
parent_module_name_part(node) { |parent_module_name_for_sclass(node)| ... } click to toggle source
# File lib/rubocop/ast/node.rb, line 616
def parent_module_name_part(node)
  case node.type
  when :class, :module, :casgn
    # TODO: if constant name has cbase (leading ::), then we don't need
    # to keep traversing up through nested classes/modules
    node.defined_module_name
  when :sclass
    yield parent_module_name_for_sclass(node)
  else # block
    parent_module_name_for_block(node) { yield nil }
  end
end
visit_ancestors(types) { |current_node| ... } click to toggle source
# File lib/rubocop/ast/node.rb, line 584
def visit_ancestors(types)
  last_node = self

  while (current_node = last_node.parent)
    yield current_node if types.empty? ||
                          types.include?(current_node.type)
    last_node = current_node
  end
end
while_until_value_used?() click to toggle source
# File lib/rubocop/ast/node.rb, line 611
def while_until_value_used?
  # (while <condition> <body>) -> always evaluates to `nil`
  sibling_index.zero?
end