Class: RuboCop::AST::Node
- Inherits:
-
Parser::AST::Node
- Object
- Parser::AST::Node
- RuboCop::AST::Node
- 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
ArrayNode, CaseNode, ForNode, HashNode, IfNode, KeywordSplatNode, PairNode, UntilNode, WhenNode, WhileNode
Constant Summary collapse
- COMPARISON_OPERATORS =
[:!, :==, :===, :!=, :<=, :>=, :>, :<, :<=>].freeze
- TRUTHY_LITERALS =
[:str, :dstr, :xstr, :int, :float, :sym, :dsym, :array, :hash, :regexp, :true, :irange, :erange, :complex, :rational, :regopt].freeze
- FALSEY_LITERALS =
[:false, :nil].freeze
- LITERALS =
(TRUTHY_LITERALS + FALSEY_LITERALS).freeze
- COMPOSITE_LITERALS =
[:dstr, :xstr, :dsym, :array, :hash, :irange, :erange, :regexp].freeze
- BASIC_LITERALS =
(LITERALS - COMPOSITE_LITERALS).freeze
- MUTABLE_LITERALS =
[:str, :dstr, :xstr, :array, :hash].freeze
- IMMUTABLE_LITERALS =
(LITERALS - MUTABLE_LITERALS).freeze
- VARIABLES =
[:ivar, :gvar, :cvar, :lvar].freeze
- REFERENCES =
[:nth_ref, :back_ref].freeze
- KEYWORDS =
[: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 =
[:and, :or].freeze
- SPECIAL_KEYWORDS =
%w(__FILE__ __LINE__ __ENCODING__).freeze
Class Method Summary collapse
Instance Method Summary collapse
-
#ancestors ⇒ Array<Node>
Returns an array of ancestor nodes.
- #argument? ⇒ 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.
- #falsey_literal? ⇒ Boolean
- #immutable_literal? ⇒ Boolean
-
#initialize(type, children = [], properties = {}) ⇒ Node
constructor
A new instance of Node.
- #keyword? ⇒ Boolean
- #keyword_bang? ⇒ Boolean
- #keyword_not? ⇒ Boolean
- #literal? ⇒ Boolean
-
#multiline? ⇒ Boolean
Predicates.
- #mutable_literal? ⇒ Boolean
- #numeric_type? ⇒ 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_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 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 |
Class Method Details
.def_matcher(method_name, pattern_str) ⇒ Object
49 50 51 52 53 54 55 56 57 |
# File 'lib/rubocop/ast/node.rb', line 49 def def_matcher(method_name, pattern_str) compiler = RuboCop::NodePattern::Compiler.new(pattern_str, 'self') src = "def #{method_name}(" \ "#{compiler.emit_param_list});" \ "#{compiler.emit_method_code};end" file, lineno = *caller.first.split(':') class_eval(src, file, lineno.to_i) end |
Instance Method Details
#ancestors ⇒ Array<Node>
Returns an array of ancestor nodes. This is a shorthand for ‘node.each_ancestor.to_a`.
154 155 156 |
# File 'lib/rubocop/ast/node.rb', line 154 def ancestors each_ancestor.to_a end |
#argument? ⇒ Boolean
430 431 432 |
# File 'lib/rubocop/ast/node.rb', line 430 def argument? parent && parent.send_type? end |
#asgn_method_call? ⇒ Boolean
330 331 332 333 |
# File 'lib/rubocop/ast/node.rb', line 330 def asgn_method_call? !COMPARISON_OPERATORS.include?(method_name) && method_name.to_s.end_with?('='.freeze) end |
#basic_literal? ⇒ Boolean
344 345 346 |
# File 'lib/rubocop/ast/node.rb', line 344 def basic_literal? BASIC_LITERALS.include?(type) end |
#binary_operation? ⇒ Boolean
417 418 419 420 421 |
# File 'lib/rubocop/ast/node.rb', line 417 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
423 424 425 426 427 428 |
# File 'lib/rubocop/ast/node.rb', line 423 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`.
194 195 196 |
# File 'lib/rubocop/ast/node.rb', line 194 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 |
#const_name ⇒ Object
281 282 283 284 285 286 287 288 289 |
# File 'lib/rubocop/ast/node.rb', line 281 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
299 300 301 302 |
# File 'lib/rubocop/ast/node.rb', line 299 def defined_module namespace, name = *defined_module0 s(:const, namespace, name) if name end |
#defined_module_name ⇒ Object
304 305 306 |
# File 'lib/rubocop/ast/node.rb', line 304 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`.
228 229 230 |
# File 'lib/rubocop/ast/node.rb', line 228 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.
142 143 144 145 146 147 148 |
# File 'lib/rubocop/ast/node.rb', line 142 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.
179 180 181 182 183 184 185 186 187 188 |
# File 'lib/rubocop/ast/node.rb', line 179 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.
216 217 218 219 220 221 222 |
# File 'lib/rubocop/ast/node.rb', line 216 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.
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 |
#falsey_literal? ⇒ Boolean
352 353 354 |
# File 'lib/rubocop/ast/node.rb', line 352 def falsey_literal? FALSEY_LITERALS.include?(type) end |
#immutable_literal? ⇒ Boolean
360 361 362 |
# File 'lib/rubocop/ast/node.rb', line 360 def immutable_literal? IMMUTABLE_LITERALS.include?(type) end |
#keyword? ⇒ Boolean
390 391 392 393 394 395 |
# File 'lib/rubocop/ast/node.rb', line 390 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
406 407 408 409 |
# File 'lib/rubocop/ast/node.rb', line 406 def keyword_bang? _receiver, method_name, *args = *self args.empty? && method_name == :! && loc.selector.is?('!'.freeze) end |
#keyword_not? ⇒ Boolean
401 402 403 404 |
# File 'lib/rubocop/ast/node.rb', line 401 def keyword_not? _receiver, method_name, *args = *self args.empty? && method_name == :! && loc.selector.is?('not'.freeze) end |
#literal? ⇒ Boolean
340 341 342 |
# File 'lib/rubocop/ast/node.rb', line 340 def literal? LITERALS.include?(type) end |
#multiline? ⇒ Boolean
Predicates
322 323 324 |
# File 'lib/rubocop/ast/node.rb', line 322 def multiline? source_range && (source_range.first_line != source_range.last_line) end |
#mutable_literal? ⇒ Boolean
356 357 358 |
# File 'lib/rubocop/ast/node.rb', line 356 def mutable_literal? MUTABLE_LITERALS.include?(type) end |
#numeric_type? ⇒ Boolean
434 435 436 |
# File 'lib/rubocop/ast/node.rb', line 434 def numeric_type? int_type? || float_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
310 311 312 313 314 315 316 317 318 |
# File 'lib/rubocop/ast/node.rb', line 310 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?
500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 |
# File 'lib/rubocop/ast/node.rb', line 500 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
274 |
# File 'lib/rubocop/ast/node.rb', line 274 def_matcher :receiver, '{(send $_ ...) (block (send $_ ...) ...)}' |
#reference? ⇒ Boolean
386 387 388 |
# File 'lib/rubocop/ast/node.rb', line 386 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.)
120 121 122 |
# File 'lib/rubocop/ast/node.rb', line 120 def sibling_index parent.children.index { |sibling| sibling.equal?(self) } end |
#single_line? ⇒ Boolean
326 327 328 |
# File 'lib/rubocop/ast/node.rb', line 326 def single_line? !multiline? end |
#source ⇒ Object
264 265 266 |
# File 'lib/rubocop/ast/node.rb', line 264 def source loc.expression.source end |
#source_range ⇒ Object
268 269 270 |
# File 'lib/rubocop/ast/node.rb', line 268 def source_range loc.expression end |
#special_keyword? ⇒ Boolean
397 398 399 |
# File 'lib/rubocop/ast/node.rb', line 397 def special_keyword? SPECIAL_KEYWORDS.include?(source) end |
#truthy_literal? ⇒ Boolean
348 349 350 |
# File 'lib/rubocop/ast/node.rb', line 348 def truthy_literal? TRUTHY_LITERALS.include?(type) end |
#unary_operation? ⇒ Boolean
411 412 413 414 415 |
# File 'lib/rubocop/ast/node.rb', line 411 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.
111 112 113 114 |
# File 'lib/rubocop/ast/node.rb', line 111 def updated(type = nil, children = nil, properties = {}) properties[:location] ||= @location Node.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
469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 |
# File 'lib/rubocop/ast/node.rb', line 469 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
382 383 384 |
# File 'lib/rubocop/ast/node.rb', line 382 def variable? VARIABLES.include?(type) end |