nokogiri 1.2.3 → 1.3.0

data/lib/nokogiri/html/builder.rb

@@ -1,6 +1,32 @@
 module Nokogiri
   module HTML
-    class Builder < XML::Builder
+    ###
+    # Nokogiri HTML builder is used for building HTML documents.  It is very
+    # similar to the Nokogiri::XML::Builder.  In fact, you should go read the
+    # documentation for Nokogiri::XML::Builder before reading this
+    # documentation.
+    #
+    # == Synopsis:
+    #
+    # Create an HTML document with a body that has an onload attribute, and a
+    # span tag with a class of "bold" that has content of "Hello world".
+    #
+    #   builder = Nokogiri::HTML::Builder.new do |doc|
+    #     doc.html {
+    #       doc.body(:onload => 'some_func();') {
+    #         doc.span.bold {
+    #           doc.text "Hello world"
+    #         }
+    #       }
+    #     }
+    #   end
+    #   puts builder.to_html
+    #
+    # The HTML builder inherits from the XML builder, so make sure to read the
+    # Nokogiri::XML::Builder documentation.
+    class Builder < Nokogiri::XML::Builder
+      ###
+      # Convert the builder to HTML
       def to_html
         @doc.to_html
       end

data/lib/nokogiri/html/document.rb

@@ -1,15 +1,71 @@
 module Nokogiri
   module HTML
-    class Document < XML::Document
+    class Document < Nokogiri::XML::Document
+
+      def initialize *args
+        super
+      end
+
       ####
       # Serialize this Document with +encoding+ using +options+
-      def serialize encoding = nil, options = XML::Node::SaveOptions::FORMAT |
-        XML::Node::SaveOptions::AS_HTML |
-        XML::Node::SaveOptions::NO_DECLARATION |
-        XML::Node::SaveOptions::NO_EMPTY_TAGS
+      def serialize *args
+        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.join("\n")}
 
-        super(encoding, options)
+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] || XML::Node::SaveOptions::FORMAT |
+            XML::Node::SaveOptions::AS_HTML |
+            XML::Node::SaveOptions::NO_DECLARATION |
+            XML::Node::SaveOptions::NO_EMPTY_TAGS
+        }
+        super(options)
+      end
+
+      ####
+      # Create a Nokogiri::XML::DocumentFragment from +tags+
+      def fragment tags
+        DocumentFragment.new(self, tags)
       end
+
+      class << self
+        ###
+        # Parse HTML.  +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?(:encoding)
+            encoding ||= string_or_io.encoding.name
+          end
+
+          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
+
+          return self.new if(string_or_io.length == 0)
+          self.read_memory(string_or_io, url, encoding, options.to_i)
+        end
+      end
+
     end
   end
 end

data/lib/nokogiri/html/document_fragment.rb

@@ -0,0 +1,15 @@
+module Nokogiri
+  module HTML
+    class DocumentFragment < Nokogiri::XML::DocumentFragment
+
+      class << self
+        ####
+        # Create a Nokogiri::XML::DocumentFragment from +tags+
+        def parse tags
+          HTML::DocumentFragment.new(HTML::Document.new, tags)
+        end
+      end
+
+    end
+  end
+end

data/lib/nokogiri/html/element_description.rb

@@ -0,0 +1,23 @@
+module Nokogiri
+  module HTML
+    class ElementDescription
+      ###
+      # Is this element a block element?
+      def block?
+        !inline?
+      end
+
+      ###
+      # Convert this description to a string
+      def to_s
+        "#{name}: #{description}"
+      end
+
+      ###
+      # Inspection information
+      def inspect
+        "#<#{self.class.name}: #{name} #{description}>"
+      end
+    end
+  end
+end

data/lib/nokogiri/html/entity_lookup.rb

@@ -3,6 +3,8 @@ module Nokogiri
     class EntityDescription < Struct.new(:value, :name, :description); end
 
     class EntityLookup
