Class: RuboCop::AST::Node
- Inherits:
-
Parser::AST::Node
- Object
- Parser::AST::Node
- RuboCop::AST::Node
- 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:
Direct Known Subclasses
AliasNode, AndNode, ArgsNode, ArrayNode, BlockNode, BreakNode, CaseMatchNode, CaseNode, ClassNode, DefNode, DefinedNode, EnsureNode, FloatNode, ForNode, ForwardArgsNode, HashNode, IfNode, IndexNode, IndexasgnNode, IntNode, KeywordSplatNode, LambdaNode, ModuleNode, NextNode, OrNode, PairNode, RangeNode, RegexpNode, ResbodyNode, ReturnNode, SelfClassNode, 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
- 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].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
-
#ancestors ⇒ Array<Node>
Returns an array of ancestor nodes.
- #argument? ⇒ Boolean
- #argument_type? ⇒ Boolean
- #assignment? ⇒ Boolean
- #basic_conditional? ⇒ Boolean
- #basic_literal? ⇒ Boolean
- #boolean_type? ⇒ Boolean
- #call_type? ⇒ Boolean
- #chained? ⇒ Boolean
-
#child_nodes ⇒ Array<Node>
Returns an array of child nodes.
- #complete! ⇒ Object
- #complete? ⇒ Boolean
- #conditional? ⇒ 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
- #equals_asgn? ⇒ Boolean
- #falsey_literal? ⇒ Boolean
- #first_line ⇒ Object
- #guard_clause? ⇒ Boolean
- #immutable_literal? ⇒ Boolean
-
#initialize(type, children = [], properties = {}) ⇒ Node
constructor
A new instance of Node.
- #keyword? ⇒ Boolean
- #last_line ⇒ Object
- #line_count ⇒ Object
- #literal? ⇒ Boolean
-
#loop_keyword? ⇒ Boolean
Note: ‘loop { }` is a normal method call and thus not a loop keyword.
-
#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
- #post_condition_loop? ⇒ Boolean
-
#pure? ⇒ Boolean
Some expressions are evaluated for their value, some for their side effects, and some for both.
- #range_type? ⇒ Boolean
-
#receiver ⇒ Object
Destructuring.
- #reference? ⇒ Boolean
- #shorthand_asgn? ⇒ 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
-
#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 RuboCop::AST::NodePattern::Macros
def_node_matcher, def_node_search
Methods included from Sexp
Constructor Details
#initialize(type, children = [], properties = {}) ⇒ Node
Returns a new instance of Node.
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`.
162 163 164 |
# File 'lib/rubocop/ast/node.rb', line 162 def ancestors each_ancestor.to_a end |
#argument? ⇒ Boolean
467 468 469 |
# File 'lib/rubocop/ast/node.rb', line 467 def argument? parent&.send_type? && parent.arguments.include?(self) end |
#argument_type? ⇒ Boolean
471 472 473 |
# File 'lib/rubocop/ast/node.rb', line 471 def argument_type? ARGUMENT_TYPES.include?(type) end |
#assignment? ⇒ Boolean
419 420 421 |
# File 'lib/rubocop/ast/node.rb', line 419 def assignment? ASSIGNMENTS.include?(type) end |
#basic_conditional? ⇒ Boolean
423 424 425 |
# File 'lib/rubocop/ast/node.rb', line 423 def basic_conditional? BASIC_CONDITIONALS.include?(type) end |
#basic_literal? ⇒ Boolean
366 367 368 |
# File 'lib/rubocop/ast/node.rb', line 366 def basic_literal? BASIC_LITERALS.include?(type) end |
#boolean_type? ⇒ Boolean
475 476 477 |
# File 'lib/rubocop/ast/node.rb', line 475 def boolean_type? true_type? || false_type? end |
#call_type? ⇒ Boolean
459 460 461 |
# File 'lib/rubocop/ast/node.rb', line 459 def call_type? send_type? || csend_type? end |
#chained? ⇒ Boolean
463 464 465 |
# File 'lib/rubocop/ast/node.rb', line 463 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`.
200 201 202 |
# File 'lib/rubocop/ast/node.rb', line 200 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
100 101 102 |
# File 'lib/rubocop/ast/node.rb', line 100 def complete? @mutable_attributes.frozen? end |
#conditional? ⇒ Boolean
427 428 429 |
# File 'lib/rubocop/ast/node.rb', line 427 def conditional? CONDITIONALS.include?(type) end |
#const_name ⇒ Object
302 303 304 305 306 307 308 309 310 311 |
# File 'lib/rubocop/ast/node.rb', line 302 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
322 323 324 325 |
# File 'lib/rubocop/ast/node.rb', line 322 def defined_module namespace, name = *defined_module0 s(:const, namespace, name) if name end |
#defined_module_name ⇒ Object
327 328 329 |
# File 'lib/rubocop/ast/node.rb', line 327 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`.
231 232 233 |
# File 'lib/rubocop/ast/node.rb', line 231 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.
150 151 152 153 154 155 156 |
# File 'lib/rubocop/ast/node.rb', line 150 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.
184 185 186 187 188 189 190 191 192 193 194 |
# File 'lib/rubocop/ast/node.rb', line 184 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.
219 220 221 222 223 224 225 |
# File 'lib/rubocop/ast/node.rb', line 219 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.
254 255 256 257 258 259 260 261 262 |
# File 'lib/rubocop/ast/node.rb', line 254 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
353 354 355 |
# File 'lib/rubocop/ast/node.rb', line 353 def empty_source? source_length.zero? end |
#equals_asgn? ⇒ Boolean
411 412 413 |
# File 'lib/rubocop/ast/node.rb', line 411 def equals_asgn? EQUALS_ASSIGNMENTS.include?(type) end |
#falsey_literal? ⇒ Boolean
374 375 376 |
# File 'lib/rubocop/ast/node.rb', line 374 def falsey_literal? FALSEY_LITERALS.include?(type) end |
#first_line ⇒ Object
272 273 274 |
# File 'lib/rubocop/ast/node.rb', line 272 def first_line loc.line end |
#guard_clause? ⇒ Boolean
487 488 489 490 491 |
# File 'lib/rubocop/ast/node.rb', line 487 def guard_clause? node = and_type? || or_type? ? rhs : self node.match_guard_clause? end |
#immutable_literal? ⇒ Boolean
382 383 384 |
# File 'lib/rubocop/ast/node.rb', line 382 def immutable_literal? IMMUTABLE_LITERALS.include?(type) end |
#keyword? ⇒ Boolean
440 441 442 443 444 445 |
# File 'lib/rubocop/ast/node.rb', line 440 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
276 277 278 |
# File 'lib/rubocop/ast/node.rb', line 276 def last_line loc.last_line end |
#line_count ⇒ Object
280 281 282 283 284 |
# File 'lib/rubocop/ast/node.rb', line 280 def line_count return 0 unless source_range source_range.last_line - source_range.first_line + 1 end |
#literal? ⇒ Boolean
362 363 364 |
# File 'lib/rubocop/ast/node.rb', line 362 def literal? LITERALS.include?(type) end |
#loop_keyword? ⇒ Boolean
Note: ‘loop { }` is a normal method call and thus not a loop keyword.
436 437 438 |
# File 'lib/rubocop/ast/node.rb', line 436 def loop_keyword? LOOP_TYPES.include?(type) end |
#multiline? ⇒ Boolean
Predicates
345 346 347 |
# File 'lib/rubocop/ast/node.rb', line 345 def multiline? line_count > 1 end |
#mutable_literal? ⇒ Boolean
378 379 380 |
# File 'lib/rubocop/ast/node.rb', line 378 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.
131 132 133 |
# File 'lib/rubocop/ast/node.rb', line 131 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
479 480 481 |
# File 'lib/rubocop/ast/node.rb', line 479 def numeric_type? int_type? || float_type? end |
#operator_keyword? ⇒ Boolean
451 452 453 |
# File 'lib/rubocop/ast/node.rb', line 451 def operator_keyword? OPERATOR_KEYWORDS.include?(type) end |
#parent ⇒ Node?
Returns the parent node, or ‘nil` if the receiver is a root node.
87 88 89 |
# File 'lib/rubocop/ast/node.rb', line 87 def parent @mutable_attributes[:parent] end |
#parent_module_name ⇒ Object
Searching the AST
333 334 335 336 337 338 339 340 341 |
# File 'lib/rubocop/ast/node.rb', line 333 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
455 456 457 |
# File 'lib/rubocop/ast/node.rb', line 455 def parenthesized_call? loc.respond_to?(:begin) && loc.begin && loc.begin.is?('(') end |
#post_condition_loop? ⇒ Boolean
431 432 433 |
# File 'lib/rubocop/ast/node.rb', line 431 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?
568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 |
# File 'lib/rubocop/ast/node.rb', line 568 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
483 484 485 |
# File 'lib/rubocop/ast/node.rb', line 483 def range_type? irange_type? || erange_type? end |
#receiver ⇒ Object
Destructuring
296 297 298 |
# File 'lib/rubocop/ast/node.rb', line 296 def_node_matcher :receiver, <<~PATTERN {(send $_ ...) ({block numblock} (send $_ ...) ...)} PATTERN |
#reference? ⇒ Boolean
407 408 409 |
# File 'lib/rubocop/ast/node.rb', line 407 def reference? REFERENCES.include?(type) end |
#shorthand_asgn? ⇒ Boolean
415 416 417 |
# File 'lib/rubocop/ast/node.rb', line 415 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.)
121 122 123 |
# File 'lib/rubocop/ast/node.rb', line 121 def sibling_index parent&.children&.index { |sibling| sibling.equal?(self) } end |
#single_line? ⇒ Boolean
349 350 351 |
# File 'lib/rubocop/ast/node.rb', line 349 def single_line? line_count == 1 end |
#source ⇒ Object
264 265 266 |
# File 'lib/rubocop/ast/node.rb', line 264 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
268 269 270 |
# File 'lib/rubocop/ast/node.rb', line 268 def source_range loc.expression end |
#special_keyword? ⇒ Boolean
447 448 449 |
# File 'lib/rubocop/ast/node.rb', line 447 def special_keyword? SPECIAL_KEYWORDS.include?(source) end |
#truthy_literal? ⇒ Boolean
370 371 372 |
# File 'lib/rubocop/ast/node.rb', line 370 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
537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 |
# File 'lib/rubocop/ast/node.rb', line 537 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
403 404 405 |
# File 'lib/rubocop/ast/node.rb', line 403 def variable? VARIABLES.include?(type) end |