sexp_path 0.4.0

data/lib/sexp_path/matcher/atom.rb

@@ -0,0 +1,14 @@
+# See SexpQueryBuilder.atom
+class SexpPath::Matcher::Atom < SexpPath::Matcher::Base
+  # Satisfied when +o+ is an atom (anything that is not an S-Expression)
+  def satisfy?(o, data={})
+    return nil if o.is_a? Sexp
+  
+    capture_match o, data
+  end
+  
+  # Prints as +atom+
+  def inspect
+    "atom"
+  end
+end

data/lib/sexp_path/matcher/base.rb

@@ -0,0 +1,54 @@
+# This is the base class for all Sexp matchers.
+#
+# A matcher should implement the following methods:
+#
+# * satisfy?
+# * inspect
+#
+# +satisfy?+ determines whether the matcher matches a given input,
+# and +inspect+ will print the matcher nicely in a user's console.
+#
+# The base matcher is created with the SexpQueryBuilder as follows
+#   Q?{ s() }
+class SexpPath::Matcher::Base < Sexp
+  # Combines the Matcher with another Matcher, the resulting one will
+  # be satisfied if either Matcher would be satisfied.
+  # 
+  # Example:
+  #   s(:a) | s(:b) 
+  def | o
+    SexpPath::Matcher::Any.new(self, o)
+  end
+  
+  # Combines the Matcher with another Matcher, the resulting one will
+  # be satisfied only if both Matchers would be satisfied.
+  # 
+  # Example:
+  #   t(:a) & include(:b)
+  def & o
+    SexpPath::Matcher::All.new(self, o)
+  end
+  
+  # Returns a Matcher that matches whenever this Matcher would not have matched
+  # 
+  # Example:
+  #   -s(:a)
+  def -@
+    SexpPath::Matcher::Not.new(self)
+  end
+  
+  # Returns a Matcher that matches if this has a sibling +o+
+  # 
+  # Example:
+  #   s(:a) >> s(:b)
+  def >> o
+    SexpPath::Matcher::Sibling.new(self, o)
+  end
+  
+  # Formats the matcher as:
+  #   q(:a, :b)
+  def inspect
+    children = map{|e| e.inspect}.join(', ')
+    "q(#{children})"
+  end
+end

data/lib/sexp_path/matcher/block.rb

@@ -0,0 +1,16 @@
+class SexpPath::Matcher::Block < SexpPath::Matcher::Base
+  attr_reader :exp
+  def initialize &block
+    @exp = block
+  end
+
+  def satisfy?(o, data={})
+    return nil unless @exp[o]
+  
+    capture_match o, data
+  end
+
+  def inspect
+    "<custom>"
+  end
+end

data/lib/sexp_path/matcher/child.rb

@@ -0,0 +1,24 @@
+# See SexpQueryBuilder.child
+class SexpPath::Matcher::Child < SexpPath::Matcher::Base
+  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, data={})
+    if child.satisfy?(o,data)
+      capture_match o, data
+    elsif o.is_a? Sexp
+      o.search_each(child,data) do 
+        return capture_match(o, data)
+      end
+    end
+  end
+
+  def inspect
+    "child(#{child.inspect})"
+  end
+end

data/lib/sexp_path/matcher/include.rb

@@ -0,0 +1,22 @@
+# See SexpQueryBuilder.include
+class SexpPath::Matcher::Include < SexpPath::Matcher::Base
+  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, data={})
+    if o.is_a? Sexp
+      return nil unless o.any?{|c| value.is_a?(Sexp) ? value.satisfy?(c, data) : value == c}
+    end
+  
+    capture_match o, data
+  end
+
+  def inspect
+    "include(#{value.inspect})"
+  end
+end

data/lib/sexp_path/matcher/not.rb

@@ -0,0 +1,20 @@
+# See SexpQueryBuilder.not
+class SexpPath::Matcher::Not < SexpPath::Matcher::Base
+  attr_reader :value
+  
+  # Creates a Matcher which will match any Sexp that does not match the +value+
+  def initialize(value)
+    @value = value
+  end
+  
+  # Satisfied if a +o+ does not match the +value+
+  def satisfy?(o, data={})
+    return nil if value.is_a?(Sexp) ? value.satisfy?(o, data) : value == o
+
+    capture_match o, {}
+  end
+
+  def inspect
+    "is_not(#{value.inspect})"
+  end
+end

data/lib/sexp_path/matcher/pattern.rb

