wgibbs-xpath 0.1.4

data/README.rdoc

@@ -0,0 +1,56 @@
+= XPath
+
+XPath is a Ruby DSL around a subset of XPath 1.0. It's primary purpose is to
+facilitate writing complex XPath queries from Ruby code.
+
+== Generating expressions
+
+To create quick, one of 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
+the XPath module into your own class or module:
+
+    module MyXPaths
+      include XPath
+
+      def foo_ul
+        descendant(:ul)[attr(:id) == 'foo']
+      end
+
+      def password_field(id)
+        descendant(:input)[attr(:type) == 'password'][attr(:id) == id]
+      end
+    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.
+
+== HTML
+
+XPath comes with a set of premade XPaths for use with HTML documents.
+
+== License
+
+(The MIT License)
+
+Copyright © 2010 Jonas Nicklas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the ‘Software’), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED ‘AS IS’, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/lib/xpath.rb

@@ -0,0 +1,68 @@
+require 'nokogiri'
+
+module XPath
+  autoload :Expression, 'xpath/expression'
+  autoload :Union, 'xpath/union'
+  autoload :HTML, 'xpath/html'
+
+  extend self
+
+  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
+  end
+end

data/lib/xpath/expression.rb

@@ -0,0 +1,310 @@
+module XPath
+  class Expression
+    include XPath
+
+    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
+    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
+    end
+  end
+end
+

data/lib/xpath/html.rb

@@ -0,0 +1,114 @@
+module XPath
+  module HTML
+    include XPath
+    extend self
+
+    def link(locator, options={})
+      href = options[:href]
+      link = descendant(:a)[href ? attr(:href).equals(href) : attr(:href)]
+      link[attr(:id).equals(locator) | string.n.is(locator) | attr(:title).is(locator) | descendant(:img)[attr(:alt).is(locator)]]
+    end
+
+    def content(locator)
+      child(:"descendant-or-self::*")[current.n.contains(locator)]
+    end
+
+    def button(locator)
+      button = descendant(:input)[attr(:type).one_of('submit', 'image', 'button')][attr(:id).equals(locator) | attr(:value).is(locator)]
+      button += descendant(:button)[attr(:id).equals(locator) | attr(:value).is(locator) | string.n.is(locator)]
+      button += descendant(:input)[attr(:type).equals('image')][attr(:alt).is(locator)]
+    end
+
+    def link_or_button(locator)
+      link(locator) + button(locator)
+    end
+
+    def fieldset(locator)
+      descendant(:fieldset)[attr(:id).equals(locator) | descendant(:legend)[string.n.is(locator)]]
+    end
+
+    def field(locator, options={})
+      xpath = descendant(:input, :textarea, :select)[~attr(:type).one_of('submit', 'image', 'hidden')]
+      xpath = locate_field(xpath, locator)
+      xpath = xpath[attr(:checked)] if options[:checked]
+      xpath = xpath[~attr(:checked)] if options[:unchecked]
+      xpath = xpath[field_value(options[:with])] if options.has_key?(:with)
+      xpath
+    end
+
+    def fillable_field(locator, options={})
+      xpath = descendant(:input, :textarea)[~attr(:type).one_of('submit', 'image', 'radio', 'checkbox', 'hidden', 'file')]
+      xpath = locate_field(xpath, locator)
+      xpath = xpath[field_value(options[:with])] if options.has_key?(:with)
+      xpath
+    end
+
+    def select(locator, options={})
+      xpath = locate_field(descendant(:select), locator)
+
+      options[:options].each do |option|
+        xpath = xpath[descendant(:option).equals(option)]
+      end if options[:options]
+
+      [options[:selected]].flatten.each do |option|
+        xpath = xpath[descendant(:option)[attr(:selected)].equals(option)]
+      end if options[:selected]
+
+      xpath
+    end
+
+    def checkbox(locator, options={})
+      xpath = locate_field(descendant(:input)[attr(:type).equals('checkbox')], locator)
+    end
+
+    def radio_button(locator, options={})
+      locate_field(descendant(:input)[attr(:type).equals('radio')], locator)
+    end
+
+    def file_field(locator, options={})
+      locate_field(descendant(:input)[attr(:type).equals('file')], locator)
+    end
+
+    def optgroup(name)
+      descendant(:optgroup)[attr(:label).is(name)]
+    end
+
+    def option(name)
+      descendant(:option)[string.n.is(name)]
+    end
+
+    def table(locator, options={})
+      xpath = descendant(:table)[attr(:id).equals(locator) | descendant(:caption).contains(locator)]
+      xpath = xpath[table_rows(options[:rows])] if options[:rows]
+      xpath
+    end
+
+    def table_rows(rows)
+      row_conditions = descendant(:tr)[table_row(rows.first)]
+      rows.drop(1).each do |row|
+        row_conditions = row_conditions.next_sibling(:tr)[table_row(row)]
+      end
+      row_conditions
+    end
+
+    def table_row(cells)
+      cell_conditions = child(:td, :th)[string.n.equals(cells.first)]
+      cells.drop(1).each do |cell|
+        cell_conditions = cell_conditions.next_sibling(:td, :th)[string.n.equals(cell)]
+      end
+      cell_conditions
+    end
+
+  protected
+
+    def locate_field(xpath, locator)
+      locate_field = xpath[attr(:id).equals(locator) | attr(:name).equals(locator) | attr(:id).equals(anywhere(:label)[string.n.is(locator)].attr(:for)) | attr(:placeholder).equals(locator)]
+      locate_field += descendant(:label)[string.n.is(locator)].descendant(xpath)
+    end
+
+    def field_value(value)
+      (string.n.is(value) & tag(:textarea)) | (attr(:value).equals(value) & ~tag(:textarea))
+    end
+
+  end
+end