nokogiri 1.2.3-x86-mswin32-60 → 1.4.5-x86-mswin32-60

data/lib/nokogiri/xml/cdata.rb

@@ -1,6 +1,8 @@
 module Nokogiri
   module XML
-    class CDATA < Text
+    class CDATA < Nokogiri::XML::Text
+      ###
+      # Get the name of this CDATA node
       def name
         '#cdata-section'
       end

data/lib/nokogiri/xml/character_data.rb

@@ -0,0 +1,7 @@
+module Nokogiri
+  module XML
+    class CharacterData < Nokogiri::XML::Node
+      include Nokogiri::XML::PP::CharacterData
+    end
+  end
+end

data/lib/nokogiri/xml/document.rb

@@ -1,16 +1,86 @@
 module Nokogiri
   module XML
-    ####
+    ##
     # Nokogiri::XML::Document is the main entry point for dealing with
     # XML documents.  The Document is created by parsing an XML document.
     # See Nokogiri.XML()
     #
     # For searching a Document, see Nokogiri::XML::Node#css and
     # Nokogiri::XML::Node#xpath
-    class Document < Node
+    class Document < Nokogiri::XML::Node
+      ##
+      # Parse an XML file.  +thing+ may be a String, or any object that
+      # responds to _read_ and _close_ such as an IO, or StringIO.
+      # +url+ is resource where this document is located.  +encoding+ is the
+      # encoding that should be used when processing the document. +options+
+      # is a number that sets options in the parser, such as
+      # Nokogiri::XML::ParseOptions::RECOVER.  See the constants in
+      # Nokogiri::XML::ParseOptions.
+      def self.parse string_or_io, url = nil, encoding = nil, options = ParseOptions::DEFAULT_XML, &block
+
+        options = Nokogiri::XML::ParseOptions.new(options) if Fixnum === options
+        # Give the options to the user
+        yield options if block_given?
+
+        if string_or_io.respond_to?(:read)
+          url ||= string_or_io.respond_to?(:path) ? string_or_io.path : nil
+          return read_io(string_or_io, url, encoding, options.to_i)
+        end
+
+        # read_memory pukes on empty docs
+        return new if string_or_io.nil? or string_or_io.empty?
+
+        read_memory(string_or_io, url, encoding, options.to_i)
+      end
+
       # A list of Nokogiri::XML::SyntaxError found when parsing a document
       attr_accessor :errors
 
+      def initialize *args # :nodoc:
+        @errors     = []
+        @decorators = nil
+      end
+
+      ##
+      # Create an element with +name+, and optionally setting the content and attributes.
+      #
+      #   doc.create_element "div" # <div></div>
+      #   doc.create_element "div", :class => "container" # <div class='container'></div>
+      #   doc.create_element "div", "contents" # <div>contents</div>
+      #   doc.create_element "div", "contents", :class => "container" # <div class='container'>contents</div>
+      #   doc.create_element "div" { |node| node['class'] = "container" } # <div class='container'></div>
+      #
+      def create_element name, *args, &block
+        elm = Nokogiri::XML::Element.new(name, self, &block)
+        args.each do |arg|
+          case arg
+          when Hash
+            arg.each { |k,v|
+              key = k.to_s
+              if key =~ /^xmlns(:\w+)?$/
+                ns_name = key.split(":", 2)[1]
+                elm.add_namespace_definition ns_name, v
+                next
+              end
+              elm[k.to_s] = v.to_s
+            }
+          else
+            elm.content = arg
+          end
+        end
+        elm
+      end
+
+      # Create a text node with +text+
+      def create_text_node text, &block
+        Nokogiri::XML::Text.new(text.to_s, self, &block)
+      end
+
+      # Create a CDATA element containing +text+
+      def create_cdata text
+        Nokogiri::XML::CDATA.new(self, text.to_s)
+      end
+
       # The name of this document.  Always returns "document"
       def name
         'document'
@@ -21,14 +91,71 @@ module Nokogiri
         self
       end
 
+      ##
+      # Recursively get all namespaces from this node and its subtree and
+      # return them as a hash.
+      #
+      # For example, given this document:
+      #
+      #   <root xmlns:foo="bar">
+      #     <bar xmlns:hello="world" />
+      #   </root>
+      #
+      # This method will return:
+      #
+      #   { 'xmlns:foo' => 'bar', 'xmlns:hello' => 'world' }
+      #
+      # WARNING: this method will clobber duplicate names in the keys.
+      # For example, given this document:
+      #
+      #   <root xmlns:foo="bar">
+      #     <bar xmlns:foo="baz" />
+      #   </root>
+      #
+      # The hash returned will look like this: { 'xmlns:foo' => 'bar' }
+      #
+      # Non-prefixed default namespaces (as in "xmlns=") are not included
+      # in the hash.
+      #
+      # Note this is a very expensive operation in current implementation, as it
+      # traverses the entire graph, and also has to bring each node accross the
+      # libxml bridge into a ruby object.
+      def collect_namespaces
+        ns = {}
+        traverse { |j| ns.merge!(j.namespaces) }
+        ns
+      end
+
       # Get the list of decorators given +key+
-      def decorators(key)
+      def decorators key
         @decorators ||= Hash.new
         @decorators[key] ||= []
       end
 
-      ###
-      # Explore a document with shortcut methods.
+      ##
+      # Validate this Document against it's DTD.  Returns a list of errors on
+      # the document or +nil+ when there is no DTD.
+      def validate
+        return nil unless internal_subset
+        internal_subset.validate self
+      end
+
+      ##
+      # Explore a document with shortcut methods. See Nokogiri::Slop for details.
+      #
+      # Note that any nodes that have been instantiated before #slop!
+      # is called will not be decorated with sloppy behavior. So, if you're in
+      # irb, the preferred idiom is:
+      #
+      #   irb> doc = Nokogiri::Slop my_markup
+      #
+      # and not
+      #
+      #   irb> doc = Nokogiri::HTML my_markup
+      #   ... followed by irb's implicit inspect (and therefore instantiation of every node) ...
+      #   irb> doc.slop!
+      #   ... which does absolutely nothing.
+      #
       def slop!
         unless decorators(XML::Node).include? Nokogiri::Decorators::Slop
           decorators(XML::Node) << Nokogiri::Decorators::Slop