+      ###
+      # Look up entity with +name+
       def [] name
         (val = get(name)) && val.value
       end

data/lib/nokogiri/html/sax/parser.rb

@@ -1,16 +1,42 @@
 module Nokogiri
   module HTML
+    ###
+    # Nokogiri lets you write a SAX parser to process HTML but get HTML
+    # correction features.
+    #
+    # See Nokogiri::HTML::SAX::Parser for a basic example of using a
+    # SAX parser with HTML.
+    #
+    # For more information on SAX parsers, see Nokogiri::XML::SAX
     module SAX
-      class Parser < XML::SAX::Parser
+      ###
+      # This class lets you perform SAX style parsing on HTML with HTML
+      # error correction.
+      #
+      # Here is a basic usage example:
+      #
+      #   class MyDoc < Nokogiri::XML::SAX::Document
+      #     def start_element name, attributes = []
+      #       puts "found a #{name}"
+      #     end
+      #   end
+      #
+      #   parser = Nokogiri::HTML::SAX::Parser.new(MyDoc.new)
+      #   parser.parse(File.read(ARGV[0], 'rb'))
+      #
+      # For more information on SAX parsers, see Nokogiri::XML::SAX
+      class Parser < Nokogiri::XML::SAX::Parser
         ###
         # Parse html stored in +data+ using +encoding+
         def parse_memory data, encoding = 'UTF-8'
+          raise ArgumentError unless data
           native_parse_memory(data, encoding)
         end
 
         ###
         # Parse a file with +filename+
         def parse_file filename, encoding = 'UTF-8'
+          raise ArgumentError unless filename
           raise Errno::ENOENT unless File.exists?(filename)
           raise Errno::EISDIR if File.directory?(filename)
           native_parse_file filename, encoding

data/lib/nokogiri/version.rb

@@ -1,4 +1,29 @@
 module Nokogiri
   # The version of Nokogiri you are using
-  VERSION = '1.2.3'
+  VERSION = '1.3.0'
+
+  # More complete version information about libxml
+  VERSION_INFO = {}
+  VERSION_INFO['warnings']              = []
+  VERSION_INFO['nokogiri']              = VERSION
+  if defined?(LIBXML_VERSION) && ! defined?(FFI)
+    VERSION_INFO['libxml']              = {}
+    VERSION_INFO['libxml']['binding']   = 'extension'
+    VERSION_INFO['libxml']['compiled']  = LIBXML_VERSION
+    VERSION_INFO['libxml']['loaded']    = LIBXML_PARSER_VERSION.scan(/^(.*)(..)(..)$/).first.collect{|j|j.to_i}.join(".")
+
+    if VERSION_INFO['libxml']['compiled'] != VERSION_INFO['libxml']['loaded']
+      warning = "Nokogiri was built against LibXML version #{VERSION_INFO['libxml']['compiled']}, but has dynamically loaded #{VERSION_INFO['libxml']['loaded']}"
+      VERSION_INFO['warnings'] << warning
+      warn "WARNING: #{warning}"
+    end
+  end
+
+  def self.ffi? # :nodoc:
+    Nokogiri::VERSION_INFO['libxml']['binding'] == 'ffi'
+  end
+
+  def self.is_2_6_16? # :nodoc:
+    Nokogiri::VERSION_INFO['libxml']['loaded'] <= '2.6.16'
+  end
 end

data/lib/nokogiri/version_warning.rb

@@ -0,0 +1,11 @@
+module Nokogiri
+  if self.is_2_6_16? && !defined?(I_KNOW_I_AM_USING_AN_OLD_AND_BUGGY_VERSION_OF_LIBXML2)
+    warn <<-eom
+HI.  You're using libxml2 version 2.6.16 which is over 4 years old and has
+plenty of bugs.  We suggest that for maximum HTML/XML parsing pleasure, you
+upgrade your version of libxml2 and re-install nokogiri.  If you like using
+libxml2 version 2.6.16, but don't like this warning, please define the constant
+I_KNOW_I_AM_USING_AN_OLD_AND_BUGGY_VERSION_OF_LIBXML2 before requring nokogiri.
+    eom
+  end
+end

