xpath 0.1.4 → 1.0.0.beta1

data/README.rdoc

@@ -1,15 +1,21 @@
 = XPath
 
-XPath is a Ruby DSL around a subset of XPath 1.0. It's primary purpose is to
+XPath is a Ruby DSL around a subset of XPath 1.0. Its primary purpose is to
 facilitate writing complex XPath queries from Ruby code.
 
+{<img src="http://travis-ci.org/jnicklas/xpath.png" />}[http://travis-ci.org/jnicklas/xpath]
+
 == Generating expressions
 
-To create quick, one of expressions, XPath.generate can be used:
+To create quick, one-off expressions, +XPath.generate+ can be used:
 
     XPath.generate { |x| x.descendant(:ul)[x.attr(:id) == 'foo'] }
 
-However for more complex expressions, it is probably ore convenient to include
+You can also call expression methods directly on the XPath module:
+
+    XPath.descendant(:ul)[XPath.attr(:id) == 'foo'] }
+
+However for more complex expressions, it is probably more convenient to include
 the XPath module into your own class or module:
 
     module MyXPaths
@@ -25,12 +31,63 @@ the XPath module into your own class or module:
     end
 
 Both ways return an XPath::Expression instance, which can be further modified.
-To convert the expression to a string, just call #to_s on it.
+To convert the expression to a string, just call #to_s on it. All available
+expressions are defined in XPath::DSL.
+
+== String, Hashes and Symbols
+
+When you send a string as an argument to any XPath function, XPath assumes this
+to be a string literal. On the other hand if you send in Symbol, XPath assumes
+this to be an XPath literal. Thus the following two statements are not
+equivalent:
+
+    XPath.descendant(:p)[XPath.attr(:id) == 'foo']
+    XPath.descendant(:p)[XPath.attr(:id) == :foo]
+
+These are the XPath expressions that these would be translated to:
+
+    .//p[@id = 'foo']
+    .//p[@id = foo]
+
+The second expression would match any p tag whose id attribute matches a 'foo'
+tag it contains. Most likely this is not what you want.
+
+In fact anything other than a String is treated as a literal. Thus the
+following works as expected:
+
+    XPath.descendant(:p)[1]
+
+Keep in mind that XPath is 1-indexed and not 0-indexed like most other
+programming languages, including Ruby.
+
+Hashes are automatically converted to equality expressions, so the above
+example could be written as:
+
+    XPath.descendant(:p)[:@id => 'foo']
+
+Which would generate the same expression:
+
+    .//p[@id = 'foo']
+
+Note that the same rules apply here, both the keys and values in the hash are
+treated the same way as any other expression in XPath. Thus the following are
+not equivalent:
+
+    XPath.descendant(:p)[:@id => 'foo'] # => .//p[@id = 'foo']
+    XPath.descendant(:p)[:id => 'foo']  # => .//p[id = 'foo']
+    XPath.descendant(:p)['id' => 'foo'] # => .//p['id' = 'foo']
 
 == HTML
 
 XPath comes with a set of premade XPaths for use with HTML documents.
 
+You can generate these like this:
+
+    XPath::HTML.link('Home')
+    XPath::HTML.field('Name')
+
+See XPath::HTML for all available matchers.
+
 == License
 
 (The MIT License)

data/lib/xpath.rb

@@ -2,67 +2,16 @@ require 'nokogiri'
 
 module XPath
   autoload :Expression, 'xpath/expression'
+  autoload :Literal, 'xpath/literal'
   autoload :Union, 'xpath/union'
+  autoload :Renderer, 'xpath/renderer'
   autoload :HTML, 'xpath/html'
+  autoload :DSL, 'xpath/dsl'
 
-  extend self
+  extend XPath::DSL::TopLevel
+  include XPath::DSL::TopLevel
 
   def self.generate
