nokogiri 1.2.3 → 1.3.0

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/document.rb

@@ -11,6 +11,9 @@ module Nokogiri
       # A list of Nokogiri::XML::SyntaxError found when parsing a document
       attr_accessor :errors
 
+      def initialize *args
+      end
+
       # The name of this document.  Always returns "document"
       def name
         'document'
@@ -22,7 +25,7 @@ module Nokogiri
       end
 
       # Get the list of decorators given +key+
-      def decorators(key)
+      def decorators key
         @decorators ||= Hash.new
         @decorators[key] ||= []
       end
@@ -40,7 +43,7 @@ module Nokogiri
 
       ###
       # 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,10 +51,6 @@ module Nokogiri
         }
       end
 
-      def node_cache # :nodoc:
-        @node_cache ||= {}
-      end
-
       alias :to_xml :serialize
       alias :inner_html :serialize
 
@@ -60,7 +59,41 @@ module Nokogiri
         root ? root.collect_namespaces : {}
       end
 
+      ####
+      # Create a Nokogiri::XML::DocumentFragment from +tags+
+      def fragment tags
+        DocumentFragment.new(self, tags)
+      end
+
       undef_method :swap, :parent, :namespace
+
+      class << self
+        ###
+        # 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::PARSE_RECOVER.  See the constants in
+        # Nokogiri::XML.
+        def parse string_or_io, url = nil, encoding = nil, options = 2145, &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 self.read_io(string_or_io, url, encoding, options.to_i)
+          end
+
+          # read_memory pukes on empty docs
+          return self.new if string_or_io.nil? or string_or_io.empty?
+
+          self.read_memory(string_or_io, url, encoding, options.to_i)
+        end
+      end
+
     end
   end
 end

data/lib/nokogiri/xml/document_fragment.rb

@@ -1,9 +1,49 @@
 module Nokogiri
   module XML
-    class DocumentFragment < Node
+    class DocumentFragment < Nokogiri::XML::Node
+      def initialize document, tags=nil
+        if tags
+          parser = if self.kind_of?(Nokogiri::HTML::DocumentFragment)
+                     HTML::SAX::Parser.new(FragmentHandler.new(self, tags))
+                   else
+                     XML::SAX::Parser.new(FragmentHandler.new(self, tags))
+                   end
+          parser.parse(tags)
+        end
+      end
+
+      ###
+      # return the name for DocumentFragment
       def name
         '#document-fragment'
       end
+
+      def to_s
+        children.to_s
+      end
+
+      def to_html *args
+        children.to_html(*args)
+      end
+
+      def to_xhtml *args
+        children.to_xhtml(*args)
+      end
+
+      def to_xml *args
+        children.to_xml(*args)
+      end
+
+      alias :serialize :to_s
+
+      class << self
+        ####
+        # Create a Nokogiri::XML::DocumentFragment from +tags+
+        def parse tags
+          XML::DocumentFragment.new(XML::Document.new, tags)
+        end
+      end
+
     end
   end
 end

data/lib/nokogiri/xml/dtd.rb

@@ -1,6 +1,8 @@
 module Nokogiri
   module XML
-    class DTD < Node
+    class DTD < Nokogiri::XML::Node
+      ###
+      # Return attributes for DTD.  Always returns +nil+
       def attributes
         nil
       end

data/lib/nokogiri/xml/entity_declaration.rb

@@ -1,6 +1,8 @@
 module Nokogiri
   module XML
-    class EntityDeclaration < Node
+    class EntityDeclaration < Nokogiri::XML::Node
+      ###
+      # return attributes.  Always returns +nil+
       def attributes
         nil
       end

data/lib/nokogiri/xml/fragment_handler.rb

@@ -3,16 +3,37 @@ module Nokogiri
     class FragmentHandler < Nokogiri::XML::SAX::Document # :nodoc:
       def initialize node, original_html
         @doc_started    = false
-        @original_html  = original_html
         @document       = node.document
         @stack          = [node]
+        @klass          = if node.kind_of?(Nokogiri::HTML::DocumentFragment)
+                            Nokogiri::HTML::DocumentFragment
+                          else
+                            Nokogiri::XML::DocumentFragment
+                          end
+        #
+        # the regexes used in start_element() and characters() anchor at
+        # start-of-line, but we really only want them to anchor at
+        # start-of-doc. so let's only save up to the first newline.
+        #
+        # this implementation choice was the result of some benchmarks, if
+        # you're curious: http://gist.github.com/115936
+        #
+        newline_index = original_html.index("\n")
+        @original_html = if newline_index
+                           original_html[0,newline_index]
+                         else
+                           original_html
+                         end
       end
 
       def start_element name, attrs = []