@@ -38,9 +165,9 @@ module Nokogiri
         self
       end
 
-      ###
+      ##
       # Apply any decorators to +node+
-      def decorate(node)
+      def decorate node
         return unless @decorators
         @decorators.each { |klass,list|
           next unless node.is_a?(klass)
@@ -48,19 +175,44 @@ module Nokogiri
         }
       end
 
-      def node_cache # :nodoc:
-        @node_cache ||= {}
-      end
-
       alias :to_xml :serialize
-      alias :inner_html :serialize
+      alias :clone :dup
 
       # Get the hash of namespaces on the root Nokogiri::XML::Node
       def namespaces
-        root ? root.collect_namespaces : {}
+        root ? root.namespaces : {}
+      end
+
+      ##
+      # Create a Nokogiri::XML::DocumentFragment from +tags+
+      # Returns an empty fragment if +tags+ is nil.
+      def fragment tags = nil
+        DocumentFragment.new(self, tags, self.root)
       end
 
-      undef_method :swap, :parent, :namespace
+      undef_method :swap, :parent, :namespace, :default_namespace=
+      undef_method :add_namespace_definition, :attributes
+      undef_method :namespace_definitions, :line, :add_namespace
+
+      def add_child child
+        raise "Document already has a root node" if root
+        if child.type == Node::DOCUMENT_FRAG_NODE
+          raise "Document cannot have multiple root nodes" if child.children.size > 1
+          super(child.children.first)
+        else
+          super
+        end
+      end
+      alias :<< :add_child
+
+      private
+      def implied_xpath_context
+        "/"
+      end
+
+      def inspect_attributes
+        [:name, :children]
+      end
     end
   end
 end

data/lib/nokogiri/xml/document_fragment.rb

@@ -1,9 +1,84 @@
 module Nokogiri
   module XML
-    class DocumentFragment < Node
+    class DocumentFragment < Nokogiri::XML::Node
+      ##
+      #  Create a new DocumentFragment from +tags+.
+      #
+      #  If +ctx+ is present, it is used as a context node for the
+      #  subtree created, e.g., namespaces will be resolved relative
+      #  to +ctx+.
+      def initialize document, tags = nil, ctx = nil
+        return self unless tags
+
+        children = if ctx
+                     ctx.parse(tags)
+                   else
+                     XML::Document.parse("<root>#{tags}</root>") \
+                       .xpath("/root/node()")
+                   end
+        children.each { |child| child.parent = self }
+      end
+
+      ###
+      # return the name for DocumentFragment
       def name
         '#document-fragment'
       end
+
+      ###
+      # Convert this DocumentFragment to a string
+      def to_s
+        children.to_s
+      end
+
+      ###
+      # Convert this DocumentFragment to html
+      # See Nokogiri::XML::NodeSet#to_html
+      def to_html *args
+        children.to_html(*args)
+      end
+
+      ###
+      # Convert this DocumentFragment to xhtml
+      # See Nokogiri::XML::NodeSet#to_xhtml
+      def to_xhtml *args
+        children.to_xhtml(*args)
+      end
+
+      ###
+      # Convert this DocumentFragment to xml
+      # See Nokogiri::XML::NodeSet#to_xml
+      def to_xml *args
+        children.to_xml(*args)
+      end
+
+      ###
+      # Search this fragment.  See Nokogiri::XML::Node#css
+      def css *args
+        if children.any?
+          children.css(*args)
+        else
+          NodeSet.new(document)
+        end
+      end
+
+      alias :serialize :to_s
+
+      class << self
+        ####
+        # Create a Nokogiri::XML::DocumentFragment from +tags+
+        def parse tags
+          self.new(XML::Document.new, tags)
+        end
+      end
+
+      private
+
+      def coerce data
+        return super unless String === data
+
+        document.fragment(data).children
+      end
     end
   end
 end

data/lib/nokogiri/xml/dtd.rb

@@ -1,8 +1,21 @@
 module Nokogiri
   module XML
-    class DTD < Node
-      def attributes
-        nil
+    class DTD < Nokogiri::XML::Node
+      undef_method :attribute_nodes
+      undef_method :values
+      undef_method :content
+      undef_method :namespace
+      undef_method :namespace_definitions
+      undef_method :line
+
+      def keys
+        attributes.keys
+      end
+
+      def each &block
+        attributes.each { |key, value|
+          block.call([key, value])
+        }
       end
     end
   end

data/lib/nokogiri/xml/element_content.rb

@@ -0,0 +1,36 @@
+module Nokogiri
+  module XML
+    ###
+    # Represents the allowed content in an Element Declaration inside a DTD:
+    #
+    #   <?xml version="1.0"?><?TEST-STYLE PIDATA?>
+    #   <!DOCTYPE staff SYSTEM "staff.dtd" [
+    #      <!ELEMENT div1 (head, (p | list | note)*, div2*)>
+    #   ]>
+    #   </root>
+    #
+    # ElementContent represents the tree inside the <!ELEMENT> tag shown above
+    # that lists the possible content for the div1 tag.
+    class ElementContent
+      # Possible definitions of type
+      PCDATA  = 1
+      ELEMENT = 2
+      SEQ     = 3
+      OR      = 4
+
+      # Possible content occurrences
+      ONCE    = 1
+      OPT     = 2
+      MULT    = 3
+      PLUS    = 4
+
+      attr_reader :document
+
+      ###
+      # Get the children of this ElementContent node
+      def children
+        [c1, c2].compact
+      end
+    end
+  end
+end

data/lib/nokogiri/xml/element_decl.rb

