Class: RuboCop::AST::Node

Inherits:
Parser::AST::Node
  • Object
show all
Extended by:
NodePattern::Macros
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 =

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

i[== === != <= >= > <].freeze
TRUTHY_LITERALS = 
i[str dstr xstr int float sym dsym array
hash regexp true irange erange complex
rational regopt].freeze
FALSEY_LITERALS = 
i[false nil].freeze
LITERALS = 
(TRUTHY_LITERALS + FALSEY_LITERALS).freeze
COMPOSITE_LITERALS = 
i[dstr xstr dsym array hash irange
erange regexp].freeze
BASIC_LITERALS = 
(LITERALS - COMPOSITE_LITERALS).freeze
MUTABLE_LITERALS = 
i[str dstr xstr array hash].freeze
IMMUTABLE_LITERALS = 
(LITERALS - MUTABLE_LITERALS).freeze
VARIABLES = 
i[ivar gvar cvar lvar].freeze
REFERENCES = 
i[nth_ref back_ref].freeze
KEYWORDS = 
i[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 = 
i[and or].freeze
SPECIAL_KEYWORDS = 
%w[__FILE__ __LINE__ __ENCODING__].freeze

Instance Method Summary collapse

Methods included from NodePattern::Macros

def_node_matcher, def_node_search, node_search, node_search_all, node_search_body, node_search_first

Methods included from Sexp

#s

Constructor Details

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

Returns a new instance of Node.

See Also:



50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
 
# File 'lib/rubocop/ast/node.rb', line 50

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

Instance Method Details

#ancestors ⇒ Array<Node>

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



143
144
145
 
# File 'lib/rubocop/ast/node.rb', line 143

def ancestors
  each_ancestor.to_a
end

#argument? ⇒ Boolean 



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

def argument?
  parent && parent.send_type?
end

#asgn_method_call? ⇒ Boolean 



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

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

#basic_literal? ⇒ Boolean 



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

def basic_literal?
  BASIC_LITERALS.include?(type)
end

#binary_operation? ⇒ Boolean 



420
421
422
423
424
 
# File 'lib/rubocop/ast/node.rb', line 420

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 



426
427
428
429
430
431
 
# File 'lib/rubocop/ast/node.rb', line 426

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`.



183
184
185
 
# File 'lib/rubocop/ast/node.rb', line 183

def child_nodes
  each_child_node.to_a
end

#complete! ⇒ Object 



84
85
86
87
 
# File 'lib/rubocop/ast/node.rb', line 84

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

#complete? ⇒ Boolean 



89
90
91
 
# File 'lib/rubocop/ast/node.rb', line 89

def complete?
  @mutable_attributes.frozen?
end

#const_name ⇒ Object 



275
276
277
278
279
280
281
282
283
 
# File 'lib/rubocop/ast/node.rb', line 275

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 



293
294
295
296
 
# File 'lib/rubocop/ast/node.rb', line 293

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

#defined_module_name ⇒ Object 



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

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`.



217
218
219
 
# File 'lib/rubocop/ast/node.rb', line 217

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.

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

    Yield only nodes matching any of the types.

  • #each_ancestor(types) ⇒ self, Enumerator

    Yield only nodes matching any of types in the array.

Yield Parameters:

  • node (Node) —

    each ancestor node



131
132
133
134
135
136
137
 
# File 'lib/rubocop/ast/node.rb', line 131

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.

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

    Yield only nodes matching any of the types.

  • #each_child_node(types) ⇒ self, Enumerator

    Yield only nodes matching any of types in the array.

Yield Parameters:

  • node (Node) —

    each child node



168
169
170
171
172
173
174
175
176
177
 
# File 'lib/rubocop/ast/node.rb', line 168

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.

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

    Yield only nodes matching any of the types.

  • #each_descendant(types) ⇒ self, Enumerator

    Yield only nodes matching any of types in the array.

Yield Parameters:

  • node (Node) —

    each descendant node



205
206
207
208
209
210
211
 
# File 'lib/rubocop/ast/node.rb', line 205

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.

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

    Yield only nodes matching any of the types.

  • #each_node(types) ⇒ self, Enumerator

    Yield only nodes matching any of types in the array.

Yield Parameters:

  • node (Node) —

    each node



243
244
245
246
247
248
249
250
251
 
# File 'lib/rubocop/ast/node.rb', line 243

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 



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

def falsey_literal?
  FALSEY_LITERALS.include?(type)
end

#immutable_literal? ⇒ Boolean 



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

def immutable_literal?
  IMMUTABLE_LITERALS.include?(type)
end

#keyword? ⇒ Boolean 



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

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 



409
410
411
412
 
# File 'lib/rubocop/ast/node.rb', line 409

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

#keyword_not? ⇒ Boolean 



404
405
406
407
 
# File 'lib/rubocop/ast/node.rb', line 404

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

#literal? ⇒ Boolean 



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

def literal?
  LITERALS.include?(type)
end

#multiline? ⇒ Boolean

Predicates



316
317
318
 
# File 'lib/rubocop/ast/node.rb', line 316

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

#mutable_literal? ⇒ Boolean 



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

def mutable_literal?
  MUTABLE_LITERALS.include?(type)
end

#numeric_type? ⇒ Boolean 



437
438
439
 
# File 'lib/rubocop/ast/node.rb', line 437

def numeric_type?
  int_type? || float_type?
end

#operator_keyword? ⇒ Boolean 



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

def operator_keyword?
  OPERATOR_KEYWORDS.include?(type)
end

#parent ⇒ Node?

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



76
77
78
 
# File 'lib/rubocop/ast/node.rb', line 76

def parent
  @mutable_attributes[:parent]
end

#parent_module_name ⇒ Object

Searching the AST



304
305
306
307
308
309
310
311
312
 
# File 'lib/rubocop/ast/node.rb', line 304

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?



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

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



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

def_node_matcher :receiver, "  {(send $_ ...) (block (send $_ ...) ...)}\n"

#reference? ⇒ Boolean 



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

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



109
110
111
 
# File 'lib/rubocop/ast/node.rb', line 109

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

#single_line? ⇒ Boolean 



320
321
322
 
# File 'lib/rubocop/ast/node.rb', line 320

def single_line?
  !multiline?
end

#source ⇒ Object 



253
254
255
 
# File 'lib/rubocop/ast/node.rb', line 253

def source
  loc.expression.source
end

#source_range ⇒ Object 



257
258
259
 
# File 'lib/rubocop/ast/node.rb', line 257

def source_range
  loc.expression
end

#special_keyword? ⇒ Boolean 



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

def special_keyword?
  SPECIAL_KEYWORDS.include?(source)
end

#truthy_literal? ⇒ Boolean 



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

def truthy_literal?
  TRUTHY_LITERALS.include?(type)
end

#unary_operation? ⇒ Boolean 



414
415
416
417
418
 
# File 'lib/rubocop/ast/node.rb', line 414

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.



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

def updated(type = nil, children = nil, properties = {})
  properties[:location] ||= @location
  self.class.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, Metrics/CyclomaticComplexity



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

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 



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

def variable?
  VARIABLES.include?(type)
end