actionpack-2.3.17-rack-upgrade 2.3.17

data/lib/action_controller/translation.rb

@@ -0,0 +1,13 @@
+module ActionController
+  module Translation
+    def translate(*args)
+      I18n.translate(*args)
+    end
+    alias :t :translate
+
+    def localize(*args)
+      I18n.localize(*args)
+    end
+    alias :l :localize
+  end
+end

data/lib/action_controller/uploaded_file.rb

@@ -0,0 +1,44 @@
+module ActionController
+  module UploadedFile
+    def self.included(base)
+      base.class_eval do
+        attr_accessor :original_path, :content_type
+        alias_method :local_path, :path if method_defined?(:path)
+      end
+    end
+
+    def self.extended(object)
+      object.class_eval do
+        attr_accessor :original_path, :content_type
+        alias_method :local_path, :path if method_defined?(:path)
+      end
+    end
+
+    # Take the basename of the upload's original filename.
+    # This handles the full Windows paths given by Internet Explorer
+    # (and perhaps other broken user agents) without affecting
+    # those which give the lone filename.
+    # The Windows regexp is adapted from Perl's File::Basename.
+    def original_filename
+      unless defined? @original_filename
+        @original_filename =
+          unless original_path.blank?
+            if original_path =~ /^(?:.*[:\\\/])?(.*)/m
+              $1
+            else
+              File.basename original_path
+            end
+          end
+      end
+      @original_filename
+    end
+  end
+
+  class UploadedStringIO < StringIO
+    include UploadedFile
+  end
+
+  class UploadedTempfile < Tempfile
+    include UploadedFile
+  end
+end

data/lib/action_controller/url_rewriter.rb

