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

BASIC_LITERALS
COMPARISON_OPERATORS

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

COMPOSITE_LITERALS
FALSEY_LITERALS
IMMUTABLE_LITERALS
KEYWORDS
LITERALS
MUTABLE_LITERALS
OPERATOR_KEYWORDS
REFERENCES
SPECIAL_KEYWORDS
TRUTHY_LITERALS
VARIABLES

Public Class Methods

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

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

Calls superclass method
# File lib/rubocop/ast/node.rb, line 49
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 142
def ancestors
  each_ancestor.to_a
end
argument?() click to toggle source
# File lib/rubocop/ast/node.rb, line 432
def argument?
  parent && parent.send_type?
end
asgn_method_call?() click to toggle source
# File lib/rubocop/ast/node.rb, line 323
def asgn_method_call?
  !COMPARISON_OPERATORS.include?(method_name) &&
    method_name.to_s.end_with?('='.freeze)
end
basic_literal?() click to toggle source
# File lib/rubocop/ast/node.rb, line 342
def basic_literal?
  BASIC_LITERALS.include?(type)
end
binary_operation?() click to toggle source
# File lib/rubocop/ast/node.rb, line 419
def binary_operation?
  return false unless loc.respond_to?(:selector) && loc.selector
  Cop::Util.operator?(method_name) &&
    source_range.begin_pos != loc.selector.begin_pos
end
chained?() click to toggle source
# File lib/rubocop/ast/node.rb, line 425
def chained?
  return false unless argument?

  receiver, _method_name, *_args = *parent
  equal?(receiver)
end
child_nodes() click to toggle source

Returns an array of child nodes. This is a shorthand for `node.each_child_node.to_a`.

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

# File lib/rubocop/ast/node.rb, line 182
def child_nodes
  each_child_node.to_a
end
complete!() click to toggle source
# File lib/rubocop/ast/node.rb, line 83
def complete!
  @mutable_attributes.freeze
  each_child_node(&:complete!)
end
complete?() click to toggle source
# File lib/rubocop/ast/node.rb, line 88
def complete?
  @mutable_attributes.frozen?
end
const_name() click to toggle source
# File lib/rubocop/ast/node.rb, line 274
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 292
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 297
def defined_module_name
  (const = defined_module) && const.const_name
end
descendants() click to toggle source

Returns an array of descendant nodes. This is a shorthand for `node.each_descendant.to_a`.

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

# File lib/rubocop/ast/node.rb, line 216
def descendants
  each_descendant.to_a
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

@overload #each_ancestor(types)

Yield only nodes matching any of types in the array.
@param [Array<Symbol>] types an array containing node types

@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 130
def each_ancestor(*types, &block)
  return to_enum(__method__, *types) unless block_given?

  visit_ancestors(types, &block)

  self
end
each_child_node(*types) { |child| ... } click to toggle source

Calls the given block for each child node. If no block is given, an `Enumerator` is returned.

Note that this is different from `node.children.each { |child| … }` which yields all children including non-node elements.

@overload #each_child_node

Yield all nodes.

@overload #each_child_node(type)

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

@overload #each_child_node(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

@overload #each_child_node(types)

Yield only nodes matching any of types in the array.
@param [Array<Symbol>] types an array containing node types

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

# File lib/rubocop/ast/node.rb, line 167
def each_child_node(*types)
  return to_enum(__method__, *types) unless block_given?

  children.each do |child|
    next unless child.is_a?(Node)
    yield child if types.empty? || types.include?(child.type)
  end

  self
end
each_descendant(*types, &block) click to toggle source

Calls the given block for each descendant node with depth first order. If no block is given, an `Enumerator` is returned.

@overload #each_descendant

Yield all nodes.

@overload #each_descendant(type)

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

@overload #each_descendant(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

@overload #each_descendant(types)

Yield only nodes matching any of types in the array.
@param [Array<Symbol>] types an array containing node types

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

# File lib/rubocop/ast/node.rb, line 204
def each_descendant(*types, &block)
  return to_enum(__method__, *types) unless block_given?

  visit_descendants(types, &block)

  self
end
each_node(*types) { |self| ... } click to toggle source

Calls the given block for the receiver and each descendant node in depth-first order. If no block is given, an `Enumerator` is returned.

This method would be useful when you treat the receiver node as the root of a tree and want to iterate over all nodes in the tree.

@overload #each_node

Yield all nodes.

@overload #each_node(type)

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

@overload #each_node(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

@overload #each_node(types)

Yield only nodes matching any of types in the array.
@param [Array<Symbol>] types an array containing node types

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

