sexp_processor 4.9.0 → 4.10.0b1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c8a4cb1d34e3c86a00ee122db28cf4d3b7d2ef34
-  data.tar.gz: bec449692c425f44e6e40da22b7dae0192956640
+  metadata.gz: 65bf12b262290613b30fc69ea149c71e8943ddb8
+  data.tar.gz: 21c0cd86b86276dbf0dc862205b28cb145c2e26a
 SHA512:
-  metadata.gz: 7ca8f74ecc9e62dc1dd2d2eb272b0cd2502255fa956c75bf8bdad60990070ec05a03d8806c6acf6f61f6d30915b5d3caea73410c551f1a21c7eb528d085f7553
-  data.tar.gz: ef4dde66d8a7a6903ddad8520c1bba5ac2885c3fea7a13d54f4d6affd7e42780e78faaebf7c70aa7b26a4aca650673c26d9f39a166bebb1d1cd201e31be25bc0
+  metadata.gz: edc58c9bcf7547d5457787581ca887b9ca843fe64224cdf4b416b095b6e577940f62e1014716409d8ea9ef2c273860eed19fd52a4d3a34779ada9319158c69e3
+  data.tar.gz: 8bc9add51b1b81eb67f6b651a13f78450bf97e72716eaa346f5c90f782dbc7e733c8e5c45a657903c6e5df4fed3abcb5c6a51e735524cc32eb8d3f63143b3639

data/History.txt

@@ -1,3 +1,48 @@
+=== 4.10.0b1 / 2017-06-13
+
+* 2 major enhancements:
+
+  * Added experimental pattern matcher to Sexp. Forked from sexp_path.
+  * Extended s to take a block and return a matcher: eg s{ s(:defn, atom, _, ___) }
+
+* 23 minor enhancements:
+
+  * Added $STRICT_SEXP to crank down Sexp.[] and friends.
+  * Added Matcher#/ w/ real functionality.
+  * Added Sexp#/ to search with new patterns.
+  * Added Sexp#map to ensure you get a Sexp back.
+  * Added Sexp#new to create a new sexp with the same file/line/comment info.
+  * Added Sexp#search_each to recursively search w/ new patterns. Returns enum if no block.
+  * Added Sexp#sexp_body=
+  * Added Sexp::Matcher.match_subs? and .match_subs= to extend =~ so you can match strictly.
+  * Added Sexp::Matcher.parse to convert lispy string to safe matcher: "(defn atom _ ___)"
+  * Added all mutation methods to STRICT_SEXP >= 4
+  * Added deprecation message to Sexp#structure for [s(...)] forms.
+  * Added strict_sexp.rb to help you clamp down for future changes. STRICT_SEXP=1+
+  * Auto-require strict_sexp if $STRICT_SEXP is > 0.
+  * Converted a lot of indexed access to sexp_type/sexp_body, etc.
+  * Finally enforced SexpProcessor#process to only process sexps, not bare arrays.
+  * Made Sexp#/ double-dispatch to Matcher#/.
+  * Made Sexp#gsub work with new patterns.
+  * Made Sexp#sub work with new patterns.
+  * Made SexpProcessor STRICT_SEXP=4 compliant.
+  * Retired SexpMatchSpecial & SexpAny. Never used by anything AFAICT.
+  * Sexp#=== goes back to default.
+  * Sexp#=~(pat) calls pat =~ self.
+  * Sexp#sexp_body now takes optional offset. Use instead of sexp[n..-1].
+
+* 9 bug fixes:
+
+  * Extended Sexp::Matcher::Parser.parse to lex more forms of regexp.
+  * Finished off all missing doco.
+  * Fixed == methods on all Matcher classes to include ivars.
+  * Fixed Child#satisfy? to properly return false if failed.
+  * Fixed Sexp#sexp_body to return a sexp using Sexp#new.
+  * Fixed map to use Sexp#new.
+  * Only try to set c_type if it responds to it. Make STRICT_SEXP safe.
+  * R2C has a hack in SexpProcessor to call sexp_type=. Renamed to c_type= in R2C.
+  * Removed very obsolete attrset test from pt_testcase.rb
+
 === 4.9.0 / 2017-04-13
 
 * 9 minor enhancements:

data/Manifest.txt

@@ -6,6 +6,7 @@ lib/composite_sexp_processor.rb
 lib/pt_testcase.rb
 lib/sexp.rb
 lib/sexp_processor.rb
+lib/strict_sexp.rb
 lib/unique.rb
 test/test_composite_sexp_processor.rb
 test/test_environment.rb

data/README.txt

@@ -15,21 +15,50 @@ for your language processing pleasure.
 
   * Allows you to write very clean filters.
 
+* Includes MethodBasedSexpProcessor
+
+  * Makes writing language processors even easier!
+
 * Sexp provides a simple and clean interface to creating and manipulating ASTs.
 
+  * Includes new pattern matching system.
+
 == SYNOPSIS:
 
-  class MyProcessor < SexpProcessor
-    def initialize
-      super
-      self.strict = false
+You can use SexpProcessor to do all kinds of language processing. Here
+is a simple example of a simple documentation printer:
+
+  class ArrrDoc < MethodBasedSexpProcessor
+    def process_class exp
+      super do
+        puts "#{self.klass_name}: #{exp.comments}"
+      end
     end
-    def process_lit(exp)
-      val = exp.shift
-      return val
+
+    def process_defn exp
+      super do
+        args, *_body = exp
+
+        puts "#{self.method_name}(#{process_args args}): #{exp.comments}"
+      end
     end
   end
 
+Sexp provides a lot of power with the new pattern matching system.
+Here is an example that parses all the test files using RubyParser and
+then quickly finds all the test methods and prints their names:
+
+  >> require "ruby_parser";
+  >> rp = RubyParser.new;
+  >> matcher = Sexp::Matcher.parse "(defn [m /^test_/] ___)"
+  => q(:defn, m(/^test_/), ___)
+  >> paths = Dir["test/**/*.rb"];
+  >> sexps = s(:block, *paths.map { |path| rp.process File.read(path), path });
+  >> (sexps / matcher).size
+  => 189
+  ?> (sexps / matcher).map { |(_, name, *_rest)| name }.sort
+  => [:test_all, :test_amp, :test_and_satisfy_eh, :test_any_search, ...]
+
 == REQUIREMENTS:
 
 * rubygems

data/Rakefile

@@ -5,8 +5,12 @@ require 'hoe'
 
 Hoe.plugin :seattlerb
 
+Hoe.add_include_dirs("../../ruby_parser/dev/lib")
+
 Hoe.spec 'sexp_processor' do
   developer 'Ryan Davis', 'ryand-ruby@zenspider.com'
