Class: RuboCop::AST::Node

Inherits:
Parser::AST::Node
  • Object
show all
Includes:
Sexp
Defined in:
lib/rubocop/ast/node.rb

Overview

‘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:

Examples:

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?)

Constant Summary collapse

COMPARISON_OPERATORS = 
[:!, :==, :===, :!=, :<=, :>=, :>, :<, :<=>].freeze
TRUTHY_LITERALS = 
[:str, :dstr, :xstr, :int, :float, :sym, :dsym, :array,
:hash, :regexp, :true, :irange, :erange, :complex,
:rational, :regopt].freeze
FALSEY_LITERALS = 
[:false, :nil].freeze
LITERALS = 
(TRUTHY_LITERALS + FALSEY_LITERALS).freeze
COMPOSITE_LITERALS = 
[:dstr, :xstr, :dsym, :array, :hash, :irange,
:erange, :regexp].freeze
BASIC_LITERALS = 
(LITERALS - COMPOSITE_LITERALS).freeze
MUTABLE_LITERALS = 
[:str, :dstr, :xstr, :array, :hash].freeze
IMMUTABLE_LITERALS = 
(LITERALS - MUTABLE_LITERALS).freeze
VARIABLES = 
[:ivar, :gvar, :cvar, :lvar].freeze
REFERENCES = 
[:nth_ref, :back_ref].freeze
KEYWORDS = 
[:alias, :and, :break, :case, :class, :def, :defs, :defined?,
:kwbegin, :do, :else, :ensure, :for, :if, :module, :next,
:not, :or, :postexe, :redo, :rescue, :retry, :return, :self,
:super, :zsuper, :then, :undef, :until, :when, :while,
:yield].freeze
OPERATOR_KEYWORDS = 
[:and, :or].freeze
SPECIAL_KEYWORDS = 
%w(__FILE__ __LINE__ __ENCODING__).freeze

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Sexp

#s

Constructor Details

#initialize(type, children = [], properties = {}) ⇒ Node

Returns a new instance of Node.

See Also:



61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
 
# File 'lib/rubocop/ast/node.rb', line 61

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

Class Method Details

.def_matcher(method_name, pattern_str) ⇒ Object 



49
50
51
52
53
54
55
56
57
 
# File 'lib/rubocop/ast/node.rb', line 49

def def_matcher(method_name, pattern_str)
  compiler = RuboCop::NodePattern::Compiler.new(pattern_str, 'self')
  src = "def #{method_name}(" \
        "#{compiler.emit_param_list});" \
        "#{compiler.emit_method_code};end"

  file, lineno = *caller.first.split(':')
  class_eval(src, file, lineno.to_i)
end

Instance Method Details

#ancestors ⇒ Array<Node>

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

Returns:

  • (Array<Node>) —

    an array of ancestor nodes



154
155
156
 
# File 'lib/rubocop/ast/node.rb', line 154

def ancestors
  each_ancestor.to_a
end

#argument? ⇒ Boolean

Returns:

  • (Boolean) 


430
431
432
 
# File 'lib/rubocop/ast/node.rb', line 430

def argument?
  parent && parent.send_type?
end

#asgn_method_call? ⇒ Boolean

Returns:

  • (Boolean) 


330
331
332
333
 
# File 'lib/rubocop/ast/node.rb', line 330

def asgn_method_call?
  !COMPARISON_OPERATORS.include?(method_name) &&
    method_name.to_s.end_with?('='.freeze)
end

#basic_literal? ⇒ Boolean

Returns:

  • (Boolean) 


344
345
346
 
# File 'lib/rubocop/ast/node.rb', line 344

def basic_literal?
  BASIC_LITERALS.include?(type)
end

#binary_operation? ⇒ Boolean

Returns:

  • (Boolean) 


417
418
419
420
421
 
# File 'lib/rubocop/ast/node.rb', line 417

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? ⇒ Boolean

Returns:

  • (Boolean) 


