rubocop-ast 0.0.3 → 0.4.1

data/lib/rubocop/ast/node/mixin/parameterized_node.rb

@@ -2,8 +2,11 @@
 
 module RuboCop
   module AST
+    # Requires implementing `arguments`.
+    #
     # Common functionality for nodes that are parameterized:
     # `send`, `super`, `zsuper`, `def`, `defs`
+    # and (modern only): `index`, `indexasgn`, `lambda`
     module ParameterizedNode
       # Checks whether this node's arguments are wrapped in parentheses.
       #
@@ -56,6 +59,59 @@ module RuboCop
         arguments? &&
           (last_argument.block_pass_type? || last_argument.blockarg_type?)
       end
+
+      # A specialized `ParameterizedNode` for node that have a single child
+      # containing either `nil`, an argument, or a `begin` node with all the
+      # arguments
+      module WrappedArguments
+        include ParameterizedNode
+        # @return [Array] The arguments of the node.
+        def arguments
+          first = children.first
+          if first&.begin_type?
+            first.children
+          else
+            children
+          end
+        end
+      end
+
+      # A specialized `ParameterizedNode`.
+      # Requires implementing `first_argument_index`
+      # Implements `arguments` as `children[first_argument_index..-1]`
+      # and optimizes other calls
+      module RestArguments
+        include ParameterizedNode
+        # @return [Array<Node>] arguments, if any
+        def arguments
+          children[first_argument_index..-1].freeze
+        end
+
+        # A shorthand for getting the first argument of the node.
+        # Equivalent to `arguments.first`.
+        #
+        # @return [Node, nil] the first argument of the node,
+        #                     or `nil` if there are no arguments
+        def first_argument
+          children[first_argument_index]
+        end
+
+        # A shorthand for getting the last argument of the node.
+        # Equivalent to `arguments.last`.
+        #
+        # @return [Node, nil] the last argument of the node,
+        #                     or `nil` if there are no arguments
+        def last_argument
+          children[-1] if arguments?
+        end
+
+        # Checks whether this node has any arguments.
+        #
+        # @return [Boolean] whether this node has any arguments
+        def arguments?
+          children.size > first_argument_index
+        end
+      end
     end
   end
 end

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

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module AST
+    # A node extension for `next` nodes. This will be used in place of a
+    # plain node when the builder constructs the AST, making its methods
+    # available to all `next` nodes within RuboCop.
+    class NextNode < Node
+      include ParameterizedNode::WrappedArguments
+    end
+  end
+end

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

@@ -32,7 +32,7 @@ module RuboCop
       #
       # @param [Boolean] with_spacing whether to include spacing
       # @return [String] the delimiter of the `pair`
-      def delimiter(with_spacing = false)
+      def delimiter(*deprecated, with_spacing: deprecated.first)
         if with_spacing
           hash_rocket? ? SPACED_HASH_ROCKET : SPACED_COLON
         else
@@ -44,7 +44,7 @@ module RuboCop
       #
       # @param [Boolean] with_spacing whether to include spacing
       # @return [String] the inverse delimiter of the `pair`
-      def inverse_delimiter(with_spacing = false)
+      def inverse_delimiter(*deprecated, with_spacing: deprecated.first)
         if with_spacing
           hash_rocket? ? SPACED_COLON : SPACED_HASH_ROCKET
         else

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

@@ -31,6 +31,62 @@ module RuboCop
       def content
         children.select(&:str_type?).map(&:str_content).join
       end
+
+      # @return [Bool] if the regexp is a /.../ literal
+      def slash_literal?
+        loc.begin.source == '/'
+      end
+
+      # @return [Bool] if the regexp is a %r{...} literal (using any delimiters)
+      def percent_r_literal?
+        !slash_literal?
+      end
+
+      # @return [String] the regexp delimiters (without %r)
+      def delimiters
+        [loc.begin.source[-1], loc.end.source[0]]
+      end
+
+      # @return [Bool] if char is one of the delimiters
+      def delimiter?(char)
+        delimiters.include?(char)
+      end
+
+      # @return [Bool] if regexp contains interpolation
+      def interpolation?
+        children.any?(&:begin_type?)
+      end
+
+      # @return [Bool] if regexp uses the multiline regopt
+      def multiline_mode?
+        regopt_include?(:m)
+      end
+
+      # @return [Bool] if regexp uses the extended regopt
+      def extended?
+        regopt_include?(:x)
+      end
+
+      # @return [Bool] if regexp uses the ignore-case regopt
+      def ignore_case?
+        regopt_include?(:i)
+      end
+
+      # @return [Bool] if regexp uses the single-interpolation regopt
+      def single_interpolation?
+        regopt_include?(:o)
+      end
+
+      # @return [Bool] if regexp uses the no-encoding regopt
+      def no_encoding?
+        regopt_include?(:n)
+      end
+
+      private
+
+      def regopt_include?(option)
+        regopt.children.include?(option)
+      end
     end
   end
 end

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