@@ -0,0 +1,229 @@
+require 'uri'
+
+module ActionController
+  # In <b>routes.rb</b> one defines URL-to-controller mappings, but the reverse
+  # is also possible: an URL can be generated from one of your routing definitions.
+  # URL generation functionality is centralized in this module.
+  #
+  # See ActionController::Routing and ActionController::Resources for general
+  # information about routing and routes.rb.
+  #
+  # <b>Tip:</b> If you need to generate URLs from your models or some other place,
+  # then ActionController::UrlWriter is what you're looking for. Read on for
+  # an introduction.
+  #
+  # == URL generation from parameters
+  #
+  # As you may know, some functions - such as ActionController::Base#url_for
+  # and ActionView::Helpers::UrlHelper#link_to, can generate URLs given a set
+  # of parameters. For example, you've probably had the chance to write code
+  # like this in one of your views:
+  #
+  #   <%= link_to('Click here', :controller => 'users',
+  #           :action => 'new', :message => 'Welcome!') %>
+  #
+  #   #=> Generates a link to: /users/new?message=Welcome%21
+  #
+  # link_to, and all other functions that require URL generation functionality,
+  # actually use ActionController::UrlWriter under the hood. And in particular,
+  # they use the ActionController::UrlWriter#url_for method. One can generate
+  # the same path as the above example by using the following code:
+  #
+  #   include UrlWriter
+  #   url_for(:controller => 'users',
+  #           :action => 'new',
+  #           :message => 'Welcome!',
+  #           :only_path => true)
+  #   # => "/users/new?message=Welcome%21"
+  #
+  # Notice the <tt>:only_path => true</tt> part. This is because UrlWriter has no
+  # information about the website hostname that your Rails app is serving. So if you
+  # want to include the hostname as well, then you must also pass the <tt>:host</tt>
+  # argument:
+  #
+  #   include UrlWriter
+  #   url_for(:controller => 'users',
+  #           :action => 'new',
+  #           :message => 'Welcome!',
+  #           :host => 'www.example.com')        # Changed this.
+  #   # => "http://www.example.com/users/new?message=Welcome%21"
+  #
+  # By default, all controllers and views have access to a special version of url_for,
+  # that already knows what the current hostname is. So if you use url_for in your
+  # controllers or your views, then you don't need to explicitly pass the <tt>:host</tt>
+  # argument.
+  #
+  # For convenience reasons, mailers provide a shortcut for ActionController::UrlWriter#url_for.
+  # So within mailers, you only have to type 'url_for' instead of 'ActionController::UrlWriter#url_for'
+  # in full. However, mailers don't have hostname information, and what's why you'll still
+  # have to specify the <tt>:host</tt> argument when generating URLs in mailers.
+  #
+  #
+  # == URL generation for named routes
+  #
+  # UrlWriter also allows one to access methods that have been auto-generated from
+  # named routes. For example, suppose that you have a 'users' resource in your
+  # <b>routes.rb</b>:
+  #
+  #   map.resources :users
+  #
+  # This generates, among other things, the method <tt>users_path</tt>. By default,
+  # this method is accessible from your controllers, views and mailers. If you need
+  # to access this auto-generated method from other places (such as a model), then
+  # you can do that in two ways.
+  #
+  # The first way is to include ActionController::UrlWriter in your class:
+  #
+  #   class User < ActiveRecord::Base
+  #     include ActionController::UrlWriter         # !!!
+  #
+  #     def name=(value)
+  #       write_attribute('name', value)
+  #       write_attribute('base_uri', users_path)   # !!!
+  #     end
+  #   end
+  #
+  # The second way is to access them through ActionController::UrlWriter.
+  # The autogenerated named routes methods are available as class methods:
+  #
+  #   class User < ActiveRecord::Base
+  #     def name=(value)
+  #       write_attribute('name', value)
+  #       path = ActionController::UrlWriter.users_path   # !!!
+  #       write_attribute('base_uri', path)               # !!!
+  #     end
+  #   end
+  module UrlWriter
+    RESERVED_PCHAR = ':@&=+$,;%'
+    SAFE_PCHAR = "#{URI::REGEXP::PATTERN::UNRESERVED}#{RESERVED_PCHAR}"
+    if RUBY_VERSION >= '1.9'
+      UNSAFE_PCHAR = Regexp.new("[^#{SAFE_PCHAR}]", false).freeze
+    else
+      UNSAFE_PCHAR = Regexp.new("[^#{SAFE_PCHAR}]", false, 'N').freeze
+    end
+
+    def self.included(base) #:nodoc:
+      ActionController::Routing::Routes.install_helpers(base)
+      base.mattr_accessor :default_url_options
+
+      # The default options for urls written by this writer. Typically a <tt>:host</tt> pair is provided.
+      base.default_url_options ||= {}
+    end
+
+    # Generate a url based on the options provided, default_url_options and the
+    # routes defined in routes.rb.  The following options are supported:
+    #
+    # * <tt>:only_path</tt> - If true, the relative url is returned. Defaults to +false+.
+    # * <tt>:protocol</tt> - The protocol to connect to. Defaults to 'http'.
+    # * <tt>:host</tt> - Specifies the host the link should be targetted at.
+    #   If <tt>:only_path</tt> is false, this option must be
+    #   provided either explicitly, or via +default_url_options+.
+    # * <tt>:port</tt> - Optionally specify the port to connect to.
+    # * <tt>:anchor</tt> - An anchor name to be appended to the path.
+    # * <tt>:skip_relative_url_root</tt> - If true, the url is not constructed using the
+    #   +relative_url_root+ set in ActionController::Base.relative_url_root.
+    # * <tt>:trailing_slash</tt> - If true, adds a trailing slash, as in "/archive/2009/"
+    #
+    # Any other key (<tt>:controller</tt>, <tt>:action</tt>, etc.) given to
+    # +url_for+ is forwarded to the Routes module.
+    #
+    # Examples:
+    #
+    #    url_for :controller => 'tasks', :action => 'testing', :host=>'somehost.org', :port=>'8080'    # => 'http://somehost.org:8080/tasks/testing'
+    #    url_for :controller => 'tasks', :action => 'testing', :host=>'somehost.org', :anchor => 'ok', :only_path => true    # => '/tasks/testing#ok'
+    #    url_for :controller => 'tasks', :action => 'testing', :trailing_slash=>true  # => 'http://somehost.org/tasks/testing/'
+    #    url_for :controller => 'tasks', :action => 'testing', :host=>'somehost.org', :number => '33'  # => 'http://somehost.org/tasks/testing?number=33'
+    def url_for(options)
+      options = self.class.default_url_options.merge(options)
+
+      url = ''
+
+      unless options.delete(:only_path)
+        url << (options.delete(:protocol) || 'http')
+        url << '://' unless url.match("://")
+
+        raise "Missing host to link to! Please provide :host parameter or set default_url_options[:host]" unless options[:host]
+
+        url << options.delete(:host)
+        url << ":#{options.delete(:port)}" if options.key?(:port)
+      else
+        # Delete the unused options to prevent their appearance in the query string.
+        [:protocol, :host, :port, :skip_relative_url_root].each { |k| options.delete(k) }
+      end
+      trailing_slash = options.delete(:trailing_slash) if options.key?(:trailing_slash)
+      url << ActionController::Base.relative_url_root.to_s unless options[:skip_relative_url_root]
+      anchor = "##{URI.escape(options.delete(:anchor).to_param.to_s, UNSAFE_PCHAR)}" if options[:anchor]
+      generated = Routing::Routes.generate(options, {})
+      url << (trailing_slash ? generated.sub(/\?|\z/) { "/" + $& } : generated)
+      url << anchor if anchor
+
+      url
+    end
+  end
+
+  # Rewrites URLs for Base.redirect_to and Base.url_for in the controller.
+  class UrlRewriter #:nodoc:
+    RESERVED_OPTIONS = [:anchor, :params, :only_path, :host, :protocol, :port, :trailing_slash, :skip_relative_url_root]
+    def initialize(request, parameters)
+      @request, @parameters = request, parameters
+    end
+
+    def rewrite(options = {})
+      if options.include?(:overwrite_params)
+        ActiveSupport::Deprecation.warn 'The :overwrite_params option is deprecated. Specify all the necessary parameters instead', caller
+      end
+      rewrite_url(options)
+    end
+
+    def to_str
+      "#{@request.protocol}, #{@request.host_with_port}, #{@request.path}, #{@parameters[:controller]}, #{@parameters[:action]}, #{@request.parameters.inspect}"
+    end
+
+    alias_method :to_s, :to_str
+
+    private
+      # Given a path and options, returns a rewritten URL string
+      def rewrite_url(options)
+        rewritten_url = ""
+
+        unless options[:only_path]
+          rewritten_url << (options[:protocol] || @request.protocol)
+          rewritten_url << "://" unless rewritten_url.match("://")
+          rewritten_url << rewrite_authentication(options)
+          rewritten_url << (options[:host] || @request.host_with_port)
+          rewritten_url << ":#{options.delete(:port)}" if options.key?(:port)
+        end
+
+        path = rewrite_path(options)
+        rewritten_url << ActionController::Base.relative_url_root.to_s unless options[:skip_relative_url_root]
+        rewritten_url << (options[:trailing_slash] ? path.sub(/\?|\z/) { "/" + $& } : path)
+        rewritten_url << "##{CGI.escape(options[:anchor].to_param.to_s)}" if options[:anchor]
+
+        rewritten_url
+      end
+
+      # Given a Hash of options, generates a route
+      def rewrite_path(options)
+        options = options.symbolize_keys
+        options.update(options[:params].symbolize_keys) if options[:params]
+
+        if overwrite = options.delete(:overwrite_params)
+          options.update(@parameters.symbolize_keys)
+          options.update(overwrite.symbolize_keys)
+        end
+
+        RESERVED_OPTIONS.each { |k| options.delete(k) }
+
+        # Generates the query string, too
+        Routing::Routes.generate(options, @request.symbolized_path_parameters)
+      end
+
+      def rewrite_authentication(options)
+        if options[:user] && options[:password]
+          "#{CGI.escape(options.delete(:user))}:#{CGI.escape(options.delete(:password))}@"
+        else
+          ""
+        end
+      end
+  end
+end

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