# File lib/rubocop/ast/node.rb, line 242
def each_node(*types, &block)
  return to_enum(__method__, *types) unless block_given?

  yield self if types.empty? || types.include?(type)

  visit_descendants(types, &block)

  self
end
falsey_literal?() click to toggle source
# File lib/rubocop/ast/node.rb, line 350
def falsey_literal?
  FALSEY_LITERALS.include?(type)
end
immutable_literal?() click to toggle source
# File lib/rubocop/ast/node.rb, line 358
def immutable_literal?
  IMMUTABLE_LITERALS.include?(type)
end
keyword?() click to toggle source
# File lib/rubocop/ast/node.rb, line 388
def keyword?
  return true if special_keyword? || keyword_not?
  return false unless KEYWORDS.include?(type)

  !OPERATOR_KEYWORDS.include?(type) || loc.operator.is?(type.to_s)
end
keyword_bang?() click to toggle source
# File lib/rubocop/ast/node.rb, line 408
def keyword_bang?
  _receiver, method_name, *args = *self
  args.empty? && method_name == :! && loc.selector.is?('!'.freeze)
end
keyword_not?() click to toggle source
# File lib/rubocop/ast/node.rb, line 403
def keyword_not?
  _receiver, method_name, *args = *self
  args.empty? && method_name == :! && loc.selector.is?('not'.freeze)
end
literal?() click to toggle source
# File lib/rubocop/ast/node.rb, line 338
def literal?
  LITERALS.include?(type)
end
multiline?() click to toggle source

Predicates

# File lib/rubocop/ast/node.rb, line 315
def multiline?
  source_range && (source_range.first_line != source_range.last_line)
end
mutable_literal?() click to toggle source
# File lib/rubocop/ast/node.rb, line 354
def mutable_literal?
  MUTABLE_LITERALS.include?(type)
end
numeric_type?() click to toggle source
# File lib/rubocop/ast/node.rb, line 436
def numeric_type?
  int_type? || float_type?
end
operator_keyword?() click to toggle source
# File lib/rubocop/ast/node.rb, line 399
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 75
def parent
  @mutable_attributes[:parent]
end
parent_module_name() click to toggle source

Searching the AST

# File lib/rubocop/ast/node.rb, line 303
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) { |full_name| return full_name }
  end.compact.reverse.join('::')
  result.empty? ? 'Object' : result
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 502
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
reference?() click to toggle source
# File lib/rubocop/ast/node.rb, line 384
def reference?
  REFERENCES.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.)

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

# File lib/rubocop/ast/node.rb, line 108
def sibling_index
  parent.children.index { |sibling| sibling.equal?(self) }
end
single_line?() click to toggle source
# File lib/rubocop/ast/node.rb, line 319
def single_line?
  !multiline?
end
source() click to toggle source
# File lib/rubocop/ast/node.rb, line 252
def source
  loc.expression.source
end
source_range() click to toggle source
# File lib/rubocop/ast/node.rb, line 256
def source_range
  loc.expression
end
special_keyword?() click to toggle source
# File lib/rubocop/ast/node.rb, line 395
def special_keyword?
  SPECIAL_KEYWORDS.include?(source)
end
truthy_literal?() click to toggle source
# File lib/rubocop/ast/node.rb, line 346
def truthy_literal?
  TRUTHY_LITERALS.include?(type)
end
unary_operation?() click to toggle source
# File lib/rubocop/ast/node.rb, line 413
def unary_operation?
  return false unless loc.respond_to?(:selector) && loc.selector
  Cop::Util.operator?(loc.selector.source.to_sym) &&
    source_range.begin_pos == loc.selector.begin_pos
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 99
def updated(type = nil, children = nil, properties = {})
  properties[:location] ||= @location
  self.class.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, Metrics/CyclomaticComplexity

# File lib/rubocop/ast/node.rb, line 471
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 380
def variable?
  VARIABLES.include?(type)
end

Protected Instance Methods

parent=(node) click to toggle source
# File lib/rubocop/ast/node.rb, line 79
def parent=(node)
  @mutable_attributes[:parent] = node
end
visit_descendants(types) { |child| ... } click to toggle source
# File lib/rubocop/ast/node.rb, line 520
def visit_descendants(types, &block)
  each_child_node do |child|
    yield child if types.empty? || types.include?(child.type)
    child.visit_descendants(types, &block)
  end
end

Private Instance Methods

begin_value_used?() click to toggle source
# File lib/rubocop/ast/node.rb, line 539
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 550
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 544
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 586
def parent_module_name_for_block(ancestor)
  if ancestor.method_name == :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 574
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 561
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 529
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 556
def while_until_value_used?
  # (while <condition> <body>) -> always evaluates to `nil`
  sibling_index.zero?
end