nokogiri 1.2.3 → 1.3.0

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

@@ -1,7 +1,36 @@
 module Nokogiri
   module XML
     module SAX
+      ###
+      # This parser is a SAX style parser that reads it's input as it
+      # deems necessary.  The parser takes a Nokogiri::XML::SAX::Document,
+      # an optional encoding, then given an XML input, sends messages to
+      # the Nokogiri::XML::SAX::Document.
+      #
+      # Here is an example of using this parser:
+      #
+      #   # Create a subclass of Nokogiri::XML::SAX::Document and implement
+      #   # the events we care about:
+      #   class MyDoc < Nokogiri::XML::SAX::Document
+      #     def start_element name, attrs = []
+      #       puts "starting: #{name}"
+      #     end
+      #
+      #     def end_element name
+      #       puts "ending: #{name}"
+      #     end
+      #   end
+      #
+      #   # Create our parser
+      #   parser = Nokogiri::XML::SAX::Parser.new(MyDoc.new)
+      #
+      #   # Send some XML to the parser
+      #   parser.parse(File.read(ARGV[0]))
+      #
+      # For more information about SAX parsers, see Nokogiri::XML::SAX.  Also
+      # see Nokogiri::XML::SAX::Document for the available events.
       class Parser
+        # Encodinds this parser supports
         ENCODINGS = {
           'NONE'        => 0, # No char encoding detected
           'UTF-8'       => 1, # UTF-8
@@ -28,8 +57,14 @@ module Nokogiri
           'ASCII'       => 22, # pure ASCII
         }
 
-        attr_accessor :document, :encoding
-        def initialize(doc = XML::SAX::Document.new, encoding = 'ASCII')
+        # The Nokogiri::XML::SAX::Document where events will be sent.
+        attr_accessor :document
+
+        # The encoding beings used for this document.
+        attr_accessor :encoding
+
+        # Create a new Parser with +doc+ and +encoding+
+        def initialize(doc = Nokogiri::XML::SAX::Document.new, encoding = 'ASCII')
           @encoding = encoding
           @document = doc
         end
@@ -55,6 +90,7 @@ module Nokogiri
         ###
         # Parse a file with +filename+
         def parse_file filename
+          raise ArgumentError unless filename
           raise Errno::ENOENT unless File.exists?(filename)
           raise Errno::EISDIR if File.directory?(filename)
           native_parse_file filename

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

@@ -23,8 +23,14 @@ module Nokogiri
       #   parser << "/div>"
       #   parser.finish
       class PushParser
+
+        # The Nokogiri::XML::SAX::Document on which the PushParser will be
+        # operating
         attr_accessor :document
 
+        ###
+        # Create a new PushParser with +doc+ as the SAX Document, providing
+        # an optional +file_name+ and +encoding+
         def initialize(doc = XML::SAX::Document.new, file_name = nil, encoding = 'ASCII')
           @document = doc
           @encoding = encoding
@@ -34,11 +40,17 @@ module Nokogiri
           initialize_native(@sax_parser, file_name)
         end
 
+        ###
+        # Write a +chunk+ of XML to the PushParser.  Any callback methods
+        # that can be called will be called immidiately.
         def write chunk, last_chunk = false
           native_write(chunk, last_chunk)
         end
         alias :<< :write
 
+        ###
+        # Finish the parsing.  This method is only necessary for
+        # Nokogiri::XML::SAX::Document#end_document to be called.
         def finish
           write '', true
         end

data/lib/nokogiri/xml/schema.rb

@@ -0,0 +1,65 @@
+module Nokogiri
+  module XML
+    class << self
+      ###
+      # Create a new Nokogiri::XML::Schema object using a +string_or_io+
+      # object.
+      def Schema string_or_io
+        Schema.new(string_or_io)
+      end
+    end
+
+    ###
+    # Nokogiri::XML::Schema is used for validating XML against a schema
+    # (usually from an xsd file).
+    #
+    # == Synopsis
+    #
+    # Validate an XML document against a Schema.  Loop over the errors that
+    # are returned and print them out:
+    #
+    #   xsd = Nokogiri::XML::Schema(File.read(PO_SCHEMA_FILE))
+    #   doc = Nokogiri::XML(File.read(PO_XML_FILE))
+    #
+    #   xsd.validate(doc).each do |error|
+    #     puts error.message
+    #   end
+    #
+    # The list of errors are Nokogiri::XML::SyntaxError objects.
+    class Schema
+      # Errors while parsing the schema file
+      attr_accessor :errors
+
+      ###
+      # Create a new Nokogiri::XML::Schema object using a +string_or_io+
+      # object.
+      def self.new string_or_io
+        if string_or_io.respond_to?(:read)
+          string_or_io = string_or_io.read
+        end
+
+        read_memory(string_or_io)
+      end
+
+      ###
+      # Validate +thing+ against this schema.  +thing+ can be a
+      # Nokogiri::XML::Document object, or a filename.  An Array of
+      # Nokogiri::XML::SyntaxError objects found while validating the
+      # +thing+ is returned.
+      def validate thing
+        return validate_document(thing) if thing.is_a?(Nokogiri::XML::Document)
+
+        # FIXME libxml2 has an api for validating files.  We should switch
+        # to that because it will probably save memory.
+        validate_document(Nokogiri::XML(File.read(thing)))
+      end
+
+      ###
+      # Returns true if +thing+ is a valid Nokogiri::XML::Document or
+      # file.
+      def valid? thing
+        validate(thing).length == 0
+      end
+    end
+  end
+end

