nokogiri 1.0.0 → 1.6.8.1

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.open(ADDRESS_SCHEMA_FILE))
+    #   doc     = Nokogiri::XML(File.open(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/document.rb

@@ -1,7 +1,78 @@
 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 you 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.open(ARGV[0]))
+    #
+    # 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 an XML declaration is parsed
+        def xmldecl version, encoding, standalone
+        end
+
         ###
         # Called when document starts parsing
         def start_document
@@ -14,7 +85,9 @@ module Nokogiri
 
         ###
         # Called at the beginning of an element
-        # +name+ is the name of the tag with +attrs+ as attributes
+        # * +name+ is the name of the tag
+        # * +attrs+ are an assoc list of namespaces and attributes, e.g.:
+        #     [ ["xmlns:foo", "http://sample.net"], ["size", "large"] ]
         def start_element name, attrs = []
         end
 
@@ -25,7 +98,39 @@ module Nokogiri
         end
 
         ###
-        # Characters read between a tag
+        # Called at the beginning of an element
+        # +name+ is the element name
+        # +attrs+ is a list of attributes
+        # +prefix+ is the namespace prefix for the element
+        # +uri+ is the associated namespace URI
+        # +ns+ is a hash of namespace prefix:urls associated with the element
+        def start_element_namespace name, attrs = [], prefix = nil, uri = nil, ns = []
+          ###
+          # Deal with SAX v1 interface
+          name = [prefix, name].compact.join(':')
+          attributes = ns.map { |ns_prefix,ns_uri|
+            [['xmlns', ns_prefix].compact.join(':'), ns_uri]
+          } + attrs.map { |attr|
+            [[attr.prefix, attr.localname].compact.join(':'), attr.value]
+          }
+          start_element name, attributes
+        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_namespace name, prefix = nil, uri = nil
+          ###
+          # Deal with SAX v1 interface
+          end_element [prefix, name].compact.join(':')
+        end
+
+        ###
+        # Characters read between a tag.  This method might be called multiple
+        # times given one contiguous string of characters.
+        #
         # +string+ contains the character data
         def characters string
         end
@@ -53,6 +158,13 @@ module Nokogiri
         # +string+ contains the cdata content
         def cdata_block string
         end
+
+        ###
+        # Called when processing instructions are found
+        # +name+ is the target of the instruction
+        # +content+ is the value of the instruction
+        def processing_instruction name, content
+        end
       end
     end
   end

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

@@ -1,31 +1,121 @@
 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.open(ARGV[0]))
+      #
+      # For more information about SAX parsers, see Nokogiri::XML::SAX.  Also
+      # see Nokogiri::XML::SAX::Document for the available events.
       class Parser
+        class Attribute < Struct.new(:localname, :prefix, :uri, :value)
+        end
+
+        # Encodinds this parser supports
+        ENCODINGS = {
+          'NONE'        => 0, # No char encoding detected
+          'UTF-8'       => 1, # UTF-8
+          'UTF16LE'     => 2, # UTF-16 little endian
+          'UTF16BE'     => 3, # UTF-16 big endian
+          'UCS4LE'      => 4, # UCS-4 little endian
+          'UCS4BE'      => 5, # UCS-4 big endian
+          'EBCDIC'      => 6, # EBCDIC uh!
+          'UCS4-2143'   => 7, # UCS-4 unusual ordering
+          'UCS4-3412'   => 8, # UCS-4 unusual ordering
+          'UCS2'        => 9, # UCS-2
+          'ISO-8859-1'  => 10, # ISO-8859-1 ISO Latin 1
+          'ISO-8859-2'  => 11, # ISO-8859-2 ISO Latin 2
+          'ISO-8859-3'  => 12, # ISO-8859-3
+          'ISO-8859-4'  => 13, # ISO-8859-4
+          'ISO-8859-5'  => 14, # ISO-8859-5
+          'ISO-8859-6'  => 15, # ISO-8859-6
+          'ISO-8859-7'  => 16, # ISO-8859-7
+          'ISO-8859-8'  => 17, # ISO-8859-8
+          'ISO-8859-9'  => 18, # ISO-8859-9
+          'ISO-2022-JP' => 19, # ISO-2022-JP
+          'SHIFT-JIS'   => 20, # Shift_JIS
+          'EUC-JP'      => 21, # EUC-JP
+          'ASCII'       => 22, # pure ASCII
+        }
+
+        # The Nokogiri::XML::SAX::Document where events will be sent.
         attr_accessor :document
-        def initialize(doc = XML::SAX::Document.new)
+
+        # 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 = 'UTF-8'
+          check_encoding(encoding)
+          @encoding = encoding
           @document = doc