-    yield(Expression::Self.new)
-  end
-
-  def current
-    Expression::Self.new
-  end
-
-  def name
-    Expression::Name.new(current)
-  end
-
-  def descendant(*expressions)
-    Expression::Descendant.new(current, expressions)
-  end
-
-  def child(*expressions)
-    Expression::Child.new(current, expressions)
-  end
-
-  def anywhere(expression)
-    Expression::Anywhere.new(expression)
-  end
-
-  def attr(expression)
-    Expression::Attribute.new(current, expression)
-  end
-
-  def contains(expression)
-    Expression::Contains.new(current, expression)
-  end
-
-  def text
-    Expression::Text.new(current)
-  end
-
-  def var(name)
-    Expression::Variable.new(name)
-  end
-
-  def string
-    Expression::StringFunction.new(current)
-  end
-
-  def tag(name)
-    Expression::Tag.new(name)
-  end
-
-  def css(selector)
-    paths = Nokogiri::CSS.xpath_for(selector).map do |selector|
-      Expression::CSS.new(current, Expression::Literal.new(selector))
-    end
-    Union.new(*paths)
-  end
-
-  def varstring(name)
-    var(name).string_literal
+    yield(self)
   end
 end

data/lib/xpath/dsl.rb

@@ -0,0 +1,104 @@
+module XPath
+  module DSL
+    module TopLevel
+      def current
+        Expression.new(:this_node)
+      end
+
+      def name
+        Expression.new(:node_name, current)
+      end
+
+      def descendant(*expressions)
+        Expression.new(:descendant, current, expressions)
+      end
+
+      def child(*expressions)
+        Expression.new(:child, current, expressions)
+      end
+
+      def axis(name, tag_name=:*)
+        Expression.new(:axis, current, name, tag_name)
+      end
+
+      def anywhere(expression)
+        Expression.new(:anywhere, expression)
+      end
+
+      def attr(expression)
+        Expression.new(:attribute, current, expression)
+      end
+
+      def contains(expression)
+        Expression.new(:contains, current, expression)
+      end
+
+      def starts_with(expression)
+        Expression.new(:starts_with, current, expression)
+      end
+
+      def text
+        Expression.new(:text, current)
+      end
+
+      def string
+        Expression.new(:string_function, current)
+      end
+
+      def css(selector)
+        Expression.new(:css, current, Literal.new(selector))
+      end
+    end
+
+    module ExpressionLevel
+      include XPath::DSL::TopLevel
+
+      def where(expression)
+        Expression.new(:where, current, expression)
+      end
+      alias_method :[], :where
+
+      def next_sibling(*expressions)
+        Expression.new(:next_sibling, current, expressions)
+      end
+
+      def one_of(*expressions)
+        Expression.new(:one_of, current, expressions)
+      end
+
+      def equals(expression)
+        Expression.new(:equality, current, expression)
+      end
+      alias_method :==, :equals
+
+      def or(expression)
+        Expression.new(:or, current, expression)
+      end
+      alias_method :|, :or
+
+      def and(expression)
+        Expression.new(:and, current, expression)
+      end
+      alias_method :&, :and
+
+      def union(*expressions)
+        Union.new(*[self, expressions].flatten)
+      end
+      alias_method :+, :union
+
+      def inverse
+        Expression.new(:inverse, current)
+      end
+      alias_method :~, :inverse
+
+      def string_literal
+        Expression.new(:string_literal, self)
+      end
+
+      def normalize
+        Expression.new(:normalized_space, current)
+      end
+      alias_method :n, :normalize
+    end
+  end
+end

data/lib/xpath/expression.rb

@@ -1,310 +1,20 @@
 module XPath
   class Expression
-    include XPath
+    attr_accessor :expression, :arguments
+    include XPath::DSL::ExpressionLevel
 