-        @doc_started = true if @original_html =~ /^<#{name}/
+        regex = (@klass == Nokogiri::HTML::DocumentFragment) ? %r{^\s*<#{Regexp.escape(name)}}i \
+                                                             : %r{^\s*<#{Regexp.escape(name)}}
+        @doc_started = true if @original_html =~ regex
         return unless @doc_started
 
         node = Node.new(name, @document)
+        attrs << "" unless (attrs.length % 2) == 0
         Hash[*attrs].each do |k,v|
           node[k] = v
         end
@@ -21,7 +42,7 @@ module Nokogiri
       end
 
       def characters string
-        @doc_started = true if @original_html =~ /^\s*#{string}/
+        @doc_started = true if @original_html.strip =~ %r{^\s*#{Regexp.escape(string.strip)}}
         @stack.last << Nokogiri::XML::Text.new(string, @document)
       end
 

data/lib/nokogiri/xml/namespace.rb

@@ -0,0 +1,7 @@
+module Nokogiri
+  module XML
+    class Namespace
+      attr_reader :document
+    end
+  end
+end

data/lib/nokogiri/xml/node.rb

@@ -34,35 +34,57 @@ module Nokogiri
     #
     # You may search this node's subtree using Node#xpath and Node#css
     class Node
+      # 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
+        # ... 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
 
       ###
@@ -150,7 +172,7 @@ module Nokogiri
       #     def regex node_set, regex
       #       node_set.find_all { |node| node['some_attribute'] =~ /#{regex}/ }
       #     end
-      #   })
+      #   }.new)
       #
       def css *rules
         # Pop off our custom function handler if it exists
@@ -174,6 +196,7 @@ module Nokogiri
       def at path, ns = document.root ? document.root.namespaces : {}
         search(path, ns).first
       end
+      alias :% :at
 
       ###
       # Get the attribute value for the attribute +name+
@@ -195,6 +218,7 @@ module Nokogiri
       alias :name=          :node_name=
       alias :type           :node_type
       alias :to_str         :text
+      alias :clone          :dup
 
       ####
       # Returns a hash containing the node's attributes.  The key is the
@@ -232,6 +256,12 @@ module Nokogiri
       end
       alias :delete :remove_attribute
 
+      ###
+      # Returns true if this Node matches +selector+
+      def matches? selector
+        document.search(selector).include?(self)
+      end
+
       ####
       # Create nodes from +data+ and insert them before this node
       # (as a sibling).
@@ -271,23 +301,13 @@ module Nokogiri
         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
+      def fragment tags # :nodoc:
+        # TODO: deprecate?
+        document.fragment(tags)
       end
 
       ####
-      # Set the content to +string+.
+      # Set the Node content to +string+.  The content gets XML escaped.
       def content= string
         self.native_content = encode_special_chars(string.to_s)
       end
@@ -299,6 +319,21 @@ module Nokogiri
         parent_node
       end
 
+      ###
+      # Get a hash containing the Namespace definitions for this Node
+      def namespaces
+        Hash[*namespace_definitions.map { |nd|
+          key = ['xmlns', nd.prefix].compact.join(':')
+          if defined?(Encoding) && 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 +359,16 @@ module Nokogiri
         type == TEXT_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,10 +380,14 @@ 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
 
+      # Get the inner_html for this node's Node#children
       def inner_html
         children.map { |x| x.to_html }.join
       end
@@ -359,27 +408,60 @@ module Nokogiri
       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
+
+        NodeSet.new(document, parents.find_all { |parent|
+          parent.matches?(selector)
+        })
+      end
+
+      ###
+      # Set the default namespace for this node to +url+
+      def default_namespace= url
+        add_namespace_definition(nil, url)
+      end
+      alias :add_namespace :add_namespace_definition
+
+      ###
+      # Set the namespace for this node to +ns+
+      def namespace= ns
+        if ns.document != document
+          raise ArgumentError, 'namespace must be declared on the same document'
+        end
+        unless ns.is_a? Nokogiri::XML::Namespace
+          raise TypeError, "#{ns.class} can't be coerced into Nokogiri::XML::Namespace"
+        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
 
+      ###
+      # Accept a visitor.  This method calls "visit" on +visitor+ with self.
+      def accept visitor
+        visitor.visit(self)
+      end
+
       ####
-      #  replace node with the new node in the document.
+      #  replace this 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
@@ -399,97 +481,264 @@ Node.replace requires a Node argument, and cannot accept a Document.
       end
 
       ###
-      # Serialize Node using +encoding+ and +save_options+.  Save options 
+      # 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
+      def serialize *args, &block
+        if args.first && !args.first.is_a?(Hash)
+          $stderr.puts(<<-eowarn)
+#{self.class}#serialize(encoding, save_opts) is deprecated and will be removed in
+Nokogiri version 1.4.0 *or* after June 1 2009.
+You called serialize from here:
+
+  #{caller.first}
+
+Please change to #{self.class}#serialize(:encoding => enc, :save_with => opts)
+          eowarn
+        end
+
+        options = args.first.is_a?(Hash) ? args.shift : {
+          :encoding   => args[0],
+          :save_with  => args[1] || SaveOptions::FORMAT
+        }
+
         io = StringIO.new
-        write_to io, encoding, save_options, &block
+        write_to io, options, &block
         io.rewind
         io.read
       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 = {}
+        if options.is_a?(String)
+          $stderr.puts(<<-eowarn)
+Node#to_html(encoding) is deprecated and will be removed in
+Nokogiri version 1.4.0 *or* after June 1 2009.
+You called to_html from here:
+
+  #{caller.first}
+
+Please change to Node#to_html(:encoding => #{options})
+          eowarn
+          options = { :encoding => options }
+        end
+
         # 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::FORMAT |
+                                SaveOptions::NO_DECLARATION |
+                                SaveOptions::NO_EMPTY_TAGS |
+                                SaveOptions::AS_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 = {}
+        encoding = nil
+
+        # FIXME add a deprecation warning
+        if options.is_a? String
+          $stderr.puts(<<-eowarn)
+Node#to_xml(encoding) is deprecated and will be removed in
+Nokogiri version 1.4.0 *or* after June 1 2009.
+You called to_xml from here:
+
+  #{caller.first}
+
+Please change to Node#to_xml(:encoding => #{options})
+          eowarn
+          options = {
+            :encoding => options
+          }
+        end
+        options[:save_with] ||= SaveOptions::FORMAT | SaveOptions::AS_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 = {}
+        if options.is_a?(String)
+          options = { :encoding => options }
+          $stderr.puts(<<-eowarn)
+Node#to_xml(encoding) is deprecated and will be removed in
+Nokogiri version 1.4.0 *or* after June 1 2009.
+You called to_xhtml from here:
+
+  #{caller.first}
+
+Please change to Node#to_xhtml(:encoding => #{options})
+          eowarn
+        end
+
         # 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::FORMAT |
+                                SaveOptions::NO_DECLARATION |
+                                SaveOptions::NO_EMPTY_TAGS |
+                                SaveOptions::AS_XHTML
+
+        serialize(options)
       end
 
       ###
-      # Write Node to +io+ with +encoding+ and +save_options+
-      def write_to io, encoding = nil, save_options = SaveOptions::FORMAT
+      # 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
+        if options.length > 0 && !options.first.is_a?(Hash)
+          $stderr.puts(<<-eowarn)
+Node#write_to(io, encoding, save_options) is deprecated and will be removed in
+Nokogiri version 1.4.0 *or* after June 1 2009.
+You called write_to from here:
+
+  #{caller.first}
+
+Please change to: Node#write_to(io, :encoding => e, :save_options => opts)
+          eowarn
+        end
+
+        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)
         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 +encoding+
-      def write_html_to io, encoding = nil
-        write_to io, encoding, SaveOptions::FORMAT |
+      # Write Node as HTML to +io+ with +options+
+      #
+      # See Node#write_to for a list of +options+
+      def write_html_to io, options = {}
+        if options.is_a?(String)
+          $stderr.puts(<<-eowarn)
+Node#write_html_to(io, encoding) is deprecated and will be removed in
+Nokogiri version 1.4.0 *or* after June 1 2009.
+You called write_html_to from here:
+
+  #{caller.first}
+
+Please change to Node#write_html_to(io, :encoding => #{options})
+          eowarn
+          options = { :encoding => options }
+        end
+
+        # 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::FORMAT |
           SaveOptions::NO_DECLARATION |
           SaveOptions::NO_EMPTY_TAGS |
           SaveOptions::AS_HTML
+        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 |
+      # Write Node as XHTML to +io+ with +options+
+      #
+      # See Node#write_to for a list of +options+
+      def write_xhtml_to io, options = {}
+        if options.is_a?(String)
+          $stderr.puts(<<-eowarn)
+Node#write_xhtml_to(io, encoding) is deprecated and will be removed in
+Nokogiri version 1.4.0 *or* after June 1 2009.
+You called write_xhtml_to from here:
+
+  #{caller.first}
+
+Please change to Node#write_xhtml_to(io, :encoding => #{options})
+          eowarn
+          options = { :encoding => options }
+        end
+
+        # 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::FORMAT |
           SaveOptions::NO_DECLARATION |
           SaveOptions::NO_EMPTY_TAGS |
           SaveOptions::AS_XHTML
+        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
+      # 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 = {}
+        if options.is_a?(String)
+          $stderr.puts(<<-eowarn)
+Node#write_xml_to(io, encoding) is deprecated and will be removed in
+Nokogiri version 1.4.0 *or* after June 1 2009.
+You called write_xml_to from here:
+
+  #{caller.first}
+
+Please change to Node#write_xml_to(io, :encoding => #{options})
+          eowarn
+          options = { :encoding => options }
+        end
+        options[:save_with] ||= SaveOptions::FORMAT | SaveOptions::AS_XML
+        write_to io, options
       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
+      ###
+      # 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
     end
   end