423
424
425
426
427
428
 
# File 'lib/rubocop/ast/node.rb', line 423

def chained?
  return false unless argument?

  receiver, _method_name, *_args = *parent
  equal?(receiver)
end

#child_nodes ⇒ Array<Node>

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

Returns:

  • (Array<Node>) —

    an array of child nodes



194
195
196
 
# File 'lib/rubocop/ast/node.rb', line 194

def child_nodes
  each_child_node.to_a
end

#complete! ⇒ Object 



95
96
97
98
 
# File 'lib/rubocop/ast/node.rb', line 95

def complete!
  @mutable_attributes.freeze
  each_child_node(&:complete!)
end

#complete? ⇒ Boolean

Returns:

  • (Boolean) 


100
101
102
 
# File 'lib/rubocop/ast/node.rb', line 100

def complete?
  @mutable_attributes.frozen?
end

#const_name ⇒ Object 



281
282
283
284
285
286
287
288
289
 
# File 'lib/rubocop/ast/node.rb', line 281

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 ⇒ Object 



299
300
301
302
 
# File 'lib/rubocop/ast/node.rb', line 299

def defined_module
  namespace, name = *defined_module0
  s(:const, namespace, name) if name
end

#defined_module_name ⇒ Object 



304
305
306
 
# File 'lib/rubocop/ast/node.rb', line 304

def defined_module_name
  (const = defined_module) && const.const_name
end

#descendants ⇒ Array<Node>

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

Returns:

  • (Array<Node>) —

    an array of descendant nodes



228
229
230
 
# File 'lib/rubocop/ast/node.rb', line 228

def descendants
  each_descendant.to_a
end

#each_ancestor ⇒ self, Enumerator #each_ancestor(type) ⇒ self, Enumerator #each_ancestor(type_a, type_b, ...) ⇒ self, Enumerator #each_ancestor(types) ⇒ self, Enumerator

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

Overloads:

  • #each_ancestor ⇒ self, Enumerator

    Yield all nodes.

  • #each_ancestor(type) ⇒ self, Enumerator

    Yield only nodes matching the type.

    Parameters:

    • type (Symbol) —

      a node type

  • #each_ancestor(type_a, type_b, ...) ⇒ self, Enumerator

    Yield only nodes matching any of the types.

    Parameters:

    • type_a (Symbol) —

      a node type

    • type_b (Symbol) —

      a node type

  • #each_ancestor(types) ⇒ self, Enumerator

    Yield only nodes matching any of types in the array.

    Parameters:

    • types (Array<Symbol>) —

      an array containing node types

Yield Parameters:

  • node (Node) —

    each ancestor node

Returns:

  • (self) —

    if a block is given

  • (Enumerator) —

    if no block is given



142
143
144
145
146
147
148
 
# File 'lib/rubocop/ast/node.rb', line 142

def each_ancestor(*types, &block)
  return to_enum(__method__, *types) unless block_given?

  visit_ancestors(types, &block)

  self
end

#each_child_node ⇒ self, Enumerator #each_child_node(type) ⇒ self, Enumerator #each_child_node(type_a, type_b, ...) ⇒ self, Enumerator #each_child_node(types) ⇒ self, Enumerator

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.

Overloads:

  • #each_child_node ⇒ self, Enumerator

    Yield all nodes.

  • #each_child_node(type) ⇒ self, Enumerator

    Yield only nodes matching the type.

    Parameters:

    • type (Symbol) —

      a node type

  • #each_child_node(type_a, type_b, ...) ⇒ self, Enumerator

    Yield only nodes matching any of the types.

    Parameters:

    • type_a (Symbol) —

      a node type

    • type_b (Symbol) —

      a node type

  • #each_child_node(types) ⇒ self, Enumerator

    Yield only nodes matching any of types in the array.

    Parameters:

    • types (Array<Symbol>) —

      an array containing node types

Yield Parameters:

  • node (Node) —

    each child node

