Class: RuboCop::AST::Node
- Inherits:
-
Parser::AST::Node
- Object
- Parser::AST::Node
- RuboCop::AST::Node
- 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:
Direct Known Subclasses
AndNode, ArgsNode, ArrayNode, BlockNode, CaseNode, DefNode, EnsureNode, ForNode, HashNode, IfNode, KeywordSplatNode, OrNode, PairNode, RegexpNode, ResbodyNode, SendNode, StrNode, SuperNode, SymbolNode, UntilNode, WhenNode, WhileNode, YieldNode
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
-
#ancestors ⇒ Array<Node>
Returns an array of ancestor nodes.
- #argument? ⇒ Boolean
- #arithmetic_operation? ⇒ Boolean
- #asgn_method_call? ⇒ Boolean
- #basic_literal? ⇒ Boolean
- #binary_operation? ⇒ Boolean
- #chained? ⇒ Boolean
-
#child_nodes ⇒ Array<Node>
Returns an array of child nodes.
- #complete! ⇒ Object
- #complete? ⇒ Boolean
- #const_name ⇒ Object
-
#defined_module ⇒ Object
rubocop:enable Style/AccessModifierDeclarations.
- #defined_module_name ⇒ Object
-
#descendants ⇒ Array<Node>
Returns an array of descendant nodes.
-
#each_ancestor(*types) {|node| ... } ⇒ self, Enumerator
Calls the given block for each ancestor node from parent to root.
-
#each_child_node(*types) {|node| ... } ⇒ self, Enumerator
Calls the given block for each child node.
-
#each_descendant(*types) {|node| ... } ⇒ self, Enumerator
Calls the given block for each descendant node with depth first order.
-
#each_node(*types) {|node| ... } ⇒ self, Enumerator
Calls the given block for the receiver and each descendant node in depth-first order.
- #empty_source? ⇒ Boolean
- #falsey_literal? ⇒ Boolean
- #first_line ⇒ Object
- #immutable_literal? ⇒ Boolean
-
#initialize(type, children = [], properties = {}) ⇒ Node
constructor
A new instance of Node.
- #keyword? ⇒ Boolean
- #keyword_bang? ⇒ Boolean
- #keyword_not? ⇒ Boolean
- #last_line ⇒ Object
- #line_count ⇒ Object
- #literal? ⇒ Boolean
-
#multiline? ⇒ Boolean
Predicates.
- #mutable_literal? ⇒ Boolean
-
#node_parts ⇒ Array<Node>
Common destructuring method.
- #nonempty_line_count ⇒ Object
- #numeric_type? ⇒ Boolean
- #operator_keyword? ⇒ Boolean
-
#parent ⇒ Node?
Returns the parent node, or ‘nil` if the receiver is a root node.
-
#parent_module_name ⇒ Object
Searching the AST.
- #parenthesized_call? ⇒ Boolean
-
#pure? ⇒ Boolean
Some expressions are evaluated for their value, some for their side effects, and some for both.
-
#receiver ⇒ Object
Destructuring.
- #reference? ⇒ Boolean
-
#sibling_index ⇒ Integer
Returns the index of the receiver node in its siblings.
- #single_line? ⇒ Boolean
- #source ⇒ Object
- #source_length ⇒ Object
- #source_range ⇒ Object
- #special_keyword? ⇒ Boolean
- #truthy_literal? ⇒ Boolean
- #unary_operation? ⇒ Boolean
-
#updated(type = nil, children = nil, properties = {}) ⇒ Object
Override ‘AST::Node#updated` so that `AST::Processor` does not try to mutate our ASTs.
-
#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?.
- #variable? ⇒ Boolean
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
Constructor Details
#initialize(type, children = [], properties = {}) ⇒ Node
Returns a new instance of Node.
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`.
155 156 157 |
# File 'lib/rubocop/ast/node.rb', line 155 def ancestors each_ancestor.to_a end |
#argument? ⇒ Boolean
485 486 487 |
# File 'lib/rubocop/ast/node.rb', line 485 def argument? parent && parent.send_type? end |
#arithmetic_operation? ⇒ 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
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
391 392 393 |
# File 'lib/rubocop/ast/node.rb', line 391 def basic_literal? BASIC_LITERALS.include?(type) end |
#binary_operation? ⇒ Boolean
468 469 470 471 472 |
# File 'lib/rubocop/ast/node.rb', line 468 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
478 479 480 481 482 483 |
# File 'lib/rubocop/ast/node.rb', line 478 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`.
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
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`.
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.
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.
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.
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.
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
359 360 361 |
# File 'lib/rubocop/ast/node.rb', line 359 def empty_source? source_length.zero? end |
#falsey_literal? ⇒ Boolean
399 400 401 |
# File 'lib/rubocop/ast/node.rb', line 399 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
407 408 409 |
# File 'lib/rubocop/ast/node.rb', line 407 def immutable_literal? IMMUTABLE_LITERALS.include?(type) end |
#keyword? ⇒ Boolean
437 438 439 440 441 442 |
# File 'lib/rubocop/ast/node.rb', line 437 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
457 458 459 460 |
# File 'lib/rubocop/ast/node.rb', line 457 def keyword_bang? _receiver, method_name, *args = *self args.empty? && method_name == :! && loc.selector.is?('!'.freeze) end |
#keyword_not? ⇒ Boolean
452 453 454 455 |
# File 'lib/rubocop/ast/node.rb', line 452 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
387 388 389 |
# File 'lib/rubocop/ast/node.rb', line 387 def literal? LITERALS.include?(type) end |
#multiline? ⇒ Boolean
Predicates
351 352 353 |
# File 'lib/rubocop/ast/node.rb', line 351 def multiline? line_count > 1 end |
#mutable_literal? ⇒ Boolean
403 404 405 |
# File 'lib/rubocop/ast/node.rb', line 403 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.
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
489 490 491 |
# File 'lib/rubocop/ast/node.rb', line 489 def numeric_type? int_type? || float_type? end |
#operator_keyword? ⇒ Boolean
448 449 450 |
# File 'lib/rubocop/ast/node.rb', line 448 def operator_keyword? OPERATOR_KEYWORDS.include?(type) end |
#parent ⇒ Node?
Returns the parent node, or ‘nil` if the receiver is a root node.
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
474 475 476 |
# File 'lib/rubocop/ast/node.rb', line 474 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?
555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 |
# File 'lib/rubocop/ast/node.rb', line 555 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
433 434 435 |
# File 'lib/rubocop/ast/node.rb', line 433 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.)
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
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
444 445 446 |
# File 'lib/rubocop/ast/node.rb', line 444 def special_keyword? SPECIAL_KEYWORDS.include?(source) end |
#truthy_literal? ⇒ Boolean
395 396 397 |
# File 'lib/rubocop/ast/node.rb', line 395 def truthy_literal? TRUTHY_LITERALS.include?(type) end |
#unary_operation? ⇒ Boolean
462 463 464 465 466 |
# File 'lib/rubocop/ast/node.rb', line 462 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
524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 |
# File 'lib/rubocop/ast/node.rb', line 524 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
429 430 431 |
# File 'lib/rubocop/ast/node.rb', line 429 def variable? VARIABLES.include?(type) end |