Class: RuboCop::AST::Node

Inherits:
Parser::AST::Node
  • Object
show all
Extended by:
RuboCop::AST::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
regexp irange erange].freeze
IMMUTABLE_LITERALS = 
(LITERALS - MUTABLE_LITERALS).freeze
EQUALS_ASSIGNMENTS = 
%i[lvasgn ivasgn cvasgn gvasgn
casgn masgn rasgn mrasgn].freeze
SHORTHAND_ASSIGNMENTS = 
%i[op_asgn or_asgn and_asgn].freeze
ASSIGNMENTS = 
(EQUALS_ASSIGNMENTS + SHORTHAND_ASSIGNMENTS).freeze
BASIC_CONDITIONALS = 
%i[if while until].freeze
CONDITIONALS = 
[*BASIC_CONDITIONALS, :case].freeze
POST_CONDITION_LOOP_TYPES = 
%i[while_post until_post].freeze
LOOP_TYPES = 
(POST_CONDITION_LOOP_TYPES + %i[while until for]).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
ARGUMENT_TYPES = 
%i[arg optarg restarg kwarg kwoptarg kwrestarg blockarg].freeze

Instance Method Summary collapse

Methods included from RuboCop::AST::NodePattern::Macros

def_node_matcher, def_node_search

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

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



200
201
202
 
# File 'lib/rubocop/ast/node.rb', line 200

def ancestors
  each_ancestor.to_a
end

#argument? ⇒ Boolean

Returns:

  • (Boolean) 


505
506
507
 
# File 'lib/rubocop/ast/node.rb', line 505

def argument?
  parent&.send_type? && parent.arguments.include?(self)
end

#argument_type? ⇒ Boolean

Returns:

  • (Boolean) 


509
510
511
 
# File 'lib/rubocop/ast/node.rb', line 509

def argument_type?
  ARGUMENT_TYPES.include?(type)
end

#assignment? ⇒ Boolean

Returns:

  • (Boolean) 


457
458
459
 
# File 'lib/rubocop/ast/node.rb', line 457

def assignment?
  ASSIGNMENTS.include?(type)
end

#basic_conditional? ⇒ Boolean

Returns:

  • (Boolean) 


461
462
463
 
# File 'lib/rubocop/ast/node.rb', line 461

def basic_conditional?
  BASIC_CONDITIONALS.include?(type)
end

#basic_literal? ⇒ Boolean

Returns:

  • (Boolean) 


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

def basic_literal?
  BASIC_LITERALS.include?(type)
end

#boolean_type? ⇒ Boolean

Returns:

  • (Boolean) 


513
514
515
 
# File 'lib/rubocop/ast/node.rb', line 513

def boolean_type?
  true_type? || false_type?
end

#call_type? ⇒ Boolean

Returns:

  • (Boolean) 


497
498
499
 
# File 'lib/rubocop/ast/node.rb', line 497

def call_type?
  send_type? || csend_type?
end

#chained? ⇒ Boolean

Returns:

  • (Boolean) 


501
502
503
 
# File 'lib/rubocop/ast/node.rb', line 501