+
+  license "MIT"
 end
 
 # vim: syntax=ruby

data/lib/composite_sexp_processor.rb

@@ -1,4 +1,4 @@
-require 'sexp_processor'
+require "sexp_processor"
 
 ##
 # Implements the Composite pattern on SexpProcessor. Need we say more?
@@ -24,7 +24,7 @@ class CompositeSexpProcessor < SexpProcessor
   ##
   # Add a +processor+ to the list of processors to run.
 
-  def <<(processor)
+  def << processor
     raise ArgumentError, "Can only add sexp processors" unless
       SexpProcessor === processor || processor.respond_to?(:process)
     @processors << processor
@@ -34,14 +34,14 @@ class CompositeSexpProcessor < SexpProcessor
   # Run +exp+ through all of the processors, returning the final
   # result.
 
-  def process(exp)
+  def process exp
     @processors.each do |processor|
       exp = processor.process(exp)
     end
     exp
   end
 
-  def on_error_in(node_type, &block)
+  def on_error_in node_type, &block
     @processors.each do |processor|
       processor.on_error_in(node_type, &block)
     end

data/lib/pt_testcase.rb

@@ -1,9 +1,10 @@
 # encoding: US-ASCII
 
 $TESTING = true
+# :stopdoc:
 
-require 'minitest/test'
-require 'sexp_processor' # for deep_clone
+require "minitest/test"
+require "sexp_processor" # for deep_clone
 
 # key:
 # wwtt = what were they thinking?
@@ -12,7 +13,7 @@ class Examples
   attr_reader :reader
   attr_writer :writer
 
-  def a_method(x); x+1; end
+  def a_method x; x+1; end
   alias an_alias a_method
 
   define_method(:bmethod_noargs) do
@@ -136,9 +137,9 @@ class ParseTreeTestCase < Minitest::Test
         extra_input = []
 
         _, expected, extra_expected = *expected if
-          Array === expected and expected.first == :defx
+          Array === expected and expected.sexp_type == :defx
         _, input, extra_input = *input if
-          Array === input and input.first == :defx
+          Array === input and input.sexp_type == :defx
 
         # OMG... I can't believe I have to do this this way.  these
         # hooks are here instead of refactoring this define_method
@@ -167,7 +168,7 @@ class ParseTreeTestCase < Minitest::Test
     install_missing_reporter
     clone_same
 
-    output_name = klass.name.to_s.sub(/^Test/, '')
+    output_name = klass.name.to_s.sub(/^Test/, "")
 
     input_name = self.previous(output_name)
 
@@ -202,7 +203,7 @@ class ParseTreeTestCase < Minitest::Test
     end
   end
 
-  def self.previous(key, extra=0) # FIX: remove R2C code
+  def self.previous key, extra=0 # FIX: remove R2C code
     idx = @@testcase_order.index(key)
 
     raise "Unknown class #{key} in @@testcase_order" if idx.nil?
@@ -307,7 +308,7 @@ class ParseTreeTestCase < Minitest::Test
               "Ruby2Ruby"    => "10")
 
   add_18tests("str_question_literal",
-              "Ruby"         => '?a',
+              "Ruby"         => "?a",
               "ParseTree"    => s(:lit, 97),
               "Ruby2Ruby"    => "97")
 
@@ -595,7 +596,7 @@ class ParseTreeTestCase < Minitest::Test
               "ParseTree"    => s(:str, "\n"))
 
   add_19tests("str_question_literal",
-              "Ruby"         => '?a',
+              "Ruby"         => "?a",
               "ParseTree"    => s(:str, "a"))
 
   add_19tests("unless_post_not",
@@ -748,13 +749,6 @@ class ParseTreeTestCase < Minitest::Test
                                   s(:lit, 42), s(:lit, 24))),
             "Ruby2Ruby"    => "a = []\na[42] = 24\n")
 