Returns:

  • (self) —

    if a block is given

  • (Enumerator) —

    if no block is given



179
180
181
182
183
184
185
186
187
188
 
# File 'lib/rubocop/ast/node.rb', line 179

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 ⇒ self, Enumerator #each_descendant(type) ⇒ self, Enumerator #each_descendant(type_a, type_b, ...) ⇒ self, Enumerator #each_descendant(types) ⇒ self, Enumerator

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

Overloads:

  • #each_descendant ⇒ self, Enumerator

    Yield all nodes.

  • #each_descendant(type) ⇒ self, Enumerator

    Yield only nodes matching the type.

    Parameters:

    • type (Symbol) —

      a node type

  • #each_descendant(type_a, type_b, ...) ⇒ self, Enumerator

    Yield only nodes matching any of the types.

    Parameters:

    • type_a (Symbol) —

      a node type

    • type_b (Symbol) —

      a node type

  • #each_descendant(types) ⇒ self, Enumerator

    Yield only nodes matching any of types in the array.

    Parameters:

    • types (Array<Symbol>) —

      an array containing node types

Yield Parameters:

  • node (Node) —

    each descendant node

Returns:

  • (self) —

    if a block is given

  • (Enumerator) —

    if no block is given



216
217
218
219
220
221
222
 
# File 'lib/rubocop/ast/node.rb', line 216

def each_descendant(*types, &block)
  return to_enum(__method__, *types) unless block_given?

  visit_descendants(types, &block)

  self
end

#each_node ⇒ self, Enumerator #each_node(type) ⇒ self, Enumerator #each_node(type_a, type_b, ...) ⇒ self, Enumerator #each_node(types) ⇒ self, Enumerator

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.

Overloads:

  • #each_node ⇒ self, Enumerator

    Yield all nodes.

  • #each_node(type) ⇒ self, Enumerator

    Yield only nodes matching the type.

    Parameters:

    • type (Symbol) —

      a node type

  • #each_node(type_a, type_b, ...) ⇒ self, Enumerator

    Yield only nodes matching any of the types.

    Parameters:

    • type_a (Symbol) —

      a node type

    • type_b (Symbol) —

      a node type

  • #each_node(types) ⇒ self, Enumerator

    Yield only nodes matching any of types in the array.

    Parameters:

    • types (Array<Symbol>) —

      an array containing node types

Yield Parameters:

  • node (Node) —

    each node

Returns:

  • (self) —

    if a block is given

  • (Enumerator) —

    if no block is given



254
255
256
257
258
259
260
261
262
 
# File 'lib/rubocop/ast/node.rb', line 254

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? ⇒ Boolean

Returns:

  • (Boolean) 


352
353
354
 
# File 'lib/rubocop/ast/node.rb', line 352

def falsey_literal?
  FALSEY_LITERALS.include?(type)
end

#immutable_literal? ⇒ Boolean

Returns:

  • (Boolean) 


360
361
362
 
# File 'lib/rubocop/ast/node.rb', line 360

def immutable_literal?
  IMMUTABLE_LITERALS.include?(type)
end

#keyword? ⇒ Boolean

Returns:

  • (Boolean) 


390
391
392
393
394
395
 
# File 'lib/rubocop/ast/node.rb', line 390

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? ⇒ Boolean

Returns:

  • (Boolean) 


406
407
408
409
 
# File 'lib/rubocop/ast/node.rb', line 406

def keyword_bang?
  _receiver, method_name, *args = *self
  args.empty? && method_name == :! && loc.selector.is?('!'.freeze)
end

#keyword_not? ⇒ Boolean

Returns:

  • (Boolean) 


401
402
403
404
 
# File 'lib/rubocop/ast/node.rb', line 401

def keyword_not?
  _receiver, method_name, *args = *self
  args.empty? && method_name == :! && loc.selector.is?('not'.freeze)
end

#literal? ⇒ Boolean

Returns:

  • (Boolean) 