data/lib/nokogiri/xml.rb

@@ -1,14 +1,14 @@
+require 'nokogiri/xml/parse_options'
 require 'nokogiri/xml/sax'
 require 'nokogiri/xml/fragment_handler'
 require 'nokogiri/xml/node'
+require 'nokogiri/xml/namespace'
 require 'nokogiri/xml/attr'
 require 'nokogiri/xml/dtd'
-require 'nokogiri/xml/text'
 require 'nokogiri/xml/cdata'
-require 'nokogiri/xml/processing_instruction'
-require 'nokogiri/xml/comment'
 require 'nokogiri/xml/document'
 require 'nokogiri/xml/document_fragment'
+require 'nokogiri/xml/processing_instruction'
 require 'nokogiri/xml/node_set'
 require 'nokogiri/xml/syntax_error'
 require 'nokogiri/xml/xpath'
@@ -16,72 +16,46 @@ require 'nokogiri/xml/xpath_context'
 require 'nokogiri/xml/builder'
 require 'nokogiri/xml/reader'
 require 'nokogiri/xml/notation'
-require 'nokogiri/xml/element'
 require 'nokogiri/xml/entity_declaration'
+require 'nokogiri/xml/schema'
+require 'nokogiri/xml/relax_ng'
 
 module Nokogiri
   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 XML thing, url = nil, encoding = nil, options = 1
-      Nokogiri::XML.parse(thing, url, encoding, options)
+    # Parse XML.  Convenience method for Nokogiri::XML::Document.parse
+    def XML thing, url = nil, encoding = nil, options = 1, &block
+      Nokogiri::XML::Document.parse(thing, url, encoding, options, &block)
     end
   end
 
   module XML
-    # Parser options
-    PARSE_RECOVER     = 1 << 0  # Recover from errors
-    PARSE_NOENT       = 1 << 1  # Substitute entities
-    PARSE_DTDLOAD     = 1 << 2  # Load external subsets
-    PARSE_DTDATTR     = 1 << 3  # Default DTD attributes
-    PARSE_DTDVALID    = 1 << 4  # validate with the DTD
-    PARSE_NOERROR     = 1 << 5  # suppress error reports
-    PARSE_NOWARNING   = 1 << 6  # suppress warning reports
-    PARSE_PEDANTIC    = 1 << 7  # pedantic error reporting
-    PARSE_NOBLANKS    = 1 << 8  # remove blank nodes
-    PARSE_SAX1        = 1 << 9  # use the SAX1 interface internally
-    PARSE_XINCLUDE    = 1 << 10 # Implement XInclude substitition
-    PARSE_NONET       = 1 << 11 # Forbid network access
-    PARSE_NODICT      = 1 << 12 # Do not reuse the context dictionnary
-    PARSE_NSCLEAN     = 1 << 13 # remove redundant namespaces declarations
-    PARSE_NOCDATA     = 1 << 14 # merge CDATA as text nodes
-    PARSE_NOXINCNODE  = 1 << 15 # do not generate XINCLUDE START/END nodes
-
     class << self
-      def Reader string, url = nil, encoding = nil, options = 0
-        Reader.from_memory(string, url, encoding, options)
-      end
-
       ###
-      # Parse an XML document.  See Nokogiri.XML.
-      def parse string_or_io, url = nil, encoding = nil, options = 2159
-        if string_or_io.respond_to?(:read)
-          url ||= string_or_io.respond_to?(:path) ? string_or_io.path : nil
-          return Document.read_io(string_or_io, url, encoding, options)
-        end
+      # Parse an XML document using the Nokogiri::XML::Reader API.  See
+      # Nokogiri::XML::Reader for mor information
+      def Reader string_or_io, url = nil, encoding = nil, options = 0
 