@@ -13,12 +13,33 @@ module RuboCop
         node_parts[2]
       end
 
+      # Returns an array of all the exceptions in the `rescue` clause.
+      #
+      # @return [Array<Node>] an array of exception nodes
+      def exceptions
+        exceptions_node = node_parts[0]
+        if exceptions_node.nil?
+          []
+        elsif exceptions_node.array_type?
+          exceptions_node.values
+        else
+          [exceptions_node]
+        end
+      end
+
       # Returns the exception variable of the `rescue` clause.
       #
       # @return [Node, nil] The exception variable of the `resbody`.
       def exception_variable
         node_parts[1]
       end
+
+      # Returns the index of the `resbody` branch within the exception handling statement.
+      #
+      # @return [Integer] the index of the `resbody` branch
+      def branch_index
+        parent.resbody_branches.index(self)
+      end
     end
   end
 end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module AST
+    # A node extension for `rescue` nodes. This will be used in place of a
+    # plain node when the builder constructs the AST, making its methods
+    # available to all `rescue` nodes within RuboCop.
+    class RescueNode < Node
+      # Returns the body of the rescue node.
+      #
+      # @return [Node, nil] The body of the rescue node.
+      def body
+        node_parts[0]
+      end
+
+      # Returns an array of all the rescue branches in the exception handling statement.
+      #
+      # @return [Array<ResbodyNode>] an array of `resbody` nodes
+      def resbody_branches
+        node_parts[1...-1]
+      end
+
+      # Returns an array of all the rescue branches in the exception handling statement.
+      #
+      # @return [Array<Node, nil>] an array of the bodies of the rescue branches
+      # and the else (if any). Note that these bodies could be nil.
+      def branches
+        bodies = resbody_branches.map(&:body)
+        bodies.push(else_branch) if else?
+        bodies
+      end
+
+      # Returns the else branch of the exception handling statement, if any.
+      #
+      # @return [Node] the else branch node of the exception handling statement
+      # @return [nil] if the exception handling statement does not have an else branch.
+      def else_branch
+        node_parts[-1]
+      end
+
+      # Checks whether this exception handling statement has an `else` branch.
+      #
+      # @return [Boolean] whether the exception handling statement has an `else` branch
+      def else?
+        loc.else
+      end
+    end
+  end
+end

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

@@ -6,19 +6,7 @@ module RuboCop
     # plain node when the builder constructs the AST, making its methods
     # available to all `return` nodes within RuboCop.
     class ReturnNode < Node
-      include MethodDispatchNode
-      include ParameterizedNode
-
-      # Returns the arguments of the `return`.
-      #
-      # @return [Array] The arguments of the `return`.
-      def arguments
-        if node_parts.one? && node_parts.first.begin_type?
-          node_parts.first.children
-        else
-          node_parts
-        end
-      end
+      include ParameterizedNode::WrappedArguments
     end
   end
 end

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

@@ -6,12 +6,19 @@ module RuboCop
     # node when the builder constructs the AST, making its methods available
     # to all `send` nodes within RuboCop.
     class SendNode < Node
-      include ParameterizedNode
+      include ParameterizedNode::RestArguments
       include MethodDispatchNode
 
       def_node_matcher :attribute_accessor?, <<~PATTERN
-        (send nil? ${:attr_reader :attr_writer :attr_accessor :attr} $...)
+        [(send nil? ${:attr_reader :attr_writer :attr_accessor :attr} $...)
+         (_    _    _                                                 _ ...)]
       PATTERN
+
+      private
+
+      def first_argument_index
+        2
+      end
     end
   end
 end

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

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

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

@@ -13,17 +13,11 @@ module RuboCop
         node_parts[0...-1]
       end
 