-  add_tests("attrset",
-            "Ruby"         => [Examples, :writer=],
-            "ParseTree"    => s(:defn, :writer=,
-                                s(:args, :arg),
-                                s(:attrset, :@writer)),
-            "Ruby2Ruby"    => "attr_writer :writer")
-
   add_tests("back_ref",
             "Ruby"         => "[$&, $`, $', $+]",
             "ParseTree"    => s(:array,
@@ -1534,15 +1528,15 @@ class ParseTreeTestCase < Minitest::Test
 
   add_tests("dregx_interp",
             "Ruby"         => "/#\{@rakefile}/",
-            "ParseTree"    => s(:dregx, '', s(:evstr, s(:ivar, :@rakefile))))
+            "ParseTree"    => s(:dregx, "", s(:evstr, s(:ivar, :@rakefile))))
 
   add_tests("dregx_interp_empty",
             "Ruby"         => "/a#\{}b/",
-            "ParseTree"    => s(:dregx, 'a', s(:evstr), s(:str, "b")))
+            "ParseTree"    => s(:dregx, "a", s(:evstr), s(:str, "b")))
 
   add_tests("dregx_n",
             "Ruby"         => '/#{1}/n',
-            "ParseTree"    => s(:dregx, '',
+            "ParseTree"    => s(:dregx, "",
                                 s(:evstr, s(:lit, 1)), /x/n.options))
 
   add_tests("dregx_once",
@@ -1554,7 +1548,7 @@ class ParseTreeTestCase < Minitest::Test
 
   add_tests("dregx_once_n_interp",
             "Ruby"         => "/#\{IAC}#\{SB}/no",
-            "ParseTree"    => s(:dregx_once, '',
+            "ParseTree"    => s(:dregx_once, "",
                                 s(:evstr, s(:const, :IAC)),
                                 s(:evstr, s(:const, :SB)), /x/n.options))
 
@@ -1624,7 +1618,7 @@ class ParseTreeTestCase < Minitest::Test
   add_tests("dstr_heredoc_windoze_sucks",
             "Ruby"         => "<<-EOF\r\ndef test_#\{action}_valid_feed\r\n  EOF\r\n",
             "ParseTree"    => s(:dstr,
-                                'def test_',
+                                "def test_",
                                 s(:evstr, s(:call, nil, :action)),
                                 s(:str, "_valid_feed\n")),
             "Ruby2Ruby"    => "\"def test_#\{action}_valid_feed\\n\"")
@@ -1681,7 +1675,7 @@ class ParseTreeTestCase < Minitest::Test
             "Ruby"         => "t = 5\n`touch #\{t}`\n",
             "ParseTree"    => s(:block,
                                 s(:lasgn, :t, s(:lit, 5)),
-                                s(:dxstr, 'touch ', s(:evstr, s(:lvar, :t)))))
+                                s(:dxstr, "touch ", s(:evstr, s(:lvar, :t)))))
 
   add_tests("ensure",
             "Ruby"         => "begin\n  (1 + 1)\nrescue SyntaxError => e1\n  2\nrescue Exception => e2\n  3\nelse\n  4\nensure\n  5\nend",
@@ -2164,7 +2158,7 @@ class ParseTreeTestCase < Minitest::Test
             "ParseTree"    => s(:lit, /x/))
 
   add_tests("lit_regexp_i_wwtt",
-            "Ruby"         => 'str.split(//i)',
+            "Ruby"         => "str.split(//i)",
             "ParseTree"    => s(:call,
                                 s(:call, nil, :str),
                                 :split,
@@ -2369,7 +2363,7 @@ class ParseTreeTestCase < Minitest::Test
                                   s(:call,
                                     s(:call, nil, :d),
                                     :e,
-                                    s(:str, 'f')))))
+                                    s(:str, "f")))))
 
   add_tests("match",
             "Ruby"         => "1 if /x/",
@@ -3083,7 +3077,7 @@ class ParseTreeTestCase < Minitest::Test
 
   add_tests("xstr",
             "Ruby"         => "`touch 5`",
-            "ParseTree"    => s(:xstr, 'touch 5'))
+            "ParseTree"    => s(:xstr, "touch 5"))
 
   add_tests("yield_0",
             "Ruby"         => "yield",
@@ -3125,3 +3119,5 @@ class ParseTreeTestCase < Minitest::Test
 #   end
 
 end
+
+# :startdoc:

data/lib/sexp.rb

@@ -7,66 +7,66 @@ $TESTING ||= false # unless defined $TESTING
 # dispatch the Sexp to for processing.
 
 class Sexp < Array # ZenTest FULL
+  ##
+  # A setter for the line this sexp was found on. Usually set by ruby_parser.
 
   attr_writer :line
-  attr_accessor :file, :comments
 
-  @@array_types = [ :array, :args, ]
+  ##
+  # Accessors for the file. Usually set by ruby_parser.
+
+  attr_accessor :file
+
+  ##
+  # Optional comments above/aside this sexp. Usually set by ruby_parser.
+
+  attr_accessor :comments
+
+  @@array_types = [ :array, :args ] # TODO: remove
 
   ##
   # Create a new Sexp containing +args+.
 
-  def initialize(*args)
+  def initialize *args
     super(args)
   end
 
   ##
   # Creates a new Sexp from Array +a+.
 
-  def self.from_array(a)
+  def self.from_array a
     ary = Array === a ? a : [a]
 
-    result = self.new
-
-    ary.each do |x|
-      case x
-      when Sexp
-        result << x
-      when Array
-        result << self.from_array(x)
-      else
-        result << x
-      end
-    end
-
-    result
-  end
-
-  def ==(obj) # :nodoc:
-    obj.class == self.class and super
+    self.new(*ary.map { |x|
+               case x
+               when Sexp
+                 x
+               when Array
+                 self.from_array(x)
+               else
+                 x
+               end
+             })
   end
 
   ##
-  # Returns true if this Sexp's pattern matches +sexp+.
-
-  def ===(sexp)
-    return nil unless Sexp === sexp
-    pattern = self # this is just for my brain
-
-    return true if pattern == sexp
-
-    sexp.each do |subset|
-      return true if pattern === subset
-    end
-
-    return nil
+  # Creates a new sexp with the new contents of +body+, but with the
+  # same +file+, +line+, and +comment+ as self.
+
+  def new(*body)
+    r = self.class.new(*body) # ensures a sexp from map
+    r.file     = self.file     if self.file
+    r.line     = self.line     if self.line
+    r.comments = self.comments if self.comments
+    r
   end
 
-  ##
-  # Returns true if this Sexp matches +pattern+.  (Opposite of #===.)
+  def map &blk # :nodoc:
+    self.new(*super(&blk)) # ensures a sexp from map
+  end
 
-  def =~(pattern)
-    return pattern === self
+  def == obj # :nodoc:
+    obj.class == self.class and super # only because of a bug in ruby
   end
 
   ##
@@ -75,18 +75,19 @@ class Sexp < Array # ZenTest FULL
   # REFACTOR: to TypedSexp - we only care when we have units.
 
   def array_type?
-    type = self.first
+    warn "DEPRECATED: please file an issue if you actually use this. from #{caller.first}"
+    type = self.sexp_type
     @@array_types.include? type
   end
 
   def compact # :nodoc:
-    self.delete_if { |o| o.nil? }
+    self.delete_if(&:nil?)
   end
 
   ##
   # Recursively enumerates the sexp yielding to +block+ for every element.
 
-  def deep_each(&block)
+  def deep_each &block
     return enum_for(:deep_each) unless block_given?
 
     self.each_sexp do |sexp|
@@ -95,6 +96,9 @@ class Sexp < Array # ZenTest FULL
     end
   end
 
+  ##
+  # Return the maximum depth of the sexp. One-based.
+
   def depth
     1 + (each_sexp.map(&:depth).max || 0)
   end
@@ -102,14 +106,12 @@ class Sexp < Array # ZenTest FULL
   ##
   # Enumeratates the sexp yielding to +b+ when the node_type == +t+.
 
-  def each_of_type(t, &b)
+  def each_of_type t, &b
     return enum_for(:each_of_type) unless block_given?
 
-    each do | elem |
-      if Sexp === elem then
-        elem.each_of_type(t, &b)
-        b.call(elem) if elem.first == t
-      end
+    each_sexp do | sexp |
+      sexp.each_of_type(t, &b)
+      yield sexp if sexp.sexp_type == t
     end
   end
 
@@ -130,12 +132,12 @@ class Sexp < Array # ZenTest FULL
   # Replaces all elements whose node_type is +from+ with +to+. Used
   # only for the most trivial of rewrites.
 
-  def find_and_replace_all(from, to)
+  def find_and_replace_all from, to
     each_with_index do | elem, index |
       if Sexp === elem then
         elem.find_and_replace_all(from, to)
-      else
-        self[index] = to if elem == from
+      elsif elem == from
+        self[index] = to
       end
     end
   end
@@ -143,31 +145,35 @@ class Sexp < Array # ZenTest FULL
   ##
   # Replaces all Sexps matching +pattern+ with Sexp +repl+.
 
-  def gsub(pattern, repl)
+  def gsub pattern, repl
     return repl if pattern == self
 
-    new = self.map do |subset|
+    new = self.map { |subset|
       case subset
       when Sexp then
-        subset.gsub(pattern, repl)
+        if Matcher === pattern && pattern.satisfy?(subset) then # TODO: make === be satisfy? maybe?
+          repl.dup rescue repl
+        else
+          subset.gsub pattern, repl
+        end
       else
         subset
       end
-    end
+    }
 
-    return Sexp.from_array(new)
+    Sexp.from_array new
   end
 
   def inspect # :nodoc:
-    sexp_str = self.map {|x|x.inspect}.join(', ')
-    if ENV['VERBOSE'] && line then
+    sexp_str = self.map(&:inspect).join ", "
+    if ENV["VERBOSE"] && line then
       "s(#{sexp_str}).line(#{line})"
     else
       "s(#{sexp_str})"
     end
   end
 
-  def find_node name, delete = false
+  def find_node name, delete = false # :nodoc:
     matches = find_nodes name
 
     case matches.size
@@ -186,7 +192,7 @@ class Sexp < Array # ZenTest FULL
   # Find every node with type +name+.
 
   def find_nodes name
-    find_all { | sexp | Sexp === sexp and sexp.first == name }
+    each_sexp.find_all { |sexp| sexp.sexp_type == name }
   end
 
   ##
@@ -194,7 +200,7 @@ class Sexp < Array # ZenTest FULL
   # returns the line number. This allows you to do message cascades
   # and still get the sexp back.
 
-  def line(n=nil)
+  def line n = nil
     if n then
       @line = n
       self
@@ -214,14 +220,7 @@ class Sexp < Array # ZenTest FULL
   # Returns the size of the sexp, flattened.
 
   def mass
-    @mass ||=
-      inject(1) { |t, s|
-      if Sexp === s then
-        t + s.mass
-      else
-        t
-      end
-    }
+    @mass ||= inject(1) { |t, s| Sexp === s ? t + s.mass : t }
   end
 
   ##
@@ -244,11 +243,11 @@ class Sexp < Array # ZenTest FULL
     super
   end
 
-  def pretty_print(q) # :nodoc:
-    nnd = ')'
-    nnd << ".line(#{line})" if line && ENV['VERBOSE']
+  def pretty_print q # :nodoc:
+    nnd = ")"
+    nnd << ".line(#{line})" if line && ENV["VERBOSE"]
 
-    q.group(1, 's(', nnd) do
+    q.group(1, "s(", nnd) do
       q.seplist(self) {|v| q.pp v }
     end
   end
@@ -267,11 +266,19 @@ class Sexp < Array # ZenTest FULL
     self[0] = v
   end
 
+  ##
+  # Returns the Sexp body (starting at +from+, defaulting to 1), ie
+  # the values without the node type.
+
+  def sexp_body from = 1
+    self.new(*self[from..-1])
+  end
+
   ##
   # Returns the Sexp body, ie the values without the node type.
 
-  def sexp_body
-    self[1..-1]
+  def sexp_body= v
+    self[1..-1] = v
   end
 
   alias :head :sexp_type
@@ -284,29 +291,27 @@ class Sexp < Array # ZenTest FULL
   def shift
     raise "I'm empty" if self.empty?
     super
-  end if ($DEBUG or $TESTING) unless (defined?(RUBY_ENGINE) and RUBY_ENGINE == "maglev")
+  end if ($DEBUG or $TESTING)
 
   ##
   # Returns the bare bones structure of the sexp.
   # s(:a, :b, s(:c, :d), :e) => s(:a, s(:c))
 
   def structure
-    if Array === self.first then
+    if Array === self.sexp_type then
+      warn "NOTE: form s(s(:subsexp)).structure is deprecated. Removing in 5.0"
       s(:bogus, *self).structure # TODO: remove >= 4.2.0
     else
-      result = s(self.first)
-      self.each do |subexp|
-        result << subexp.structure if Sexp === subexp
-      end
-      result
+      s(self.sexp_type, *each_sexp.map(&:structure))
     end
   end
 
   ##
   # Replaces the Sexp matching +pattern+ with +repl+.
 
-  def sub(pattern, repl)
+  def sub pattern, repl
     return repl.dup if pattern == self
+    return repl.dup if Matcher === pattern && pattern.satisfy?(self)
 
     done = false
 
@@ -318,12 +323,12 @@ class Sexp < Array # ZenTest FULL
         when Sexp then
           if pattern == subset then
             done = true
-            repl.dup
-          elsif pattern === subset then
+            repl.dup rescue repl
+          elsif Matcher === pattern && pattern.satisfy?(subset) then
             done = true
-            subset.sub pattern, repl
+            repl.dup rescue repl
           else
-            subset
+            subset.sub pattern, repl
           end
         else
           subset
@@ -331,41 +336,1079 @@ class Sexp < Array # ZenTest FULL
       end
     end
 
-    return Sexp.from_array(new)
+    Sexp.from_array new
   end
 
   def to_a # :nodoc:
     self.map { |o| Sexp === o ? o.to_a : o }
   end
 
-  def to_s # :nodoc:
-    inspect
-  end
+  alias to_s inspect # :nodoc:
 end
 
-class SexpMatchSpecial < Sexp; end
+##
+# This is a very important shortcut to make using Sexps much more awesome.
+#
+# In its normal form +s(...)+, creates a Sexp instance. If passed a
+# block, it creates a Sexp::Matcher using the factory methods on Sexp.
+#
+# See Matcher and other factory class methods on Sexp.
+
+def s *args, &blk
+  return Sexp.class_eval(&blk) if blk
+  Sexp.new(*args)
+end
 
-class SexpAny < SexpMatchSpecial
-  def ==(o)
-    Sexp === o
+class Sexp #:nodoc:
+  ##
+  # Verifies that +pattern+ is a Matcher and then dispatches to its
+  # #=~ method.
+  #
+  # See Matcher.=~
+
+  def =~ pattern
+    raise ArgumentError, "Not a pattern: %p" % [pattern] unless Matcher === pattern
+    pattern =~ self
   end
 
-  def ===(o)
-    return Sexp === o
+  ##
+  # Verifies that +pattern+ is a Matcher and then dispatches to its
+  # #satisfy? method.
+  #
+  # TODO: rename match?
+
+  def satisfy? pattern
+    raise ArgumentError, "Not a pattern: %p" % [pattern] unless Matcher === pattern
+    pattern.satisfy? self
   end
 
-  def inspect
-    "ANY"
+  ##
+  # Verifies that +pattern+ is a Matcher and then dispatches to its #/
+  # method.
+  #
+  # TODO: rename grep? match_all ? find_all ?
+
+  def / pattern
+    raise ArgumentError, "Not a pattern: %p" % [pattern] unless Matcher === pattern
+    pattern / self
   end
-end
 
-module SexpMatchSpecials
-  def ANY(); return SexpAny.new; end
-end
+  ##
+  # Recursively searches for the +pattern+ yielding the matches.
 
-##
-# This is a very important shortcut to make using Sexps much more awesome.
+  def search_each pattern, &block # TODO: rename to grep?
+    raise ArgumentError, "Needs a pattern" unless pattern.kind_of? Matcher
 
-def s(*args)
-  Sexp.new(*args)
+    return enum_for(:search_each, pattern) unless block_given?
+
+    if pattern.satisfy? self then
+      yield self
+    end
+
+    self.each_sexp do |subset|
+      subset.search_each pattern, &block
+    end
+  end
+
+  ##
+  # Recursively searches for the +pattern+ yielding each match, and
+  # replacing it with the result of the block.
+  #
+
+  def replace_sexp pattern, &block # TODO: rename to gsub?
+    raise ArgumentError, "Needs a pattern" unless pattern.kind_of? Matcher
+
+    return yield self if pattern.satisfy? self
+
+    # TODO: Needs #new_from(*new_body) to copy file/line/comment
+    self.class.new(*self.map { |subset|
+                     case subset
+                     when Sexp then
+                       subset.replace_sexp pattern, &block
+                     else
+                       subset
+                     end
+                   })
+  end
+
+  ##
+  # Matches an S-Expression.
+  #
+  # See Matcher for examples.
+
+  def self.s *args
+    Matcher.new(*args)
+  end
+
+  ##
+  # Matches any single item.
+  #
+  # See Wild for examples.
+
+  def self._
+    Wild.new
+  end
+
+  # TODO: reorder factory methods and classes to match
+
+  ##
+  # Matches all remaining input.
+  #
+  # See Remaining for examples.
+
+  def self.___
+    Remaining.new
+  end
+
+  ##
+  # Matches an expression or any expression that includes the child.
+  #
+  # See Include for examples.
+
+  def self.include child # TODO: rename, name is generic ruby
+    Include.new(child)
+  end
+
+  ##
+  # Matches any atom.
+  #
+  # See Atom for examples.
+
+  def self.atom
+    Atom.new
+  end
+
+  ##
+  # Matches when any of the sub-expressions match.
+  #
+  # This is also available via Matcher#|.
+  #
+  # See Any for examples.
+
+  def self.any *args
+    Any.new(*args)
+  end
+
+  ##
+  # Matches only when all sub-expressions match.
+  #
+  # This is also available via Matcher#&.
+  #
+  # See All for examples.
+
+  def self.all *args
+    All.new(*args)
+  end
+
+  ##
+  # Matches when sub-expression does not match.
+  #
+  # This is also available via Matcher#-@.
+  #
+  # See Not for examples.
+
+  def self.not? arg
+    Not.new arg
+  end
+
+  # TODO: add Sibling factory method?
+
+  ##
+  # Matches anything that has a child matching the sub-expression.
+  #
+  # See Child for examples.
+
+  def self.child child
+    Child.new child
+  end
+
+  ##
+  # Matches anything having the same sexp_type, which is the first
+  # value in a Sexp.
+  #
+  # See Type for examples.
+
+  def self.t name
+    Type.new name
+  end
+
+  ##
+  # Matches any atom who's string representation matches the patterns
+  # passed in.
+  #
+  # See Pattern for examples.
+
+  def self.m *values
+    res = values.map { |value|
+      case value
+      when Regexp then
+        value
+      else
+        re = Regexp.escape value.to_s
+        Regexp.new "\\A%s\\Z" % re
+      end
+    }
+    Pattern.new Regexp.union(*res)
+  end
+
+  ##
+  # Defines a family of objects that can be used to match sexps to
+  # certain types of patterns, much like regexps can be used on
+  # strings. Generally you won't use this class directly.
+  #
+  # You would normally create a matcher using the top-level #s method,
+  # but with a block, calling into the Sexp factory methods. For example:
+  #
+  #   s{ s(:class, m(/^Test/), _, ___) }
+  #
+  # This creates a matcher for classes whose names start with "Test".
+  # It uses Sexp.m to create a Sexp::Matcher::Pattern matcher, Sexp._
+  # to create a Sexp::Matcher::Wild matcher, and Sexp.___ to create a
+  # Sexp::Matcher::Remaining matcher. It works like this:
+  #
+  #   s{              # start to create a pattern
+  #     s(            # create a sexp matcher
+  #       :class.     # for class nodes
+  #       m(/^Test/), # matching name slots that start with "Test"
+  #       _,          # any superclass value
+  #       ___         # and whatever is in the class
+  #      )
+  #    }
+  #
+  # Then you can use that with #=~, #/, Sexp#replace_sexp, and others.
+  #
+  # For more examples, see the various Sexp class methods, the examples,
+  # and the tests supplied with Sexp.
+  #
+  # * For pattern creation, see factory methods: Sexp::_, Sexp::___, etc.
+  # * For matching returning truthy/falsey results, see Sexp#=~.
+  # * See Sexp#=~ for matching returning truthy/falsey results.
+  # * For case expressions, see Matcher#===.
+  # * For getting all subtree matches, see Sexp#/.
+  #
+  # If rdoc didn't suck, these would all be links.
+
+  class Matcher < Sexp
+    ##
+    # Should #=~ match sub-trees?
+
+    def self.match_subs?
+      @@match_subs
+    end
+
+    ##
+    # Setter for +match_subs?+.
+
+    def self.match_subs= o
+      @@match_subs = o
+    end
+
+    self.match_subs = true
+
+    ##
+    # Does this matcher actually match +o+? Returns falsey if +o+ is
+    # not a Sexp or if any sub-tree of +o+ is not satisfied by or
+    # equal to its corresponding sub-matcher.
+    #
+    #--
+    # TODO: push this up to Sexp and make this the workhorse
+    # TODO: do the same with ===/satisfy?
+
+    def satisfy? o
+      return unless o.kind_of?(Sexp) &&
+        (length == o.length || Matcher === last && last.greedy?)
+
+      each_with_index.all? { |child, i|
+        sexp = o.at i
+        if Sexp === child then # TODO: when will this NOT be a matcher?
+          sexp = o.sexp_body i if child.respond_to?(:greedy?) && child.greedy?
+          child.satisfy? sexp
+        else
+          child == sexp
+        end
+      }
+    end
+
+    ##
+    # Tree equivalent to String#=~, returns true if +self+ matches
+    # +sexp+ as a whole or in a sub-tree (if +match_subs?+).
+    #
+    # TODO: maybe this should NOT be aliased to === ?
+    #
+    # TODO: example
+
+    def =~ sexp
+      raise ArgumentError, "Can't both be matchers: %p" % [sexp] if Matcher === sexp
+
+      self.satisfy?(sexp) ||
+        (self.class.match_subs? && sexp.each_sexp.any? { |sub| self =~ sub })
+    end
+
+    alias === =~ # TODO?: alias === satisfy?
+
+    ##
+    # Searches through +sexp+ for all sub-trees that match this
+    # matcher and returns a MatchCollection for each match.
+    #
+    # TODO: redirect?
+    # Example:
+    #   Q{ s(:b) } / s(:a, s(:b)) => [s(:b)]
+
+    def / sexp
+      raise ArgumentError, "can't both be matchers" if Matcher === sexp
+
+      # TODO: move search_each into matcher?
+      MatchCollection.new sexp.search_each(self).to_a
+    end
+
+    ##
+    # Combines the Matcher with another Matcher, the resulting one will
+    # be satisfied if either Matcher would be satisfied.
+    #
+    # TODO: redirect
+    # Example:
+    #   s(:a) | s(:b)
+
+    def | other
+      Any.new self, other
+    end
+
+    ##
+    # Combines the Matcher with another Matcher, the resulting one will
+    # be satisfied only if both Matchers would be satisfied.
+    #
+    # TODO: redirect
+    # Example:
+    #   t(:a) & include(:b)
+
+    def & other
+      All.new self, other
+    end
+
+    ##
+    # Returns a Matcher that matches whenever this Matcher would not have matched
+    #
+    # Example:
+    #   -s(:a)
+
+    def -@
+      Not.new self
+    end
+
+    ##
+    # Returns a Matcher that matches if this has a sibling +o+
+    #
+    # Example:
+    #   s(:a) >> s(:b)
+
+    def >> other
+      Sibling.new self, other
+    end
+
+    ##
+    # Is this matcher greedy? Defaults to false.
+
+    def greedy?
+      false
+    end
+
+    def inspect # :nodoc:
+      s = super
+      s[0] = "q"
+      s
+    end
+
+    def pretty_print q # :nodoc:
+      q.group 1, "q(", ")" do
+        q.seplist self do |v|
+          q.pp v
+        end
+      end
+    end
+
+    ##
+    # Parse a lispy string representation of a matcher into a Matcher.
+    # See +Parser+.
+
+    def self.parse s
+      Parser.new(s).parse
+    end
+
+    ##
+    # Converts from a lispy string to Sexp matchers in a safe manner.
+    #
+    #   "(a 42 _ (c) [t x] ___)" => s{ s(:a, 42, _, s(:c), t(:x), ___) }
+
+    class Parser
+
+      ##
+      # The stream of tokens to parse. See #lex.
+
+      attr_accessor :tokens
+
+      ##
+      # Create a new Parser instance on +s+
+
+      def initialize s
+        self.tokens = []
+        lex s
+      end
+
+      ##
+      # Converts +s+ into a stream of tokens and adds them to +tokens+.
+
+      def lex s
+        tokens.concat s.scan(%r%[()\[\]]|\"[^"]*\"|/[^/]*/|[\w-]+%)
+      end
+
+      ##
+      # Returns the next token and removes it from the stream or raises if empty.
+
+      def next_token
+        raise SyntaxError, "unbalanced input" if tokens.empty?
+        tokens.shift
+      end
+
+      ##
+      # Returns the next token without removing it from the stream.
+
+      def peek_token
+        tokens.first
+      end
+
+      ##
+      # Parses tokens and returns a +Matcher+ instance.
+
+      def parse
+        result = parse_sexp until tokens.empty?
+        result
+      end
+
+      ##
+      # Parses a string into a sexp matcher:
+      #
+      #   SEXP : "(" SEXP:args* ")"          => Sexp.q(*args)
+      #        | "[" CMD:cmd sexp:args* "]"  => Sexp.cmd(*args)
+      #        | "nil"                       => nil
+      #        | /\d+/:n                     => n.to_i
+      #        | "___"                       => Sexp.___
+      #        | "_"                         => Sexp._
+      #        | /^\/(.*)\/$/:re             => Regexp.new re[0]
+      #        | /^"(.*)"$/:s                => String.new s[0]
+      #        | NAME:name                   => name.to_sym
+      #   NAME : /\w+/
+      #    CMD : "t" | "m" | "atom"
+
+      def parse_sexp
+        token = next_token
+
+        case token
+        when "(" then
+          parse_list
+        when "[" then
+          parse_cmd
+        when "nil" then
+          nil
+        when /^\d+$/ then
+          token.to_i
+        when "___" then
+          Sexp.___
+        when "_" then
+          Sexp._
+        when %r%^/(.*)/$% then
+          re = $1
+          raise SyntaxError, "Not allowed: /%p/" % [re] unless
+            re =~ /\A([\w()|.*+^$]+)\z/
+          Regexp.new re
+        when /^"(.*)"$/ then
+          $1
+        when /^\w+$/ then
+          token.to_sym
+        else
+          raise SyntaxError, "unhandled token: %p" % [token]
+        end
+      end
+
+      ##
+      # Parses a balanced list of expressions and returns the
+      # equivalent matcher.
+
+      def parse_list
+        result = []
+
+        result << parse_sexp while peek_token && peek_token != ")"
+        next_token # pop off ")"
+
+        Sexp.s(*result)
+      end
+
+      ##
+      # A collection of allowed commands to convert into matchers.
+
+      ALLOWED = [:t, :m, :atom].freeze
+
+      ##
+      # Parses a balanced command. A command is denoted by square
+      # brackets and must conform to a whitelisted set of allowed
+      # commands (see +ALLOWED+).
+
+      def parse_cmd
+        args = []
+        args << parse_sexp while peek_token && peek_token != "]"
+        next_token # pop off "]"
+
+        cmd = args.shift
+        args = Sexp.s(*args)
+
+        raise SyntaxError, "bad cmd: %p" % [cmd] unless ALLOWED.include? cmd
+
+        result = Sexp.send cmd, *args
+
+        result
+      end
+    end # class Parser
+  end # class Matcher
+
+  ##
+  # Matches any single item.
+  #
+  # examples:
+  #
+  #   s(:a)           / s{ _ }    #=> [s(:a)]
+  #   s(:a, s(s(:b))) / s{ s(_) } #=> [s(s(:b))]
+
+  class Wild < Matcher
+    ##
+    # Matches any single element.
+
+    def satisfy? o
+      true
+    end
+
+    def inspect # :nodoc:
+      "_"
+    end
+
+    def pretty_print q # :nodoc:
+      q.text "_"
+    end
+  end
+
+  ##
+  # Matches all remaining input. If remaining comes before any other
+  # matchers, they will be ignored.
+  #
+  # examples:
+  #
+  #   s(:a)         / s{ s(:a, ___ ) } #=> [s(:a)]
+  #   s(:a, :b, :c) / s{ s(:a, ___ ) } #=> [s(:a, :b, :c)]
+
+  class Remaining < Matcher
+    ##
+    # Always satisfied once this is reached. Think of it as a var arg.
+
+    def satisfy? o
+      true
+    end
+
+    def greedy?
+      true
+    end
+
+    def inspect # :nodoc:
+      "___"
+    end
+
+    def pretty_print q # :nodoc:
+      q.text "___"
+    end
+  end
+
+  ##
+  # Matches when any of the sub-expressions match.
+  #
+  # This is also available via Matcher#|.
+  #
+  # examples:
+  #
+  #   s(:a) / s{ any(s(:a), s(:b)) } #=> [s(:a)]
+  #   s(:a) / s{     s(:a) | s(:b) } #=> [s(:a)] # same thing via |
+  #   s(:a) / s{ any(s(:b), s(:c)) } #=> []
+
+  class Any < Matcher
+    ##
+    # The collection of sub-matchers to match against.
+
+    attr_reader :options
+
+    ##
+    # Create an Any matcher which will match any of the +options+.
+
+    def initialize *options
+      @options = options
+    end
+
+    ##
+    # Satisfied when any sub expressions match +o+
+
+    def satisfy? o
+      options.any? { |exp|
+        Sexp === exp && exp.satisfy?(o) || exp == o
+      }
+    end
+
+    def == o # :nodoc:
+      super && self.options == o.options
+    end
+
+    def inspect # :nodoc:
+      options.map(&:inspect).join(" | ")
+    end
+
+    def pretty_print q # :nodoc:
+      q.group 1, "any(", ")" do
+        q.seplist options do |v|
+          q.pp v
+        end
+      end
+    end
+  end
+
+  ##
+  # Matches only when all sub-expressions match.
+  #
+  # This is also available via Matcher#&.
+  #
+  # examples:
+  #
+  #   s(:a)     / s{ all(s(:a), s(:b)) }    #=> []
+  #   s(:a, :b) / s{ t(:a) & include(:b)) } #=> [s(:a, :b)]
+
+  class All < Matcher
+    ##
+    # The collection of sub-matchers to match against.
+
+    attr_reader :options
+
+    ##
+    # Create an All matcher which will match all of the +options+.
+
+    def initialize *options
+      @options = options
+    end
+
+    ##
+    # Satisfied when all sub expressions match +o+
+
+    def satisfy? o
+      options.all? { |exp|
+        exp.kind_of?(Sexp) ? exp.satisfy?(o) : exp == o
+      }
+    end
+
+    def == o # :nodoc:
+      super && self.options == o.options
+    end
+
+    def inspect # :nodoc:
+      options.map(&:inspect).join(" & ")
+    end
+
+    def pretty_print q # :nodoc:
+      q.group 1, "all(", ")" do
+        q.seplist options do |v|
+          q.pp v
+        end
+      end
+    end
+  end
+
+  ##
+  # Matches when sub-expression does not match.
+  #
+  # This is also available via Matcher#-@.
+  #
+  # examples:
+  #
+  #   s(:a) / s{ not?(s(:b)) } #=> [s(:a)]
+  #   s(:a) / s{ -s(:b) }      #=> [s(:a)]
+  #   s(:a) / s{ s(not? :a) } #=> []
+
+  class Not < Matcher
+
+    ##
+    # The value to negate in the match.
+
+    attr_reader :value
+
+    ##
+    # Creates a Matcher which will match any Sexp that does not match the +value+
+
+    def initialize value
+      @value = value
+    end
+
+    def == o # :nodoc:
+      super && self.value == o.value
+    end
+
+    ##
+    # Satisfied if a +o+ does not match the +value+
+
+    def satisfy? o
+      !(value.kind_of?(Sexp) ? value.satisfy?(o) : value == o)
+    end
+
+    def inspect # :nodoc:
+      "not?(%p)" % [value]
+    end
+
+    def pretty_print q # :nodoc:
+      q.group 1, "not?(", ")" do
+        q.pp value
+      end
+    end
+  end
+
+  ##
+  # Matches anything that has a child matching the sub-expression
+  #
+  # example:
+  #
+  #   s(s(s(s(s(:a))))) / s{ child(s(:a)) } #=> [s(s(s(s(s(:a))))),
+  #                                              s(s(s(s(:a)))),
+  #                                              s(s(s(:a))),
+  #                                              s(s(:a)),
+  #                                              s(:a)]
+
+  class Child < Matcher
+    ##
+    # The child to match.
+
+    attr_reader :child
+
+    ##
+    # Create a Child matcher which will match anything having a
+    # descendant matching +child+.
+
+    def initialize child
+      @child = child
+    end
+
+    ##
+    # Satisfied if matches +child+ or +o+ has a descendant matching
+    # +child+.
+
+    def satisfy? o
+      if child.satisfy? o
+        true
+      elsif o.kind_of? Sexp
+        o.search_each(child).any?
+      end
+    end
+
+    def == o # :nodoc:
+      super && self.child == o.child
+    end
+
+    def inspect # :nodoc:
+      "child(%p)" % [child]
+    end
+
+    def pretty_print q # :nodoc:
+      q.group 1, "child(", ")" do
+        q.pp child
+      end
+    end
+  end
+
+  ##
+  # Matches any atom (non-Sexp).
+  #
+  # examples:
+  #
+  #   s(:a)        / s{ s(atom) } #=> [s(:a)]
+  #   s(:a, s(:b)) / s{ s(atom) } #=> [s(:b)]
+
+  class Atom < Matcher
+    ##
+    # Satisfied when +o+ is an atom.
+
+    def satisfy? o
+      !(o.kind_of? Sexp)
+    end
+
+    def inspect #:nodoc:
+      "atom"
+    end
+
+    def pretty_print q # :nodoc:
+      q.text "atom"
+    end
+  end
+
+  ##
+  # Matches any atom who's string representation matches the patterns
+  # passed in.
+  #
+  # examples:
+  #
+  #   s(:a) / s{ m('a') }                                      #=> [s(:a)]
+  #   s(:a) / s{ m(/\w/,/\d/) }                                #=> [s(:a)]
+  #   s(:tests, s(s(:test_a), s(:test_b))) / s{ m(/test_\w/) } #=> [s(:test_a),
+  #
+  # TODO: maybe don't require non-sexps? This does respond to =~ now.
+
+  class Pattern < Matcher
+
+    ##
+    # The regexp to match for the pattern.
+
+    attr_reader :pattern
+
+    def == o # :nodoc:
+      super && self.pattern == o.pattern
+    end
+
+    ##
+    # Create a Patten matcher which will match any atom that either
+    # matches the input +pattern+.
+
+    def initialize pattern
+      @pattern = pattern
+    end
+
+    ##
+    # Satisfied if +o+ is an atom, and +o+ matches +pattern+
+
+    def satisfy? o
+      !o.kind_of?(Sexp) && o.to_s =~ pattern # TODO: question to_s
+    end
+
+    def inspect # :nodoc:
+      "m(%p)" % pattern
+    end
+
+    def pretty_print q # :nodoc:
+      q.group 1, "m(", ")" do
+        q.pp pattern
+      end
+    end
+  end
+
+  ##
+  # Matches anything having the same sexp_type, which is the first
+  # value in a Sexp.
+  #
+  # examples:
+  #
+  #   s(:a, :b) / s{ t(:a) }        #=> [s(:a, :b)]
+  #   s(:a, :b) / s{ t(:b) }        #=> []
+  #   s(:a, s(:b, :c)) / s{ t(:b) } #=> [s(:b, :c)]
+
+  class Type < Matcher
+    attr_reader :sexp_type
+
+    ##
+    # Creates a Matcher which will match any Sexp who's type is +type+, where a type is
+    # the first element in the Sexp.
+
+    def initialize type
+      @sexp_type = type
+    end
+
+    def == o # :nodoc:
+      super && self.sexp_type == o.sexp_type
+    end
+
+    ##
+    # Satisfied if the sexp_type of +o+ is +type+.
+
+    def satisfy? o
+      o.kind_of?(Sexp) && o.sexp_type == sexp_type
+    end
+
+    def inspect # :nodoc:
+      "t(%p)" % sexp_type
+    end
+
+    def pretty_print q # :nodoc:
+      q.group 1, "t(", ")" do
+        q.pp sexp_type
+      end
+    end
+  end
+
+  ##
+  # Matches an expression or any expression that includes the child.
+  #
+  # examples:
+  #
+  #   s(:a, :b)   / s{ include(:b) } #=> [s(:a, :b)]
+  #   s(s(s(:a))) / s{ include(:a) } #=> [s(:a)]
+
+  class Include < Matcher
+    ##
+    # The value that should be included in the match.
+
+    attr_reader :value
+
+    ##
+    # Creates a Matcher which will match any Sexp that contains the
+    # +value+.
+
+    def initialize value
+      @value = value
+    end
+
+    ##
+    # Satisfied if a +o+ is a Sexp and one of +o+'s elements matches
+    # value
+
+    def satisfy? o
+      Sexp === o && o.any? { |c|
+        # TODO: switch to respond_to??
+        Sexp === value ? value.satisfy?(c) : value == c
+      }
+    end
+
+    def == o # :nodoc:
+      super && self.value == o.value
+    end
+
+    def inspect # :nodoc:
+      "include(%p)" % [value]
+    end
+
+    def pretty_print q # :nodoc:
+      q.group 1, "include(", ")" do
+        q.pp value
+      end
+    end
+  end
+
+  ##
+  # See Matcher for sibling relations: <,<<,>>,>
+
+  class Sibling < Matcher
+
+    ##
+    # The LHS of the matcher.
+
+    attr_reader :subject
+
+    ##
+    # The RHS of the matcher.
+
+    attr_reader :sibling
+
+    ##
+    # An optional distance requirement for the matcher.
+
+    attr_reader :distance
+
+    ##
+    # Creates a Matcher which will match any pair of Sexps that are siblings.
+    # Defaults to matching the immediate following sibling.
+
+    def initialize subject, sibling, distance = nil
+      @subject = subject
+      @sibling = sibling
+      @distance = distance
+    end
+
+    ##
+    # Satisfied if o contains +subject+ followed by +sibling+
+
+    def satisfy? o
+      # Future optimizations:
+      # * Shortcut matching sibling
+      subject_matches = index_matches(subject, o)
+      return nil if subject_matches.empty?
+
+      sibling_matches = index_matches(sibling, o)
+      return nil if sibling_matches.empty?
+
+      subject_matches.any? { |i1, _data_1|
+        sibling_matches.any? { |i2, _data_2|
+          distance ? (i2-i1 == distance) : i2 > i1
+        }
+      }
+    end
+
+    def == o # :nodoc:
+      super &&
+        self.subject  == o.subject &&
+        self.sibling  == o.sibling &&
+        self.distance == o.distance
+    end
+
+    def inspect # :nodoc:
+      "%p >> %p" % [subject, sibling]
+    end
+
+    def pretty_print q # :nodoc:
+      if distance then
+        q.group 1, "sibling(", ")" do
+          q.seplist [subject, sibling, distance] do |v|
+            q.pp v
+          end
+        end
+      else
+        q.group 1 do
+          q.pp subject
+          q.text " >> "
+          q.pp sibling
+        end
+      end
+    end
+
+    private
+
+    def index_matches pattern, o
+      indexes = []
+      return indexes unless o.kind_of? Sexp
+
+      o.each_with_index do |e, i|
+        data = {}
+        if pattern.kind_of?(Sexp) ? pattern.satisfy?(e) : pattern == o[i]
+          indexes << [i, data]
+        end
+      end
+
+      indexes
+    end
+  end # class Sibling
+
+  ##
+  # Wraps the results of a Sexp query. MatchCollection defines
+  # MatchCollection#/ so that you can chain queries.
+  #
+  # For instance:
+  #   res = s(:a, s(:b)) / s{ s(:a,_) } / s{ s(:b) }
+
+  class MatchCollection < Array
+    ##
+    # See Traverse#search
+
+    def / pattern
+      inject(self.class.new) { |result, match|
+        result.concat match / pattern
+      }
+    end
+
+    def inspect # :nodoc:
+      "MatchCollection.new(%s)" % self.to_a.inspect[1..-2]
+    end
+
+    alias :to_s :inspect # :nodoc:
+
+    def pretty_print q # :nodoc:
+      q.group 1, "MatchCollection.new(", ")" do
+        q.seplist(self) {|v| q.pp v }
+      end
+    end
+  end # class MatchCollection
 end
+
+require "strict_sexp" if ENV["STRICT_SEXP"].to_i > 0