data/lib/nokogiri/xml/syntax_error.rb

@@ -1,18 +1,29 @@
 module Nokogiri
   module XML
+    ###
+    # This class provides information about XML SyntaxErrors.  These
+    # exceptions are typically stored on Nokogiri::XML::Document#errors.
     class SyntaxError < ::Nokogiri::SyntaxError
+      ###
+      # return true if this is a non error
       def none?
         level == 0
       end
 
+      ###
+      # return true if this is a warning
       def warning?
         level == 1
       end
 
+      ###
+      # return true if this is an error
       def error?
         level == 2
       end
 
+      ###
+      # return true if this error is fatal
       def fatal?
         level == 3
       end

data/lib/nokogiri/xml/xpath.rb

@@ -3,8 +3,8 @@ require 'nokogiri/xml/xpath/syntax_error'
 module Nokogiri
   module XML
     class XPath
+      # The Nokogiri::XML::Document tied to this XPath instance
       attr_accessor :document
-
     end
   end
 end

data/lib/nokogiri/xml/xpath_context.rb

@@ -2,6 +2,8 @@ module Nokogiri
   module XML
     class XPathContext
 
+      ###
+      # Register namespaces in +namespaces+
       def register_namespaces(namespaces)
         namespaces.each do |k, v|
           k = k.gsub(/.*:/,'') # strip off 'xmlns:' or 'xml:'

data/lib/nokogiri/xslt.rb

@@ -1,12 +1,32 @@
 require 'nokogiri/xslt/stylesheet'
 
 module Nokogiri
+  class << self
+    ###
+    # Create a Nokogiri::XSLT::Stylesheet with +stylesheet+.
+    #
+    # Example:
+    #
+    #   xslt = Nokogiri::XSLT(File.read(ARGV[0]))
+    #
+    def XSLT stylesheet
+      XSLT.parse(stylesheet)
+    end
+  end
+
+  ###
+  # See Nokogiri::XSLT::Stylesheet for creating and maniuplating
+  # Stylesheet object.
   module XSLT
     class << self
-      def parse(string)
+      ###
+      # Parse the stylesheet in +string+
+      def parse string
         Stylesheet.parse_stylesheet_doc(XML.parse(string))
       end
       
+      ###
+      # Quote parameters in +params+ for stylesheet safety
       def quote_params params
         parray = (params.instance_of?(Hash) ? params.to_a.flatten : params).dup
         parray.each_with_index do |v,i|

data/lib/nokogiri/xslt/stylesheet.rb

@@ -1,6 +1,25 @@
 module Nokogiri
   module XSLT
+    ###
+    # A Stylesheet represents an XSLT Stylesheet object.  Stylesheet creation
+    # is done through Nokogiri.XSLT.  Here is an example of transforming
+    # an XML::Document with a Stylesheet:
+    #
+    #   doc   = Nokogiri::XML(File.read('some_file.xml'))
+    #   xslt  = Nokogir::XSLT(File.read('some_transformer.xslt'))
+    #
+    #   puts xslt.transform(doc)
+    #
+    # See Nokogiri::XSLT::Stylesheet#transform for more transformation
+    # information.
     class Stylesheet
+      ###
+      # Apply an XSLT stylesheet to an XML::Document.
+      # +params+ is an array of strings used as XSLT parameters.
+      # returns serialized document
+      def apply_to document, params = []
+        serialize(transform(document, params))
+      end
     end
   end
 end

data/lib/xsd/xmlparser/nokogiri.rb

@@ -1,7 +1,7 @@
 require 'nokogiri'
 
-module XSD
-  module XMLParser
+module XSD # :nodoc:
+  module XMLParser # :nodoc:
     ###
     # Nokogiri XML parser for soap4r.
     #
@@ -23,24 +23,34 @@ module XSD
     #     ...
     #   end
     class Nokogiri < XSD::XMLParser::Parser