-      # Calls the given block for each condition node in the `when` branch.
-      # 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_condition
+      # @deprecated Use `conditions.each`
+      def each_condition(&block)
         return conditions.to_enum(__method__) unless block_given?
 
-        conditions.each do |condition|
-          yield condition
-        end
+        conditions.each(&block)
 
         self
       end

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

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

data/lib/rubocop/ast/node_pattern.rb

@@ -70,13 +70,23 @@ module RuboCop
     #     '(send %1 _)'       # % stands for a parameter which must be supplied to
     #                         # #match at matching time
     #                         # it will be compared to the corresponding value in
-    #                         # the AST using #==
+    #                         # the AST using #=== so you can pass Procs, Regexp,
+    #                         # etc. in addition to Nodes or literals.
+    #                         # `Array#===` will never match a node element, but
+    #                         # `Set#===` is an alias to `Set#include?` (Ruby 2.5+
+    #                         # only), and so can be very useful to match within
+    #                         # many possible literals / Nodes.
     #                         # a bare '%' is the same as '%1'
     #                         # the number of extra parameters passed to #match
     #                         # must equal the highest % value in the pattern
     #                         # for consistency, %0 is the 'root node' which is
     #                         # passed as the 1st argument to #match, where the
     #                         # matching process starts
+    #     '(send _ %named)'   # arguments can also be passed as named
+    #                         # parameters (see `%1`)
+    #                         # Note that the macros `def_node_matcher` and
+    #                         # `def_node_search` accept default values for these.
+    #     '(send _ %CONST)'   # the named constant will act like `%1` and `%named`.
     #     '^^send'            # each ^ ascends one level in the AST
     #                         # so this matches against the grandparent node
     #     '`send'             # descends any number of level in the AST
@@ -86,6 +96,10 @@ module RuboCop
     #                         # if that returns a truthy value, the match succeeds
     #     'equal?(%1)'        # predicates can be given 1 or more extra args
     #     '#method(%0, 1)'    # funcalls can also be given 1 or more extra args
+    #                         # These arguments can be patterns themselves, in
+    #                         # which case a matcher responding to === will be
+    #                         # passed.
+    #     '# comment'         # comments are accepted at the end of lines
     #
     # You can nest arbitrarily deep:
     #
@@ -100,11 +114,6 @@ module RuboCop
     # and so on. Therefore, if you add methods which are named like
     # `#prefix_type?` to the AST node class, then 'prefix' will become usable as
     # a pattern.
-    #
-    # Also note that if you need a "guard clause" to protect against possible nils
-    # in a certain place in the AST, you can do it like this: `[!nil <pattern>]`
-    #
-    # The compiler code is very simple; don't be afraid to read through it!
     class NodePattern
       # @private
       Invalid = Class.new(StandardError)
@@ -114,17 +123,23 @@ module RuboCop
       class Compiler
         SYMBOL       = %r{:(?:[\w+@*/?!<>=~|%^-]+|\[\]=?)}.freeze
         IDENTIFIER   = /[a-zA-Z_][a-zA-Z0-9_-]*/.freeze
+        COMMENT      = /#\s.*$/.freeze
+
         META         = Regexp.union(
           %w"( ) { } [ ] $< < > $... $ ! ^ ` ... + * ?"
         ).freeze
         NUMBER       = /-?\d+(?:\.\d+)?/.freeze
         STRING       = /".+?"/.freeze
-        METHOD_NAME  = /\#?#{IDENTIFIER}[\!\?]?\(?/.freeze
+        METHOD_NAME  = /\#?#{IDENTIFIER}[!?]?\(?/.freeze
+        PARAM_CONST  = /%[A-Z:][a-zA-Z_:]+/.freeze
+        KEYWORD_NAME = /%[a-z_]+/.freeze
         PARAM_NUMBER = /%\d*/.freeze
 
