rubocop-ast 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4108494066548a429e972d3f2afcaa9adfd39072a929308cdb20e4a602fef66d
-  data.tar.gz: 413b4382539bffed1760d0599bc093ad40ffef64992f821484994150903812da
+  metadata.gz: 918c6017183db74497fc68166973904312bac7583f7752c2e55d1829574cb248
+  data.tar.gz: 1d04eb24fcbaec96b4bf0f17694018c31034fce4b3d81a9446ca98b3085e05a4
 SHA512:
-  metadata.gz: 97af9dd864e8f6867614a79b2aac596e18e147b9a55bcc67b8755e47ef762730ec69612dcc6858ee12017b33beae0b89e008e1267034f1730682015c4efa4255
-  data.tar.gz: 807305ab6dc90885fff96d1387d787debf8ce8f27a0d150ad4bf86a76d4afb2d288f0771b2399cf3c3cfb1472c72cd750e4df9e97ad07467da4615a97c062f79
+  metadata.gz: 54f6882ebf057c76a9c97212a62b295d03baea85ec7c44e606b412e74edce01b6c4bba93dfafa341756009a8bfa2352c4b2b3b22bdbf689dac08ddd9395a9aff
+  data.tar.gz: '08e60b802e83dba688bf1a31be417f9880b640194cf3b966849dd2c211de5a1f3797c8a37be3f2d3aa466d6c994b10c31277b0ed3dc708b12fe1c2f7a0f15552'

data/README.md