+          @warned   = false
         end
 
         ###
         # Parse given +thing+ which may be a string containing xml, or an
         # IO object.
-        def parse thing
-          parse_memory(thing.is_a?(IO) ? thing.read : thing)
+        def parse thing, &block
+          if thing.respond_to?(:read) && thing.respond_to?(:close)
+            parse_io(thing, &block)
+          else
+            parse_memory(thing, &block)
+          end
         end
 
         ###
         # Parse given +io+
-        def parse_io io
-          parse_memory io.read
+        def parse_io io, encoding = 'ASCII'
+          check_encoding(encoding)
+          @encoding = encoding
+          ctx = ParserContext.io(io, ENCODINGS[encoding])
+          yield ctx if block_given?
+          ctx.parse_with self
         end
 
         ###
         # Parse a file with +filename+
         def parse_file filename
-          raise Errno::ENOENT unless File.exists?(filename)
+          raise ArgumentError unless filename
+          raise Errno::ENOENT unless File.exist?(filename)
           raise Errno::EISDIR if File.directory?(filename)
-          native_parse_file filename
+          ctx = ParserContext.file filename
+          yield ctx if block_given?
+          ctx.parse_with self
+        end
+
+        def parse_memory data
+          ctx = ParserContext.memory data
+          yield ctx if block_given?
+          ctx.parse_with self
+        end
+
+        private
+        def check_encoding(encoding)
+          encoding.upcase!
+          raise ArgumentError.new("'#{encoding}' is not a valid encoding") unless ENCODINGS[encoding]
         end
       end
     end

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

@@ -0,0 +1,16 @@
+module Nokogiri
+  module XML
+    module SAX
+      ###
+      # Context for XML SAX parsers.  This class is usually not instantiated
+      # by the user.  Instead, you should be looking at
+      # Nokogiri::XML::SAX::Parser
+      class ParserContext
+        def self.new thing, encoding = 'UTF-8'
+          [:read, :close].all? { |x| thing.respond_to?(x) } ?
+            io(thing, Parser::ENCODINGS[encoding]) : memory(thing)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,60 @@
+module Nokogiri
+  module XML
+    module SAX
+      ###
+      # PushParser can parse a document that is fed to it manually.  It
+      # must be given a SAX::Document object which will be called with
+      # SAX events as the document is being parsed.
+      #
+      # Calling PushParser#<< writes XML to the parser, calling any SAX
+      # callbacks it can.
+      #
+      # PushParser#finish tells the parser that the document is finished
+      # and calls the end_document SAX method.
+      #
+      # Example:
+      #
+      #   parser = PushParser.new(Class.new(XML::SAX::Document) {
+      #     def start_document
+      #       puts "start document called"
+      #     end
+      #   }.new)
+      #   parser << "<div>hello<"
+      #   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 = 'UTF-8')
+          @document = doc
+          @encoding = encoding
+          @sax_parser = XML::SAX::Parser.new(doc)
+
+          ## Create our push parser context
+          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 immediately.
+        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
+      end
+    end
+  end
+end

data/lib/nokogiri/xml/sax.rb

@@ -1,9 +1,4 @@
 require 'nokogiri/xml/sax/document'
+require 'nokogiri/xml/sax/parser_context'
 require 'nokogiri/xml/sax/parser'
-
-module Nokogiri
-  module XML
-    module SAX
-    end
-  end
-end
+require 'nokogiri/xml/sax/push_parser'

data/lib/nokogiri/xml/schema.rb