+      ###
+      # Create a new XSD parser with +host+ and +opt+
       def initialize host, opt = {}
         super
         @parser = ::Nokogiri::XML::SAX::Parser.new(self, @charset || 'UTF-8')
       end
 
+      ###
+      # Start parsing +string_or_readable+
       def do_parse string_or_readable
         @parser.parse(string_or_readable)
       end
 
+      ###
+      # Handle the start_element event with +name+ and +attrs+
       def start_element name, attrs = []
         super(name, Hash[*attrs])
       end
 
+      ###
+      # Handle errors with message +msg+
       def error msg
         raise ParseError.new(msg)
       end
       alias :warning :error
 
+      ###
+      # Handle cdata_blocks containing +string+
       def cdata_block string
         characters string
       end

data/tasks/test.rb

@@ -19,36 +19,28 @@ end
 desc "run test suite under valgrind with basic ruby options"
 NokogiriTestTask.new('test:valgrind').extend(Module.new {
   def ruby *args
-    cmd = "valgrind #{VALGRIND_BASIC_OPTS} #{RUBY} #{args.join(' ')} test/test_nokogiri.rb --verbose=verbose"
-    puts cmd
-    system cmd
+    run_with_env "valgrind #{VALGRIND_BASIC_OPTS} #{RUBY} #{args.join(' ')} test/test_nokogiri.rb --verbose=verbose"
   end
 })
 
 desc "run test suite under valgrind with memory-fill ruby options"
 NokogiriTestTask.new('test:valgrind_mem').extend(Module.new {
   def ruby *args
-    cmd = "valgrind #{VALGRIND_BASIC_OPTS} --freelist-vol=100000000 --malloc-fill=6D --free-fill=66 #{RUBY} #{args.join(' ')} test/test_nokogiri.rb --verbose=verbose"
-    puts cmd
-    system cmd
+    run_with_env "valgrind #{VALGRIND_BASIC_OPTS} --freelist-vol=100000000 --malloc-fill=6D --free-fill=66 #{RUBY} #{args.join(' ')} test/test_nokogiri.rb --verbose=verbose"
   end
 })
 
 desc "run test suite under valgrind with memory-zero ruby options"
 NokogiriTestTask.new('test:valgrind_mem0').extend(Module.new {
   def ruby *args
-    cmd = "valgrind #{VALGRIND_BASIC_OPTS} --freelist-vol=100000000 --malloc-fill=00 --free-fill=00 #{RUBY} #{args.join(' ')} test/test_nokogiri.rb --verbose=verbose"
-    puts cmd
-    system cmd
+    run_with_env "valgrind #{VALGRIND_BASIC_OPTS} --freelist-vol=100000000 --malloc-fill=00 --free-fill=00 #{RUBY} #{args.join(' ')} test/test_nokogiri.rb --verbose=verbose"
   end
 })
 
 desc "run test suite under gdb"
 NokogiriTestTask.new('test:gdb').extend(Module.new {
   def ruby *args
-    cmd = "gdb --args #{RUBY} #{args.join(' ')}"
-    puts cmd
-    system cmd
+    run_with_env "gdb --args #{RUBY} #{args.join(' ')}"
   end
 })
 
@@ -56,12 +48,23 @@ desc "test coverage"
 NokogiriTestTask.new('test:coverage').extend(Module.new {
   def ruby *args
     rm_rf "coverage"
-    cmd = "rcov -x Library -I lib:ext:test #{args.join(' ')}"
-    puts cmd
-    system cmd
+    run_with_env "rcov -x Library -I lib:ext:test #{args.join(' ')}"
   end
 })
 
+desc "run test suite with verbose output"
+NokogiriTestTask.new('test:verbose').extend(Module.new {
+  def ruby *args
+    run_with_env "#{RUBY} #{args.join(' ')} test/test_nokogiri.rb --verbose=verbose"
+  end
+})
+
+def run_with_env(cmd)
+  cmd = "LD_LIBRARY_PATH='#{ENV['LD_LIBRARY_PATH']}' #{cmd}"
+  puts "=> #{cmd}"
+  system cmd
+end
+
 namespace :test do
   desc "run test suite with aggressive GC"
   task :gc => :build do
@@ -70,14 +73,32 @@ namespace :test do
   end
 
   desc "find call-seq in the rdoc"
-  task :rdoc => 'docs' do
+  task :rdoc_call_seq => 'docs' do
     Dir['doc/**/*.html'].each { |docfile|
       next if docfile =~ /\.src/
       puts "FAIL: #{docfile}" if File.read(docfile) =~ /call-seq/
     }
   end
 