340
341
342
 
# File 'lib/rubocop/ast/node.rb', line 340

def literal?
  LITERALS.include?(type)
end

#multiline? ⇒ Boolean

Predicates

Returns:

  • (Boolean) 


322
323
324
 
# File 'lib/rubocop/ast/node.rb', line 322

def multiline?
  source_range && (source_range.first_line != source_range.last_line)
end

#mutable_literal? ⇒ Boolean

Returns:

  • (Boolean) 


356
357
358
 
# File 'lib/rubocop/ast/node.rb', line 356

def mutable_literal?
  MUTABLE_LITERALS.include?(type)
end

#numeric_type? ⇒ Boolean

Returns:

  • (Boolean) 


434
435
436
 
# File 'lib/rubocop/ast/node.rb', line 434

def numeric_type?
  int_type? || float_type?
end

#parent ⇒ Node?

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

Returns:

  • (Node, nil) —

    the parent node or ‘nil`



87
88
89
 
# File 'lib/rubocop/ast/node.rb', line 87

def parent
  @mutable_attributes[:parent]
end

#parent_module_name ⇒ Object

Searching the AST



310
311
312
313
314
315
316
317
318
 
# File 'lib/rubocop/ast/node.rb', line 310

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? ⇒ Boolean

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?

Returns:

  • (Boolean) 


500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
 
# File 'lib/rubocop/ast/node.rb', line 500

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

#receiver ⇒ Object

Destructuring



274
 
# File 'lib/rubocop/ast/node.rb', line 274

def_matcher :receiver,    '{(send $_ ...) (block (send $_ ...) ...)}'

#reference? ⇒ Boolean

Returns:

  • (Boolean) 


386
387
388
 
# File 'lib/rubocop/ast/node.rb', line 386

def reference?
  REFERENCES.include?(type)
end

#sibling_index ⇒ Integer

Returns the index of the receiver node in its siblings. (Sibling index uses zero based numbering.)

Returns:

  • (Integer) —

    the index of the receiver node in its siblings



120
121
122
 
# File 'lib/rubocop/ast/node.rb', line 120

def sibling_index
  parent.children.index { |sibling| sibling.equal?(self) }
end

#single_line? ⇒ Boolean

Returns:

  • (Boolean) 


326
327
328
 
# File 'lib/rubocop/ast/node.rb', line 326

def single_line?
  !multiline?
end

#source ⇒ Object 



264
265
266
 
# File 'lib/rubocop/ast/node.rb', line 264

def source
  loc.expression.source
end

#source_range ⇒ Object 



268
269
270
 
# File 'lib/rubocop/ast/node.rb', line 268

def source_range
  loc.expression
end

#special_keyword? ⇒ Boolean

Returns:

  • (Boolean) 


397
398
399
 
# File 'lib/rubocop/ast/node.rb', line 397

def special_keyword?
  SPECIAL_KEYWORDS.include?(source)
end

#truthy_literal? ⇒ Boolean

Returns:

  • (Boolean) 


348
349
350
 
# File 'lib/rubocop/ast/node.rb', line 348

def truthy_literal?
  TRUTHY_LITERALS.include?(type)
end

#unary_operation? ⇒ Boolean

Returns:

  • (Boolean) 


411
412
413
414
415
 
# File 'lib/rubocop/ast/node.rb', line 411

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 = {}) ⇒ Object

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.



111
112
113
114
 
# File 'lib/rubocop/ast/node.rb', line 111

def updated(type = nil, children = nil, properties = {})
  properties[:location] ||= @location
  Node.new(type || @type, children || @children, properties)
end

#value_used? ⇒ Boolean

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

Returns:

  • (Boolean) 


469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
 
# File 'lib/rubocop/ast/node.rb', line 469

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? ⇒ Boolean

Returns:

  • (Boolean) 


382
383
384
 
# File 'lib/rubocop/ast/node.rb', line 382

def variable?
  VARIABLES.include?(type)
end