xpath 0.1.0

data/README.rdoc

@@ -0,0 +1,29 @@
+= 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.

data/lib/xpath.rb

@@ -0,0 +1,51 @@
+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 varstring(name)
+    var(name).string_literal
+  end
+end

data/lib/xpath/expression.rb

@@ -0,0 +1,298 @@
+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) }
+        if @expressions.empty?
+          raise ArgumentError, "must specify at least one expression"
+        end
+      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)}"
+        else
+          "#{@left.to_xpath(predicate)}/*[#{@expressions.map { |e| "self::#{e.to_xpath(predicate)}" }.join(" | ")}]"
+        end
+      end
+    end
+
+    class Descendant < Multiple
+      def to_xpath(predicate=nil)
+        if @expressions.length == 1
+          "#{@left.to_xpath(predicate)}//#{@expressions.first.to_xpath(predicate)}"
+        else
+          "#{@left.to_xpath(predicate)}//*[#{@expressions.map { |e| "self::#{e.to_xpath(predicate)}" }.join(" | ")}]"
+        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)}"
+        else
+          "#{@left.to_xpath(predicate)}/following-sibling::*[1]/self::*[#{@expressions.map { |e| "self::#{e.to_xpath(predicate)}" }.join(" | ")}]"
+        end
+      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)
+        @expression = @expression.to_xpath(predicate) unless @expression.is_a?(String)
+        if @expression.include?("'")
+          @expression = @expression.split("'", -1).map do |substr|
+            "'#{substr}'"
+          end.join(%q{,"'",})
+          "concat(#{@expression})"
+        else
+          "'#{@expression}'"
+        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
+
+    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 string
+      Expression::StringFunction.new(current)
+    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,124 @@
+module XPath
+  module HTML
+    include XPath
+    extend self
+
+    def from_css(css)
+      XPath::Union.new(*Nokogiri::CSS.xpath_for(css).map { |selector| ::XPath::Expression::Literal.new(:".#{selector}") }.flatten)
+    end
+
+    def link(locator)
+      link = descendant(:a)[attr(:href)]
+      link[attr(:id).equals(locator) | text.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) | text.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)[text.is(locator)]]
+    end
+
+    def field(locator, options={})
+      if options[:with]
+        fillable_field(locator, options)
+      else
+        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
+      end
+    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).text.equals(option)]
+      end if options[:options]
+
+      [options[:selected]].flatten.each do |option|
+        xpath = xpath[descendant(:option)[attr(:selected)].text.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 option(name)
+      descendant(:option)[text.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)[text.equals(cells.first)] 
+      cells.drop(1).each do |cell|
+        cell_conditions = cell_conditions.next_sibling(:td, :th)[text.equals(cell)]
+      end
+      cell_conditions
+    end
+
+    def wrap(path)
+      if path.respond_to?(:to_xpaths)
+        path.to_xpaths
+      else
+        [path.to_s].flatten
+      end
+    end
+
+  protected
+
+    def locate_field(xpath, locator)
+      locate_field = xpath[attr(:id).equals(locator) | attr(:name).equals(locator) | attr(:id).equals(anywhere(:label)[text.is(locator)].attr(:for))]
+      locate_field += descendant(:label)[text.is(locator)].descendant(xpath)
+    end
+
+    def field_value(value)
+      (text.is(value) & name.equals('textarea')) | (attr(:value).equals(value) & ~name.equals('textarea'))
+    end
+
+  end
+end

data/lib/xpath/union.rb

@@ -0,0 +1,27 @@
+module XPath
+  class Union
+    include Enumerable
+
+    attr_reader :expressions
+
+    def initialize(*expressions)
+      @expressions = expressions
+    end
+
+    def each(&block)
+      expressions.each(&block)
+    end
+
+    def to_xpath(predicate=nil)
+      expressions.map { |e| e.to_xpath(predicate) }.join(' | ')
+    end
+
+    def to_xpaths
+      [to_xpath(:exact), to_xpath(:fuzzy)].uniq
+    end
+
+    def method_missing(*args)
+      XPath::Union.new(*expressions.map { |e| e.send(*args) })
+    end
+  end
+end

data/lib/xpath/version.rb

@@ -0,0 +1,3 @@
+module XPath
+  VERSION = '0.1.0'
+end

data/spec/fixtures/form.html

@@ -0,0 +1,245 @@
+<h1>Form</h1>
+
+<form action="/form" method="post">
+
+  <p>
+    <label for="form_title">Title</label>
+    <select name="form[title]" id="form_title">
+      <option>Mrs</option>
+      <option>Mr</option>
+      <option>Miss</option>
+    </select>
+  </p>
+
+
+  <p>
+    <label for="form_other_title">Other title</label>
+    <select name="form[other_title]" id="form_other_title">
+      <option>Mrs</option>
+      <option>Mr</option>
+      <option>Miss</option>
+    </select>
+  </p>
+
+  <p>
+    <label for="form_first_name">
+      First Name
+      <input type="text" name="form[first_name]" value="John" id="form_first_name"/>
+    </label>
+  </p>
+
+  <p>
+    <label for="form_last_name">Last Name</label>
+    <input type="text" name="form[last_name]" value="Smith" id="form_last_name"/>
+  </p>
+  
+  <p>
+    <label for="form_name_explanation">Explanation of Name</label>
+    <textarea name="form[name_explanation]" id="form_name_explanation"></textarea>
+  </p>
+
+  <p>
+    <label for="form_name">Name</label>
+    <input type="text" name="form[name]" value="John Smith" id="form_name"/>
+  </p>
+
+  <p>
+    <label for="form_schmooo">Schmooo</label>
+    <input type="schmooo" name="form[schmooo]" value="This is Schmooo!" id="form_schmooo"/>
+  </p>
+  
+  <p>
+    <label>Street<br/>
+      <input type="text" name="form[street]" value="Sesame street 66"/>
+    </label>
+  </p>
+
+  <p>
+    <label for="form_phone">Phone</label>
+    <input name="form[phone]" value="+1 555 7021" id="form_phone"/>
+  </p>
+
+  <p>
+    <label for="form_password">Password</label>
+    <input type="password" name="form[password]" value="seeekrit" id="form_password"/>
+  </p>
+
+  <p>
+    <label for="form_terms_of_use">Terms of Use</label>
+    <input type="hidden" name="form[terms_of_use]" value="0" id="form_terms_of_use_default">
+    <input type="checkbox" name="form[terms_of_use]" value="1" id="form_terms_of_use">
+  </p>
+
+  <p>
+    <label for="form_image">Image</label>
+    <input type="file" name="form[image]" id="form_image"/>
+  </p>
+  
+  <p>
+    <input type="hidden" name="form[token]" value="12345" id="form_token"/>
+  </p>
+
+  <p>
+    <label for="form_locale">Locale</label>
+    <select name="form[locale]" id="form_locale">
+      <option value="sv">Swedish</option>
+      <option selected="selected" value="en">English</option>
+      <option value="fi">Finish</option>
+      <option value="no">Norwegian</option>
+      <option value="jo">John's made-up language</option>
+      <option value="jbo"> Lojban </option>
+    </select>
+  </p>
+
+  <p>
+    <label for="form_region">Region</label>
+    <select name="form[region]" id="form_region">
+      <option>Sweden</option>
+      <option selected="selected">Norway</option>
+      <option>Finland</option>
+    </select>
+  </p>
+
+  <p>
+    <label for="form_city">City</label>
+    <select name="form[city]" id="form_city">
+      <option>London</option>
+      <option>Stockholm</option>
+      <option>Paris</option>
+    </select>
+  </p>
+
+  <p>
+    <label for="form_tendency">Tendency</label>
+    <select name="form[tendency]" id="form_tendency"></select>
+  </p>
+
+  <p>
+    <label for="form_description">Description</label></br>
+    <textarea name="form[description]" id="form_description">Descriptive text goes here</textarea>
+  <p>
+
+  <p>
+    <input type="radio" name="form[gender]" value="male" id="gender_male"/>
+    <label for="gender_male">Male</label>
+    <input type="radio" name="form[gender]" value="female" id="gender_female" checked="checked"/>
+    <label for="gender_female">Female</label>
+    <input type="radio" name="form[gender]" value="both" id="gender_both"/>
+    <label for="gender_both">Both</label>
+  </p>
+
+  <p>
+    <input type="checkbox" value="dog" name="form[pets][]" id="form_pets_dog" checked="checked"/>
+    <label for="form_pets_dog">Dog</label>
+    <input type="checkbox" value="cat" name="form[pets][]" id="form_pets_cat"/>
+    <label for="form_pets_cat">Cat</label>
+    <input type="checkbox" value="hamster" name="form[pets][]" id="form_pets_hamster" checked="checked"/>
+    <label for="form_pets_hamster">Hamster</label>
+  </p>
+
+  <p>
+    <label for="form_languages">Languages</label>
+    <select name="form[languages][]" id="form_languages" multiple="multiple">
+      <option>Ruby</option>
+      <option>SQL</option>
+      <option>HTML</option>
+      <option>Javascript</option>
+    </select>
+  </p>
+
+  <p>
+    <label for="form_underwear">Underwear</label>
+    <select name="form[underwear][]" id="form_underwear" multiple="multiple">
+      <option selected="selected">Boxer Briefs</option>
+      <option>Boxers</option>
+      <option selected="selected">Briefs</option>
+      <option selected="selected">Commando</option>
+      <option selected="selected">Frenchman's Pantalons</option>
+    </select>
+  </p>
+
+  <div style="display:none;">
+    <label for="form_first_name_hidden">
+      Super Secret
+      <input type="text" name="form[super_secret]" value="test123" id="form_super_secret"/>
+    </label>
+  </div>
+
+  <p>
+    <input type="button" name="form[fresh]" id="fresh_btn" value="i am fresh"/>
+    <input type="submit" name="form[awesome]" id="awe123" value="awesome"/>
+    <input type="submit" name="form[crappy]" id="crap321" value="crappy"/>
+    <input type="image" name="form[okay]" id="okay556" value="okay" alt="oh hai thar"/>
+    <button type="submit" id="click_me_123" value="click_me">Click me!</button>
+    <button type="submit" name="form[no_value]">No Value!</button>
+  </p>
+</form>
+
+<form id="get-form" action="/form/get?foo=bar" method="get">
+  <p>
+    <label for="form_middle_name">Middle Name</label>
+    <input type="text" name="form[middle_name]" value="Darren" id="form_middle_name"/>
+  </p>
+
+  <p>
+    <input type="submit" name="form[mediocre]" id="mediocre" value="med"/>
+  <p>
+</form>
+
+<form action="/upload" method="post" enctype="multipart/form-data">
+  <p>
+    <label for="form_file_name">File Name</label>
+    <input type="file" name="form[file_name]" id="form_file_name"/>
+  </p>
+
+  <p>
+    <label for="form_document">Document</label>
+    <input type="file" name="form[document]" id="form_document"/>
+  </p>
+ 
+  <p>
+    <input type="submit" value="Upload"/>
+  <p>
+</form>
+
+<form action="/redirect" method="post">
+  <p>
+    <input type="submit" value="Go FAR"/>
+  </p>
+</form>
+
+<form action="/form" method="post">
+  <p>
+    <label for="html5_email">Html5 Email</label>
+    <input type="email" name="form[html5_email]" value="person@email.com" id="html5_email"/>
+  </p>
+  <p>
+    <label for="html5_url">Html5 Url</label>
+    <input type="url" name="form[html5_url]" value="http://www.example.com" id="html5_url"/>
+  </p>
+  <p>
+    <label for="html5_search">Html5 Search</label>
+    <input type="search" name="form[html5_search]" value="what are you looking for" id="html5_search"/>
+  </p>
+  <p>
+    <label for="html5_tel">Html5 Tel</label>
+    <input type="tel" name="form[html5_tel]" value="911" id="html5_tel"/>
+  </p>
+  <p>
+    <label for="html5_color">Html5 Color</label>
+    <input type="color" name="form[html5_color]" value="#FFF" id="html5_color"/>
+  </p>
+  
+  <p>
+    <input type="submit" name="form[html5_submit]" value="html5_submit"/>
+  </p>
+</form>
+
+<form action="/form" method="post">
+  <p>
+    <button type="submit" name="form[button]" value="button_first">Just an input that came first</button>
+    <button type="submit" name="form[button]" value="button_second">Just an input</button>
+    <input type="submit" name="form[button]" value="Just a button that came first"/>
+    <input type="submit" name="form[button]" value="Just a button"/>
+  </p>
+</form>

data/spec/fixtures/simple.html

@@ -0,0 +1,26 @@
+<div id="bar" title="barDiv">
+
+</div>
+
+<div title="noId"></div>
+
+<div id="foo" title="fooDiv" data="id">
+  <p id="fooDiv">Blah</p>
+  <p>Bax</p>
+  <p title="monkey">Bax</p>
+  <ul><li>A list</li></ul>
+</div>
+
+<div id="baz" title="bazDiv"></div>
+
+<div id="preference">
+  <p id="is-fuzzy">allamas</p>
+  <p id="is-exact">llama</p>
+</div>
+
+<p id="whitespace">
+A     lot
+
+  of
+      whitespace
+</p>

data/spec/fixtures/stuff.html

@@ -0,0 +1,43 @@
+<h1>This is a test</h1>
+
+<p id="first">
+  Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
+  tempor incididunt ut <a href="/with_simple_html" title="awesome title" class="simple">labore</a>
+  et dolore magna aliqua. Ut enim ad minim veniam,
+  quis nostrud exercitation <a href="/foo" id="foo">ullamco</a> laboris nisi
+  ut aliquip ex ea commodo consequat.
+  <a href="/with_simple_html"><img src="http://www.foobar.sun/dummy_image.jpg" width="20" height="20" alt="awesome image" /></a>
+</p>
+
+<p id="second">
+  Duis aute irure dolor in reprehenderit in voluptate velit esse cillum
+  dolore eu fugiat <a href="/redirect" id="red">Redirect</a> pariatur. Excepteur sint occaecat cupidatat non proident,
+  sunt in culpa qui officia
+  text   with
+  whitespace
+  id est laborum.
+</p>
+
+<p>
+  <input type="text" id="test_field" value="monkey"/>
+  <textarea>banana</textarea>
+  <a href="/redirect_back">BackToMyself</a>
+  <a title="twas a fine link" href="/redirect">A link came first</a>
+  <a title="a fine link" href="/with_simple_html">A link</a>
+  <a title="a fine link with data method" data-method="delete" href="/delete">A link with data-method</a>
+  <a>No Href</a>
+  <a href="">Blank Href</a>
+  <a href="#">Blank Anchor</a>
+  <a href="#anchor">Anchor</a>
+  <a href="/with_simple_html#anchor">Anchor on different page</a>
+  <a href="/with_html#anchor">Anchor on same page</a>
+  <input type="text" value="" id="test_field">
+  <input type="text" checked="checked" id="checked_field">
+  <a href="/redirect"><img src="http://www.foobar.sun/dummy_image.jpg" width="20" height="20" alt="very fine image" /></a>
+  <a href="/with_simple_html"><img src="http://www.foobar.sun/dummy_image.jpg" width="20" height="20" alt="fine image" /></a>
+</p>
+
+<div id="hidden" style="display: none;">
+  <div id="hidden_via_ancestor">Inside element with hidden ancestor</div>
+  <a href="/with_simple_html" title="awesome title" class="simple">hidden link</a>
+</div>

data/spec/spec_helper.rb

@@ -0,0 +1,4 @@
+require 'rubygems'
+require 'bundler/setup'
+
+require 'xpath'

data/spec/union_spec.rb

@@ -0,0 +1,63 @@
+require 'spec_helper'
+
+describe XPath::Union do
+  let(:template) { File.read(File.expand_path('fixtures/simple.html', File.dirname(__FILE__))) }
+  let(:doc) { Nokogiri::HTML(template) }
+
+  describe '#expressions' do
+    it "should return the expressions" do
+      @expr1 = XPath.generate { |x| x.descendant(:p) } 
+      @expr2 = XPath.generate { |x| x.descendant(:div) } 
+      @collection = XPath::Union.new(@expr1, @expr2)
+      @collection.expressions.should == [@expr1, @expr2]
+    end
+  end
+
+  describe '#each' do
+    it "should iterate through the expressions" do
+      @expr1 = XPath.generate { |x| x.descendant(:p) } 
+      @expr2 = XPath.generate { |x| x.descendant(:div) } 
+      @collection = XPath::Union.new(@expr1, @expr2)
+      exprs = []
+      @collection.each { |expr| exprs << expr }
+      exprs.should == [@expr1, @expr2]
+    end
+  end
+
+  describe '#map' do
+    it "should map the expressions" do
+      @expr1 = XPath.generate { |x| x.descendant(:p) } 
+      @expr2 = XPath.generate { |x| x.descendant(:div) } 
+      @collection = XPath::Union.new(@expr1, @expr2)
+      @collection.map { |expr| expr.class }.should == [XPath::Expression::Descendant, XPath::Expression::Descendant]
+    end
+  end
+
+  describe '#to_xpath' do
+    it "should create a valid xpath expression" do
+      @expr1 = XPath.generate { |x| x.descendant(:p) } 
+      @expr2 = XPath.generate { |x| x.descendant(:div).where(x.attr(:id) == 'foo') } 
+      @collection = XPath::Union.new(@expr1, @expr2)
+      @results = doc.xpath(@collection.to_xpath)
+      @results[0][:title].should == 'fooDiv'
+      @results[1].text.should == 'Blah'
+      @results[2].text.should == 'Bax'
+    end
+  end
+
+  describe '#where, #apply and others' do
+    it "should be delegated to the individual expressions" do
+      @expr1 = XPath.generate { |x| x.descendant(:p) } 
+      @expr2 = XPath.generate { |x| x.descendant(:div) } 
+      @collection = XPath::Union.new(@expr1, @expr2)
+      @xpath1 = @collection.where(XPath.attr(:id) == 'foo').to_xpath
+      @xpath2 = @collection.where(XPath.attr(:id) == XPath.varstring(:id)).apply(:id => 'fooDiv').to_xpath
+      @results = doc.xpath(@xpath1)
+      @results[0][:title].should == 'fooDiv'
+      @results = doc.xpath(@xpath2)
+      @results[0][:id].should == 'fooDiv'
+    end
+  end
+
+end
+

data/spec/xpath_spec.rb

@@ -0,0 +1,301 @@
+require 'spec_helper'
+
+require 'nokogiri'
+
+class Thingy
+  include XPath
+
+  def foo_div
+    descendant(:div).where(attr(:id) == 'foo')
+  end
+end
+
+describe XPath do
+  let(:template) { File.read(File.expand_path('fixtures/simple.html', File.dirname(__FILE__))) }
+  let(:doc) { Nokogiri::HTML(template) }
+
+  def xpath(predicate=nil, &block)
+    doc.xpath XPath.generate(&block).to_xpath(predicate)
+  end
+
+  it "should work as a mixin" do
+    xpath = Thingy.new.foo_div.to_xpath
+    doc.xpath(xpath).first[:title].should == 'fooDiv'
+  end
+
+  describe '#descendant' do
+    it "should find nodes that are nested below the current node" do
+      @results = xpath { |x| x.descendant(:p) }
+      @results[0].text.should == "Blah"
+      @results[1].text.should == "Bax"
+    end
+
+    it "should not find nodes outside the context" do
+      @results = xpath do |x|
+        foo_div = x.descendant(:div).where(x.attr(:id) == 'foo')
+        x.descendant(:p).where(x.attr(:id) == foo_div.attr(:title))
+      end
+      @results[0].should be_nil
+    end
+
+    it "should find multiple kinds of nodes" do
+      @results = xpath { |x| x.descendant(:p, :ul) }
+      @results[0].text.should == 'Blah'
+      @results[3].text.should == 'A list'
+    end
+  end
+
+  describe '#child' do
+    it "should find nodes that are nested directly below the current node" do
+      @results = xpath { |x| x.descendant(:div).child(:p) }
+      @results[0].text.should == "Blah"
+      @results[1].text.should == "Bax"
+    end
+
+    it "should not find nodes that are nested further down below the current node" do
+      @results = xpath { |x| x.child(:p) }
+      @results[0].should be_nil
+    end
+
+    it "should find multiple kinds of nodes" do
+      @results = xpath { |x| x.descendant(:div).child(:p, :ul) }
+      @results[0].text.should == 'Blah'
+      @results[3].text.should == 'A list'
+    end
+  end
+
+  describe '#next_sibling' do
+    it "should find nodes which are immediate siblings of the current node" do
+      xpath { |x| x.descendant(:p)[x.attr(:id) == 'fooDiv'].next_sibling(:p) }.first.text.should == 'Bax'
+      xpath { |x| x.descendant(:p)[x.attr(:id) == 'fooDiv'].next_sibling(:ul, :p) }.first.text.should == 'Bax'
+      xpath { |x| x.descendant(:p)[x.attr(:title) == 'monkey'].next_sibling(:ul, :p) }.first.text.should == 'A list'
+      xpath { |x| x.descendant(:p)[x.attr(:id) == 'fooDiv'].next_sibling(:ul, :li) }.first.should be_nil
+    end
+  end
+
+  describe '#anywhere' do
+    it "should find nodes regardless of the context" do
+      @results = xpath do |x|
+        foo_div = x.anywhere(:div).where(x.attr(:id) == 'foo')
+        x.descendant(:p).where(x.attr(:id) == foo_div.attr(:title))
+      end
+      @results[0].text.should == "Blah"
+    end
+  end
+
+  describe '#contains' do
+    it "should find nodes that contain the given string" do
+      @results = xpath do |x|
+        x.descendant(:div).where(x.attr(:title).contains('ooD'))
+      end
+      @results[0][:id].should == "foo"
+    end
+
+    it "should find nodes that contain the given expression" do
+      @results = xpath do |x|
+        expression = x.anywhere(:div).where(x.attr(:title) == 'fooDiv').attr(:id)
+        x.descendant(:div).where(x.attr(:title).contains(expression))
+      end
+      @results[0][:id].should == "foo"
+    end
+  end
+
+  describe '#text' do
+    it "should select a node's text" do
+      @results = xpath { |x| x.descendant(:p).where(x.text == 'Bax') }
+      @results[0].text.should == 'Bax'
+      @results[1][:title].should == 'monkey'
+      @results = xpath { |x| x.descendant(:div).where(x.descendant(:p).text == 'Bax') }
+      @results[0][:title].should == 'fooDiv'
+    end
+  end
+
+  describe '#where' do
+    it "should limit the expression to find only certain nodes" do
+      xpath { |x| x.descendant(:div).where(:"@id = 'foo'") }.first[:title].should == "fooDiv"
+    end
+
+    it "should be aliased as []" do
+      xpath { |x| x.descendant(:div)[:"@id = 'foo'"] }.first[:title].should == "fooDiv"
+    end
+  end
+
+  describe '#inverse' do
+    it "should invert the expression" do
+      xpath { |x| x.descendant(:p).where(x.attr(:id).equals('fooDiv').inverse) }.first.text.should == 'Bax'
+    end
+
+    it "should be aliased as the unary tilde" do
+      xpath { |x| x.descendant(:p).where(~x.attr(:id).equals('fooDiv')) }.first.text.should == 'Bax'
+    end
+  end
+
+  describe '#equals' do
+    it "should limit the expression to find only certain nodes" do
+      xpath { |x| x.descendant(:div).where(x.attr(:id).equals('foo')) }.first[:title].should == "fooDiv"
+    end
+
+    it "should be aliased as ==" do
+      xpath { |x| x.descendant(:div).where(x.attr(:id) == 'foo') }.first[:title].should == "fooDiv"
+    end
+  end
+
+  describe '#is' do
+    it "should limit the expression to only nodes that contain the given expression" do
+      @results = xpath { |x| x.descendant(:p).where(x.text.is('llama')) }
+      @results[0][:id].should == 'is-fuzzy'
+      @results[1][:id].should == 'is-exact'
+    end
+
+    it "should limit the expression to only nodes that contain the given expression if fuzzy predicate given" do
+      @results = xpath(:fuzzy) { |x| x.descendant(:p).where(x.text.is('llama')) }
+      @results[0][:id].should == 'is-fuzzy'
+      @results[1][:id].should == 'is-exact'
+    end
+
+    it "should limit the expression to only nodes that equal the given expression if exact predicate given" do
+      @results = xpath(:exact) { |x| x.descendant(:p).where(x.text.is('llama')) }
+      @results[0][:id].should == 'is-exact'
+      @results[1].should be_nil
+    end
+
+    context "with to_xpaths" do
+      it "should prefer exact matches" do
+        @xpath = XPath.generate { |x| x.descendant(:p).where(x.text.is('llama')) }
+        @results = @xpath.to_xpaths.map { |path| doc.xpath(path) }.flatten
+        @results[0][:id].should == 'is-exact'
+        @results[1][:id].should == 'is-fuzzy'
+      end
+    end
+  end
+
+  describe '#one_of' do
+    it "should return all nodes where the condition matches" do
+      @results = xpath do |x|
+        p = x.anywhere(:div).where(x.attr(:id) == 'foo').attr(:title)
+        x.descendant(:*).where(x.attr(:id).one_of('foo', p, 'baz'))
+      end
+      @results[0][:title].should == "fooDiv"
+      @results[1].text.should == "Blah"
+      @results[2][:title].should == "bazDiv"
+    end
+  end
+
+  describe '#and' do
+    it "should find all nodes in both expression" do
+      @results = xpath do |x|
+        x.descendant(:*).where(x.contains('Bax').and(x.attr(:title).equals('monkey')))
+      end
+      @results[0][:title].should == "monkey"
+    end
+
+    it "should be aliased as ampersand (&)" do
+      @results = xpath do |x|
+        x.descendant(:*).where(x.contains('Bax') & x.attr(:title).equals('monkey'))
+      end
+      @results[0][:title].should == "monkey"
+    end
+  end
+
+  describe '#or' do
+    it "should find all nodes in either expression" do
+      @results = xpath do |x|
+        x.descendant(:*).where(x.attr(:id).equals('foo').or(x.attr(:id).equals('fooDiv')))
+      end
+      @results[0][:title].should == "fooDiv"
+      @results[1].text.should == "Blah"
+    end
+
+    it "should be aliased as pipe (|)" do
+      @results = xpath do |x|
+        x.descendant(:*).where(x.attr(:id).equals('foo') | x.attr(:id).equals('fooDiv'))
+      end
+      @results[0][:title].should == "fooDiv"
+      @results[1].text.should == "Blah"
+    end
+  end
+
+  describe '#attr' do
+    it "should be an attribute" do
+      @results = xpath { |x| x.descendant(:div).where(x.attr(:id)) }
+      @results[0][:title].should == "barDiv"
+      @results[1][:title].should == "fooDiv"
+    end
+    
+    it "should be closed" do
+      @results = xpath do |x|
+        foo_div = x.anywhere(:div).where(x.attr(:id) == 'foo')
+        id = x.attr(foo_div.attr(:data))
+        x.descendant(:div).where(id == 'bar')
+      end.first[:title].should == "barDiv"
+    end
+  end
+
+  describe '#name' do
+    it "should match the node's name" do
+      xpath { |x| x.descendant(:*).where(x.name == 'ul') }.first.text.should == "A list"
+    end
+  end
+
+  describe '#apply and #var' do
+    it "should interpolate variables in the xpath expression" do
+      @xpath = XPath.generate do |x|
+        exp = x.descendant(:*).where(x.attr(:id) == x.var(:id).string_literal)
+      end
+      @result1 = doc.xpath(@xpath.apply(:id => 'foo').to_xpath).first
+      @result1[:title].should == 'fooDiv'
+      @result2 = doc.xpath(@xpath.apply(:id => 'baz').to_xpath).first
+      @result2[:title].should == 'bazDiv'
+    end
+
+    it "should raise an argument error if the interpolation key is not given" do
+      @xpath = XPath.generate { |x| x.descendant(:*).where(x.attr(:id) == x.var(:id).string_literal) }
+      lambda { @xpath.apply.to_xpath }.should raise_error(ArgumentError)
+    end
+  end
+
+  describe '#varstring' do
+    it "should add a literal string variable" do
+      @xpath = XPath.generate { |x| x.descendant(:*).where(x.attr(:id) == x.varstring(:id)) }
+      @result1 = doc.xpath(@xpath.apply(:id => 'foo').to_xpath).first
+      @result1[:title].should == 'fooDiv'
+    end
+  end
+
+  describe '#normalize' do
+    it "should normalize whitespace" do
+      xpath { |x| x.descendant(:p).where(x.text.normalize == 'A lot of whitespace') }.first[:id].should == "whitespace"
+    end
+
+    it "should be aliased as 'n'" do
+      xpath { |x| x.descendant(:p).where(x.text.n == 'A lot of whitespace') }.first[:id].should == "whitespace"
+    end
+  end
+
+  describe '#union' do
+    it "should create a union expression" do
+      @expr1 = XPath.generate { |x| x.descendant(:p) } 
+      @expr2 = XPath.generate { |x| x.descendant(:div) } 
+      @collection = @expr1.union(@expr2)
+      @xpath1 = @collection.where(XPath.attr(:id) == 'foo').to_xpath
+      @xpath2 = @collection.where(XPath.attr(:id) == XPath.varstring(:id)).apply(:id => 'fooDiv').to_xpath
+      @results = doc.xpath(@xpath1)
+      @results[0][:title].should == 'fooDiv'
+      @results = doc.xpath(@xpath2)
+      @results[0][:id].should == 'fooDiv'
+    end
+
+    it "should be aliased as +" do
+      @expr1 = XPath.generate { |x| x.descendant(:p) } 
+      @expr2 = XPath.generate { |x| x.descendant(:div) } 
+      @collection = @expr1 + @expr2
+      @xpath1 = @collection.where(XPath.attr(:id) == 'foo').to_xpath
+      @xpath2 = @collection.where(XPath.attr(:id) == XPath.varstring(:id)).apply(:id => 'fooDiv').to_xpath
+      @results = doc.xpath(@xpath1)
+      @results[0][:title].should == 'fooDiv'
+      @results = doc.xpath(@xpath2)
+      @results[0][:id].should == 'fooDiv'
+    end
+  end
+
+end

metadata

@@ -0,0 +1,127 @@
+--- !ruby/object:Gem::Specification 
+name: xpath
+version: !ruby/object:Gem::Version 
+  hash: 27
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Jonas Nicklas
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-08-15 00:00:00 +02:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 13
+        segments: 
+        - 1
+        - 2
+        - 9
+        version: 1.2.9
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: nokogiri
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 29
+        segments: 
+        - 1
+        - 3
+        - 3
+        version: 1.3.3
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: yard
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 27
+        segments: 
+        - 0
+        - 5
+        - 8
+        version: 0.5.8
+  type: :development
+  version_requirements: *id003
+description: XPath is a Ruby DSL for generating XPath expressions
+email: 
+- jonas.nicklas@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- lib/xpath/expression.rb
+- lib/xpath/html.rb
+- lib/xpath/union.rb
+- lib/xpath/version.rb
+- lib/xpath.rb
+- spec/fixtures/form.html
+- spec/fixtures/simple.html
+- spec/fixtures/stuff.html
+- spec/spec_helper.rb
+- spec/union_spec.rb
+- spec/xpath_spec.rb
+- README.rdoc
+has_rdoc: true
+homepage: http://github.com/jnicklas/xpath
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --main
+- README.rdoc
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: xpath
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Generate XPath expressions from Ruby
+test_files: []
+