-        # read_memory pukes on empty docs
-        return Document.new if string_or_io.nil? or string_or_io.empty?
+        options = Nokogiri::XML::ParseOptions.new(options) if Fixnum === options
+        # Give the options to the user
+        yield options if block_given?
 
-        Document.read_memory(string_or_io, url, encoding, options)
+        if string_or_io.respond_to? :read
+          return Reader.from_io(string_or_io, url, encoding, options.to_i)
+        end
+        Reader.from_memory(string_or_io, url, encoding, options.to_i)
       end
 
       ###
-      # Sets whether or not entities should be substituted.
-      def substitute_entities=(value = true)
-        Document.substitute_entities = value
+      # Parse XML.  Convenience method for Nokogiri::XML::Document.parse
+      def parse thing, url = nil, encoding = nil, options = 1, &block
+        Document.parse(thing, url, encoding, options, &block)
       end
 
-      ###
-      # Sets whether or not external subsets should be loaded
-      def load_external_subsets=(value = true)
-        Document.load_external_subsets = value
+      ####
+      # Parse a fragment from +string+ in to a NodeSet.
+      def fragment string
+        XML::DocumentFragment.parse(string)
       end
     end
   end

data/lib/nokogiri/xml/builder.rb

@@ -1,39 +1,180 @@
 module Nokogiri
   module XML
+    ###
+    # Nokogiri builder can be used for building XML and HTML documents.
+    #
+    # == Synopsis:
+    #
+    #   builder = Nokogiri::XML::Builder.new do |xml|
+    #     xml.root {
+    #       xml.products {
+    #         xml.widget {
+    #           xml.id_ "10"
+    #           xml.name "Awesome widget"
+    #         }
+    #       }
+    #     }
+    #   end
+    #   puts builder.to_xml
+    #
+    # === Builder scope
+    #
+    # The builder allows two forms.  When the builder is supplied with a block
+    # that has a parameter, the outside scope is maintained.  This means you
+    # can access variables that are outside your builder.  If you don't need
+    # outside scope, you can use the builder without the "xml" prefix like
+    # this:
+    #
+    #   builder = Nokogiri::XML::Builder.new do
+    #     root {
+    #       products {
+    #         widget {
+    #           id_ "10"
+    #           name "Awesome widget"
+    #         }
+    #       }
+    #     }
+    #   end
+    #
+    # == Special Tags
+    #
+    # The builder works by taking advantage of method_missing.  Unfortunately
+    # some methods are defined in ruby that are difficult or dangerous to
+    # remove.  You may want to create tags with the name "type", "class", and
+    # "id" for example.  In that case, you can use an underscore to
+    # disambiguate your tag name from the method call.
+    #
+    # Here is an example of using the underscore to disambiguate tag names from
+    # ruby methods:
+    #
+    #   @objects = [Object.new, Object.new, Object.new]
+    #
+    #   builder = Nokogiri::XML::Builder.new do |xml|
+    #     xml.root {
+    #       xml.objects {
+    #         @objects.each do |o|
+    #           xml.object {
+    #             xml.type_   o.type
+    #             xml.class_  o.class.name
+    #             xml.id_     o.id
+    #           }
+    #         end
+    #       }
+    #     }
+    #   end
+    #   puts builder.to_xml
+    #
+    # The underscore may be used with any tag name, and the last underscore
+    # will just be removed.
+    #
+    # == Tag Attributes
+    #
+    # Tag attributes may be supplied as method arguments.  Here is our
+    # previous example, but using attributes rather than tags:
+    #
+    #   @objects = [Object.new, Object.new, Object.new]
+    #
+    #   builder = Nokogiri::XML::Builder.new do |xml|
+    #     xml.root {
+    #       xml.objects {
+    #         @objects.each do |o|
+    #           xml.object(:type => o.type, :class => o.class, :id => o.id)
+    #         end
+    #       }
+    #     }
+    #   end
+    #   puts builder.to_xml
+    #
+    # === Tag Attribute Short Cuts
+    #
+    # A couple attribute short cuts are available when building tags.  The
+    # short cuts are available by special method calls when building a tag.
+    #
+    # This example builds an "object" tag with the class attribute "classy"
+    # and the id of "thing":
+    #
+    #   builder = Nokogiri::XML::Builder.new do |xml|
+    #     xml.root {
+    #       xml.objects {
+    #         xml.object.classy.thing!
+    #       }
+    #     }
+    #   end
+    #   puts builder.to_xml
+    #
+    # All other options are still supported with this syntax, including
+    # blocks and extra tag attributes.
     class Builder