@@ -0,0 +1,63 @@
+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
+        from_document Nokogiri::XML(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
+        if thing.is_a?(Nokogiri::XML::Document) 
+          validate_document(thing) 
+        elsif File.file?(thing)
+          validate_file(thing)
+        else
+          raise ArgumentError, "Must provide Nokogiri::Xml::Document or the name of an existing file"
+        end
+      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/searchable.rb

@@ -0,0 +1,221 @@
+module Nokogiri
+  module XML
+    #
+    #  The Searchable module declares the interface used for searching your DOM.
+    #
+    #  It implements the public methods `search`, `css`, and `xpath`,
+    #  as well as allowing specific implementations to specialize some
+    #  of the important behaviors.
+    #
+    module Searchable
+      # Regular expression used by Searchable#search to determine if a query
+      # string is CSS or XPath
+      LOOKS_LIKE_XPATH = /^(\.\/|\/|\.\.|\.$)/
+      
+      ###
+      # call-seq: search *paths, [namespace-bindings, xpath-variable-bindings, custom-handler-class]
+      #
+      # Search this object for +paths+. +paths+ must be one or more XPath or CSS queries:
+      #
+      #   node.search("div.employee", ".//title")
+      #
+      # A hash of namespace bindings may be appended:
+      #
+      #   node.search('.//bike:tire', {'bike' => 'http://schwinn.com/'})
+      #   node.search('bike|tire', {'bike' => 'http://schwinn.com/'})
+      #
+      # For XPath queries, a hash of variable bindings may also be
+      # appended to the namespace bindings. For example:
+      #
+      #   node.search('.//address[@domestic=$value]', nil, {:value => 'Yes'})
+      #
+      # Custom XPath functions and CSS pseudo-selectors 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.search('.//title[regex(., "\w+")]', 'div.employee:regex("[0-9]+")'
+      #     Class.new {
+      #       def regex node_set, regex
+      #         node_set.find_all { |node| node['some_attribute'] =~ /#{regex}/ }
+      #       end
+      #     }.new
+      #   )
+      #
+      # See Searchable#xpath and Searchable#css for further usage help.
+      def search *args
+        paths, handler, ns, binds = extract_params(args)
+
+        xpaths = paths.map(&:to_s).map do |path|
+          (path =~ LOOKS_LIKE_XPATH) ? path : xpath_query_from_css_rule(path, ns)
+        end.flatten.uniq
+
+        xpath(*(xpaths + [ns, handler, binds].compact))
+      end
+      alias :/ :search
+
+      ###
+      # call-seq: search *paths, [namespace-bindings, xpath-variable-bindings, custom-handler-class]
+      #
+      # Search this object for +paths+, and return only the first
+      # result. +paths+ must be one or more XPath or CSS queries.
+      #
+      # See Searchable#search for more information.
+      def at *args
+        search(*args).first
+      end
+      alias :% :at
+
+      ###
+      # call-seq: css *rules, [namespace-bindings, custom-pseudo-class]
+      #
+      # Search this object for CSS +rules+. +rules+ must be one or more CSS
+      # selectors. For example:
+      #
+      #   node.css('title')
+      #   node.css('body h1.bold')
+      #   node.css('div + p.green', 'div#one')
+      #
+      # 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 *args
+        rules, handler, ns, _ = extract_params(args)
+
+        css_internal self, rules, handler, ns
+      end
+
+      ##
+      # call-seq: css *rules, [namespace-bindings, custom-pseudo-class]
+      #
+      # Search this object for CSS +rules+, and return only the first
+      # match. +rules+ must be one or more CSS selectors.
+      #
+      # See Searchable#css for more information.
+      def at_css *args
+        css(*args).first
+      end
+
+      ###
+      # 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.
+      #
+      #   node.xpath('.//title')
+      #
+      # 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)
+      #
+      # 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
+      #       node_set.find_all { |node| node['some_attribute'] =~ /#{regex}/ }
+      #     end
+      #   }.new)
+      #
+      def xpath *args
+        return NodeSet.new(document) unless document
+
+        paths, handler, ns, binds = extract_params(args)
+
+        sets = paths.map do |path|
+          ctx = XPathContext.new(self)
+          ctx.register_namespaces(ns)
+          path = path.gsub(/xmlns:/, ' :') unless Nokogiri.uses_libxml?
+
+          binds.each do |key,value|
+            ctx.register_variable key.to_s, value
+          end if binds
+
+          ctx.evaluate(path, handler)
+        end
+        return sets.first if sets.length == 1
+
+        NodeSet.new(document) do |combined|
+          sets.each do |set|
+            set.each do |node|
+              combined << node
+            end
+          end
+        end
+      end
+
+      ##
+      # call-seq: xpath *paths, [namespace-bindings, variable-bindings, custom-handler-class]
+      #
+      # Search this node for XPath +paths+, and return only the first
+      # match. +paths+ must be one or more XPath queries.
+      #
+      # See Searchable#xpath for more information.
+      def at_xpath *args
+        xpath(*args).first
+      end
+
+      private
+
+      def css_internal node, rules, handler, ns
+        xpaths = rules.map { |rule| xpath_query_from_css_rule(rule, ns) }
+        node.xpath(*(xpaths + [ns, handler].compact))
+      end
+
+      def xpath_query_from_css_rule rule, ns
+        implied_xpath_contexts.map do |implied_xpath_context|
+          CSS.xpath_for(rule.to_s, :prefix => implied_xpath_context, :ns => ns)
+        end.join(' | ')
+      end
+
+      def extract_params params # :nodoc:
+        handler = params.find do |param|
+          ![Hash, String, Symbol].include?(param.class)
+        end
+        params -= [handler] if handler
+
+        hashes = []
+        while Hash === params.last || params.last.nil?
+          hashes << params.pop
+          break if params.empty?
+        end
+        ns, binds = hashes.reverse
+
+        ns ||= document.root ? document.root.namespaces : {}
+
+        [params, handler, ns, binds]
+      end
+    end
+  end
+end