Class: RuboCop::Node

Inherits:
Parser::AST::Node
  • Object
show all
Includes:
Sexp
Defined in:
lib/rubocop/ast_node.rb,
lib/rubocop/ast_node/builder.rb,
lib/rubocop/ast_node/traversal.rb

Overview

‘RuboCop::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?)

Defined Under Namespace

Modules: Traversal Classes: Builder

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:



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

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 



48
49
50
51
52
53
54
55
56
 
# File 'lib/rubocop/ast_node.rb', line 48

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



157
158
159
 
# File 'lib/rubocop/ast_node.rb', line 157

def ancestors
  each_ancestor.to_a
end

#asgn_method_call? ⇒ Boolean

Returns:

  • (Boolean) 


384
385
386
387
 
# File 'lib/rubocop/ast_node.rb', line 384

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

#basic_literal? ⇒ Boolean

Returns:

  • (Boolean) 


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

def basic_literal?
  BASIC_LITERALS.include?(type)
end

#binary_operation? ⇒ Boolean

Returns:

  • (Boolean) 


465
466
467
468
469
 
# File 'lib/rubocop/ast_node.rb', line 465

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) 


471
472
473
474
475
 
# File 'lib/rubocop/ast_node.rb', line 471

def chained?
  return false if parent.nil? || !parent.send_type?
  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



197
198
199
 
# File 'lib/rubocop/ast_node.rb', line 197

def child_nodes
  each_child_node.to_a
end

#complete! ⇒ Object 



94
95
96
97
 
# File 'lib/rubocop/ast_node.rb', line 94

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

#complete? ⇒ Boolean

Returns:

  • (Boolean) 


99
100
101
 
# File 'lib/rubocop/ast_node.rb', line 99

def complete?
  @mutable_attributes.frozen?
end

#const_name ⇒ Object 



292
293
294
295
296
297
298
299
300
 
# File 'lib/rubocop/ast_node.rb', line 292

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 



310
311
312
313
 
# File 'lib/rubocop/ast_node.rb', line 310

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

#defined_module_name ⇒ Object 



315
316
317
 
# File 'lib/rubocop/ast_node.rb', line 315

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



235
236
237
 
# File 'lib/rubocop/ast_node.rb', line 235

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



141
142
143
144
145
146
147
148
149
150
151
 
# File 'lib/rubocop/ast_node.rb', line 141

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

  if types.empty?
    visit_ancestors(&block)
  else
    visit_ancestors_with_types(types, &block)
  end

  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



182
183
184
185
186
187
188
189
190
191
 
# File 'lib/rubocop/ast_node.rb', line 182

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



219
220
221
222
223
224
225
226
227
228
229
 
# File 'lib/rubocop/ast_node.rb', line 219

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

  if types.empty?
    visit_descendants(&block)
  else
    visit_descendants_with_types(types, &block)
  end

  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



261
262
263
264
265
266
267
268
269
270
271
272
273
 
# File 'lib/rubocop/ast_node.rb', line 261

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

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

  if types.empty?
    visit_descendants(&block)
  else
    visit_descendants_with_types(types, &block)
  end

  self
end

#falsey_literal? ⇒ Boolean

Returns:

  • (Boolean) 


405
406
407
 
# File 'lib/rubocop/ast_node.rb', line 405

def falsey_literal?
  FALSEY_LITERALS.include?(type)
end

#immutable_literal? ⇒ Boolean

Returns:

  • (Boolean) 


413
414
415
 
# File 'lib/rubocop/ast_node.rb', line 413

def immutable_literal?
  IMMUTABLE_LITERALS.include?(type)
end

#keyword? ⇒ Boolean

Returns:

  • (Boolean) 


443
444
445
446
447
448
 
# File 'lib/rubocop/ast_node.rb', line 443

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

Returns:

  • (Boolean) 


454
455
456
457
 
# File 'lib/rubocop/ast_node.rb', line 454

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

#literal? ⇒ Boolean

Returns:

  • (Boolean) 


393
394
395
 
# File 'lib/rubocop/ast_node.rb', line 393

def literal?
  LITERALS.include?(type)
end

#multiline? ⇒ Boolean

Predicates

Returns:

  • (Boolean) 


375
376
377
378
 
# File 'lib/rubocop/ast_node.rb', line 375

def multiline?
  expr = loc.expression
  expr && (expr.first_line != expr.last_line)
end

#mutable_literal? ⇒ Boolean

Returns:

  • (Boolean) 


409
410
411
 