@@ -0,0 +1,13 @@
+module Nokogiri
+  module XML
+    class ElementDecl < Nokogiri::XML::Node
+      undef_method :namespace
+      undef_method :namespace_definitions
+      undef_method :line
+
+      def inspect
+        "#<#{self.class.name}:#{sprintf("0x%x", object_id)} #{to_s.inspect}>"
+      end
+    end
+  end
+end

data/lib/nokogiri/xml/entity_decl.rb

@@ -0,0 +1,19 @@
+module Nokogiri
+  module XML
+    class EntityDecl < Nokogiri::XML::Node
+      undef_method :attribute_nodes
+      undef_method :attributes
+      undef_method :namespace
+      undef_method :namespace_definitions
+      undef_method :line
+
+      def self.new name, doc, *args
+        doc.create_entity(name, *args)
+      end
+
+      def inspect
+        "#<#{self.class.name}:#{sprintf("0x%x", object_id)} #{to_s.inspect}>"
+      end
+    end
+  end
+end

data/lib/nokogiri/xml/namespace.rb

@@ -0,0 +1,13 @@
+module Nokogiri
+  module XML
+    class Namespace
+      include Nokogiri::XML::PP::Node
+      attr_reader :document
+
+      private
+      def inspect_attributes
+        [:prefix, :href]
+      end
+    end
+  end
+end

data/lib/nokogiri/xml/node.rb

@@ -34,35 +34,60 @@ module Nokogiri
     #
     # You may search this node's subtree using Node#xpath and Node#css
     class Node
+      include Nokogiri::XML::PP::Node
+      include Enumerable
+
+      # Element node type, see Nokogiri::XML::Node#element?
       ELEMENT_NODE =       1
+      # Attribute node type
       ATTRIBUTE_NODE =     2
+      # Text node type, see Nokogiri::XML::Node#text?
       TEXT_NODE =          3
+      # CDATA node type, see Nokogiri::XML::Node#cdata?
       CDATA_SECTION_NODE = 4
+      # Entity reference node type
       ENTITY_REF_NODE =    5
+      # Entity node type
       ENTITY_NODE =        6
+      # PI node type
       PI_NODE =            7
+      # Comment node type, see Nokogiri::XML::Node#comment?
       COMMENT_NODE =       8
+      # Document node type, see Nokogiri::XML::Node#xml?
       DOCUMENT_NODE =      9
+      # Document type node type
       DOCUMENT_TYPE_NODE = 10
+      # Document fragment node type
       DOCUMENT_FRAG_NODE = 11
+      # Notation node type
       NOTATION_NODE =      12
+      # HTML document node type, see Nokogiri::XML::Node#html?
       HTML_DOCUMENT_NODE = 13
+      # DTD node type
       DTD_NODE =           14
+      # Element declaration type
       ELEMENT_DECL =       15
+      # Attribute declaration type
       ATTRIBUTE_DECL =     16
+      # Entity declaration type
       ENTITY_DECL =        17
+      # Namespace declaration type
       NAMESPACE_DECL =     18
+      # XInclude start type
       XINCLUDE_START =     19
+      # XInclude end type
       XINCLUDE_END =       20
+      # DOCB document node type
       DOCB_DOCUMENT_NODE = 21
 
-      # The Document associated with this Node.
-      attr_accessor :document
+      def initialize name, document # :nodoc:
+        # ... Ya.  This is empty on purpose.
+      end
 
       ###
       # Decorate this node with the decorators set up in this node's Document
       def decorate!
-        document.decorate(self) if document
+        document.decorate(self)
       end
 
       ###
@@ -70,13 +95,17 @@ module Nokogiri
       # optional hash of namespaces may be appended.
       # See Node#xpath and Node#css.
       def search *paths
+        # TODO use         paths, handler, ns, binds = extract_params(paths)
         ns = paths.last.is_a?(Hash) ? paths.pop :
           (document.root ? document.root.namespaces : {})
