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
ARITHMETIC_OPERATORS = 
%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:



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

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



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

def ancestors
  each_ancestor.to_a
end

#argument? ⇒ Boolean

Returns:

  • (Boolean) 


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

def argument?
  parent && parent.send_type?
end

#arithmetic_operation? ⇒ Boolean

Returns:

  • (Boolean) 


368
369
370
 
# File 'lib/rubocop/ast/node.rb', line 368

def arithmetic_operation?
  ARITHMETIC_OPERATORS.include?(method_name)
end

#asgn_method_call? ⇒ Boolean

Returns:

  • (Boolean) 


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

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

#basic_literal? ⇒ Boolean

Returns:

  • (Boolean) 


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

def basic_literal?
  BASIC_LITERALS.include?(type)
end

#binary_operation? ⇒ Boolean

Returns:

  • (Boolean) 


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

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) 


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

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



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

def child_nodes
  each_child_node.to_a
end

#complete! ⇒ Object 



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

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

#complete? ⇒ Boolean

Returns:

  • (Boolean) 


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

def complete?
  @mutable_attributes.frozen?
end

#const_name ⇒ Object 



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

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

rubocop:enable Style/AccessModifierDeclarations



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

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

#defined_module_name ⇒ Object 



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

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



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

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



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

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



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

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



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

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



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

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) 


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

def empty_source?
  source_length.zero?
end

#falsey_literal? ⇒ Boolean

Returns:

  • (Boolean) 


394
395
396
 
# File 'lib/rubocop/ast/node.rb', line 394

def falsey_literal?
  FALSEY_LITERALS.include?(type)
end

#first_line ⇒ Object 



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

def first_line
  loc.line
end

#immutable_literal? ⇒ Boolean

Returns:

  • (Boolean) 


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

def immutable_literal?
  IMMUTABLE_LITERALS.include?(type)
end

#keyword? ⇒ Boolean

Returns:

  • (Boolean) 


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

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) 


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

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

#keyword_not? ⇒ Boolean

Returns:

  • (Boolean) 


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

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

#last_line ⇒ Object 



277
278
279
 
# File 'lib/rubocop/ast/node.rb', line 277

def last_line
  loc.last_line
end

#line_count ⇒ Object 



281
282
283
284
 
# File 'lib/rubocop/ast/node.rb', line 281

def line_count
  return 0 unless source_range
  source_range.last_line - source_range.first_line + 1
end

#literal? ⇒ Boolean

Returns:

  • (Boolean) 


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

def literal?
  LITERALS.include?(type)
end

#multiline? ⇒ Boolean

Predicates

Returns:

  • (Boolean) 


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

def multiline?
  line_count > 1
end

#mutable_literal? ⇒ Boolean

Returns:

  • (Boolean) 


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

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



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

def node_parts
  to_a
end

#nonempty_line_count ⇒ Object 



286
287
288
 
# File 'lib/rubocop/ast/node.rb', line 286

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

#numeric_type? ⇒ Boolean

Returns:

  • (Boolean) 


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

def numeric_type?
  int_type? || float_type?
end

#operator_keyword? ⇒ Boolean

Returns:

  • (Boolean) 


443
444
445
 
# File 'lib/rubocop/ast/node.rb', line 443

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`



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

def parent
  @mutable_attributes[:parent]
end

#parent_module_name ⇒ Object

Searching the AST



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

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) 


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

def parenthesized_call?
  loc.respond_to?(:begin) && loc.begin && loc.begin.is?('(')
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) 


550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
 
# File 'lib/rubocop/ast/node.rb', line 550

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



296
297
298
 
# File 'lib/rubocop/ast/node.rb', line 296

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

#reference? ⇒ Boolean

Returns:

  • (Boolean) 


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

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



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

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

#single_line? ⇒ Boolean

Returns:

  • (Boolean) 


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

def single_line?
  line_count == 1
end

#source ⇒ Object 



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

def source
  loc.expression.source
end

#source_length ⇒ Object 



290
291
292
 
# File 'lib/rubocop/ast/node.rb', line 290

def source_length
  source_range ? source_range.size : 0
end

#source_range ⇒ Object 



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

def source_range
  loc.expression
end

#special_keyword? ⇒ Boolean

Returns:

  • (Boolean) 


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

def special_keyword?
  SPECIAL_KEYWORDS.include?(source)
end

#truthy_literal? ⇒ Boolean

Returns:

  • (Boolean) 


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

def truthy_literal?
  TRUTHY_LITERALS.include?(type)
end

#unary_operation? ⇒ Boolean

Returns:

  • (Boolean) 


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

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.



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

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, Metrics/CyclomaticComplexity

Returns:

  • (Boolean) 


519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
 
# File 'lib/rubocop/ast/node.rb', line 519

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) 


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

def variable?
  VARIABLES.include?(type)
end