-    class Self < Expression
-      def to_xpath(predicate=nil)
-        '.'
-      end
-    end
-
-    class Unary < Expression
-      def initialize(expression)
-        @expression = wrap_xpath(expression)
-      end
-    end
-
-    class Binary < Expression
-      def initialize(left, right)
-        @left = wrap_xpath(left)
-        @right = wrap_xpath(right)
-      end
-    end
-
-    class Multiple < Expression
-      def initialize(left, expressions)
-        @left = wrap_xpath(left)
-        @expressions = expressions.map { |e| wrap_xpath(e) }
-      end
-    end
-
-    class Literal < Expression
-      def initialize(expression)
-        @expression = expression
-      end
-
-      def to_xpath(predicate=nil)
-        @expression.to_s
-      end
-    end
-
-    class Child < Multiple
-      def to_xpath(predicate=nil)
-        if @expressions.length == 1
-          "#{@left.to_xpath(predicate)}/#{@expressions.first.to_xpath(predicate)}"
-        elsif @expressions.length > 1
-          "#{@left.to_xpath(predicate)}/*[#{@expressions.map { |e| "self::#{e.to_xpath(predicate)}" }.join(" | ")}]"
-        else
-          "#{@left.to_xpath(predicate)}/*"
-        end
-      end
-    end
-
-    class Descendant < Multiple
-      def to_xpath(predicate=nil)
-        if @expressions.length == 1
-          "#{@left.to_xpath(predicate)}//#{@expressions.first.to_xpath(predicate)}"
-        elsif @expressions.length > 1
-          "#{@left.to_xpath(predicate)}//*[#{@expressions.map { |e| "self::#{e.to_xpath(predicate)}" }.join(" | ")}]"
-        else
-          "#{@left.to_xpath(predicate)}//*"
-        end
-      end
-    end
-
-    class NextSibling < Multiple
-      def to_xpath(predicate=nil)
-        if @expressions.length == 1
-          "#{@left.to_xpath(predicate)}/following-sibling::*[1]/self::#{@expressions.first.to_xpath(predicate)}"
-        elsif @expressions.length > 1
-          "#{@left.to_xpath(predicate)}/following-sibling::*[1]/self::*[#{@expressions.map { |e| "self::#{e.to_xpath(predicate)}" }.join(" | ")}]"
-        else
-          "#{@left.to_xpath(predicate)}/following-sibling::*[1]/self::*"
-        end
-      end
-    end
-
-    class Tag < Unary
-      def to_xpath(predicate=nil)
-        "self::#{@expression.to_xpath(predicate)}"
-      end
-    end
-
-    class Anywhere < Unary
-      def to_xpath(predicate=nil)
-        "//#{@expression.to_xpath(predicate)}"
-      end
-    end
-
-    class Name < Unary
-      def to_xpath(predicate=nil)
-        "name(#{@expression.to_xpath(predicate)})"
-      end
-    end
-
-    class Where < Binary
-      def to_xpath(predicate=nil)
-        "#{@left.to_xpath(predicate)}[#{@right.to_xpath(predicate)}]"
-      end
-    end
-
-    class Attribute < Binary
-      def to_xpath(predicate=nil)
-        if @right.is_a?(Literal)
-          "#{@left.to_xpath(predicate)}/@#{@right.to_xpath(predicate)}"
-        else
-          "#{@left.to_xpath(predicate)}/attribute::node()[name(.) = #{@right.to_xpath(predicate)}]"
-        end
-      end
-    end
-
-    class Equality < Binary
-      def to_xpath(predicate=nil)
-        "#{@left.to_xpath(predicate)} = #{@right.to_xpath(predicate)}"
-      end
-    end
-
-    class StringFunction < Unary
-      def to_xpath(predicate=nil)
-        "string(#{@expression.to_xpath(predicate)})"
-      end
-    end
-
-    class StringLiteral < Expression
-      def initialize(expression)
-        @expression = expression
-      end
-
-      def to_xpath(predicate=nil)
-        string = @expression
-        string = @expression.to_xpath(predicate) unless @expression.is_a?(String)
-        if string.include?("'")
-          string = string.split("'", -1).map do |substr|
-            "'#{substr}'"
-          end.join(%q{,"'",})
-          "concat(#{string})"
-        else
-          "'#{string}'"
-        end
-      end
-    end
-
-    class NormalizedSpace < Unary
-      def to_xpath(predicate=nil)
-        "normalize-space(#{@expression.to_xpath(predicate)})"
-      end
-    end
-
-    class And < Binary
-      def to_xpath(predicate=nil)
-        "(#{@left.to_xpath(predicate)} and #{@right.to_xpath(predicate)})"
-      end
-    end
-
-    class Or < Binary
-      def to_xpath(predicate=nil)
-        "(#{@left.to_xpath(predicate)} or #{@right.to_xpath(predicate)})"
-      end
-    end
-
-    class OneOf < Expression
-      def initialize(left, right)
-        @left = wrap_xpath(left)
-        @right = right.map { |r| wrap_xpath(r) }
-      end
-
-      def to_xpath(predicate=nil)
-        @right.map { |r| "#{@left.to_xpath(predicate)} = #{r.to_xpath(predicate)}" }.join(' or ')
-      end
-    end
-
-    class Contains < Binary
-      def to_xpath(predicate=nil)
-        "contains(#{@left.to_xpath(predicate)}, #{@right.to_xpath(predicate)})"
-      end
-    end
-
-    class Is < Binary
-      def to_xpath(predicate=nil)
-        if predicate == :exact
-          Equality.new(@left, @right).to_xpath(predicate)
-        else
-          Contains.new(@left, @right).to_xpath(predicate)
-        end
-      end
-    end
-
-    class Text < Unary
-      def to_xpath(predicate=nil)
-        "#{@expression.to_xpath(predicate)}/text()"
-      end
-    end
-
-    class Variable < Expression
-      def initialize(name)
-        @name = name
-      end
-
-      def to_xpath(predicate=nil)
-        "%{#{@name}}"
-      end
-    end
-
-    class Inverse < Unary
-      def to_xpath(predicate=nil)
-        "not(#{@expression.to_xpath(predicate)})"
-      end
-    end
-
-    class Applied < Expression
-      def initialize(expression, variables={})
-        @variables = variables
-        @expression = expression
-      end
-
-      def to_xpath(predicate=nil)
-        @expression.to_xpath(predicate) % @variables
-      rescue ArgumentError # for ruby < 1.9 compat
-        @expression.to_xpath(predicate).gsub(/%\{(\w+)\}/) do |_|
-          @variables[$1.to_sym] or raise(ArgumentError, "expected variable #{$1} to be set")
-        end
-      end
-    end
-
-    class CSS < Binary
-      def to_xpath(predicate=nil)
-        "#{@left.to_xpath}#{@right.to_xpath}"
-      end
+    def initialize(expression, *arguments)
+      @expression = expression
+      @arguments = arguments
     end
 
     def current
       self
     end
 