-  desc "Test against multiple versions of libxml2"
+  desc "find all undocumented things"
+  task :rdoc => 'docs' do
+    base = File.expand_path(File.join(File.dirname(__FILE__), '..', 'doc'))
+    require 'test/unit'
+    test = Class.new(Test::Unit::TestCase)
+    Dir["#{base}/**/*.html"].each { |docfile|
+      test.class_eval(<<-eotest)
+        def test_#{docfile.sub("#{base}/", '').gsub(/[\/\.-]/, '_')}
+          assert_no_match(
+            /Not documented/,
+            File.read('#{docfile}'),
+            '#{docfile} has undocumented things'
+          )
+        end
+      eotest
+    }
+  end
+
+  desc "Test against multiple versions of libxml2 (MULTIXML2_DIR=directory)"
   task :multixml2 do
     MULTI_XML = File.join(ENV['HOME'], '.multixml2')
     unless File.exists?(MULTI_XML)
@@ -117,10 +138,12 @@ namespace :test do
 
     test_results = {}
     libxslt = Dir[File.join(MULTI_XML, 'install', 'libxslt*')].first
-    Dir[File.join(MULTI_XML, 'install', '*')].each do |xml2_version|
+
+    directories = ENV['MULTIXML2_DIR'] ? [ENV['MULTIXML2_DIR']] : Dir[File.join(MULTI_XML, 'install', '*')]
+    directories.sort.reverse.each do |xml2_version|
       next unless xml2_version =~ /libxml2/
       extopts = "--with-xml2-include=#{xml2_version}/include/libxml2 --with-xml2-lib=#{xml2_version}/lib --with-xslt-dir=#{libxslt}"
-      cmd = "#{$0} clean test EXTOPTS='#{extopts}'"
+      cmd = "#{$0} clean test EXTOPTS='#{extopts}' LD_LIBRARY_PATH='#{xml2_version}/lib'"
 
       version = File.basename(xml2_version)
       result = system(cmd)

data/test/css/test_parser.rb

@@ -54,6 +54,20 @@ module Nokogiri
         )
       end
 
+      def test_dashmatch
+        assert_xpath  "//a[@class = 'bar' or starts-with(@class, concat('bar', '-'))]",
+                      @parser.parse("a[@class|='bar']")
+        assert_xpath  "//a[@class = 'bar' or starts-with(@class, concat('bar', '-'))]",
+                      @parser.parse("a[@class |= 'bar']")
+      end
+
+      def test_includes
+        assert_xpath  "//a[contains(concat(\" \", @class, \" \"),concat(\" \", 'bar', \" \"))]",
+                      @parser.parse("a[@class~='bar']")
+        assert_xpath  "//a[contains(concat(\" \", @class, \" \"),concat(\" \", 'bar', \" \"))]",
+                      @parser.parse("a[@class ~= 'bar']")
+      end
+
       def test_function_with_arguments
         assert_xpath  "//*[position() = 2 and self::a]",
                       @parser.parse("a[2]")
@@ -64,12 +78,23 @@ module Nokogiri
       def test_carrot
         assert_xpath  "//a[starts-with(@id, 'Boing')]",
                       @parser.parse("a[id^='Boing']")
+        assert_xpath  "//a[starts-with(@id, 'Boing')]",
+                      @parser.parse("a[id ^= 'Boing']")
+      end
+
+      def test_suffix_match
+        assert_xpath "//a[substring(@id, string-length(@id) - string-length('Boing') + 1, string-length('Boing')) = 'Boing']",
+                      @parser.parse("a[id$='Boing']")
+        assert_xpath "//a[substring(@id, string-length(@id) - string-length('Boing') + 1, string-length('Boing')) = 'Boing']",
+                      @parser.parse("a[id $= 'Boing']")
       end
 
       def test_attributes_with_at
         ## This is non standard CSS
         assert_xpath  "//a[@id = 'Boing']",
                       @parser.parse("a[@id='Boing']")
+        assert_xpath  "//a[@id = 'Boing']",
+                      @parser.parse("a[@id = 'Boing']")
       end
 
       def test_attributes_with_at_and_stuff
@@ -82,6 +107,8 @@ module Nokogiri
         ## This is non standard CSS
         assert_xpath  "//a[child::text() != 'Boing']",
                       @parser.parse("a[text()!='Boing']")
+        assert_xpath  "//a[child::text() != 'Boing']",
+                      @parser.parse("a[text() != 'Boing']")
       end
 
       def test_function
@@ -96,6 +123,8 @@ module Nokogiri
         ## This is non standard CSS
         assert_xpath  "//a[contains(child::text(), 'Boing')]",
                       @parser.parse("a[text()*='Boing']")
+        assert_xpath  "//a[contains(child::text(), 'Boing')]",
+                      @parser.parse("a[text() *= 'Boing']")
 
         ## This is non standard CSS
         assert_xpath  "//script//comment()",