-        SEPARATORS = /[\s]+/.freeze
-        TOKENS     = Regexp.union(META, PARAM_NUMBER, NUMBER,
-                                  METHOD_NAME, SYMBOL, STRING)
+        SEPARATORS = /\s+/.freeze
+        ONLY_SEPARATOR = /\A#{SEPARATORS}\Z/.freeze
+
+        TOKENS = Regexp.union(META, PARAM_CONST, KEYWORD_NAME, PARAM_NUMBER, NUMBER,
+                              METHOD_NAME, SYMBOL, STRING)
 
         TOKEN = /\G(?:#{SEPARATORS}|#{TOKENS}|.)/.freeze
 
@@ -135,6 +150,8 @@ module RuboCop
         FUNCALL   = /\A\##{METHOD_NAME}/.freeze
         LITERAL   = /\A(?:#{SYMBOL}|#{NUMBER}|#{STRING})\Z/.freeze
         PARAM     = /\A#{PARAM_NUMBER}\Z/.freeze
+        CONST     = /\A#{PARAM_CONST}\Z/.freeze
+        KEYWORD   = /\A#{KEYWORD_NAME}\Z/.freeze
         CLOSING   = /\A(?:\)|\}|\])\Z/.freeze
 
         REST      = '...'
@@ -149,6 +166,7 @@ module RuboCop
         CUR_NODE = "#{CUR_PLACEHOLDER} node@@@"
         CUR_ELEMENT = "#{CUR_PLACEHOLDER} element@@@"
         SEQ_HEAD_GUARD = '@@@seq guard head@@@'
+        MULTIPLE_CUR_PLACEHOLDER = /#{CUR_PLACEHOLDER}.*#{CUR_PLACEHOLDER}/.freeze
 
         line = __LINE__
         ANY_ORDER_TEMPLATE = ERB.new <<~RUBY.gsub("-%>\n", '%>')
@@ -185,21 +203,26 @@ module RuboCop
         RUBY
         REPEATED_TEMPLATE.location = [__FILE__, line + 1]
 
-        def initialize(str, node_var = 'node0')
+        def initialize(str, root = 'node0', node_var = root)
           @string   = str
-          @root     = node_var
+          # For def_node_matcher, root == node_var
+          # For def_node_search, root is the root node to search on,
+          # and node_var is the current descendant being searched.
+          @root     = root
+          @node_var = node_var
 
           @temps    = 0  # avoid name clashes between temp variables
           @captures = 0  # number of captures seen
           @unify    = {} # named wildcard -> temp variable
           @params   = 0  # highest % (param) number seen
-          run(node_var)
+          @keywords = Set[] # keyword parameters seen
+          run
         end
 
-        def run(node_var)
+        def run
           @tokens = Compiler.tokens(@string)
 
-          @match_code = with_context(compile_expr, node_var, use_temp_node: false)
+          @match_code = with_context(compile_expr, @node_var, use_temp_node: false)
           @match_code.prepend("(captures = Array.new(#{@captures})) && ") \
             if @captures.positive?
 
@@ -219,6 +242,10 @@ module RuboCop
           #   CUR_NODE: Ruby code that evaluates to an AST node
           #   CUR_ELEMENT: Either the node or the type if in first element of
           #   a sequence (aka seq_head, e.g. "(seq_head first_node_arg ...")
+          if (atom = compile_atom(token))
+            return atom_to_expr(atom)
+          end
+
           case token
           when '('       then compile_seq
           when '{'       then compile_union
@@ -227,14 +254,10 @@ module RuboCop
           when '$'       then compile_capture
           when '^'       then compile_ascend
           when '`'       then compile_descend
-          when WILDCARD  then compile_wildcard(token[1..-1])
+          when WILDCARD  then compile_new_wildcard(token[1..-1])
           when FUNCALL   then compile_funcall(token)
-          when LITERAL   then compile_literal(token)
           when PREDICATE then compile_predicate(token)
           when NODE      then compile_nodetype(token)
-          when PARAM     then compile_param(token[1..-1])
-          when CLOSING   then fail_due_to("#{token} in invalid position")
-          when nil       then fail_due_to('pattern ended prematurely')
           else                fail_due_to("invalid token #{token.inspect}")
           end
         end
@@ -243,7 +266,7 @@ module RuboCop
         def tokens_until(stop, what)
           return to_enum __method__, stop, what unless block_given?
 
-          fail_due_to("empty #{what}") if tokens.first == stop && what
+          fail_due_to("empty #{what}") if tokens.first == stop
           yield until tokens.first == stop
           tokens.shift
         end
@@ -307,11 +330,15 @@ module RuboCop
         # @private
         # Builds Ruby code for a sequence
         # (head *first_terms variadic_term *last_terms)