-      attr_accessor :doc, :parent, :context
-      def initialize &block
+      # The current Document object being built
+      attr_accessor :doc
+
+      # The parent of the current node being built
+      attr_accessor :parent
+
+      # A context object for use when the block has no arguments
+      attr_accessor :context
+
+      attr_accessor :arity # :nodoc:
+
+      ###
+      # Create a new Builder object.  +options+ are sent to the top level
+      # Document that is being built.
+      #
+      # Building a document with a particular encoding for example:
+      #
+      #   Nokogiri::XML::Builder.new(:encoding => 'UTF-8') do |xml|
+      #     ...
+      #   end
+      def initialize options = {}, &block
         namespace = self.class.name.split('::')
         namespace[-1] = 'Document'
-        @doc = eval(namespace.join('::')).new
-        @parent = @doc
-        @context = nil
-        if block_given?
+        @doc      = eval(namespace.join('::')).new
+        @parent   = @doc
+        @context  = nil
+        @arity    = nil
+
+        options.each do |k,v|
+          @doc.send(:"#{k}=", v)
+        end
+
+        return unless block_given?
+
+        @arity = block.arity
+        if @arity <= 0
           @context = eval('self', block.binding)
+          instance_eval(&block)
+        else
+          yield self
         end
-        instance_eval(&block) if block_given?
+
         @parent = @doc
       end
 
+      ###
+      # Create a Text Node with content of +string+
       def text string
         node = Nokogiri::XML::Text.new(string.to_s, @doc)
         insert(node)
       end
 
+      ###
+      # Create a CDATA Node with content of +string+
       def cdata string
         node = Nokogiri::XML::CDATA.new(@doc, string.to_s)
         insert(node)
       end
 
+      ###
+      # Convert this Builder object to XML
       def to_xml
         @doc.to_xml
       end
 
-      def method_missing method, *args, &block
+      def method_missing method, *args, &block # :nodoc:
         if @context && @context.respond_to?(method)
           @context.send(method, *args, &block)
         else
-          node = Nokogiri::XML::Node.new(method.to_s, @doc) { |n|
+          node = Nokogiri::XML::Node.new(method.to_s.sub(/[_!]$/, ''), @doc) { |n|
             args.each do |arg|
               case arg
               when Hash
@@ -48,11 +189,18 @@ module Nokogiri
       end
 
       private
+      ###
+      # Insert +node+ as a child of the current Node
       def insert(node, &block)
         node.parent = @parent
         if block_given?
           @parent = node
-          instance_eval(&block)
+          @arity ||= block.arity
+          if @arity <= 0
+            instance_eval(&block)
+          else
+            block.call(self)
+          end
           @parent = node.parent
         end
         NodeBuilder.new(node, self)
@@ -64,6 +212,14 @@ module Nokogiri
           @doc_builder = doc_builder
         end
 
+        def []= k, v
+          @node[k] = v
+        end
+
+        def [] k
+          @node[k]
+        end
+
         def method_missing(method, *args, &block)
           opts = args.last.is_a?(Hash) ? args.pop : {}
           case method.to_s