actionpack 1.7.0 → 1.8.0

data/lib/action_controller/pagination.rb

@@ -150,8 +150,8 @@ module ActionController
     # Returns the total number of items in the collection to be paginated for
     # the +model+ and given +conditions+. Override this method to implement a
     # custom counter.
-    def count_collection_for_pagination(model, conditions)
-      model.count(conditions)
+    def count_collection_for_pagination(model, conditions, joins)
+      model.count(conditions,joins)
     end
   
     # Returns a collection of items for the given +model+ and +conditions+,
@@ -166,9 +166,9 @@ module ActionController
               :find_collection_for_pagination
 
     def paginator_and_collection_for(collection_id, options) #:nodoc:
-      klass = eval options[:class_name]
+      klass = options[:class_name].constantize
       page  = @params[options[:parameter]]
-      count = count_collection_for_pagination(klass, options[:conditions])
+      count = count_collection_for_pagination(klass, options[:conditions], options[:join])
 
       paginator = Paginator.new(self, count, options[:per_page], page)
       

data/lib/action_controller/request.rb

@@ -74,8 +74,16 @@ module ActionController
     end
     
     def request_uri
-      (%r{^\w+\://[^/]+(/.*|$)$} =~ env['REQUEST_URI']) ? $1 : env['REQUEST_URI'] # Remove domain, which webrick puts into the request_uri.
-    end
+      unless env['REQUEST_URI'].nil?
+        (%r{^\w+\://[^/]+(/.*|$)$} =~ env['REQUEST_URI']) ? $1 : env['REQUEST_URI'] # Remove domain, which webrick puts into the request_uri.
+      else  # REQUEST_URI is blank under IIS - get this from PATH_INFO and SCRIPT_NAME
+        script_filename = env["SCRIPT_NAME"].to_s.match(%r{[^/]+$})
+        request_uri = env["PATH_INFO"]
+        request_uri.sub!(/#{script_filename}\//, '') unless script_filename.nil?
+        request_uri += '?' + env["QUERY_STRING"] unless env["QUERY_STRING"].nil? || env["QUERY_STRING"].empty?
+        return request_uri
+      end
+     end
 
     def protocol
       env["HTTPS"] == "on" ? 'https://' : 'http://'
@@ -122,6 +130,14 @@ module ActionController
       @path_parameters ||= {}
     end
     
+    # Returns true if the request's "X-Requested-With" header contains
+    # "XMLHttpRequest". (The Prototype Javascript library sends this header with
+    # every Ajax request.)
+    def xml_http_request?
+      env['HTTP_X_REQUESTED_WITH'] =~ /XMLHttpRequest/i
+    end
+    alias xhr? :xml_http_request?
+    
     #--
     # Must be implemented in the concrete request
     #++

data/lib/action_controller/routing.rb

@@ -119,7 +119,11 @@ module ActionController
             options[:controller] = controller_class.controller_path
             return nil, requirements_for(:controller) unless passes_requirements?(:controller, options[:controller])
           elsif /^\*/ =~ item.to_s
-            value = components.empty? ? @defaults[item].clone : components.clone
+            if components.empty?
+              value = @defaults.has_key?(item) ? @defaults[item].clone : []
+            else
+              value = components.clone
+            end
             value.collect! {|c| CGI.unescape c}
             components = []
             def value.to_s() self.join('/') end
@@ -162,7 +166,7 @@ module ActionController
             name = name.camelize
             return nil, nil unless /^[A-Z][_a-zA-Z\d]*$/ =~ name
             controller_name = name + "Controller"
-            return mod.const_get(controller_name), path[length..-1] if mod.const_available? controller_name
+            return eval("mod::#{controller_name}"), path[length..-1] if mod.const_available? controller_name
             return nil, nil unless mod.const_available? name
             [mod.const_get(name), length + 1]
           end

data/lib/action_controller/scaffolding.rb

@@ -99,7 +99,7 @@ module ActionController
         
         module_eval <<-"end_eval", __FILE__, __LINE__
           def list#{suffix}
-            @#{plural_name} = #{class_name}.find_all
+            @#{singular_name}_pages, @#{plural_name} = paginate :#{singular_name}, :per_page => 10
             render#{suffix}_scaffold "list#{suffix}"
           end
 

data/lib/action_controller/templates/rescues/diagnostics.rhtml

@@ -8,7 +8,7 @@
   <%=h @exception.class.to_s %> in
   <%=h (@request.parameters["controller"] || "<controller not set>").capitalize %>#<%=h @request.parameters["action"] || "<action not set>" %>
 </h1>
-<p><%=h Object.const_defined?(:RAILS_ROOT) ? @exception.message.gsub(RAILS_ROOT, "") : @exception.message %></p>
+<pre><%=h Object.const_defined?(:RAILS_ROOT) ? @exception.message.gsub(RAILS_ROOT, "") : @exception.message %></pre>
 
 <% unless app_trace.empty? %><pre><code><%=h app_trace.join("\n") %></code></pre><% end %>
 

data/lib/action_controller/templates/rescues/routing_error.rhtml

@@ -1,8 +1,10 @@
 <h1>Routing Error</h1>
-<p><%=h @exception.message %></p>
+<p><pre><%=h @exception.message %></pre></p>
 <% unless @exception.failures.empty? %><p>
 	<h2>Failure reasons:</h2>
+	<ol>
 	<% @exception.failures.each do |route, reason| %>
-		<%=h route.inspect.gsub('\\', '') %> failed because <%=h reason.downcase %><br />
+		<li><code><%=h route.inspect.gsub('\\', '') %></code> failed because <%=h reason.downcase %></li>
   <% end %>
+  </ol>
 </p><% end %>

data/lib/action_controller/templates/rescues/template_error.rhtml

@@ -1,14 +1,15 @@
 <h1>
   <%=h @exception.original_exception.class.to_s %> in
-  <%=h @request.parameters["controller"].capitalize %>#<%=h @request.parameters["action"] %>
+  <%=h @request.parameters["controller"].capitalize if @request.parameters["controller"]%>#<%=h @request.parameters["action"] %>
 </h1>
 
 <p>
-  Showing <i><%=h @exception.file_name %></i> where line <b>#<%=h @exception.line_number %></b> raised
-  <u><%=h @exception.message %></u>
+  Showing <i><%=h @exception.file_name %></i> where line <b>#<%=h @exception.line_number %></b> raised:
+  <pre><code><%=h @exception.message %></code></pre>
 </p>
 
-<pre><code><%=h @exception.source_extract %></code></pre>
+<p>Extracted source (around line <b>#<%=h @exception.line_number %></b>):
+<pre><code><%=h @exception.source_extract %></code></pre></p>
 
 <p><%=h @exception.sub_template_message %></p>
 

data/lib/action_controller/templates/scaffolds/list.rhtml

@@ -19,6 +19,9 @@
 <% end %>
 </table>
 
+<%= link_to "Previous page", { :page => instance_variable_get("@#{@scaffold_singular_name}_pages").current.previous } if instance_variable_get("@#{@scaffold_singular_name}_pages").current.previous %>
+<%= link_to "Next page", { :page => instance_variable_get("@#{@scaffold_singular_name}_pages").current.next } if instance_variable_get("@#{@scaffold_singular_name}_pages").current.next %> 
+
 <br />
 
 <%= link_to "New #{@scaffold_singular_name}", :action => "new#{@scaffold_suffix}" %>

data/lib/action_controller/test_process.rb

@@ -1,5 +1,5 @@
-require File.dirname(__FILE__) + '/assertions/action_pack_assertions'
-require File.dirname(__FILE__) + '/assertions/active_record_assertions'
+require File.dirname(__FILE__) + '/assertions'
+require File.dirname(__FILE__) + '/deprecated_assertions'
 
 if defined?(RAILS_ROOT)
   # Temporary hack for getting functional tests in Rails running under 1.8.2
@@ -94,17 +94,6 @@ module ActionController #:nodoc:
   end
   
   class TestResponse < AbstractResponse #:nodoc:
-    # the class attribute ties a TestResponse to the assertions 
-    class << self
-      attr_accessor :assertion_target
-    end
-
-    # initializer
-    def initialize
-      TestResponse.assertion_target=self# if TestResponse.assertion_target.nil?
-      super()
-    end
-    
     # the response code of the request
     def response_code
       headers['Status'][0,3].to_i rescue 0
@@ -126,10 +115,12 @@ module ActionController #:nodoc:
     end
     
     # was there a server-side error?
-    def server_error?
+    def error?
       (500..599).include?(response_code)
     end
 
+    alias_method :server_error?, :error?
+
     # returns the redirection location or nil
     def redirect_url
       redirect? ? headers['location'] : nil
@@ -252,12 +243,15 @@ module Test
       private  
         # execute the request and set/volley the response
         def process(action, parameters = nil, session = nil, flash = nil)
+          @html_document = nil
           @request.env['REQUEST_METHOD'] ||= "GET"
           @request.action = action.to_s
-          @request.path_parameters = { :controller => @controller.class.controller_path }
+          @request.path_parameters = { :controller => @controller.class.controller_path,
+                                       :action => action.to_s }
           @request.parameters.update(parameters) unless parameters.nil?
           @request.session = ActionController::TestSession.new(session) unless session.nil?
           @request.session["flash"] = ActionController::Flash::FlashHash.new.update(flash) if flash
+          build_request_uri(action, parameters)
           @controller.process(@request, @response)
         end
     
@@ -279,8 +273,57 @@ module Test
           get(@response.redirected_to.delete(:action), @response.redirected_to.stringify_keys)
         end
 
-        def assigns(name)
-          @response.template.assigns[name.to_s]
+        def assigns(key = nil)
+          if key.nil?
+            @response.template.assigns
+          else
+            @response.template.assigns[key.to_s]
+          end
+        end
+        
+        def session
+          @response.session
+        end
+
+        def flash
+          @response.flash
+        end
+
+        def cookies
+          @response.cookies
+        end
+
+        def redirect_to_url
+          @response.redirect_url
+        end
+
+        def build_request_uri(action, parameters)
+          return if @request.env['REQUEST_URI']
+          url = ActionController::UrlRewriter.new(@request, parameters)
+          @request.set_REQUEST_URI(
+            url.rewrite(@controller.send(:rewrite_options,
+              (parameters||{}).update(:only_path => true, :action=>action))))
+        end
+
+        def html_document
+          require_html_scanner
+          @html_document ||= HTML::Document.new(@response.body)
+        end
+        
+        def find_tag(conditions)
+          html_document.find(conditions)
+        end
+
+        def find_all_tag(conditions)
+          html_document.find_all(conditions)
+        end
+
+        def require_html_scanner
+          return true if defined?(HTML::Document)
+          require 'html/document'
+        rescue LoadError
+          $:.unshift File.dirname(__FILE__) + "/vendor/html-scanner"
+          require 'html/document'
         end
       end
   end

data/lib/action_controller/url_rewriter.rb

@@ -2,7 +2,7 @@ module ActionController
   # Rewrites URLs for Base.redirect_to and Base.url_for in the controller.
 
   class UrlRewriter #:nodoc:
-    RESERVED_OPTIONS = [:anchor, :params, :only_path, :host, :protocol, :trailing_slash]
+    RESERVED_OPTIONS = [:anchor, :params, :only_path, :host, :protocol, :trailing_slash, :skip_relative_url_root]
     def initialize(request, parameters)
       @request, @parameters = request, parameters
     end
@@ -23,7 +23,7 @@ module ActionController
         rewritten_url << (options[:protocol] || @request.protocol) unless options[:only_path]
         rewritten_url << (options[:host] || @request.host_with_port) unless options[:only_path]
 
-        rewritten_url << @request.relative_url_root.to_s
+        rewritten_url << @request.relative_url_root.to_s unless options[:skip_relative_url_root]
         rewritten_url << path
         rewritten_url << '/' if options[:trailing_slash]
         rewritten_url << "##{options[:anchor]}" if options[:anchor]
@@ -38,7 +38,7 @@ module ActionController
         path, extras = Routing::Routes.generate(options, @request)
 
         if extras[:overwrite_params]
-          params_copy = @request.parameters.delete_if { |k,v| ["controller","action"].include? k }
+          params_copy = @request.parameters.reject { |k,v| ["controller","action"].include? k }
           params_copy.update extras[:overwrite_params]
           extras.delete(:overwrite_params)
           extras.update(params_copy)

data/lib/action_controller/vendor/html-scanner/html/document.rb

@@ -0,0 +1,63 @@
+require 'html/tokenizer'
+require 'html/node'
+
+module HTML#:nodoc:
+  
+  # A top-level HTMl document. You give it a body of text, and it will parse that
+  # text into a tree of nodes.
+  class Document #:nodoc:
+
+    # The root of the parsed document.
+    attr_reader :root
+
+    # Create a new Document from the given text.
+    def initialize(text)
+      tokenizer = Tokenizer.new(text)
+      @root = Node.new(nil)
+      node_stack = [ @root ]
+      while token = tokenizer.next
+        node = Node.parse(node_stack.last, tokenizer.line, tokenizer.position, token)
+
+        node_stack.last.children << node unless node.tag? && node.closing == :close
+        if node.tag? && !node.childless?
+          if node_stack.length > 1 && node.closing == :close
+            if node_stack.last.name == node.name
+              node_stack.pop
+            else
+              open_start = node_stack.last.position - 20
+              open_start = 0 if open_start < 0
+              close_start = node.position - 20
+              close_start = 0 if close_start < 0
+              warn <<EOF.strip
+ignoring attempt to close #{node_stack.last.name} with #{node.name}
+  opened at byte #{node_stack.last.position}, line #{node_stack.last.line}
+  closed at byte #{node.position}, line #{node.line}
+  attributes at open: #{node_stack.last.attributes.inspect}
+  text around open: #{text[open_start,40].inspect}
+  text around close: #{text[close_start,40].inspect}
+EOF
+            end
+          elsif node.closing != :close
+            node_stack.push node
+          end
+        end
+      end
+    end
+  
+    # Search the tree for (and return) the first node that matches the given
+    # conditions. The conditions are interpreted differently for different node
+    # types, see HTML::Text#find and HTML::Tag#find.
+    def find(conditions)
+      @root.find(conditions)
+    end
+
+    # Search the tree for (and return) all nodes that match the given
+    # conditions. The conditions are interpreted differently for different node
+    # types, see HTML::Text#find and HTML::Tag#find.
+    def find_all(conditions)
+      @root.find_all(conditions)
+    end
+    
+  end
+
+end

data/lib/action_controller/vendor/html-scanner/html/node.rb

@@ -0,0 +1,431 @@
+require 'strscan'
+
+module HTML#:nodoc:
+  
+  class Conditions < Hash#:nodoc:
+    def initialize(hash)
+      super()
+      hash = { :content => hash } unless Hash === hash
+      hash = keys_to_symbols(hash)
+      hash.each do |k,v|
+        case k
+          when :tag, :content then
+            # keys are valid, and require no further processing
+          when :attributes then
+            hash[k] = keys_to_strings(v)
+          when :parent, :child, :ancestor, :descendant
+            hash[k] = Conditions.new(v)
+          when :children
+            hash[k] = v = keys_to_symbols(v)
+            v.each do |k,v2|
+              case k
+                when :count, :greater_than, :less_than
+                  # keys are valid, and require no further processing
+                when :only
+                  v[k] = Conditions.new(v2)
+                else
+                  raise "illegal key #{k.inspect} => #{v2.inspect}"
+              end
+            end
+          else
+            raise "illegal key #{k.inspect} => #{v.inspect}"
+        end
+      end
+      update hash
+    end
+
+    private
+
+      def keys_to_strings(hash)
+        hash.keys.inject({}) do |h,k|
+          h[k.to_s] = hash[k]
+          h
+        end
+      end
+
+      def keys_to_symbols(hash)
+        hash.keys.inject({}) do |h,k|
+          raise "illegal key #{k.inspect}" unless k.respond_to?(:to_sym)
+          h[k.to_sym] = hash[k]
+          h
+        end
+      end
+  end
+
+  # The base class of all nodes, textual and otherwise, in an HTML document.
+  class Node#:nodoc:
+    # The array of children of this node. Not all nodes have children.
+    attr_reader :children
+    
+    # The parent node of this node. All nodes have a parent, except for the
+    # root node.
+    attr_reader :parent
+    
+    # The line number of the input where this node was begun
+    attr_reader :line
+    
+    # The byte position in the input where this node was begun
+    attr_reader :position
+    
+    # Create a new node as a child of the given parent.
+    def initialize(parent, line=0, pos=0)
+      @parent = parent
+      @children = []
+      @line, @position = line, pos
+    end
+
+    # Return a textual representation of the node.
+    def to_s
+      s = ""
+      @children.each { |child| s << child.to_s }
+      s
+    end
+
+    # Return false (subclasses must override this to provide specific matching
+    # behavior.) +conditions+ may be of any type.
+    def match(conditions)
+      false
+    end
+
+    # Search the children of this node for the first node for which #find
+    # returns non +nil+. Returns the result of the #find call that succeeded.
+    def find(conditions)
+      @children.each do |child|        
+        node = child.find(conditions)
+        return node if node
+      end
+      nil
+    end
+
+    # Search for all nodes that match the given conditions, and return them
+    # as an array.
+    def find_all(conditions)
+      matches = []
+      matches << self if match(conditions)
+      @children.each do |child|
+        matches.concat child.find_all(conditions)
+      end
+      matches
+    end
+
+    # Returns +false+. Subclasses may override this if they define a kind of
+    # tag.
+    def tag?
+      false
+    end
+
+    def validate_conditions(conditions)
+      Conditions === conditions ? conditions : Conditions.new(conditions)
+    end
+    
+    class <<self
+      def parse(parent, line, pos, content)
+        if content !~ /^<\S/
+          Text.new(parent, line, pos, content)
+        else
+          scanner = StringScanner.new(content)
+          scanner.skip(/</) or raise "expected <"
+          closing = ( scanner.scan(/\//) ? :close : nil )
+          return Text.new(parent, line, pos, content) unless name = scanner.scan(/[\w:]+/)
+          name.downcase!
+  
+          unless closing
+            scanner.skip(/\s*/)
+            attributes = {}
+            while attr = scanner.scan(/[-\w:]+/)
+              value = true
+              if scanner.scan(/\s*=\s*/)
+                if delim = scanner.scan(/['"]/)
+                  value = ""
+                  while text = scanner.scan(/[^#{delim}\\]+|./)
+                    case text
+                      when "\\" then
+                        value << text
+                        value << scanner.getch
+                      when delim
+                        break
+                      else value << text
+                    end
+                  end
+                else
+                  value = scanner.scan(/[^\s>\/]+/)
+                end
+              end
+              attributes[attr.downcase] = value
+              scanner.skip(/\s*/)
+            end
+    
+            closing = ( scanner.scan(/\//) ? :self : nil )
+          end
+          
+          scanner.scan(/\s*>/) or raise "expected > (got #{scanner.rest.inspect} for #{content}, #{attributes.inspect})" 
+
+          Tag.new(parent, line, pos, name, attributes, closing)
+        end
+      end
+    end
+  end
+
+  # A node that represents text, rather than markup.
+  class Text < Node#:nodoc:
+    
+    attr_reader :content
+    
+    # Creates a new text node as a child of the given parent, with the given
+    # content.
+    def initialize(parent, line, pos, content)
+      super(parent, line, pos)
+      @content = content
+    end
+
+    # Returns the content of this node.
+    def to_s
+      @content
+    end
+
+    # Returns +self+ if this node meets the given conditions. Text nodes support
+    # conditions of the following kinds:
+    #
+    # * if +conditions+ is a string, it must be a substring of the node's
+    #   content
+    # * if +conditions+ is a regular expression, it must match the node's
+    #   content
+    # * if +conditions+ is a hash, it must contain a <tt>:content</tt> key that
+    #   is either a string or a regexp, and which is interpreted as described
+    #   above.
+    def find(conditions)
+      match(conditions) && self
+    end
+    
+    # Returns non-+nil+ if this node meets the given conditions, or +nil+
+    # otherwise. See the discussion of #find for the valid conditions.
+    def match(conditions)
+      case conditions
+        when String
+          @content.index(conditions)
+        when Regexp
+          @content =~ conditions
+        when Hash
+          conditions = validate_conditions(conditions)
+
+          # Text nodes only have :content, :parent, :ancestor
+          unless (conditions.keys - [:content, :parent, :ancestor]).empty?
+            return false
+          end
+
+          match(conditions[:content])
+        else
+          nil
+      end
+    end
+  end
+
+  # A Tag is any node that represents markup. It may be an opening tag, a
+  # closing tag, or a self-closing tag. It has a name, and may have a hash of
+  # attributes.
+  class Tag < Node#:nodoc:
+    
+    # Either +nil+, <tt>:close</tt>, or <tt>:self</tt>
+    attr_reader :closing
+    
+    # Either +nil+, or a hash of attributes for this node.
+    attr_reader :attributes
+
+    # The name of this tag.
+    attr_reader :name
+        
+    # Create a new node as a child of the given parent, using the given content
+    # to describe the node. It will be parsed and the node name, attributes and
+    # closing status extracted.
+    def initialize(parent, line, pos, name, attributes, closing)
+      super(parent, line, pos)
+      @name = name
+      @attributes = attributes
+      @closing = closing
+    end
+
+    # A convenience for obtaining an attribute of the node. Returns +nil+ if
+    # the node has no attributes.
+    def [](attr)
+      @attributes ? @attributes[attr] : nil
+    end
+
+    # Returns non-+nil+ if this tag can contain child nodes.
+    def childless?
+      @name =~ /^(img|br|hr|link|meta|area|base|basefont|col|frame|input|isindex|param)$/o
+    end
+
+    # Returns a textual representation of the node
+    def to_s
+      if @closing == :close
+        "</#{@name}>"
+      else
+        s = "<#{@name}"
+        @attributes.each { |k,v| s << " #{k}='#{v.gsub(/'/,"\\\\'")}'" }
+        s << " /" if @closing == :self
+        s << ">"
+        @children.each { |child| s << child.to_s }
+        s
+      end
+    end
+
+    # If either the node or any of its children meet the given conditions, the
+    # matching node is returned. Otherwise, +nil+ is returned. (See the
+    # description of the valid conditions in the +match+ method.)
+    def find(conditions)
+      match(conditions) && self || super
+    end
+
+    # Returns +true+, indicating that this node represents an HTML tag.
+    def tag?
+      true
+    end
+    
+    # Returns +true+ if the node meets any of the given conditions. The
+    # +conditions+ parameter must be a hash of any of the following keys
+    # (all are optional):
+    #
+    # * <tt>:tag</tt>: the node name must match the corresponding value
+    # * <tt>:attributes</tt>: a hash. The node's values must match the
+    #   corresponding values in the hash.
+    # * <tt>:parent</tt>: a hash. The node's parent must match the
+    #   corresponding hash.
+    # * <tt>:child</tt>: a hash. At least one of the node's immediate children
+    #   must meet the criteria described by the hash.
+    # * <tt>:ancestor</tt>: a hash. At least one of the node's ancestors must
+    #   meet the criteria described by the hash.
+    # * <tt>:descendant</tt>: a hash. At least one of the node's descendants
+    #   must meet the criteria described by the hash.
+    # * <tt>:children</tt>: a hash, for counting children of a node. Accepts the
+    #   keys:
+    # ** <tt>:count</tt>: either a number or a range which must equal (or
+    #    include) the number of children that match.
+    # ** <tt>:less_than</tt>: the number of matching children must be less than
+    #    this number.
+    # ** <tt>:greater_than</tt>: the number of matching children must be
+    #    greater than this number.
+    # ** <tt>:only</tt>: another hash consisting of the keys to use
+    #    to match on the children, and only matching children will be
+    #    counted.
+    #
+    # Conditions are matched using the following algorithm:
+    #
+    # * if the condition is a string, it must be a substring of the value.
+    # * if the condition is a regexp, it must match the value.
+    # * if the condition is a number, the value must match number.to_s.
+    # * if the condition is +true+, the value must not be +nil+.
+    # * if the condition is +false+ or +nil+, the value must be +nil+.
+    #
+    # Usage:
+    #
+    #   # test if the node is a "span" tag
+    #   node.match :tag => "span"
+    #
+    #   # test if the node's parent is a "div"
+    #   node.match :parent => { :tag => "div" }
+    #
+    #   # test if any of the node's ancestors are "table" tags
+    #   node.match :ancestor => { :tag => "table" }
+    #
+    #   # test if any of the node's immediate children are "em" tags
+    #   node.match :child => { :tag => "em" }
+    #
+    #   # test if any of the node's descendants are "strong" tags
+    #   node.match :descendant => { :tag => "strong" }
+    #
+    #   # test if the node has between 2 and 4 span tags as immediate children
+    #   node.match :children => { :count => 2..4, :only => { :tag => "span" } } 
+    #
+    #   # get funky: test to see if the node is a "div", has a "ul" ancestor
+    #   # and an "li" parent (with "class" = "enum"), and whether or not it has
+    #   # a "span" descendant that contains # text matching /hello world/:
+    #   node.match :tag => "div",
+    #              :ancestor => { :tag => "ul" },
+    #              :parent => { :tag => "li",
+    #                           :attributes => { :class => "enum" } },
+    #              :descendant => { :tag => "span",
+    #                               :child => /hello world/ }
+    def match(conditions)
+      conditions = validate_conditions(conditions)
+  
+      # only Text nodes have content
+      return false if conditions[:content]
+
+      # test the name
+      return false unless match_condition(@name, conditions[:tag]) if conditions[:tag]
+
+      # test attributes
+      (conditions[:attributes] || {}).each do |key, value|
+        return false unless match_condition(self[key], value)
+      end
+
+      # test parent
+      return false unless parent.match(conditions[:parent]) if conditions[:parent]
+
+      # test children
+      return false unless children.find { |child| child.match(conditions[:child]) } if conditions[:child]
+   
+      # test ancestors
+      if conditions[:ancestor]
+        return false unless catch :found do
+          p = self
+          throw :found, true if p.match(conditions[:ancestor]) while p = p.parent
+        end
+      end
+
+      # test descendants
+      if conditions[:descendant]
+        return false unless children.find do |child|
+          # test the child
+          child.match(conditions[:descendant]) ||
+          # test the child's descendants
+          child.match(:descendant => conditions[:descendant])
+        end
+      end
+      
+      # count children
+      if opts = conditions[:children]
+        matches = children
+        matches = matches.select { |c| c.match(opts[:only]) } if opts[:only]
+        opts.each do |key, value|
+          next if key == :only
+          case key
+            when :count
+              if Integer === value
+                return false if matches.length != value
+              else
+                return false unless value.include?(matches.length)
+              end
+            when :less_than
+              return false unless matches.length < value
+            when :greater_than
+              return false unless matches.length > value
+            else raise "unknown count condition #{key}"
+          end
+        end
+      end
+  
+      true
+    end
+
+    private
+
+      # Match the given value to the given condition.
+      def match_condition(value, condition)
+        case condition
+          when String
+            value && value.index(condition)
+          when Regexp
+            value && value.match(condition)
+          when Numeric
+            value == condition.to_s
+          when true
+            !value.nil?
+          when false, nil
+            value.nil?
+          else
+            false
+        end
+      end
+  end
+end