+
+        prefix = "#{implied_xpath_context}/"
+
         xpath(*(paths.map { |path|
           path = path.to_s
-          path =~ /^(\.\/|\/)/ ? path : CSS.xpath_for(
+          path =~ /^(\.\/|\/|\.\.)/ ? path : CSS.xpath_for(
             path,
-            :prefix => ".//",
+            :prefix => prefix,
             :ns     => ns
           )
         }.flatten.uniq) + [ns])
@@ -84,16 +113,28 @@ module Nokogiri
       alias :/ :search
 
       ###
+      # call-seq: xpath *paths, [namespace-bindings, variable-bindings, custom-handler-class]
+      #
       # Search this node for XPath +paths+. +paths+ must be one or more XPath
-      # queries.  A hash of namespaces may be appended.  For example:
+      # queries.
       #
       #   node.xpath('.//title')
-      #   node.xpath('.//foo:name', { 'foo' => 'http://example.org/' })
+      #
+      # A hash of namespace bindings may be appended. For example:
+      #
+      #   node.xpath('.//foo:name', {'foo' => 'http://example.org/'})
       #   node.xpath('.//xmlns:name', node.root.namespaces)
       #
-      # Custom XPath functions may also be defined.  To define custom functions
-      # create a class and implement the # function you want to define.
-      # For example:
+      # A hash of variable bindings may also be appended to the namespace bindings. For example:
+      #
+      #   node.xpath('.//address[@domestic=$value]', nil, {:value => 'Yes'})
+      #
+      # Custom XPath functions may also be defined.  To define custom
+      # functions create a class and implement the function you want
+      # to define.  The first argument to the method will be the
+      # current matching NodeSet.  Any other arguments are ones that
+      # you pass in.  Note that this class may appear anywhere in the
+      # argument list.  For example:
       #
       #   node.xpath('.//title[regex(., "\w+")]', Class.new {
       #     def regex node_set, regex
@@ -102,28 +143,23 @@ module Nokogiri
       #   }.new)
       #
       def xpath *paths
-        # Pop off our custom function handler if it exists
-        handler = ![
-          Hash, String, Symbol
-        ].include?(paths.last.class) ? paths.pop : nil
-
-        ns = paths.last.is_a?(Hash) ? paths.pop :
-          (document.root ? document.root.namespaces : {})
-
         return NodeSet.new(document) unless document
 
+        paths, handler, ns, binds = extract_params(paths)
+
         sets = paths.map { |path|
           ctx = XPathContext.new(self)
           ctx.register_namespaces(ns)
-          set = ctx.evaluate(path, handler).node_set
-          set.document = document
-          document.decorate(set)
-          set
+
+          binds.each do |key,value|
+            ctx.register_variable key.to_s, value
+          end if binds
+
+          ctx.evaluate(path, handler)
         }
         return sets.first if sets.length == 1
 
         NodeSet.new(document) do |combined|
-          document.decorate(combined)
           sets.each do |set|
             set.each do |node|
               combined << node
@@ -133,47 +169,83 @@ module Nokogiri
       end
 
       ###
+      # call-seq: css *rules, [namespace-bindings, custom-pseudo-class]
+      #
       # Search this node for CSS +rules+. +rules+ must be one or more CSS
-      # selectors.  For example:
+      # selectors. For example:
       #
       #   node.css('title')
       #   node.css('body h1.bold')
       #   node.css('div + p.green', 'div#one')
       #
-      # Custom CSS pseudo classes may also be defined.  To define custom pseudo
-      # classes, create a class and implement the custom pseudo class you
-      # want defined.  The first argument to the method will be the current
-      # matching NodeSet.  Any other arguments are ones that you pass in.
-      # For example:
+      # A hash of namespace bindings may be appended. For example:
+      #
+      #   node.css('bike|tire', {'bike' => 'http://schwinn.com/'})
+      #
+      # Custom CSS pseudo classes may also be defined.  To define
+      # custom pseudo classes, create a class and implement the custom
+      # pseudo class you want defined.  The first argument to the
+      # method will be the current matching NodeSet.  Any other
+      # arguments are ones that you pass in.  For example:
       #
       #   node.css('title:regex("\w+")', Class.new {
       #     def regex node_set, regex
       #       node_set.find_all { |node| node['some_attribute'] =~ /#{regex}/ }
       #     end
-      #   })
+      #   }.new)
+      #
+      # Note that the CSS query string is case-sensitive with regards
+      # to your document type. That is, if you're looking for "H1" in
+      # an HTML document, you'll never find anything, since HTML tags
+      # will match only lowercase CSS queries. However, "H1" might be
+      # found in an XML document, where tags names are case-sensitive
+      # (e.g., "H1" is distinct from "h1").
       #
       def css *rules
-        # Pop off our custom function handler if it exists
-        handler = ![
-          Hash, String, Symbol
-        ].include?(rules.last.class) ? rules.pop : nil
+        rules, handler, ns, binds = extract_params(rules)
 
-        ns = rules.last.is_a?(Hash) ? rules.pop :
-          (document.root ? document.root.namespaces : {})
+        prefix = "#{implied_xpath_context}/"
 
         rules = rules.map { |rule|
-          CSS.xpath_for(rule, :prefix => ".//", :ns => ns)
-        }.flatten.uniq + [ns, handler].compact
+          CSS.xpath_for(rule, :prefix => prefix, :ns => ns)
+        }.flatten.uniq + [ns, handler, binds].compact
 
         xpath(*rules)
       end
 
+      ###
+      # Search this node's immediate children using CSS selector +selector+
+      def > selector
+        ns = document.root.namespaces
+        xpath CSS.xpath_for(selector, :prefix => "./", :ns => ns).first
+      end
+
       ###
       # Search for the first occurrence of +path+.
+      #
       # Returns nil if nothing is found, otherwise a Node.
       def at path, ns = document.root ? document.root.namespaces : {}
         search(path, ns).first
       end
+      alias :% :at
+
+      ##
+      # Search this node for the first occurrence of XPath +paths+.
+      # Equivalent to <tt>xpath(paths).first</tt>
+      # See Node#xpath for more information.
+      #
+      def at_xpath *paths
+        xpath(*paths).first
+      end
+
+      ##
+      # Search this node for the first occurrence of CSS +rules+.
+      # Equivalent to <tt>css(rules).first</tt>
+      # See Node#css for more information.
+      #
+      def at_css *rules
+        css(*rules).first
+      end
 
       ###
       # Get the attribute value for the attribute +name+
@@ -182,10 +254,172 @@ module Nokogiri
         get(name.to_s)
       end
 