-    def next_sibling(*expressions)
-      Expression::NextSibling.new(current, expressions)
-    end
-
-    def where(expression)
-      Expression::Where.new(current, expression)
-    end
-    alias_method :[], :where
-
-    def one_of(*expressions)
-      Expression::OneOf.new(current, expressions)
-    end
-
-    def equals(expression)
-      Expression::Equality.new(current, expression)
-    end
-    alias_method :==, :equals
-
-    def is(expression)
-      Expression::Is.new(current, expression)
-    end
-
-    def or(expression)
-      Expression::Or.new(current, expression)
-    end
-    alias_method :|, :or
-
-    def and(expression)
-      Expression::And.new(current, expression)
-    end
-    alias_method :&, :and
-
-    def union(*expressions)
-      Union.new(*[self, expressions].flatten)
-    end
-    alias_method :+, :union
-
-    def inverse
-      Expression::Inverse.new(current)
-    end
-    alias_method :~, :inverse
-
-    def string_literal
-      Expression::StringLiteral.new(self)
-    end
-
-    def to_xpath(predicate=nil)
-      raise NotImplementedError, "please implement in subclass"
-    end
-
-    def to_s
-      to_xpaths.join(' | ')
-    end
-
-    def to_xpaths
-      [to_xpath(:exact), to_xpath(:fuzzy)].uniq
-    end
-
-    def apply(variables={})
-      Expression::Applied.new(current, variables)
-    end
-
-    def normalize
-      Expression::NormalizedSpace.new(current)
-    end
-    alias_method :n, :normalize
-
-    def wrap_xpath(expression)
-      case expression
-        when ::String then Expression::StringLiteral.new(expression)
-        when ::Symbol then Expression::Literal.new(expression)
-        else expression
-      end
+    def to_xpath
+      Renderer.render(self)
     end
+    alias_method :to_s, :to_xpath
   end
 end
-