-        class Sequence < SimpleDelegator
+        class Sequence
+          extend Forwardable
+          def_delegators :@compiler, :compile_guard_clause, :with_seq_head_context,
+                         :with_child_context, :fail_due_to
+
           def initialize(compiler, *arity_term_list)
             @arities, @terms = arity_term_list.transpose
 
-            super(compiler)
+            @compiler = compiler
             @variadic_index = @arities.find_index { |a| a.is_a?(Range) }
             fail_due_to 'multiple variable patterns in same sequence' \
               if @variadic_index && !@arities.one? { |a| a.is_a?(Range) }
@@ -431,7 +458,6 @@ module RuboCop
           [0..Float::INFINITY, 'true']
         end
 
-        # rubocop:disable Metrics/AbcSize
         # rubocop:disable Metrics/MethodLength
         def compile_any_order(capture_all = nil)
           rest = capture_rest = nil
@@ -451,7 +477,6 @@ module RuboCop
           end
         end
         # rubocop:enable Metrics/MethodLength
-        # rubocop:enable Metrics/AbcSize
 
         def insure_same_captures(enum, what)
           return to_enum __method__, enum, what unless block_given?
@@ -564,29 +589,18 @@ module RuboCop
           end
         end
 
-        def compile_wildcard(name)
-          if name.empty?
-            'true'
-          elsif @unify.key?(name)
-            # we have already seen a wildcard with this name before
-            # so the value it matched the first time will already be stored
-            # in a temp. check if this value matches the one stored in the temp
-            "#{CUR_ELEMENT} == #{access_unify(name)}"
-          else
-            n = @unify[name] = "unify_#{name.gsub('-', '__')}"
-            # double assign to avoid "assigned but unused variable"
-            "(#{n} = #{CUR_ELEMENT}; " \
-            "#{n} = #{n}; true)"
-          end
-        end
+        # Known wildcards are considered atoms, see `compile_atom`
+        def compile_new_wildcard(name)
+          return 'true' if name.empty?
 
-        def compile_literal(literal)
-          "#{CUR_ELEMENT} == #{literal}"
+          n = @unify[name] = "unify_#{name.gsub('-', '__')}"
+          # double assign to avoid "assigned but unused variable"
+          "(#{n} = #{CUR_ELEMENT}; #{n} = #{n}; true)"
         end
 
         def compile_predicate(predicate)
           if predicate.end_with?('(') # is there an arglist?
-            args = compile_args(tokens)
+            args = compile_args
             predicate = predicate[0..-2] # drop the trailing (
             "#{CUR_ELEMENT}.#{predicate}(#{args.join(',')})"
           else
@@ -599,7 +613,7 @@ module RuboCop
           # code is used in. pass target value as an argument
           method = method[1..-1] # drop the leading #
           if method.end_with?('(') # is there an arglist?
-            args = compile_args(tokens)
+            args = compile_args
             method = method[0..-2] # drop the trailing (
             "#{method}(#{CUR_ELEMENT},#{args.join(',')})"
           else
@@ -611,33 +625,44 @@ module RuboCop
           "#{compile_guard_clause} && #{CUR_NODE}.#{type.tr('-', '_')}_type?"
         end
 
-        def compile_param(number)
-          "#{CUR_ELEMENT} == #{get_param(number)}"
+        def compile_args
+          tokens_until(')', 'call arguments').map do
+            arg = compile_arg
+            tokens.shift if tokens.first == ','
+            arg
+          end
         end
 
-        def compile_args(tokens)
-          index = tokens.find_index { |token| token == ')' }
-
-          tokens.slice!(0..index).each_with_object([]) do |token, args|
-            next if [')', ','].include?(token)
+        def atom_to_expr(atom)
+          "#{atom} === #{CUR_ELEMENT}"
+        end
 
-            args << compile_arg(token)
+        def expr_to_atom(expr)
+          with_temp_variables do |compare|
+            in_context = with_context(expr, compare, use_temp_node: false)
+            "::RuboCop::AST::NodePattern::Matcher.new{|#{compare}| #{in_context}}"
           end
         end
 
-        def compile_arg(token)
+        # @return compiled atom (e.g. ":literal" or "SOME_CONST")
+        #         or nil if not a simple atom (unknown wildcard, other tokens)
+        def compile_atom(token)
           case token
-          when WILDCARD  then
-            name = token[1..-1]
-            access_unify(name) || fail_due_to('invalid in arglist: ' + token)
+          when WILDCARD  then access_unify(token[1..-1]) # could be nil
           when LITERAL   then token
