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
- #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
- #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.
-
#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`.
144 145 146 |
# File 'lib/rubocop/ast/node.rb', line 144 def ancestors each_ancestor.to_a end |
#argument? ⇒ Boolean
463 464 465 |
# File 'lib/rubocop/ast/node.rb', line 463 def argument? parent && parent.send_type? end |
#arithmetic_operation? ⇒ Boolean
355 356 357 |
# File 'lib/rubocop/ast/node.rb', line 355 def arithmetic_operation? ARITHMETIC_OPERATORS.include?(method_name) end |
#asgn_method_call? ⇒ Boolean
350 351 352 353 |
# File 'lib/rubocop/ast/node.rb', line 350 def asgn_method_call? !COMPARISON_OPERATORS.include?(method_name) && method_name.to_s.end_with?('='.freeze) end |
#basic_literal? ⇒ Boolean
373 374 375 |
# File 'lib/rubocop/ast/node.rb', line 373 def basic_literal? BASIC_LITERALS.include?(type) end |
#binary_operation? ⇒ Boolean
450 451 452 453 454 |
# File 'lib/rubocop/ast/node.rb', line 450 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
456 457 458 459 460 461 |
# File 'lib/rubocop/ast/node.rb', line 456 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`.
184 185 186 |
# File 'lib/rubocop/ast/node.rb', line 184 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
297 298 299 300 301 302 303 304 305 |
# File 'lib/rubocop/ast/node.rb', line 297 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
315 316 317 318 |
# File 'lib/rubocop/ast/node.rb', line 315 def defined_module namespace, name = *defined_module0 s(:const, namespace, name) if name end |
#defined_module_name ⇒ Object
320 321 322 |
# File 'lib/rubocop/ast/node.rb', line 320 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`.
218 219 220 |
# File 'lib/rubocop/ast/node.rb', line 218 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.
132 133 134 135 136 137 138 |
# File 'lib/rubocop/ast/node.rb', line 132 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.
169 170 171 172 173 174 175 176 177 178 |
# File 'lib/rubocop/ast/node.rb', line 169 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.
206 207 208 209 210 211 212 |
# File 'lib/rubocop/ast/node.rb', line 206 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.
244 245 246 247 248 249 250 251 252 |
# File 'lib/rubocop/ast/node.rb', line 244 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
346 347 348 |
# File 'lib/rubocop/ast/node.rb', line 346 def empty_source? source_length.zero? end |
#falsey_literal? ⇒ Boolean
381 382 383 |
# File 'lib/rubocop/ast/node.rb', line 381 def falsey_literal? FALSEY_LITERALS.include?(type) end |
#first_line ⇒ Object
262 263 264 |
# File 'lib/rubocop/ast/node.rb', line 262 def first_line loc.line end |
#immutable_literal? ⇒ Boolean
389 390 391 |
# File 'lib/rubocop/ast/node.rb', line 389 def immutable_literal? IMMUTABLE_LITERALS.include?(type) end |
#keyword? ⇒ Boolean
419 420 421 422 423 424 |
# File 'lib/rubocop/ast/node.rb', line 419 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
439 440 441 442 |
# File 'lib/rubocop/ast/node.rb', line 439 def keyword_bang? _receiver, method_name, *args = *self args.empty? && method_name == :! && loc.selector.is?('!'.freeze) end |
#keyword_not? ⇒ Boolean
434 435 436 437 |
# File 'lib/rubocop/ast/node.rb', line 434 def keyword_not? _receiver, method_name, *args = *self args.empty? && method_name == :! && loc.selector.is?('not'.freeze) end |
#last_line ⇒ Object
266 267 268 |
# File 'lib/rubocop/ast/node.rb', line 266 def last_line loc.last_line end |
#line_count ⇒ Object
270 271 272 273 |
# File 'lib/rubocop/ast/node.rb', line 270 def line_count return 0 unless source_range source_range.last_line - source_range.first_line + 1 end |
#literal? ⇒ Boolean
369 370 371 |
# File 'lib/rubocop/ast/node.rb', line 369 def literal? LITERALS.include?(type) end |
#multiline? ⇒ Boolean
Predicates
338 339 340 |
# File 'lib/rubocop/ast/node.rb', line 338 def multiline? line_count > 1 end |
#mutable_literal? ⇒ Boolean
385 386 387 |
# File 'lib/rubocop/ast/node.rb', line 385 def mutable_literal? MUTABLE_LITERALS.include?(type) end |
#nonempty_line_count ⇒ Object
275 276 277 |
# File 'lib/rubocop/ast/node.rb', line 275 def nonempty_line_count source.lines.grep(/\S/).size end |
#numeric_type? ⇒ Boolean
467 468 469 |
# File 'lib/rubocop/ast/node.rb', line 467 def numeric_type? int_type? || float_type? end |
#operator_keyword? ⇒ Boolean
430 431 432 |
# File 'lib/rubocop/ast/node.rb', line 430 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
326 327 328 329 330 331 332 333 334 |
# File 'lib/rubocop/ast/node.rb', line 326 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?
533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 |
# File 'lib/rubocop/ast/node.rb', line 533 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 286 287 |
# File 'lib/rubocop/ast/node.rb', line 285 def_node_matcher :receiver, <<-PATTERN {(send $_ ...) (block (send $_ ...) ...)} PATTERN |
#reference? ⇒ Boolean
415 416 417 |
# File 'lib/rubocop/ast/node.rb', line 415 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.)
110 111 112 |
# File 'lib/rubocop/ast/node.rb', line 110 def sibling_index parent.children.index { |sibling| sibling.equal?(self) } end |
#single_line? ⇒ Boolean
342 343 344 |
# File 'lib/rubocop/ast/node.rb', line 342 def single_line? line_count == 1 end |
#source ⇒ Object
254 255 256 |
# File 'lib/rubocop/ast/node.rb', line 254 def source loc.expression.source end |
#source_length ⇒ Object
279 280 281 |
# File 'lib/rubocop/ast/node.rb', line 279 def source_length source_range ? source_range.size : 0 end |
#source_range ⇒ Object
258 259 260 |
# File 'lib/rubocop/ast/node.rb', line 258 def source_range loc.expression end |
#special_keyword? ⇒ Boolean
426 427 428 |
# File 'lib/rubocop/ast/node.rb', line 426 def special_keyword? SPECIAL_KEYWORDS.include?(source) end |
#truthy_literal? ⇒ Boolean
377 378 379 |
# File 'lib/rubocop/ast/node.rb', line 377 def truthy_literal? TRUTHY_LITERALS.include?(type) end |
#unary_operation? ⇒ Boolean
444 445 446 447 448 |
# File 'lib/rubocop/ast/node.rb', line 444 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 |
# File 'lib/rubocop/ast/node.rb', line 101 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
502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 |
# File 'lib/rubocop/ast/node.rb', line 502 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
411 412 413 |
# File 'lib/rubocop/ast/node.rb', line 411 def variable? VARIABLES.include?(type) end |