@@ -0,0 +1,20 @@
+# See SexpQueryBuilder.m
+class SexpPath::Matcher::Pattern < SexpPath::Matcher::Base
+  attr_reader :pattern
+  
+  # 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, data={})
+    return nil unless !o.is_a?(Sexp) && o.to_s =~ pattern
+
+    capture_match o, data
+  end
+
+  def inspect
+    "m(#{pattern.inspect})"
+  end
+end

data/lib/sexp_path/matcher/sibling.rb

@@ -0,0 +1,54 @@
+# See SexpPath::Matcher::Base for sibling relations: <,<<,>>,>
+#
+class SexpPath::Matcher::Sibling < SexpPath::Matcher::Base
+  attr_reader :subject, :sibling, :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, data={})
+    # 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.each do |i1, data_1|
+      sibling_matches.each do |i2, data_2|
+        if (distance ? (i2-i1 == distance) : i2 > i1)
+          data = data.merge(data_1).merge(data_2)
+          return capture_match(o, data)
+        end
+      end
+    end
+    
+    nil
+  end
+  
+  def inspect
+    "#{subject.inspect} >> #{sibling.inspect}"
+  end
+  
+  private  
+  def index_matches(pattern, o)
+    indexes = []
+    return indexes unless o.is_a? Sexp
+    
+    o.each_with_index do |e,i|
+      data = {}
+      if pattern.is_a?(Sexp) ? pattern.satisfy?(o[i],data) : pattern == o[i]
+        indexes << [i, data]
+      end
+    end
+    
+    indexes
+  end
+end

data/lib/sexp_path/matcher/type.rb

@@ -0,0 +1,21 @@
+# See SexpQueryBuilder.t
+class SexpPath::Matcher::Type < SexpPath::Matcher::Base
+  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
+
+  # Satisfied if the sexp_type of +o+ is +type+.
+  def satisfy?(o, data={})
+    return nil unless o.is_a?(Sexp) && o.sexp_type == sexp_type
+  
+    capture_match o, data
+  end
+
+  def inspect
+    "t(#{sexp_type.inspect})"
+  end
+end

data/lib/sexp_path/matcher/wild.rb

@@ -0,0 +1,12 @@
+# See SexpQueryBuilder.wild and SexpQueryBuilder._
+class SexpPath::Matcher::Wild < SexpPath::Matcher::Base
+  
+  # Matches any single element.
+  def satisfy?(o, data={})
+    capture_match o, data
+  end
+
+  def inspect
+    "wild"
+  end
+end

data/lib/sexp_path/sexp_collection.rb

@@ -0,0 +1,16 @@
+module SexpPath
+  # Wraps the results of a SexpPath query.
+  # SexpCollection defines SexpCollection#search so that you can
+  # chain queries.
+  # 
+  # For instance:
+  #   res = s(:a, s(:b)) / Q?{ s(:a,_) } / Q?{ s(:b) }
+  #
+  class SexpCollection < Array
+    # See Traverse#search
+    def search(pattern)
+      inject(SexpCollection.new){|collection, match| collection.concat match.sexp.search(pattern, match) }
+    end
+    alias_method :/, :search
+  end
+end

data/lib/sexp_path/sexp_query_builder.rb