+          when KEYWORD   then get_keyword(token[1..-1])
+          when CONST     then get_const(token[1..-1])
           when PARAM     then get_param(token[1..-1])
           when CLOSING   then fail_due_to("#{token} in invalid position")
           when nil       then fail_due_to('pattern ended prematurely')
-          else fail_due_to("invalid token in arglist: #{token.inspect}")
           end
         end
 
+        def compile_arg
+          token = tokens.shift
+          compile_atom(token) || expr_to_atom(compile_expr(token))
+        end
+
         def next_capture
           index = @captures
           @captures += 1
@@ -650,6 +675,15 @@ module RuboCop
           number.zero? ? @root : "param#{number}"
         end
 
+        def get_keyword(name)
+          @keywords << name
+          name
+        end
+
+        def get_const(const)
+          const # Output the constant exactly as given
+        end
+
         def emit_yield_capture(when_no_capture = '')
           yield_val = if @captures.zero?
                         when_no_capture
@@ -675,9 +709,15 @@ module RuboCop
           (1..@params).map { |n| "param#{n}" }.join(',')
         end
 
-        def emit_trailing_params
+        def emit_keyword_list(forwarding: false)
+          pattern = "%<keyword>s: #{'%<keyword>s' if forwarding}"
+          @keywords.map { |k| format(pattern, keyword: k) }.join(',')
+        end
+
+        def emit_params(*first, forwarding: false)
           params = emit_param_list
-          params.empty? ? '' : ",#{params}"
+          keywords = emit_keyword_list(forwarding: forwarding)
+          [*first, params, keywords].reject(&:empty?).join(',')
         end
 
         def emit_method_code
@@ -712,7 +752,7 @@ module RuboCop
         end
 
         def auto_use_temp_node?(code)
-          code.scan(CUR_PLACEHOLDER).count > 1
+          code.match?(MULTIPLE_CUR_PLACEHOLDER)
         end
 
         # with_<...>_context methods are used whenever the context,
@@ -751,72 +791,59 @@ module RuboCop
         end
 
         def self.tokens(pattern)