def chained?
  parent&.call_type? && eql?(parent.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



238
239
240
 
# File 'lib/rubocop/ast/node.rb', line 238

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

#conditional? ⇒ Boolean

Returns:

  • (Boolean) 


465
466
467
 
# File 'lib/rubocop/ast/node.rb', line 465

def conditional?
  CONDITIONALS.include?(type)
end

#const_name ⇒ Object 



340
341
342
343
344
345
346
347
348
349
 
# File 'lib/rubocop/ast/node.rb', line 340

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 



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

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

#defined_module_name ⇒ Object 



365
366
367
 
# File 'lib/rubocop/ast/node.rb', line 365

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



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

def descendants
  each_descendant.to_a
end

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

Yield Parameters:

  • node (Node) —

    each ancestor node

Returns:

  • (self) —

    if a block is given

  • (Enumerator) —

    if no block is given



188
189
190
191
192
193
194
 
# File 'lib/rubocop/ast/node.rb', line 188

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

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

Yield Parameters:

  • node (Node) —

    each child node

Returns:

  • (self) —

    if a block is given

  • (Enumerator) —

    if no block is given



222
223
224
225
226
227
228
229
230
231
232
 
# File 'lib/rubocop/ast/node.rb', line 222

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

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

Yield Parameters:

  • node (Node) —

    each descendant node

Returns:

  • (self) —

    if a block is given

  • (Enumerator) —

    if no block is given



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

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

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

Yield Parameters:

  • node (Node) —

    each node

Returns:

  • (self) —

    if a block is given

  • (Enumerator) —

    if no block is given



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

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

#empty_source? ⇒ Boolean

Returns:

  • (Boolean) 


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

def empty_source?
  source_length.zero?
end

#equals_asgn? ⇒ Boolean

Returns:

  • (Boolean) 


449
450
451
 
# File 'lib/rubocop/ast/node.rb', line 449

def equals_asgn?
  EQUALS_ASSIGNMENTS.include?(type)
end

#falsey_literal? ⇒ Boolean

Returns:

  • (Boolean) 


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

def falsey_literal?
  FALSEY_LITERALS.include?(type)
end

#first_line ⇒ Object 



310
311
312
 
# File 'lib/rubocop/ast/node.rb', line 310

def first_line
  loc.line
end

#guard_clause? ⇒ Boolean

Returns:

  • (Boolean) 


525
526
527
528
529
 
# File 'lib/rubocop/ast/node.rb', line 525

def guard_clause?
  node = and_type? || or_type? ? rhs : self

  node.match_guard_clause?
end

#immutable_literal? ⇒ Boolean

Returns:

  • (Boolean) 


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

def immutable_literal?
  IMMUTABLE_LITERALS.include?(type)
end

#keyword? ⇒ Boolean

Returns:

  • (Boolean) 


478
479
480
481
482
483
 
# File 'lib/rubocop/ast/node.rb', line 478

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



314
315
316
 
# File 'lib/rubocop/ast/node.rb', line 314

def last_line
  loc.last_line
end

#left_sibling ⇒ Node?

Use is discouraged, this is a potentially slow method and can lead to even slower algorithms

Returns:

  • (Node, nil) —

    the left (aka previous) sibling



138
139
140
141
142
143
 
# File 'lib/rubocop/ast/node.rb', line 138

def left_sibling
  i = sibling_index
  return if i.nil? || i.zero?

  parent.children[i - 1].freeze
end

#left_siblings ⇒ Array<Node>

Use is discouraged, this is a potentially slow method and can lead to even slower algorithms

Returns:

  • (Array<Node>) —

    the left (aka previous) siblings



148
149
150
151
152
 
# File 'lib/rubocop/ast/node.rb', line 148

def left_siblings
  return [].freeze unless parent

  parent.children[0...sibling_index].freeze
end

#line_count ⇒ Object 



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

def line_count
  return 0 unless source_range

  source_range.last_line - source_range.first_line + 1
end

#literal? ⇒ Boolean

Returns:

  • (Boolean) 


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

def literal?
  LITERALS.include?(type)
end

#loop_keyword? ⇒ Boolean

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

Returns:

  • (Boolean) 


474
475
476
 
# File 'lib/rubocop/ast/node.rb', line 474

def loop_keyword?
  LOOP_TYPES.include?(type)
end

#multiline? ⇒ Boolean

Predicates

Returns:

  • (Boolean) 


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

def multiline?
  line_count > 1
end

#mutable_literal? ⇒ Boolean

Returns:

  • (Boolean) 


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

def mutable_literal?
  MUTABLE_LITERALS.include?(type)
end

#node_parts ⇒ Array<Node>

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.

Returns:

  • (Array<Node>) —

    the different parts of the ndde



169
170
171
 
# File 'lib/rubocop/ast/node.rb', line 169

def node_parts
  to_a
end

#nonempty_line_count ⇒ Object 



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

def nonempty_line_count
  source.lines.grep(/\S/).size
end

#numeric_type? ⇒ Boolean

Returns:

  • (Boolean) 


517
518
519
 
# File 'lib/rubocop/ast/node.rb', line 517

def numeric_type?
  int_type? || float_type?
end

#operator_keyword? ⇒ Boolean

Returns:

  • (Boolean) 


489
490
491
 
# File 'lib/rubocop/ast/node.rb', line 489

def operator_keyword?
  OPERATOR_KEYWORDS.include?(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



371
372
373
374
375
376
377
378
379
 
# File 'lib/rubocop/ast/node.rb', line 371

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

#parenthesized_call? ⇒ Boolean

Returns:

  • (Boolean) 


493
494
495
 
# File 'lib/rubocop/ast/node.rb', line 493

def parenthesized_call?
  loc.respond_to?(:begin) && loc.begin && loc.begin.is?('(')
end

#post_condition_loop? ⇒ Boolean

Returns:

  • (Boolean) 


469
470
471
 
# File 'lib/rubocop/ast/node.rb', line 469

def post_condition_loop?
  POST_CONDITION_LOOP_TYPES.include?(type)
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) 


606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
 
# File 'lib/rubocop/ast/node.rb', line 606

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

Returns:

  • (Boolean) 


521
522
523
 
# File 'lib/rubocop/ast/node.rb', line 521

def range_type?
  irange_type? || erange_type?
end

#receiver ⇒ Object

Destructuring



334
335
336
 
# File 'lib/rubocop/ast/node.rb', line 334

def_node_matcher :receiver, <<~PATTERN
  {(send $_ ...) ({block numblock} (send $_ ...) ...)}
PATTERN

#reference? ⇒ Boolean

Returns:

  • (Boolean) 


445
446
447
 
# File 'lib/rubocop/ast/node.rb', line 445

def reference?
  REFERENCES.include?(type)
end

#right_sibling ⇒ Node?

Use is discouraged, this is a potentially slow method and can lead to even slower algorithms

Returns:

  • (Node, nil) —

    the right (aka next) sibling



129
130
131
132
133
 
# File 'lib/rubocop/ast/node.rb', line 129

def right_sibling
  return unless parent

  parent.children[sibling_index + 1].freeze
end

#right_siblings ⇒ Array<Node>

Use is discouraged, this is a potentially slow method and can lead to even slower algorithms

Returns:

  • (Array<Node>) —

    the right (aka next) siblings



157
158
159
160
161
 
# File 'lib/rubocop/ast/node.rb', line 157

def right_siblings
  return [].freeze unless parent

  parent.children[sibling_index + 1..-1].freeze
end

#shorthand_asgn? ⇒ Boolean

Returns:

  • (Boolean) 


453
454
455
 
# File 'lib/rubocop/ast/node.rb', line 453

def shorthand_asgn?
  SHORTHAND_ASSIGNMENTS.include?(type)
end

#sibling_index ⇒ Integer?

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.

Returns:

  • (Integer, nil) —

    the index of the receiver node in its siblings



122
123
124
 
# File 'lib/rubocop/ast/node.rb', line 122

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

#single_line? ⇒ Boolean

Returns:

  • (Boolean) 


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

def single_line?
  line_count == 1
end

#source ⇒ Object 



302
303
304
 
# File 'lib/rubocop/ast/node.rb', line 302

def source
  loc.expression.source
end

#source_length ⇒ Object 



328
329
330
 
# File 'lib/rubocop/ast/node.rb', line 328

def source_length
  source_range ? source_range.size : 0
end

#source_range ⇒ Object 



306
307
308
 
# File 'lib/rubocop/ast/node.rb', line 306

def source_range
  loc.expression
end

#special_keyword? ⇒ Boolean

Returns:

  • (Boolean) 


485
486
487
 
# File 'lib/rubocop/ast/node.rb', line 485

def special_keyword?
  SPECIAL_KEYWORDS.include?(source)
end

#truthy_literal? ⇒ Boolean

Returns:

  • (Boolean) 


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

def truthy_literal?
  TRUTHY_LITERALS.include?(type)
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
115
 
# File 'lib/rubocop/ast/node.rb', line 111

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


575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
 
# File 'lib/rubocop/ast/node.rb', line 575

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) 


441
442
443
 
# File 'lib/rubocop/ast/node.rb', line 441

def variable?
  VARIABLES.include?(type)
end