+      ###
+      # Add +node_or_tags+ as a child of this Node.
+      # +node_or_tags+ can be a Nokogiri::XML::Node, a ::DocumentFragment, a ::NodeSet, or a string containing markup.
+      #
+      # Returns the reparented node (if +node_or_tags+ is a Node), or NodeSet (if +node_or_tags+ is a DocumentFragment, NodeSet, or string).
+      def add_child node_or_tags
+        node_or_tags = coerce(node_or_tags)
+        if node_or_tags.is_a?(XML::NodeSet)
+          node_or_tags.each { |n| add_child_node n }
+        else
+          add_child_node node_or_tags
+        end
+        node_or_tags
+      end
+
+      ###
+      # Insert +node_or_tags+ before this Node (as a sibling).
+      # +node_or_tags+ can be a Nokogiri::XML::Node, a ::DocumentFragment, a ::NodeSet, or a string containing markup.
+      #
+      # Returns the reparented node (if +node_or_tags+ is a Node), or NodeSet (if +node_or_tags+ is a DocumentFragment, NodeSet, or string).
+      #
+      # Also see related method +before+.
+      def add_previous_sibling node_or_tags
+        node_or_tags = coerce(node_or_tags)
+        if node_or_tags.is_a?(XML::NodeSet)
+          if text?
+            pivot = Nokogiri::XML::Node.new 'dummy', document
+            add_previous_sibling_node pivot
+          else
+            pivot = self
+          end
+          node_or_tags.each { |n| pivot.send :add_previous_sibling_node, n }
+          pivot.unlink if text?
+        else
+          add_previous_sibling_node node_or_tags
+        end
+        node_or_tags
+      end
+
+      ###
+      # Insert +node_or_tags+ after this Node (as a sibling).
+      # +node_or_tags+ can be a Nokogiri::XML::Node, a ::DocumentFragment, a ::NodeSet, or a string containing markup.
+      #
+      # Returns the reparented node (if +node_or_tags+ is a Node), or NodeSet (if +node_or_tags+ is a DocumentFragment, NodeSet, or string).
+      #
+      # Also see related method +after+.
+      def add_next_sibling node_or_tags
+        node_or_tags = coerce(node_or_tags)
+        if node_or_tags.is_a?(XML::NodeSet)
+          if text?
+            pivot = Nokogiri::XML::Node.new 'dummy', document
+            add_next_sibling_node pivot
+          else
+            pivot = self
+          end
+          node_or_tags.reverse.each { |n| pivot.send :add_next_sibling_node, n }
+          pivot.unlink if text?
+        else
+          add_next_sibling_node node_or_tags
+        end
+        node_or_tags
+      end
+
+      ####
+      # Insert +node_or_tags+ before this node (as a sibling).
+      # +node_or_tags+ can be a Nokogiri::XML::Node, a ::DocumentFragment, a ::NodeSet, or a string containing markup.
+      #
+      # Returns self, to support chaining of calls.
+      #
+      # Also see related method +add_previous_sibling+.
+      def before node_or_tags
+        add_previous_sibling node_or_tags
+        self
+      end
+
+      ####
+      # Insert +node_or_tags+ after this node (as a sibling).
+      # +node_or_tags+ can be a Nokogiri::XML::Node, a Nokogiri::XML::DocumentFragment, or a string containing markup.
+      #
+      # Returns self, to support chaining of calls.
+      #
+      # Also see related method +add_next_sibling+.
+      def after node_or_tags
+        add_next_sibling node_or_tags
+        self
+      end
+
+      ####
+      # Set the inner html for this Node to +node_or_tags+
+      # +node_or_tags+ can be a Nokogiri::XML::Node, a Nokogiri::XML::DocumentFragment, or a string containing markup.
+      #
+      # Returns self.
+      #
+      # Also see related method +children=+
+      def inner_html= node_or_tags
+        self.children = node_or_tags
+        self
+      end
+
+      ####
+      # Set the inner html for this Node +node_or_tags+
+      # +node_or_tags+ can be a Nokogiri::XML::Node, a Nokogiri::XML::DocumentFragment, or a string containing markup.
+      #
+      # Returns the reparented node (if +node_or_tags+ is a Node), or NodeSet (if +node_or_tags+ is a DocumentFragment, NodeSet, or string).
+      #
+      # Also see related method +inner_html=+
+      def children= node_or_tags
+        node_or_tags = coerce(node_or_tags)
+        children.unlink
+        if node_or_tags.is_a?(XML::NodeSet)
+          node_or_tags.each { |n| add_child_node n }
+        else
+          add_child node_or_tags
+        end
+        node_or_tags
+      end
+
+      ####
+      # Replace this Node with +node_or_tags+.
+      # +node_or_tags+ can be a Nokogiri::XML::Node, a ::DocumentFragment, a ::NodeSet, or a string containing markup.
+      #
+      # Returns the reparented node (if +node_or_tags+ is a Node), or NodeSet (if +node_or_tags+ is a DocumentFragment, NodeSet, or string).
+      #
+      # Also see related method +swap+.
+      def replace node_or_tags
+        node_or_tags = coerce(node_or_tags)
+        if node_or_tags.is_a?(XML::NodeSet)
+          if text?
+            replacee = Nokogiri::XML::Node.new 'dummy', document
+            add_previous_sibling_node replacee
+            unlink
+          else
+            replacee = self
+          end
+          node_or_tags.each { |n| replacee.add_previous_sibling n }
+          replacee.unlink
+        else
+          replace_node node_or_tags
+        end
+        node_or_tags
+      end
+
+      ####
+      # Swap this Node for +node_or_tags+
+      # +node_or_tags+ can be a Nokogiri::XML::Node, a ::DocumentFragment, a ::NodeSet, or a string containing markup.
+      #
+      # Returns self, to support chaining of calls.
+      #
+      # Also see related method +replace+.
+      def swap node_or_tags
+        replace node_or_tags
+        self
+      end
+
       alias :next           :next_sibling
       alias :previous       :previous_sibling
+
+      # :stopdoc:
+      # HACK: This is to work around an RDoc bug
+      alias :next=          :add_next_sibling
+      # :startdoc:
+
+      alias :previous=      :add_previous_sibling
       alias :remove         :unlink
       alias :get_attribute  :[]
+      alias :attr           :[]
       alias :set_attribute  :[]=
       alias :text           :content
       alias :inner_text     :content
@@ -195,10 +429,15 @@ module Nokogiri
       alias :name=          :node_name=
       alias :type           :node_type
       alias :to_str         :text
+      alias :clone          :dup
+      alias :elements       :element_children
 
       ####
