nokogiri 1.2.3 → 1.3.0

data/lib/nokogiri/xml/node/save_options.rb

@@ -4,15 +4,25 @@ module Nokogiri
       ###
       # Save options for serializing nodes
       class SaveOptions
-        FORMAT          = 1  # Format serialized xml
-        NO_DECLARATION  = 2  # Do not include delcarations
+        # Format serialized xml
+        FORMAT          = 1
+        # Do not include delcarations
+        NO_DECLARATION  = 2
+        # Do not include empty tags
         NO_EMPTY_TAGS   = 4
+        # Do not save XHTML
         NO_XHTML        = 8
+        # Save as XHTML
         AS_XHTML        = 16
+        # Save as XML
         AS_XML          = 32
+        # Save as HTML
         AS_HTML         = 64
 
+        # Integer representation of the SaveOptions
         attr_reader :options
+
+        # Create a new SaveOptions object with +options+
         def initialize options = 0; @options = options; end
         constants.each do |constant|
           class_eval %{

data/lib/nokogiri/xml/node_set.rb

@@ -19,8 +19,13 @@ module Nokogiri
 
       ###
       # Get the first element of the NodeSet.
-      def first
-        self[0]
+      def first n = nil
+        return self[0] unless n
+        list = []
+        0.upto(n - 1) do |i|
+          list << self[i]
+        end
+        list
       end
 
       ###
@@ -35,6 +40,13 @@ module Nokogiri
         length == 0
       end
 
+      ###
+      # Returns the index of the first node in self that is == to +node+. Returns nil if no match is found. 
+      def index(node)
+        each_with_index { |member, j| return j if member == node }
+        nil
+      end
+
       ###
       # Insert +datum+ before the first Node in this NodeSet
       def before datum
@@ -77,6 +89,7 @@ module Nokogiri
         return self[path] if path.is_a?(Numeric)
         search(path, ns).first
       end
+      alias :% :at
 
       ###
       # Append the class attribute +name+ to all Node objects in the NodeSet.
@@ -112,8 +125,8 @@ module Nokogiri
           each do |el|
             el.set_attribute(key, value || blk[el])
           end
-          return self      
-        end    
+          return self
+        end
         if key.is_a? Hash
           key.each { |k,v| self.attr(k,v) }
           return self
@@ -130,7 +143,7 @@ module Nokogiri
           next unless el.respond_to? :remove_attribute
           el.remove_attribute(name)
         end
-        self      
+        self
       end
 
       ###
@@ -165,24 +178,61 @@ module Nokogiri
         self
       end
 
+      ###
+      # Convert this NodeSet to a string.
       def to_s
         map { |x| x.to_s }.join
       end
 
+      ###
+      # Convert this NodeSet to HTML
       def to_html *args
-        map { |x| x.to_html(*args) }.join('')
+        map { |x| x.to_html(*args) }.join
       end
 
+      ###
+      # Convert this NodeSet to XHTML
       def to_xhtml *args
-        map { |x| x.to_xhtml(*args) }.join('')
+        map { |x| x.to_xhtml(*args) }.join
       end
 
+      ###
+      # Convert this NodeSet to XML
       def to_xml *args
-        map { |x| x.to_xml(*args) }.join('')
+        map { |x| x.to_xml(*args) }.join
       end
 
       alias :size :length
       alias :to_ary :to_a
+
+      ###
+      # Removes the last element from set and returns it, or +nil+ if
+      # the set is empty
+      def pop
+        return nil if length == 0
+        delete last
+      end
+
+      ###
+      # Returns the first element of the NodeSet and removes it.  Returns
+      # +nil+ if the set is empty.
+      def shift
+        return nil if length == 0
+        delete first
+      end
+
+      ###
+      # Equality -- Two NodeSets are equal if the contain the same number
+      # of elements and if each element is equal to the corresponding
+      # element in the other NodeSet
+      def == other
+        return false unless other.is_a?(Nokogiri::XML::NodeSet)
+        return false unless length == other.length
+        each_with_index do |node, i|
+          return false unless node == other[i]
+        end
+        true
+      end
     end
   end
 end

data/lib/nokogiri/xml/parse_options.rb

@@ -0,0 +1,80 @@
+module Nokogiri
+  module XML
+    ###
+    # Parse options for passing to Nokogiri.XML or Nokogiri.HTML
+    class ParseOptions
+      # Strict parsing
+      STRICT      = 0
+      # Recover from errors
+      RECOVER     = 1 << 0
+      # Substitute entities
+      NOENT       = 1 << 1
+      # Load external subsets
+      DTDLOAD     = 1 << 2
+      # Default DTD attributes
+      DTDATTR     = 1 << 3
+      # validate with the DTD
+      DTDVALID    = 1 << 4
+      # suppress error reports
+      NOERROR     = 1 << 5
+      # suppress warning reports
+      NOWARNING   = 1 << 6
+      # pedantic error reporting
+      PEDANTIC    = 1 << 7
+      # remove blank nodes
+      NOBLANKS    = 1 << 8
+      # use the SAX1 interface internally
+      SAX1        = 1 << 9
+      # Implement XInclude substitition
+      XINCLUDE    = 1 << 10
+      # Forbid network access
+      NONET       = 1 << 11
+      # Do not reuse the context dictionnary
+      NODICT      = 1 << 12
+      # remove redundant namespaces declarations
+      NSCLEAN     = 1 << 13
+      # merge CDATA as text nodes
+      NOCDATA     = 1 << 14
+      # do not generate XINCLUDE START/END nodes
+      NOXINCNODE  = 1 << 15
+
+      attr_accessor :options
+      def initialize options = 0
+        @options = options
+      end
+
+      constants.each do |constant|
+        next if constant == 'STRICT'
+        class_eval %{
+          def #{constant.downcase}
+            @options |= #{constant}
+            self
+          end
+
+          def #{constant.downcase}?
+            #{constant} & @options == #{constant}
+          end
+        }
+      end
+
+      def strict
+        @options |= STRICT
+        self
+      end
+
+      def strict?
+        @options & RECOVER == STRICT
+      end
+
+      alias :to_i :options
+
+      def inspect
+        options = []
+        self.class.constants.each do |k|
+          options << k.downcase if send(:"#{k.downcase}?")
+        end
+        super.sub(/>$/, " " + options.join(', ') + ">")
+      end
+    end
+  end
+end

data/lib/nokogiri/xml/processing_instruction.rb

@@ -1,6 +1,8 @@
 module Nokogiri
   module XML
     class ProcessingInstruction < Node
+      def initialize document, name, content
+      end
     end
   end
 end

data/lib/nokogiri/xml/reader.rb

@@ -1,27 +1,66 @@
 module Nokogiri
   module XML
+    ###
+    # Nokogiri::XML::Reader parses an XML document similar to the way a cursor
+    # would move.  The Reader is given an XML document, and yields nodes
+    # to an each block.
+    #
+    # Here is an example of usage:
+    #
+    #   reader = Nokogiri::XML::Reader(<<-eoxml)
+    #     <x xmlns:tenderlove='http://tenderlovemaking.com/'>
+    #       <tenderlove:foo awesome='true'>snuggles!</tenderlove:foo>
+    #     </x>
+    #   eoxml
+    #
+    #   reader.each do |node|
+    #
+    #     # node is an instance of Nokogiri::XML::Reader
+    #     puts node.name
+    #
+    #   end
+    #
+    # Note that Nokogiri::XML::Reader#each can only be called once!!  Once
+    # the cursor moves through the entire document, you must parse the
+    # document again.  So make sure that you capture any information you
+    # need during the first iteration.
+    #
+    # The Reader parser is good for when you need the speed of a SAX parser,
+    # but do not want to write a Document handler.
     class Reader
       include Enumerable
+
+      # A list of errors encountered while parsing
       attr_accessor :errors
+
+      # The encoding for the document
       attr_reader :encoding
 
-      def initialize url = nil, encoding = nil
-        @errors = []
+      # The XML source
+      attr_reader :source
+
+      def initialize source, url = nil, encoding = nil # :nodoc:
+        @source   = source
+        @errors   = []
         @encoding = encoding
       end
+      private :initialize
 
+      ###
+      # Get a list of attributes for the current node.
       def attributes
         Hash[*(attribute_nodes.map { |node|
           [node.name, node.to_s]
         }.flatten)].merge(namespaces || {})
       end
 
+      ###
+      # Move the cursor through the document yielding each node to the block
       def each(&block)
         while node = self.read
           block.call(node)
         end
       end
-      private :initialize
     end
   end
 end

data/lib/nokogiri/xml/relax_ng.rb

@@ -0,0 +1,32 @@
+module Nokogiri
+  module XML
+    class << self
+      ###
+      # Create a new Nokogiri::XML::RelaxNG document from +string_or_io+.
+      # See Nokogiri::XML::RelaxNG for an example.
+      def RelaxNG string_or_io
+        RelaxNG.new(string_or_io)
+      end
+    end
+
+    ###
+    # Nokogiri::XML::RelaxNG is used for validating XML against a
+    # RelaxNG schema.
+    #
+    # == Synopsis
+    #
+    # Validate an XML document against a RelaxNG schema.  Loop over the errors
+    # that are returned and print them out:
+    #
+    #   schema  = Nokogiri::XML::RelaxNG(File.read(ADDRESS_SCHEMA_FILE))
+    #   doc     = Nokogiri::XML(File.read(ADDRESS_XML_FILE))
+    #
+    #   schema.validate(doc).each do |error|
+    #     puts error.message
+    #   end
+    #
+    # The list of errors are Nokogiri::XML::SyntaxError objects.
+    class RelaxNG < Nokogiri::XML::Schema
+    end
+  end
+end

data/lib/nokogiri/xml/sax.rb

@@ -1,10 +1,3 @@
 require 'nokogiri/xml/sax/document'
 require 'nokogiri/xml/sax/parser'
 require 'nokogiri/xml/sax/push_parser'
-
-module Nokogiri
-  module XML
-    module SAX
-    end
-  end
-end

data/lib/nokogiri/xml/sax/document.rb

@@ -1,6 +1,72 @@
 module Nokogiri
   module XML
+    ###
+    # SAX Parsers are event driven parsers.  Nokogiri provides two different
+    # event based parsers when dealing with XML.  If you want to do SAX style
+    # parsing using HTML, check out Nokogiri::HTML::SAX.
+    #
+    # The basic way a SAX style parser works is by creating a parser,
+    # telling the parser about the events we're interested in, then giving
+    # the parser some XML to process.  The parser will notify you when
+    # it encounters events your said you would like to know about.
+    #
+    # To register for events, you simply subclass Nokogiri::XML::SAX::Document,
+    # and implement the methods for which you would like notification.
+    #
+    # For example, if I want to be notified when a document ends, and when an
+    # element starts, I would write a class like this:
+    #
+    #   class MyDocument < Nokogiri::XML::SAX::Document
+    #     def end_document
+    #       puts "the document has ended"
+    #     end
+    #
+    #     def start_element name, attributes = []
+    #       puts "#{name} started"
+    #     end
+    #   end
+    #
+    # Then I would instantiate a SAX parser with this document, and feed the
+    # parser some XML
+    #
+    #   # Create a new parser
+    #   parser = Nokogiri::XML::SAX::Parser.new(MyDocument.new)
+    #
+    #   # Feed the parser some XML
+    #   parser.parse(File.read(ARGV[0], 'rb'))
+    #
+    # Now my document handler will be called when each node starts, and when
+    # then document ends.  To see what kinds of events are available, take
+    # a look at Nokogiri::XML::SAX::Document.
+    #
+    # Two SAX parsers for XML are available, a parser that reads from a string
+    # or IO object as it feels necessary, and a parser that lets you spoon
+    # feed it XML.  If you want to let Nokogiri deal with reading your XML,
+    # use the Nokogiri::XML::SAX::Parser.  If you want to have fine grain
+    # control over the XML input, use the Nokogiri::XML::SAX::PushParser.
     module SAX
+      ###
+      # This class is used for registering types of events you are interested
+      # in handling.  All of the methods on this class are available as
+      # possible events while parsing an XML document.  To register for any
+      # particular event, just subclass this class and implement the methods
+      # you are interested in knowing about.
+      #
+      # To only be notified about start and end element events, write a class
+      # like this:
+      #
+      #   class MyDocument < Nokogiri::XML::SAX::Document
+      #     def start_element name, attrs = []
+      #       puts "#{name} started!"
+      #     end
+      #
+      #     def end_element name
+      #       puts "#{name} ended"
+      #     end
+      #   end
+      #
+      # You can use this event handler for any SAX style parser included with
+      # Nokogiri.  See Nokogiri::XML::SAX, and Nokogiri::HTML::SAX.
       class Document
         ###
         # Called when document starts parsing
@@ -24,6 +90,24 @@ module Nokogiri
         def end_element name
         end
 
+        ###
+        # Called at the beginning of an element
+        # +name+ is the element name
+        # +attrs+ is a hash of attributes
+        # +prefix+ is the namespace prefix for the element
+        # +uri+ is the associated namespace URI
+        # +namespaces+ is a hash of namespace prefix:urls associated with the element
+        def start_element_ns(name, attrs = {}, prefix = nil, uri = nil, namespaces = {})
+        end
+
+        ###
+        # Called at the end of an element
+        # +name+ is the element's name
+        # +prefix+ is the namespace prefix associated with the element
+        # +uri+ is the associated namespace URI
+        def end_element_ns(name, prefix = nil, uri = nil)
+        end
+
         ###
         # Characters read between a tag
         # +string+ contains the character data