-          pattern.scan(TOKEN).reject { |token| token =~ /\A#{SEPARATORS}\Z/ }
+          pattern.gsub(COMMENT, '').scan(TOKEN).grep_v(ONLY_SEPARATOR)
         end
-      end
-      private_constant :Compiler
-
-      # Helpers for defining methods based on a pattern string
-      module Macros
-        # Define a method which applies a pattern to an AST node
-        #
-        # The new method will return nil if the node does not match
-        # If the node matches, and a block is provided, the new method will
-        # yield to the block (passing any captures as block arguments).
-        # If the node matches, and no block is provided, the new method will
-        # return the captures, or `true` if there were none.
-        def def_node_matcher(method_name, pattern_str)
-          compiler = Compiler.new(pattern_str, 'node')
-          src = "def #{method_name}(node = self" \
-                "#{compiler.emit_trailing_params});" \
-                "#{compiler.emit_method_code};end"
 
-          location = caller_locations(1, 1).first
-          class_eval(src, location.path, location.lineno)
+        # This method minimizes the closure for our method
+        def wrapping_block(method_name, **defaults)
+          proc do |*args, **values|
+            send method_name, *args, **defaults, **values
+          end
         end
 
-        # Define a method which recurses over the descendants of an AST node,
-        # checking whether any of them match the provided pattern
-        #
-        # If the method name ends with '?', the new method will return `true`
-        # as soon as it finds a descendant which matches. Otherwise, it will
-        # yield all descendants which match.
-        def def_node_search(method_name, pattern_str)
-          compiler = Compiler.new(pattern_str, 'node')
-          called_from = caller(1..1).first.split(':')
-
-          if method_name.to_s.end_with?('?')
-            node_search_first(method_name, compiler, called_from)
-          else
-            node_search_all(method_name, compiler, called_from)
+        def def_helper(base, method_name, **defaults)
+          location = caller_locations(3, 1).first
+          unless defaults.empty?
+            call = :"without_defaults_#{method_name}"
+            base.send :define_method, method_name, &wrapping_block(call, **defaults)
+            method_name = call
           end
+          src = yield method_name
+          base.class_eval(src, location.path, location.lineno)
         end
 
-        def node_search_first(method_name, compiler, called_from)
-          node_search(method_name, compiler, 'return true', '', called_from)
+        def def_node_matcher(base, method_name, **defaults)
+          def_helper(base, method_name, **defaults) do |name|
+            <<~RUBY
+              def #{name}(#{emit_params('node = self')})
+                #{emit_method_code}
+              end
+            RUBY
+          end
         end
 
-        def node_search_all(method_name, compiler, called_from)
-          yield_code = compiler.emit_yield_capture('node')
-          prelude = "return enum_for(:#{method_name}, node0" \
-                    "#{compiler.emit_trailing_params}) unless block_given?"
-
-          node_search(method_name, compiler, yield_code, prelude, called_from)
+        def def_node_search(base, method_name, **defaults)
+          def_helper(base, method_name, **defaults) do |name|
+            emit_node_search(name)
+          end
         end
 
-        def node_search(method_name, compiler, on_match, prelude, called_from)
-          src = node_search_body(method_name, compiler.emit_trailing_params,
-                                 prelude, compiler.match_code, on_match)
-          filename, lineno = *called_from
-          class_eval(src, filename, lineno.to_i)
+        def emit_node_search(method_name)
+          if method_name.to_s.end_with?('?')
+            on_match = 'return true'
+          else
+            args = emit_params(":#{method_name}", @root, forwarding: true)
+            prelude = "return enum_for(#{args}) unless block_given?\n"
+            on_match = emit_yield_capture(@node_var)
+          end
+          emit_node_search_body(method_name, prelude: prelude, on_match: on_match)
         end
 
-        def node_search_body(method_name, trailing_params, prelude, match_code,
-                             on_match)
+        def emit_node_search_body(method_name, prelude:, on_match:)
           <<~RUBY
-            def #{method_name}(node0#{trailing_params})
+            def #{method_name}(#{emit_params(@root)})
               #{prelude}
-              node0.each_node do |node|
+              #{@root}.each_node do |#{@node_var}|
                 if #{match_code}
                   #{on_match}
                 end
@@ -826,22 +853,53 @@ module RuboCop
           RUBY
         end
       end
+      private_constant :Compiler
+
+      # Helpers for defining methods based on a pattern string
+      module Macros
+        # Define a method which applies a pattern to an AST node
+        #
+        # The new method will return nil if the node does not match
+        # If the node matches, and a block is provided, the new method will
+        # yield to the block (passing any captures as block arguments).
+        # If the node matches, and no block is provided, the new method will
+        # return the captures, or `true` if there were none.
+        def def_node_matcher(method_name, pattern_str, **keyword_defaults)
+          Compiler.new(pattern_str, 'node')
+                  .def_node_matcher(self, method_name, **keyword_defaults)
+        end
+
+        # Define a method which recurses over the descendants of an AST node,
+        # checking whether any of them match the provided pattern
+        #
+        # If the method name ends with '?', the new method will return `true`
+        # as soon as it finds a descendant which matches. Otherwise, it will
+        # yield all descendants which match.
+        def def_node_search(method_name, pattern_str, **keyword_defaults)
+          Compiler.new(pattern_str, 'node0', 'node')
+                  .def_node_search(self, method_name, **keyword_defaults)
+        end
+      end
 
       attr_reader :pattern
 
       def initialize(str)
         @pattern = str
-        compiler = Compiler.new(str)
-        src = "def match(node0#{compiler.emit_trailing_params});" \
+        compiler = Compiler.new(str, 'node0')
+        src = "def match(#{compiler.emit_params('node0')});" \
               "#{compiler.emit_method_code}end"
         instance_eval(src, __FILE__, __LINE__ + 1)
       end
 
-      def match(*args)
+      def match(*args, **rest)
         # If we're here, it's because the singleton method has not been defined,
         # either because we've been dup'ed or serialized through YAML
         initialize(pattern)
-        match(*args)
+        if rest.empty?
+          match(*args)
+        else
+          match(*args, **rest)
+        end
       end
 
       def marshal_load(pattern)
@@ -877,6 +935,17 @@ module RuboCop
 
         nil
       end
+
+      # @api private
+      class Matcher
+        def initialize(&block)
+          @block = block
+        end
+
+        def ===(compare)
+          @block.call(compare)
+        end
+      end
     end
   end
 end