-      # Returns a hash containing the node's attributes.  The key is the
-      # attribute name, the value is the string value of the attribute.
+      # Returns a hash containing the node's attributes.  The key is
+      # the attribute name without any namespace, the value is a Nokogiri::XML::Attr
+      # representing the attribute.
+      # If you need to distinguish attributes with the same name, with different namespaces
+      # use #attribute_nodes instead.
       def attributes
         Hash[*(attribute_nodes.map { |node|
           [node.node_name, node]
@@ -221,7 +460,7 @@ module Nokogiri
       # Iterate over each attribute name and value pair for this Node.
       def each &block
         attribute_nodes.each { |node|
-          block.call(node.node_name, node.value)
+          block.call([node.node_name, node.value])
         }
       end
 
@@ -232,62 +471,51 @@ module Nokogiri
       end
       alias :delete :remove_attribute
 
-      ####
-      # Create nodes from +data+ and insert them before this node
-      # (as a sibling).
-      def before data
-        fragment(data).children.each do |node|
-          add_previous_sibling node
-        end
-        self
-      end
-
-      ####
-      # Create nodes from +data+ and insert them after this node
-      # (as a sibling).
-      def after data
-        fragment(data).children.to_a.reverse.each do |node|
-          add_next_sibling node
-        end
-        self
+      ###
+      # Returns true if this Node matches +selector+
+      def matches? selector
+        ancestors.last.search(selector).include?(self)
       end
 
-      ####
-      # Swap this Node for new nodes made from +data+
-      def swap data
-        before(data)
-        remove
-        self
+      ###
+      # Create a DocumentFragment containing +tags+ that is relative to _this_
+      # context node.
+      def fragment tags
+        type = document.html? ? Nokogiri::HTML : Nokogiri::XML
+        type::DocumentFragment.new(document, tags, self)
       end
 
-      ####
-      # Set the inner_html for this Node to +tags+
-      def inner_html= tags
-        children.each { |x| x.remove}
-
-        fragment(tags).children.to_a.reverse.each do |node|
-          add_child node
+      ###
+      # Parse +string_or_io+ as a document fragment within the context of
+      # *this* node.  Returns a XML::NodeSet containing the nodes parsed from
+      # +string_or_io+.
+      def parse string_or_io, options = nil
+        options ||= (document.html? ? ParseOptions::DEFAULT_HTML : ParseOptions::DEFAULT_XML)
+        if Fixnum === options
+          options = Nokogiri::XML::ParseOptions.new(options)
         end
-        self
-      end
-
-      ####
-      # Create a Nokogiri::XML::DocumentFragment from +tags+
-      def fragment tags
-        classes = document.class.name.split('::')
-        classes[-1] = 'SAX::Parser'
-
-
-        fragment = DocumentFragment.new(self.document)
-        parser = eval(classes.join('::')).new(
-          FragmentHandler.new(fragment, tags)
-        )
-        parser.parse(tags)
-        fragment
+        # Give the options to the user
+        yield options if block_given?
+
+        contents = string_or_io.respond_to?(:read) ?
+          string_or_io.read :
+          string_or_io
+
+        return Nokogiri::XML::NodeSet.new(document) if contents.empty?
+
+        ##
+        # This is a horrible hack, but I don't care. See #313 for background.
+        error_count = document.errors.length
+        node_set = in_context(contents, options.to_i)
+        if node_set.empty? and document.errors.length > error_count and options.recover?
+          fragment = Nokogiri::HTML::DocumentFragment.parse contents
+          node_set = fragment.children
+        end
+        node_set
       end
 
       ####
-      # Set the content to +string+.
+      # Set the Node's content to a Text node containing +string+. The string gets XML escaped, not interpreted as markup.
       def content= string
         self.native_content = encode_special_chars(string.to_s)
       end
@@ -299,6 +527,33 @@ module Nokogiri
         parent_node
       end
 
+      ###
+      # Returns a Hash of {prefix => value} for all namespaces on this
+      # node and its ancestors.
+      #
+      # This method returns the same namespaces as #namespace_scopes.
+      #
+      # Returns namespaces in scope for self -- those defined on self
+      # element directly or any ancestor node -- as a Hash of
+      # attribute-name/value pairs. Note that the keys in this hash
+      # XML attributes that would be used to define this namespace,
+      # such as "xmlns:prefix", not just the prefix. Default namespace
+      # set on self will be included with key "xmlns". However,
+      # default namespaces set on ancestor will NOT be, even if self
+      # has no explicit default namespace.
+      def namespaces
+        Hash[*namespace_scopes.map { |nd|
+          key = ['xmlns', nd.prefix].compact.join(':')
+          if RUBY_VERSION >= '1.9' && document.encoding
+            begin
+              key.force_encoding document.encoding
+            rescue ArgumentError
+            end
+          end
+          [key, nd.href]
+        }.flatten]
+      end
+
       # Returns true if this is a Comment
       def comment?
         type == COMMENT_NODE
@@ -324,6 +579,21 @@ module Nokogiri
         type == TEXT_NODE
       end
 
+      # Returns true if this is a DocumentFragment
+      def fragment?
+        type == DOCUMENT_FRAG_NODE
+      end
+
+      ###
+      # Fetch the Nokogiri::HTML::ElementDescription for this node.  Returns
+      # nil on XML documents and on unknown tags.
+      def description
+        return nil if document.xml?
+        Nokogiri::HTML::ElementDescription[name]
+      end
+
+      ###
+      # Is this a read only node?
       def read_only?
         # According to gdome2, these are read-only node types
         [NOTATION_NODE, ENTITY_NODE, ENTITY_DECL].include?(type)
@@ -335,12 +605,16 @@ module Nokogiri
       end
       alias :elem? :element?
 
+      ###
+      # Turn this node in to a string.  If the document is HTML, this method
+      # returns html.  If the document is XML, this method returns XML.
       def to_s
         document.xml? ? to_xml : to_html
       end
 
-      def inner_html
-        children.map { |x| x.to_html }.join
+      # Get the inner_html for this node's Node#children
+      def inner_html *args
+        children.map { |x| x.to_html(*args) }.join
       end
 
       # Get the path to this node as a CSS expression
@@ -350,44 +624,70 @@ module Nokogiri
         }.compact.join(' > ')
       end
 
-      #  recursively get all namespaces from this node and its subtree
-      def collect_namespaces
-        # TODO: print warning message if a prefix refers to more than one URI in the document?
-        ns = {}
-        traverse {|j| ns.merge!(j.namespaces)}
-        ns
-      end
-
       ###
-      # Get a list of ancestor Node for this Node
-      def ancestors
-        return [] unless respond_to?(:parent)
+      # Get a list of ancestor Node for this Node.  If +selector+ is given,
+      # the ancestors must match +selector+
+      def ancestors selector = nil
+        return NodeSet.new(document) unless respond_to?(:parent)
+        return NodeSet.new(document) unless parent
 
         parents = [parent]
 
         while parents.last.respond_to?(:parent)
-          parents << parents.last.parent
+          break unless ctx_parent = parents.last.parent
+          parents << ctx_parent
         end
-        parents
+
+        return NodeSet.new(document, parents) unless selector
+
+        root = parents.last
+
+        NodeSet.new(document, parents.find_all { |parent|
+          root.search(selector).include?(parent)
+        })
+      end
+
+      ###
+      # Adds a default namespace supplied as a string +url+ href, to self.
+      # The consequence is as an xmlns attribute with supplied argument were
+      # present in parsed XML.  A default namespace set with this method will
+      # now show up in #attributes, but when this node is serialized to XML an
+      # "xmlns" attribute will appear. See also #namespace and #namespace=
+      def default_namespace= url
+        add_namespace_definition(nil, url)
+      end
+      alias :add_namespace :add_namespace_definition
+
+      ###
+      # Set the default namespace on this node (as would be defined with an
+      # "xmlns=" attribute in XML source), as a Namespace object +ns+. Note that
+      # a Namespace added this way will NOT be serialized as an xmlns attribute
+      # for this node. You probably want #default_namespace= instead, or perhaps
+      # #add_namespace_definition with a nil prefix argument.
+      def namespace= ns
+        return set_namespace(ns) unless ns
+
+        unless Nokogiri::XML::Namespace === ns
+          raise TypeError, "#{ns.class} can't be coerced into Nokogiri::XML::Namespace"
+        end
+        if ns.document != document
+          raise ArgumentError, 'namespace must be declared on the same document'
+        end
+
+        set_namespace ns
       end
 
       ####
       # Yields self and all children to +block+ recursively.
-      def traverse(&block)
+      def traverse &block
         children.each{|j| j.traverse(&block) }
         block.call(self)
       end
 
-      ####
-      #  replace node with the new node in the document.
-      def replace(new_node)
-        if new_node.is_a?(Document) || !new_node.is_a?(XML::Node)
-          raise ArgumentError, <<-EOERR
-Node.replace requires a Node argument, and cannot accept a Document.
-(You probably want to select a node from the Document with at() or search(), or create a new Node via Node.new().)
-          EOERR
-        end
-        replace_with_node new_node
+      ###
+      # Accept a visitor.  This method calls "visit" on +visitor+ with self.
+      def accept visitor
+        visitor.visit(self)
       end
 
       ###
@@ -399,97 +699,192 @@ Node.replace requires a Node argument, and cannot accept a Document.
       end
 
       ###
-      # Serialize Node using +encoding+ and +save_options+.  Save options 
-      # can also be set using a block. See SaveOptions.
+      # Serialize Node using +options+.  Save options can also be set using a
+      # block. See SaveOptions.
       #
       # These two statements are equivalent:
       #
-      #  node.serialize('UTF-8', FORMAT | AS_XML)
+      #  node.serialize(:encoding => 'UTF-8', :save_with => FORMAT | AS_XML)
       #
       # or
       #
-      #   node.serialize('UTF-8') do |config|
+      #   node.serialize(:encoding => 'UTF-8') do |config|
       #     config.format.as_xml
       #   end
       #
-      def serialize encoding = nil, save_options = SaveOptions::FORMAT, &block
-        io = StringIO.new
-        write_to io, encoding, save_options, &block
-        io.rewind
-        io.read
+      def serialize *args, &block
+        options = args.first.is_a?(Hash) ? args.shift : {
+          :encoding   => args[0],
+          :save_with  => args[1] || SaveOptions::FORMAT
+        }
+
+        encoding = options[:encoding] || document.encoding
+
+        outstring = ""
+        if encoding && outstring.respond_to?(:force_encoding)
+          outstring.force_encoding(Encoding.find(encoding))
+        end
+        io = StringIO.new(outstring)
+        write_to io, options, &block
+        io.string
       end
 
       ###
-      # Serialize this Node to HTML using +encoding+
-      def to_html encoding = nil
+      # Serialize this Node to HTML
+      #
+      #   doc.to_html
+      #
+      # See Node#write_to for a list of +options+.  For formatted output,
+      # use Node#to_xhtml instead.
+      def to_html options = {}
         # FIXME: this is a hack around broken libxml versions
         return dump_html if %w[2 6] === LIBXML_VERSION.split('.')[0..1]
 
-        serialize(encoding, SaveOptions::FORMAT |
-                            SaveOptions::NO_DECLARATION |
-                            SaveOptions::NO_EMPTY_TAGS |
-                            SaveOptions::AS_HTML)
+        options[:save_with] ||= SaveOptions::DEFAULT_HTML
+        serialize(options)
       end
 
       ###
-      # Serialize this Node to XML using +encoding+
-      def to_xml encoding = nil
-        serialize(encoding, SaveOptions::FORMAT | SaveOptions::AS_XML)
+      # Serialize this Node to XML using +options+
+      #
+      #   doc.to_xml(:indent => 5, :encoding => 'UTF-8')
+      #
+      # See Node#write_to for a list of +options+
+      def to_xml options = {}
+        options[:save_with] ||= SaveOptions::DEFAULT_XML
+        serialize(options)
       end
 
       ###
-      # Serialize this Node to XML using +encoding+
-      def to_xhtml encoding = nil
+      # Serialize this Node to XHTML using +options+
+      #
+      #   doc.to_xhtml(:indent => 5, :encoding => 'UTF-8')
+      #
+      # See Node#write_to for a list of +options+
+      def to_xhtml options = {}
         # FIXME: this is a hack around broken libxml versions
         return dump_html if %w[2 6] === LIBXML_VERSION.split('.')[0..1]
 
-        serialize(encoding, SaveOptions::FORMAT |
-                            SaveOptions::NO_DECLARATION |
-                            SaveOptions::NO_EMPTY_TAGS |
-                            SaveOptions::AS_XHTML)
+        options[:save_with] ||= SaveOptions::DEFAULT_XHTML
+        serialize(options)
       end
 
       ###
-      # Write Node to +io+ with +encoding+ and +save_options+
-      def write_to io, encoding = nil, save_options = SaveOptions::FORMAT
-        config = SaveOptions.new(save_options)
+      # Write Node to +io+ with +options+. +options+ modify the output of
+      # this method.  Valid options are:
+      #
+      # * +:encoding+ for changing the encoding
+      # * +:indent_text+ the indentation text, defaults to one space
+      # * +:indent+ the number of +:indent_text+ to use, defaults to 2
+      # * +:save_with+ a combination of SaveOptions constants.
+      #
+      # To save with UTF-8 indented twice:
+      #
+      #   node.write_to(io, :encoding => 'UTF-8', :indent => 2)
+      #
+      # To save indented with two dashes:
+      #
+      #   node.write_to(io, :indent_text => '-', :indent => 2
+      #
+      def write_to io, *options
+        options       = options.first.is_a?(Hash) ? options.shift : {}
+        encoding      = options[:encoding] || options[0]
+        save_options  = options[:save_with] || options[1] || SaveOptions::FORMAT
+        indent_text   = options[:indent_text] || ' '
+        indent_times  = options[:indent] || 2
+
+
+        config = SaveOptions.new(save_options.to_i)
         yield config if block_given?
 
-        native_write_to(io, encoding, config.options)
+        native_write_to(io, encoding, indent_text * indent_times, config.options)
+      end
+
+      ###
+      # Write Node as HTML to +io+ with +options+
+      #
+      # See Node#write_to for a list of +options+
+      def write_html_to io, options = {}
+        # FIXME: this is a hack around broken libxml versions
+        return (io << dump_html) if %w[2 6] === LIBXML_VERSION.split('.')[0..1]
+
+        options[:save_with] ||= SaveOptions::DEFAULT_HTML
+        write_to io, options
       end
 
       ###
-      # Write Node as HTML to +io+ with +encoding+
-      def write_html_to io, encoding = nil
-        write_to io, encoding, SaveOptions::FORMAT |
-          SaveOptions::NO_DECLARATION |
-          SaveOptions::NO_EMPTY_TAGS |
-          SaveOptions::AS_HTML
+      # Write Node as XHTML to +io+ with +options+
+      #
+      # See Node#write_to for a list of +options+
+      def write_xhtml_to io, options = {}
+        # FIXME: this is a hack around broken libxml versions
+        return (io << dump_html) if %w[2 6] === LIBXML_VERSION.split('.')[0..1]
+
+        options[:save_with] ||= SaveOptions::DEFAULT_XHTML
+        write_to io, options
       end
 
       ###
-      # Write Node as XHTML to +io+ with +encoding+
-      def write_xhtml_to io, encoding = nil
-        write_to io, encoding, SaveOptions::FORMAT |
-          SaveOptions::NO_DECLARATION |
-          SaveOptions::NO_EMPTY_TAGS |
-          SaveOptions::AS_XHTML
+      # Write Node as XML to +io+ with +options+
+      #
+      #   doc.write_xml_to io, :encoding => 'UTF-8'
+      #
+      # See Node#write_to for a list of options
+      def write_xml_to io, options = {}
+        options[:save_with] ||= SaveOptions::DEFAULT_XML
+        write_to io, options
       end
 
       ###
-      # Write Node as XML to +io+ with +encoding+
-      def write_xml_to io, encoding = nil
-        write_to io, encoding, SaveOptions::FORMAT | SaveOptions::AS_XML
+      # Compare two Node objects with respect to their Document.  Nodes from
+      # different documents cannot be compared.
+      def <=> other
+        return nil unless other.is_a?(Nokogiri::XML::Node)
+        return nil unless document == other.document
+        compare other
       end
 
-      # Create a new node from +string+
-      #
-      # THIS METHOD IS DEPRECATED
-      # This method is deprecated and will be removed in 1.3.0 or by
-      # March 1, 2009. Instead, use Nokogiri::XML::Node#fragment()
-      def self.new_from_str string
-        $stderr.puts("This method is deprecated and will be removed in 1.3.0 or by March 1, 2009. Instead, use Nokogiri::XML::Node#fragment")
-        Nokogiri::HTML.fragment(string).first
+      private
+
+      def extract_params params # :nodoc:
+        # Pop off our custom function handler if it exists
+        handler = params.find { |param|
+          ![Hash, String, Symbol].include?(param.class)
+        }
+
+        params -= [handler] if handler
+
+        hashes = []
+        hashes << params.pop while Hash === params.last || params.last.nil?
+
+        ns, binds = hashes.reverse
+
+        ns ||= document.root ? document.root.namespaces : {}
+
+        [params, handler, ns, binds]
+      end
+
+      def coerce data # :nodoc:
+        return data                    if data.is_a?(XML::NodeSet)
+        return data.children           if data.is_a?(XML::DocumentFragment)
+        return fragment(data).children if data.is_a?(String)
+
+        if data.is_a?(Document) || !data.is_a?(XML::Node)
+          raise ArgumentError, <<-EOERR
+Requires a Node, NodeSet or String argument, and cannot accept a #{data.class}.
+(You probably want to select a node from the Document with at() or search(), or create a new Node via Node.new().)
+          EOERR
+        end
+
+        data
+      end
+
+      def implied_xpath_context
+        "./"
+      end
+
+      def inspect_attributes
+        [:name, :namespace, :attribute_nodes, :children]
       end
     end
   end