@@ -6,11 +6,12 @@
 [![Maintainability](https://api.codeclimate.com/v1/badges/a29666e6373bc41bc0a9/maintainability)](https://codeclimate.com/github/rubocop-hq/rubocop-ast/maintainability)
 
 Contains the classes needed by [RuboCop](https://github.com/rubocop-hq/rubocop) to deal with Ruby's AST, in particular:
-* `RuboCop::AST::Node`
+
+* `RuboCop::AST::Node` ([doc](docs/modules/ROOT/pages/node_types.adoc))
 * `RuboCop::AST::NodePattern` ([doc](docs/modules/ROOT/pages/node_pattern.adoc))
 
 This gem may be used independently from the main RuboCop gem. It was extracted from RuboCop in version 0.84 and its only
-dependency is the `parser` gem, which `rubocop-ast` extends.
+dependency is the [parser](https://github.com/whitequark/parser) gem, which `rubocop-ast` extends.
 
 ## Installation
 
@@ -28,12 +29,15 @@ gem 'rubocop-ast'
 
 ## Usage
 
-Refer to the documentation of `RuboCop::AST::Node` and [`RuboCop::AST::NodePattern`](docs/modules/ROOT/pages/node_pattern.adoc)
+Refer to the documentation of [`RuboCop::AST::Node`](docs/modules/ROOT/pages/node_types.adoc) and [`RuboCop::AST::NodePattern`](docs/modules/ROOT/pages/node_pattern.adoc)
+
+See the [docs site](https://docs.rubocop.org/rubocop-ast) for more details.
 
 ### Parser compatibility switches
 
-The main `RuboCop` gem uses [legacy AST output from parser](https://github.com/whitequark/parser/#usage).
-This gem is meant to be compatible with all settings. For example, to have `-> { ... }` emitted
+This gem, by default, uses most [legacy AST output from parser](https://github.com/whitequark/parser/#usage), except for `emit_forward_arg` which is set to `true`.
+
+The main `RuboCop` gem uses these defaults (and is currently only compatible with these), but this gem can be used separately from `RuboCop` and is meant to be compatible with all settings. For example, to have `-> { ... }` emitted
 as `LambdaNode` instead of `SendNode`:
 
 ```ruby

data/lib/rubocop/ast.rb

@@ -4,6 +4,7 @@ require 'parser'
 require 'forwardable'
 require 'set'
 
+require_relative 'ast/ext/range'
 require_relative 'ast/node_pattern'
 require_relative 'ast/sexp'
 require_relative 'ast/node'
@@ -41,12 +42,12 @@ require_relative 'ast/node/int_node'
 require_relative 'ast/node/keyword_splat_node'
 require_relative 'ast/node/lambda_node'
 require_relative 'ast/node/module_node'
+require_relative 'ast/node/next_node'
 require_relative 'ast/node/or_node'
 require_relative 'ast/node/pair_node'
 require_relative 'ast/node/range_node'
 require_relative 'ast/node/regexp_node'
 require_relative 'ast/node/resbody_node'
-require_relative 'ast/node/retry_node'
 require_relative 'ast/node/return_node'
 require_relative 'ast/node/self_class_node'
 require_relative 'ast/node/send_node'

data/lib/rubocop/ast/builder.rb

@@ -14,6 +14,8 @@ module RuboCop
     #   parser = Parser::Ruby25.new(builder)
     #   root_node = parser.parse(buffer)
     class Builder < Parser::Builders::Default
+      self.emit_forward_arg = true
+
       NODE_MAP = {
         and:          AndNode,
         alias:        AliasNode,
@@ -42,11 +44,11 @@ module RuboCop
         kwsplat:      KeywordSplatNode,
         lambda:       LambdaNode,
         module:       ModuleNode,
+        next:         NextNode,
         or:           OrNode,
         pair:         PairNode,
         regexp:       RegexpNode,
         resbody:      ResbodyNode,
-        retry:        RetryNode,
         return:       ReturnNode,
         csend:        SendNode,
         send:         SendNode,

data/lib/rubocop/ast/ext/range.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module AST
+    module Ext
+      # Extensions to Parser::AST::Range
+      module Range
+        # @return [Range] the range of line numbers for the node
+        # If `exclude_end` is `true`, then the range will be exclusive.
+        #
+        # Assume that `node` corresponds to the following array literal:
+        #
+        #   [
+        #     :foo,
+        #     :bar
+        #   ]
+        #
+        #   node.loc.begin.line_span                         # => 1..1
+        #   node.loc.expression.line_span(exclude_end: true) # => 1...4
+        def line_span(exclude_end: false)
+          ::Range.new(first_line, last_line, exclude_end)
+        end
+      end
+    end
+  end
+end
+
+::Parser::Source::Range.include ::RuboCop::AST::Ext::Range

data/lib/rubocop/ast/node.rb

@@ -313,8 +313,8 @@ module RuboCop
       def_node_matcher :defined_module0, <<~PATTERN
         {(class (const $_ $_) ...)
          (module (const $_ $_) ...)
-         (casgn $_ $_        (send (const nil? {:Class :Module}) :new ...))
-         (casgn $_ $_ (block (send (const nil? {:Class :Module}) :new ...) ...))}
+         (casgn $_ $_        (send #global_const?({:Class :Module}) :new ...))
+         (casgn $_ $_ (block (send #global_const?({:Class :Module}) :new ...) ...))}
       PATTERN
 
       private :defined_module0
@@ -496,16 +496,33 @@ module RuboCop
 
       def_node_matcher :proc?, <<~PATTERN
         {(block (send nil? :proc) ...)
-         (block (send (const nil? :Proc) :new) ...)
-         (send (const nil? :Proc) :new)}
+         (block (send #global_const?(:Proc) :new) ...)
+         (send #global_const?(:Proc) :new)}
       PATTERN
 
       def_node_matcher :lambda?, '({block numblock} (send nil? :lambda) ...)'
       def_node_matcher :lambda_or_proc?, '{lambda? proc?}'
 
+      def_node_matcher :global_const?, '(const {nil? cbase} %1)'
+
       def_node_matcher :class_constructor?, <<~PATTERN
-        {       (send (const nil? {:Class :Module}) :new ...)
-         (block (send (const nil? {:Class :Module}) :new ...) ...)}
+        {       (send #global_const?({:Class :Module}) :new ...)
+         (block (send #global_const?({:Class :Module}) :new ...) ...)}
+      PATTERN
+
+      def_node_matcher :struct_constructor?, <<~PATTERN
+        (block (send #global_const?(:Struct) :new ...) _ $_)
+      PATTERN
+
+      def_node_matcher :class_definition?, <<~PATTERN
+        {(class _ _ $_)
+         (sclass _ $_)
+         (block (send #global_const?({:Struct :Class}) :new ...) _ $_)}
+      PATTERN
+
+      def_node_matcher :module_definition?, <<~PATTERN
+        {(module _ $_)
+         (block (send #global_const?(:Module) :new ...) _ $_)}
       PATTERN
 
       # Some expressions are evaluated for their value, some for their side

data/lib/rubocop/ast/node/array_node.rb

@@ -14,15 +14,9 @@ module RuboCop
       # Returns an array of all value nodes in the `array` literal.
       #
       # @return [Array<Node>] an array of value nodes
-      def values
-        each_child_node.to_a
-      end
+      alias values children
 
-      # Calls the given block for all values in the `array` literal.
-      #
-      # @yieldparam [Node] node each node
-      # @return [self] if a block is given
-      # @return [Enumerator] if no block is given
+      # @deprecated Use `values.each` (a.k.a. `children.each`)
       def each_value(&block)
         return to_enum(__method__) unless block_given?
 

data/lib/rubocop/ast/node/break_node.rb

@@ -6,12 +6,7 @@ module RuboCop
     # plain node when the builder constructs the AST, making its methods
     # available to all `break` nodes within RuboCop.
     class BreakNode < Node
-      include MethodDispatchNode
-      include ParameterizedNode
-
-      def arguments
-        []
-      end
+      include ParameterizedNode::WrappedArguments
     end
   end
 end

data/lib/rubocop/ast/node/case_match_node.rb

@@ -15,17 +15,11 @@ module RuboCop
         'case'
       end
 
-      # Calls the given block for each `in_pattern` node in the `in` statement.
-      # If no block is given, an `Enumerator` is returned.
-      #
-      # @return [self] if a block is given
-      # @return [Enumerator] if no block is given
-      def each_in_pattern
+      # @deprecated Use `in_pattern_branches.each`
+      def each_in_pattern(&block)
         return in_pattern_branches.to_enum(__method__) unless block_given?
 
-        in_pattern_branches.each do |condition|
-          yield condition
-        end
+        in_pattern_branches.each(&block)
 
         self
       end

data/lib/rubocop/ast/node/case_node.rb

@@ -15,17 +15,11 @@ module RuboCop
         'case'
       end
 
-      # Calls the given block for each `when` node in the `case` statement.
-      # If no block is given, an `Enumerator` is returned.
-      #
-      # @return [self] if a block is given
-      # @return [Enumerator] if no block is given
-      def each_when
+      # @deprecated Use `when_branches.each`
+      def each_when(&block)
         return when_branches.to_enum(__method__) unless block_given?
 
-        when_branches.each do |condition|
-          yield condition
-        end
+        when_branches.each(&block)
 
         self
       end
@@ -37,6 +31,16 @@ module RuboCop
         node_parts[1...-1]
       end
 
+      # Returns an array of all the when branches in the `case` statement.
+      #
+      # @return [Array<Node, nil>] an array of the bodies of the when branches
+      # and the else (if any). Note that these bodies could be nil.
+      def branches
+        bodies = when_branches.map(&:body)
+        bodies.push(else_branch) if else?
+        bodies
+      end
+
       # Returns the else branch of the `case` statement, if any.
       #
       # @return [Node] the else branch node of the `case` statement

data/lib/rubocop/ast/node/def_node.rb

@@ -31,14 +31,14 @@ module RuboCop
       #
       # @return [Symbol] the name of the defined method
       def method_name
-        node_parts[2]
+        children[-3]
       end
 
       # An array containing the arguments of the method definition.
       #
       # @return [Array<Node>] the arguments of the method definition
       def arguments
-        node_parts[1]
+        children[-2]
       end
 
       # The body of the method definition.
@@ -49,33 +49,14 @@ module RuboCop
       #
       # @return [Node] the body of the method definition
       def body
-        node_parts[0]
+        children[-1]
       end
 
       # The receiver of the method definition, if any.
       #
       # @return [Node, nil] the receiver of the method definition, or `nil`.
       def receiver
-        node_parts[3]
-      end
-
-      # Custom destructuring method. This can be used to normalize
-      # destructuring for different variations of the node.
-      #
-      # In this case, the `def` node destructures into:
-      #
-      #   `method_name, arguments, body`
-      #
-      # while the `defs` node destructures into:
-      #
-      #   `receiver, method_name, arguments, body`
-      #
-      # so we reverse the destructured array to get the optional receiver
-      # at the end, where it can be discarded.
-      #
-      # @return [Array] the different parts of the `def` or `defs` node
-      def node_parts
-        to_a.reverse
+        children[-4]
       end
     end
   end

data/lib/rubocop/ast/node/defined_node.rb

@@ -12,6 +12,8 @@ module RuboCop
       def node_parts
         [nil, :defined?, *to_a]
       end
+
+      alias arguments children
     end
   end
 end

data/lib/rubocop/ast/node/float_node.rb

@@ -6,6 +6,7 @@ module RuboCop
     # node when the builder constructs the AST, making its methods available to
     # all `float` nodes within RuboCop.
     class FloatNode < Node
+      include BasicLiteralNode
       include NumericNode
     end
   end

data/lib/rubocop/ast/node/hash_node.rb

@@ -8,6 +8,9 @@ module RuboCop
     class HashNode < Node
       # Returns an array of all the key value pairs in the `hash` literal.
       #
+      # @note this may be different from children as `kwsplat` nodes are
+      # ignored.
+      #
       # @return [Array<PairNode>] an array of `pair` nodes
       def pairs
         each_pair.to_a
@@ -23,6 +26,8 @@ module RuboCop
       # Calls the given block for each `pair` node in the `hash` literal.
       # If no block is given, an `Enumerator` is returned.
       #
+      # @note `kwsplat` nodes are ignored.
+      #
       # @return [self] if a block is given
       # @return [Enumerator] if no block is given
       def each_pair
@@ -37,6 +42,8 @@ module RuboCop
 
       # Returns an array of all the keys in the `hash` literal.
       #
+      # @note `kwsplat` nodes are ignored.
+      #
       # @return [Array<Node>] an array of keys in the `hash` literal
       def keys
         each_key.to_a
@@ -45,20 +52,22 @@ module RuboCop
       # Calls the given block for each `key` node in the `hash` literal.
       # If no block is given, an `Enumerator` is returned.
       #
+      # @note `kwsplat` nodes are ignored.
+      #
       # @return [self] if a block is given
       # @return [Enumerator] if no block is given
-      def each_key
+      def each_key(&block)
         return pairs.map(&:key).to_enum unless block_given?
 
-        pairs.map(&:key).each do |key|
-          yield key
-        end
+        pairs.map(&:key).each(&block)
 
         self
       end
 
       # Returns an array of all the values in the `hash` literal.
       #
+      # @note `kwsplat` nodes are ignored.
+      #
       # @return [Array<Node>] an array of values in the `hash` literal
       def values
         each_pair.map(&:value)
@@ -67,14 +76,14 @@ module RuboCop
       # Calls the given block for each `value` node in the `hash` literal.
       # If no block is given, an `Enumerator` is returned.
       #
+      # @note `kwsplat` nodes are ignored.
+      #
       # @return [self] if a block is given
       # @return [Enumerator] if no block is given
-      def each_value
+      def each_value(&block)
         return pairs.map(&:value).to_enum unless block_given?
 
-        pairs.map(&:value).each do |value|
-          yield value
-        end
+        pairs.map(&:value).each(&block)
 
         self
       end
@@ -85,6 +94,8 @@ module RuboCop
       # @note A multiline `pair` is considered to be on the same line if it
       #       shares any of its lines with another `pair`
       #
+      # @note `kwsplat` nodes are ignored.
+      #
       # @return [Boolean] whether any `pair` nodes are on the same line
       def pairs_on_same_line?
         pairs.each_cons(2).any? { |first, second| first.same_line?(second) }
@@ -93,6 +104,8 @@ module RuboCop
       # Checks whether this `hash` uses a mix of hash rocket and colon
       # delimiters for its pairs.
       #
+      # @note `kwsplat` nodes are ignored.
+      #
       # @return [Boolean] whether the `hash` uses mixed delimiters
       def mixed_delimiters?
         pairs.map(&:delimiter).uniq.size > 1

data/lib/rubocop/ast/node/if_node.rb

@@ -64,10 +64,9 @@ module RuboCop
       #
       # @return [String] the inverse keyword of the `if` statement
       def inverse_keyword
-        if keyword == 'if'
-          'unless'
-        elsif keyword == 'unless'
-          'if'
+        case keyword
+        when 'if' then 'unless'
+        when 'unless' then 'if'
         else
           ''
         end
@@ -148,7 +147,7 @@ module RuboCop
       def branches
         branches = [if_branch]
 
-        return branches unless else_branch
+        return branches unless else?
 
         other_branches = if elsif_conditional?
                            else_branch.branches
@@ -158,17 +157,11 @@ module RuboCop
         branches.concat(other_branches)
       end
 
-      # Calls the given block for each branch node in the conditional statement.
-      # If no block is given, an `Enumerator` is returned.
-      #
-      # @return [self] if a block is given
-      # @return [Enumerator] if no block is given
-      def each_branch
+      # @deprecated Use `branches.each`
+      def each_branch(&block)
         return branches.to_enum(__method__) unless block_given?
 
-        branches.each do |branch|
-          yield branch
-        end
+        branches.each(&block)
       end
     end
   end