# File 'lib/rubocop/ast_node.rb', line 409

def mutable_literal?
  MUTABLE_LITERALS.include?(type)
end

#new_class_or_module_block?(block_node) ⇒ Boolean

Returns:

  • (Boolean) 


363
364
365
366
367
368
369
370
371
 
# File 'lib/rubocop/ast_node.rb', line 363

def new_class_or_module_block?(block_node)
  receiver = block_node.receiver

  block_node.method_name == :new &&
    receiver && receiver.const_type? &&
    (receiver.const_name == 'Class' || receiver.const_name == 'Module') &&
    block_node.parent &&
    block_node.parent.casgn_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`



86
87
88
 
# File 'lib/rubocop/ast_node.rb', line 86

def parent
  @mutable_attributes[:parent]
end

#parent_module_name ⇒ Object

Searching the AST



321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
 
# File 'lib/rubocop/ast_node.rb', line 321

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|
    case ancestor.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
      ancestor.defined_module_name
    when :sclass
      return parent_module_name_for_sclass(ancestor)
    else # block
      if ancestor.method_name == :class_eval
        # `class_eval` with no receiver applies to whatever module or class
        # we are currently in
        next unless (receiver = ancestor.receiver)
        return nil unless receiver.const_type?
        receiver.const_name
      elsif new_class_or_module_block?(ancestor)
        # we will catch this in the `casgn` branch above
        next
      else
        return nil
      end
    end
  end.compact.reverse.join('::')
  result.empty? ? 'Object' : result
end

#parent_module_name_for_sclass(sclass_node) ⇒ Object 



351
352
353
354
355
356
357
358
359
360
361
 
# File 'lib/rubocop/ast_node.rb', line 351

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

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


540
541
542
543
544
545
546
547
548
549
550
551
552
553
 
# File 'lib/rubocop/ast_node.rb', line 540

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



285
 
# File 'lib/rubocop/ast_node.rb', line 285

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

#reference? ⇒ Boolean

Returns:

  • (Boolean) 


439
440
441
 
# File 'lib/rubocop/ast_node.rb', line 439

def reference?
  REFERENCES.include?(type)
end

#sibling_index ⇒ Integer

Returns the index of the receiver node in its siblings.

Returns:

  • (Integer) —

    the index of the receiver node in its siblings



119
120
121
 
# File 'lib/rubocop/ast_node.rb', line 119

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

#single_line? ⇒ Boolean

Returns:

  • (Boolean) 


380
381
382
 
# File 'lib/rubocop/ast_node.rb', line 380

def single_line?
  !multiline?
end

#source ⇒ Object 



275
276
277
 
# File 'lib/rubocop/ast_node.rb', line 275

def source
  loc.expression.source
end

#source_range ⇒ Object 



279
280
281
 
# File 'lib/rubocop/ast_node.rb', line 279

def source_range
  loc.expression
end

#special_keyword? ⇒ Boolean

Returns:

  • (Boolean) 


450
451
452
 
# File 'lib/rubocop/ast_node.rb', line 450

def special_keyword?
  SPECIAL_KEYWORDS.include?(source)
end

#truthy_literal? ⇒ Boolean

Returns:

  • (Boolean) 


401
402
403
 
# File 'lib/rubocop/ast_node.rb', line 401

def truthy_literal?
  TRUTHY_LITERALS.include?(type)
end

#unary_operation? ⇒ Boolean

Returns:

  • (Boolean) 


459
460
461
462
463
 
# File 'lib/rubocop/ast_node.rb', line 459

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?

Returns:

  • (Boolean) 


503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
 
# File 'lib/rubocop/ast_node.rb', line 503

def value_used?
  # Be conservative and return true if we're not sure
  return false if parent.nil?
  index = parent.children.index { |child| child.equal?(self) }

  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
    # the last child node determines the value of the parent
    index == parent.children.size - 1 ? parent.value_used? : false
  when :for
    # `for var in enum; body; end`
    # (for <var> <enum> <body>)
    index == 2 ? parent.value_used? : true
  when :case, :if
    # (case <condition> <when...>)
    # (if <condition> <truebranch> <falsebranch>)
    index == 0 ? true : parent.value_used?
  when :while, :until, :while_post, :until_post
    # (while <condition> <body>) -> always evaluates to `nil`
    index == 0
  else
    true
  end
end

#variable? ⇒ Boolean

Returns:

  • (Boolean) 


435
436
437
 
# File 'lib/rubocop/ast_node.rb', line 435

def variable?
  VARIABLES.include?(type)
end