@@ -0,0 +1,16 @@
+$LOAD_PATH << "#{File.dirname(__FILE__)}/html-scanner"
+
+module HTML
+  autoload :CDATA, 'html/node'
+  autoload :Document, 'html/document'
+  autoload :FullSanitizer, 'html/sanitizer'
+  autoload :LinkSanitizer, 'html/sanitizer'
+  autoload :Node, 'html/node'
+  autoload :Sanitizer, 'html/sanitizer'
+  autoload :Selector, 'html/selector'
+  autoload :Tag, 'html/node'
+  autoload :Text, 'html/node'
+  autoload :Tokenizer, 'html/tokenizer'
+  autoload :Version, 'html/version'
+  autoload :WhiteListSanitizer, 'html/sanitizer'
+end

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

@@ -0,0 +1,68 @@
+require 'html/tokenizer'
+require 'html/node'
+require 'html/selector'
+require 'html/sanitizer'
+
+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, strict=false, xml=false)
+      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, strict)
+
+        node_stack.last.children << node unless node.tag? && node.closing == :close
+        if node.tag?
+          if node_stack.length > 1 && node.closing == :close
+            if node_stack.last.name == node.name
+              if node_stack.last.children.empty?
+                node_stack.last.children << Text.new(node_stack.last, node.line, node.position, "")
+              end
+              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
+              msg = <<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
+              strict ? raise(msg) : warn(msg)
+            end
+          elsif !node.childless?(xml) && 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,537 @@
+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, :sibling, :before,
+                  :after
+            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)
+      conditions = validate_conditions(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)
+      conditions = validate_conditions(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
+
+    def ==(node)
+      return false unless self.class == node.class && children.size == node.children.size
+
+      equivalent = true
+
+      children.size.times do |i|
+        equivalent &&= children[i] == node.children[i]
+      end
+
+      equivalent
+    end
+    
+    class <<self
+      def parse(parent, line, pos, content, strict=true)
+        if content !~ /^<\S/
+          Text.new(parent, line, pos, content)
+        else
+          scanner = StringScanner.new(content)
+
+          unless scanner.skip(/</)
+            if strict
+              raise "expected <"
+            else
+              return Text.new(parent, line, pos, content)
+            end
+          end
+
+          if scanner.skip(/!\[CDATA\[/)
+            unless scanner.skip_until(/\]\]>/)
+              if strict
+                raise "expected ]]> (got #{scanner.rest.inspect} for #{content})"
+              else
+                scanner.skip_until(/\Z/)
+              end
+            end
+
+            return CDATA.new(parent, line, pos, scanner.pre_match.gsub(/<!\[CDATA\[/, ''))
+          end
+          
+          closing = ( scanner.scan(/\//) ? :close : nil )
+          return Text.new(parent, line, pos, content) unless name = scanner.scan(/[^\s!>\/]+/)
+          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
+          
+          unless scanner.scan(/\s*>/)
+            if strict
+              raise "expected > (got #{scanner.rest.inspect} for #{content}, #{attributes.inspect})" 
+            else
+              # throw away all text until we find what we're looking for
+              scanner.skip_until(/>/) or scanner.terminate
+            end
+          end
+
+          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 == 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
+
+    def ==(node)
+      return false unless super
+      content == node.content
+    end
+  end
+  
+  # A CDATA node is simply a text node with a specialized way of displaying
+  # itself.
+  class CDATA < Text #:nodoc:
+    def to_s
+      "<![CDATA[#{super}]]>"
+    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?(xml = false)
+      return false if xml && @closing.nil?
+      !@closing.nil? ||
+        @name =~ /^(img|br|hr|link|meta|area|base|basefont|
+                    col|frame|input|isindex|param)$/ox
+    end
+
+    # Returns a textual representation of the node
+    def to_s
+      if @closing == :close
+        "</#{@name}>"
+      else
+        s = "<#{@name}"
+        @attributes.each do |k,v|
+          s << " #{k}"
+          s << "=\"#{v}\"" if String === v
+        end
+        s << " /" if @closing == :self
+        s << ">"
+        @children.each { |child| s << child.to_s }
+        s << "</#{@name}>" if @closing != :self && !@children.empty?
+        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>:sibling</tt>: a hash. At least one of the node's siblings must
+    #   meet the criteria described by the hash.
+    # * <tt>:after</tt>: a hash. The node must be after any sibling meeting
+    #   the criteria described by the hash, and at least one sibling must match.
+    # * <tt>:before</tt>: a hash. The node must be before any sibling meeting
+    #   the criteria described by the hash, and at least one sibling must match.
+    # * <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)
+      # check content of child nodes
+      if conditions[:content]
+        if children.empty?
+          return false unless match_condition("", conditions[:content])
+        else
+          return false unless children.find { |child| child.match(conditions[:content]) }
+        end
+      end
+
+      # 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.select do |c|
+          (c.kind_of?(HTML::Tag) and (c.closing == :self or ! c.childless?))
+        end
+        
+        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
+
+      # test siblings
+      if conditions[:sibling] || conditions[:before] || conditions[:after]
+        siblings = parent ? parent.children : []
+        self_index = siblings.index(self)
+
+        if conditions[:sibling]
+          return false unless siblings.detect do |s| 
+            s != self && s.match(conditions[:sibling])
+          end
+        end
+
+        if conditions[:before]
+          return false unless siblings[self_index+1..-1].detect do |s| 
+            s != self && s.match(conditions[:before])
+          end
+        end
+
+        if conditions[:after]
+          return false unless siblings[0,self_index].detect do |s| 
+            s != self && s.match(conditions[:after])
+          end
+        end
+      end
+  
+      true
+    end
+
+    def ==(node)
+      return false unless super
+      return false unless closing == node.closing && self.name == node.name
+      attributes == node.attributes
+    end
+    
+    private
+      # Match the given value to the given condition.
+      def match_condition(value, condition)
+        case condition
+          when String
+            value && value == 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