@@ -0,0 +1,137 @@
+module SexpPath
+  
+  # The SexpQueryBuilder is the simplest way to build SexpPath queries.
+  # 
+  # Typically, one access the SexpQueryBuilder through the helper method
+  # Q? which accepts a block, and will return a SexpPath matcher.
+  #
+  # For example here is a SexpPath query that looks for s(:a):
+  #
+  #   query = Q?{ s(:a) }
+  # 
+  # A more interesting query might look for classes with names starting
+  # in Test:
+  #
+  #   query = Q?{ s(:class, m(/^Test\w+/ % 'name', _, _)) }
+  #
+  # This makes use of a SexpPath::Matcher::Pattern, two SexpPath::Matcher::Wild
+  # matchers and SexpPath::Traverse#capture_as for capturing the name to a 
+  # variable 'name'.
+  #
+  # For more examples, see the various SexpQueryBuilder class methods, the
+  # examples, and the tests supplied with SexpPath.
+  #
+  class SexpQueryBuilder    
+    class << self
+      
+      # This is the longhand method for create a SexpPath query, normally
+      # one would use Q?{ ... }, however it is also possible to do:
+      # 
+      #   SexpPath::SexpQueryBuilder.do{ s() }
+      #
+      def do(&block)
+        instance_eval(&block)
+      end
+      
+      # Matches an S-Expression.
+      #
+      # example
+      #   s(:a) / Q?{ s(:a) }       #=> [s(:a)]
+      #   s(:a) / Q?{ s() }         #=> []
+      #   s(:a, s(:b) / Q?{ s(:b) } #=> [s(:b)]
+      #
+      def s(*args)
+        SexpPath::Matcher::Base.new(*args)
+      end
+      
+      # Matches anything.
+      #
+      # example:
+      #   s(:a) / Q?{ _ }        #=> [s(:a)]
+      #   s(:a, s(s(:b))) / Q?{ s(_) } #=> [s(s(:b))]
+      #
+      # Can also be called with +wild+
+      #   s(:a) / Q?{ wild }     #=> [s(:a)]
+      #
+      def wild()
+        SexpPath::Matcher::Wild.new
+      end
+      alias_method :_, :wild
+    
+      def include(child)
+        SexpPath::Matcher::Include.new(child)
+      end
+      
+      # Matches any atom.
+      #
+      # example:
+      #   s(:a) / Q?{ s(atom) }        #=> [s(:a)]
+      #   s(:a, s(:b)) / Q?{ s(atom) } #=> [s(:b)]
+      #
+      def atom
+        SexpPath::Matcher::Atom.new
+      end
+    
+      # Matches when any sub expression match
+      # 
+      # example:
+      #   s(:a) / Q?{ any(s(:a), s(:b)) } #=> [s(:a)]
+      #   s(:a) / Q?{ any(s(:b), s(:c)) } #=> []
+      #
+      def any(*args)
+        SexpPath::Matcher::Any.new(*args)
+      end
+      
+      # Matches when all sub expression match
+      #
+      # example:
+      #   s(:a) / Q?{ all(s(:a), s(:b)) } #=> []
+      #   s(:a,:b) / Q?{ t(:a), include(:b)) } #=> [s(:a,:b)]
+      #
+      def all(*args)
+        SexpPath::Matcher::All.new(*args)
+      end
+      
+      # Matches when sub expression does not match, see SexpPath::Matcher::Base#-@
+      #
+      # example:
+      #   s(:a) / Q?{ is_not(s(:b)) } #=> [s(:a)]
+      #   s(:a) / Q?{ s(is_not :a) } #=> []
+      #
+      def is_not(arg)
+        SexpPath::Matcher::Not.new(arg)
+      end
+      
+      # Matches anything that has a child matching the sub expression
+      # 
+      # example:
+      #   s(s(s(s(s(:a))))) / Q?{ child(s(:a)) } #=> [s(s(s(s(s(:a)))))]
+      #
+      def child(child)
+        SexpPath::Matcher::Child.new(child)
+      end
+      
+      # Matches anything having the same sexp_type, which is the first value in a Sexp.
+      # 
+      # example:
+      #   s(:a, :b) / Q?{ t(:a) } #=> [s(:a, :b)]
+      #   s(:a, :b) / Q?{ t(:b) } #=> []
+      #   s(:a, s(:b, :c)) / Q?{ t(:b) } #=> [s(:b, :c)]
+      def t(name)
+        SexpPath::Matcher::Type.new(name)
+      end
+      
+      # Matches any atom who's string representation matches the patterns passed in.
+      # 
+      # example:
+      #   s(:a) / Q?{ m('a') } #=> [s(:a)]
+      #   s(:a) / Q?{ m(/\w/,/\d/) } #=> [s(:a)]
+      #   s(:tests, s(s(:test_a), s(:test_b))) / Q?{ m(/test_\w/) } #=> [s(:test_a), s(:test_b)]
+      def m(* patterns)
+        patterns = patterns.map{|p| p.is_a?(Regexp) ? p : Regexp.new("\\A"+Regexp.escape(p.to_s)+"\\Z")}
+        regexp = Regexp.union(*patterns)
+        SexpPath::Matcher::Pattern.new(regexp)
+      end
+    end
+  end
+end

data/lib/sexp_path/sexp_result.rb

@@ -0,0 +1,21 @@
+module SexpPath
+  
+  # Wraps the results of a SexpPath query.  The matching Sexp
+  # is placed in SexpResult#sexp.  Any named captures will be
+  # available with SexpResult#[].
+  #
+  # For instance:
+  #   res = s(:a) / Q?{ s( _ % 'name') }
+  #
+  #   res.first.sexp == s(:a) 
+  #   res.first['name'] == :a
+  #
+  class SexpResult < Hash
+    attr_accessor :sexp # Matched Sexp
+    
+    def initialize(sexp, data={})
+      @sexp = sexp
+      merge! data
+    end
+  end
+end