saxon-rb 0.4.0-java → 0.7.2-java

data/lib/saxon/serializer/output_properties.rb

@@ -0,0 +1,83 @@
+module Saxon
+  module Serializer
+    # Manage access to the serialization properties of this serializer, with
+    # hash-like access.
+    #
+    # Properties can be set explicitly through this API, or via XSLT or XQuery
+    # serialization options like +<xsl:output>+.
+    #
+    # Properties set explicitly here will override properties set through the
+    # document by +<xsl:output>+.
+    module OutputProperties
+      # @return [Saxon::Serializer::OutputProperties] hash-like access to the Output Properties
+      def output_property
+        @output_property ||= OutputProperties::Accessor.new(s9_serializer)
+      end
+
+      # @api private
+      #
+      # The private wrapper class that manages getting and setting output
+      # properties on a Serializer in an idiomatic Ruby-like way.
+      class Accessor
+        # @api private
+        # Provides mapping between symbols and the underlying Saxon property
+        # instances
+        def self.output_properties
+          @output_properties ||= Hash[
+            Saxon::S9API::Serializer::Property.values.map { |property|
+              qname = property.getQName
+              key = [
+                qname.getPrefix,
+                qname.getLocalName.tr('-', '_')
+              ].reject { |str| str == '' }.join('_').to_sym
+              [key, property]
+            }
+          ]
+        end
+
+        attr_reader :s9_serializer
+
+        # @api private
+        def initialize(s9_serializer)
+          @s9_serializer = s9_serializer
+        end
+
+        # @param [Symbol, Saxon::S9API::Serializer::Property] property The property to fetch
+        def [](property)
+          s9_serializer.getOutputProperty(resolved_property(property))
+        end
+
+        # @param [Symbol, Saxon::S9API::Serializer::Property] property The property to set
+        # @param [String] value The string value of the property
+        def []=(property, value)
+          s9_serializer.setOutputProperty(resolved_property(property), value)
+        end
+
+        # @overload fetch(property)
+        #   @param [Symbol, Saxon::S9API::Serializer::Property] property The property to fetch
+        # @overload fetch(property, default)
+        #   @param property [Symbol, Saxon::S9API::Serializer::Property] The property to fetch
+        #   @param default [Object] The value to return if the property is unset
+        def fetch(property, default = nil)
+          explicit_value = self[property]
+          if explicit_value.nil? && !default.nil?
+            default
+          else
+            explicit_value
+          end
+        end
+
+        private
+
+        def resolved_property(property_key)
+          case property_key
+          when Symbol
+            self.class.output_properties.fetch(property_key)
+          else
+            property_key
+          end
+        end
+      end
+    end
+  end
+end

data/lib/saxon/source.rb

@@ -1,6 +1,7 @@
 require 'java'
 require 'saxon/jaxp'
 require 'uri'
+require 'open-uri'
 require 'pathname'
 
 module Saxon
@@ -8,10 +9,13 @@ module Saxon
   # the XML bytestream in. Provides some extra methods to make handling closing
   # the source and its inputstream after consumption more idiomatic
   class Source
+    # Helper methods for getting Java-useful representations of source document
+    # strings and files
     module Helpers
       # Given a File, or IO object which will return either #path or
       # #base_uri, return the #base_uri, if present, or the #path, if present, or
       # nil
+      #
       # @param [File, IO] io A File or IO
       #   object representing the input XML file or data, or a String containing
       #   the XML
@@ -23,30 +27,92 @@ module Saxon
         io.path if io.respond_to?(:path)
       end
 
-      # Given a File or IO return a Java InputStream
-      # @param [File, IO, org.jruby.util.IOInputStream, java.io.InputStream]
-      #   io input to be converted to an input stream
+      # Given a File or IO return a Java InputStream, or an InputStreamReader if
+      # the Encoding is explicitly specified (rather than inferred from the
+      # <?xml charset="..."?>) declaration in the source.
+      #
+      # @param io [File, IO, org.jruby.util.IOInputStream, java.io.InputStream]
+      #   input to be converted to an input stream
+      # @param encoding [Encoding, String] the character encoding to be used to
+      #   for the stream, overriding the XML parser.
       # @return [java.io.InputStream] the wrapped input
-      def self.inputstream(io)
-        case io
+      def self.inputstream(io, encoding = nil)
+        stream = case io
         when org.jruby.util.IOInputStream, java.io.InputStream
           io
         else
           io.to_inputstream if io.respond_to?(:read)
         end
+
+        return stream if encoding.nil?
+        java.io.InputStreamReader.new(stream, ruby_encoding_to_charset(encoding))
       end
 
       # Given a path return a Java File object
-      # @param [String, Pathname] path the path to the file
+      #
+      # @param path [String, Pathname] the path to the file
       # @return [java.io.File] the Java File object
       def self.file(path)
         java.io.File.new(path.to_s)
       end
+
+      # Given a file path and encoding, return a Java InputStreamReader object
+      # for the file.
+      #
+      # @param path [String, Pathname] the path to the file
+      # @param encoding [String, Encoding] the file's character encoding
+      # @return [java.io.InputStreamReader] a Java InputStreamReader object
+      #   wrapping a FileInputStream for the file
+      def self.file_reader(path, encoding)
+        java.io.InputStreamReader.new(java.io.FileInputStream.new(file(path)), ruby_encoding_to_charset(encoding))
+      end
+
+      # Return a File or Reader object for a file, depending on whether the
+      # encoding must be explicitly specified or not.
+      #
+      # @param path [String, Pathname] the path to the file
+      # @param encoding [String, Encoding] the file's character encoding
+      # @return [java.io.Reader] a Java Reader object
+      def self.file_or_reader(path, encoding = nil)
+        encoding.nil? ? file(path) : file_reader(path, encoding)
+      end
+
+      # Return a Reader object for the String with an explicitly set encoding.
+      # If the encoding is +ASCII_8BIT+ then a binary-mode StreamReader is
+      # returned, rather than a character Reader
+      #
+      # @param string [String] the string
+      # @param encoding [String, Encoding] the string's character encoding
+      # @return [java.io.InputStream, java.io.Reader] a Java InputStream or Reader object
+      def self.string_reader(string, encoding)
+        inputstream = StringIO.new(string).to_inputstream
+        encoding = ruby_encoding(encoding)
+        return inputstream if encoding == ::Encoding::ASCII_8BIT
+        java.io.InputStreamReader.new(inputstream, ruby_encoding_to_charset(encoding))
+      end
+
+      # Figure out the equivalent Java +Charset+ for a Ruby {Encoding}.
+      #
+      # @param encoding [String, Encoding] the encoding to find a +Charset+ for
+      def self.ruby_encoding_to_charset(encoding)
+        ruby_encoding(encoding).to_java.getEncoding.getCharset
+      end
+
+      # Given a String with an {Encoding} name or an {Encoding} instance, return
+      # an {Encoding} instance
+      #
+      # @param encoding [String, Encoding] the encoding or encoding name
+      # @return [Encoding] the encoding
+      def self.ruby_encoding(encoding)
+        encoding.nil? ? nil : ::Encoding.find(encoding)
+      end
     end
 
+    # Lambda that checks if the given path exists and is a file
     PathChecker = ->(path) {
       File.file?(path)
     }
+    # Lambda that checks if the given string is a valid URI
     URIChecker = ->(uri) {
       begin
         URI.parse(uri)
@@ -56,75 +122,144 @@ module Saxon
       end
     }
 
-    # Generate a Saxon::Source given an IO-like
-    #
-    # @param [IO, File] io The IO-like containing XML to be parsed
-    # @param [Hash] opts
-    # @option opts [String] :base_uri The Base URI for the Source - an
-    #   absolute URI or relative path that will be used to resolve relative
-    #   URLs in the XML. Setting this will override any path or URI derived
-    #   from the IO-like.
-    # @return [Saxon::Source] the Saxon::Source wrapping the input
-    def self.from_io(io, opts = {})
-      base_uri = opts.fetch(:base_uri) { Helpers.base_uri(io) }
-      inputstream = Helpers.inputstream(io)
-      stream_source = Saxon::JAXP::StreamSource.new(inputstream, base_uri)
-      new(stream_source, inputstream)
-    end
+    class << self
+      # Generate a Saxon::Source given an IO-like
+      #
+      # @param [IO, File] io The IO-like containing XML to be parsed
+      # @param [Hash] opts
+      # @option opts [String] :base_uri The Base URI for the Source - an
+      #   absolute URI or relative path that will be used to resolve relative
+      #   URLs in the XML. Setting this will override any path or URI derived
+      #   from the IO-like.
+      # @option opts [String, Encoding] :encoding The encoding of the source.
+      #   Note that specifying this will force the parser to ignore the charset
+      #   if it's set in the XML declaration of the source. Only really useful
+      #   if there's a discrepancy between the source's declared and actual
+      #   encoding. Defaults to the <?xml charset="..."?> declaration in the
+      #   source.
+      # @return [Saxon::Source] the Saxon::Source wrapping the input
+      def from_io(io, opts = {})
+        base_uri = opts.fetch(:base_uri) { Helpers.base_uri(io) }
+        encoding = opts.fetch(:encoding, nil)
+        inputstream = Helpers.inputstream(io, encoding)
+        from_inputstream_or_reader(inputstream, base_uri)
+      end
 
-    # Generate a Saxon::Source given a path to a file
-    #
-    # @param [String, Pathname] path The path to the XML file to be parsed
-    # @param [Hash] opts
-    # @option opts [String] :base_uri The Base URI for the Source - an
-    #   absolute URI or relative path that will be used to resolve relative
-    #   URLs in the XML. Setting this will override the file path.
-    # @return [Saxon::Source] the Saxon::Source wrapping the input
-    def self.from_path(path, opts = {})
-      stream_source = Saxon::JAXP::StreamSource.new(Helpers.file(path))
-      stream_source.setSystemId(opts[:base_uri]) if opts[:base_uri]
-      new(stream_source)
-    end
+      # Generate a Saxon::Source given a path to a file
+      #
+      # @param [String, Pathname] path The path to the XML file to be parsed
+      # @param [Hash] opts
+      # @option opts [String] :base_uri The Base URI for the Source - an
+      #   absolute URI or relative path that will be used to resolve relative
+      #   URLs in the XML. Setting this will override the file path.
+      # @option opts [String, Encoding] :encoding The encoding of the source.
+      #   Note that specifying this will force the parser to ignore the charset
+      #   if it's set in the XML declaration of the source. Only really useful
+      #   if there's a discrepancy between the source's declared and actual
+      #   encoding. Defaults to the <?xml charset="..."?> declaration in the
+      #   source.
+      # @return [Saxon::Source] the Saxon::Source wrapping the input
+      def from_path(path, opts = {})
+        encoding = opts.fetch(:encoding, nil)
+        return from_inputstream_or_reader(Helpers.file(path), opts[:base_uri]) if encoding.nil?
+        reader = Helpers.file_reader(path, encoding)
+        base_uri = opts.fetch(:base_uri) { File.expand_path(path) }
+        from_inputstream_or_reader(reader, base_uri)
+      end
 
-    # Generate a Saxon::Source given a URI
-    #
-    # @param [String, URI] uri The URI to the XML file to be parsed
-    # @param [Hash] opts
-    # @option opts [String] :base_uri The Base URI for the Source - an
-    #   absolute URI or relative path that will be used to resolve relative
-    #   URLs in the XML. Setting this will override the given URI.
-    # @return [Saxon::Source] the Saxon::Source wrapping the input
-    def self.from_uri(uri, opts = {})
-      stream_source = Saxon::JAXP::StreamSource.new(uri.to_s)
-      stream_source.setSystemId(opts[:base_uri]) if opts[:base_uri]
-      new(stream_source)
-    end
+      # Generate a Saxon::Source given a URI
+      #
+      # @param [String, URI] uri The URI to the XML file to be parsed
+      # @param [Hash] opts
+      # @option opts [String] :base_uri The Base URI for the Source - an
+      #   absolute URI or relative path that will be used to resolve relative
+      #   URLs in the XML. Setting this will override the given URI.
+      # @option opts [String, Encoding] :encoding The encoding of the source.
+      #   Note that specifying this will force the parser to ignore the charset
+      #   if it's set in the XML declaration of the source. Only really useful
+      #   if there's a discrepancy between the source's declared and actual
+      #   encoding. Defaults to the <?xml charset="..."?> declaration in the
+      #   source.
+      # @return [Saxon::Source] the Saxon::Source wrapping the input
+      def from_uri(uri, opts = {})
+        encoding = opts.fetch(:encoding, nil)
+        return from_io(open(uri), encoding: encoding) if encoding
+        from_inputstream_or_reader(uri.to_s, opts[:base_uri])
+      end
 
-    # Generate a Saxon::Source given a string containing XML
-    #
-    # @param [String] string The string containing XML to be parsed
-    # @param [Hash] opts
-    # @option opts [String] :base_uri The Base URI for the Source - an
-    #   absolute URI or relative path that will be used to resolve relative
-    #   URLs in the XML. This will be nil unless set.
-    # @return [Saxon::Source] the Saxon::Source wrapping the input
-    def self.from_string(string, opts = {})
-      reader = java.io.StringReader.new(string)
-      stream_source = Saxon::JAXP::StreamSource.new(reader)
-      stream_source.setSystemId(opts[:base_uri]) if opts[:base_uri]
-      new(stream_source, reader)
-    end
+      # Generate a Saxon::Source given a string containing XML
+      #
+      # @param [String] string The string containing XML to be parsed
+      # @param [Hash] opts
+      # @option opts [String] :base_uri The Base URI for the Source - an
+      #   absolute URI or relative path that will be used to resolve relative
+      #   URLs in the XML. This will be nil unless set.
+      # @option opts [String, Encoding] :encoding The encoding of the source.
+      #   Note that specifying this will force the parser to ignore the charset
+      #   if it's set in the XML declaration of the source. Only really useful
+      #   if there's a discrepancy between the encoding of the string and the
+      #   encoding of the source. Defaults to the encoding of the string, unless
+      #   that is ASCII-8BIT, in which case the parser will use the
+      #   <?xml charset="..."?> declaration in the source to pick the encoding.
+      # @return [Saxon::Source] the Saxon::Source wrapping the input
+      def from_string(string, opts = {})
+        encoding = opts.fetch(:encoding) { string.encoding }
+        reader = Helpers.string_reader(string, encoding)
+        from_inputstream_or_reader(reader, opts[:base_uri])
+      end
+
+      # Generate a Saxon::Source from one of the several inputs allowed.
+      #
+      # If possible the character encoding of the input source will be left to
+      # the XML parser to discover (from the <tt><?xml charset="..."?></tt> XML
+      # declaration).
+      #
+      # The Base URI for the source (its absolute path, or URI) can be set by
+      # passing in the +:base_uri+ option. This is the same thing as an XML
+      # document's 'System ID' - Base URI is the term most widely used in Ruby
+      # libraries for this, so that's what's used here.
+      #
+      # If the source's character encoding can't be correctly discovered by the
+      # parser from the XML declaration (<tt><?xml version="..."
+      # charset="..."?></tt> at the top of the document), then it can be passed
+      # as the +:encoding+ option.
+      #
+      # If an existing {Source} is passed in, simply return it.
+      #
+      # @param [Saxon::Source, IO, File, String, Pathname, URI] input The XML to be parsed
+      # @param [Hash] opts
+      # @option opts [String] :base_uri The Base URI for the Source - an
+      #   absolute URI or relative path that will be used to resolve relative
+      #   URLs in the XML. Setting this will override any path or URI derived
+      #   from an IO, URI, or Path.
+      # @option opts [String, Encoding] :encoding The encoding of the source.
+      #   Note that specifying this will force the parser to ignore the charset
+      #   if it's set in the XML declaration of the source. Only really useful
+      #   if there's a discrepancy between the source's declared and actual
+      #   encoding. Defaults to the <?xml charset="..."?> declaration in the
+      #   source.
+      # @return [Saxon::Source] the Saxon::Source wrapping the input
+      def create(input, opts = {})
+        case input
+        when Saxon::Source
+          input
+        when IO, File, java.io.InputStream, StringIO
+          from_io(input, opts)
+        when Pathname, PathChecker
+          from_path(input, opts)
+        when URIChecker
+          from_uri(input, opts)
+        else
+          from_string(input, opts)
+        end
+      end
+
+      private
 
-    def self.create(io_path_uri_or_string, opts = {})
-      case io_path_uri_or_string
-      when IO, File, java.io.InputStream, StringIO
-        from_io(io_path_uri_or_string, opts)
-      when Pathname, PathChecker
-        from_path(io_path_uri_or_string, opts)
-      when URIChecker
-        from_uri(io_path_uri_or_string, opts)
-      else
-        from_string(io_path_uri_or_string, opts)
+      def from_inputstream_or_reader(inputstream_or_reader, base_uri = nil)
+        stream_source = Saxon::JAXP::StreamSource.new(inputstream_or_reader)
+        stream_source.setSystemId(base_uri) if base_uri
+        new(stream_source, inputstream_or_reader)
       end
     end
 
@@ -183,5 +318,6 @@ module Saxon
     end
   end
 
+  # Error raised when trying to consume an already-consumed, and closed, Source
   class SourceClosedError < Exception; end
 end

data/lib/saxon/version.rb

@@ -1,3 +1,9 @@
+require 'saxon/s9api'
+
 module Saxon
-  VERSION = "0.4.0"
+  # Provides the saxon-rb and underlying Saxon library versions
+  module Version
+    # The version of the saxon-rb gem (not of Saxon itself)
+    WRAPPER = "0.7.2"
+  end
 end

data/lib/saxon/version/library.rb

@@ -0,0 +1,89 @@
+require 'saxon/s9api'
+
+module Saxon
+  module Version
+    # The version of the underlying Saxon library, which we need to discover at
+    # runtime based on what version is on the Classpath
+    class Library
+      # The loaded version of the Saxon Java library
+      #
+      # @return [Saxon::Version::Library] the version of the loaded library
+      def self.loaded_version
+        Saxon::Loader.load!
+
+        sv = Java::net.sf.saxon.Version
+        new(sv.getProductVersion, sv.getStructuredVersionNumber, sv.softwareEdition)
+      end
+
+      include Comparable
+
+      # @return [String] the version string (e.g. '9.9.1.6', '10.0')
+      attr_reader :version
+      # @return [String] the version components (e.g. <tt>[9, 9, 1, 6]</tt>, <tt>[10, 0]</tt>)
+      attr_reader :components
+      # @return [Symbol] the edition (+:he+, +:pe+, or +:ee+)
+      attr_reader :edition
+
+      # @param version [String] the version string
+      # @param components [Array<Integer>] the version components separated
+      # @param edition [String, Symbol] the name of the Saxon edition (e.g. +:he+, +'HE'+)
+      def initialize(version, components, edition)
+        @version = version.dup.freeze
+        @components = components.dup.freeze
+        @edition = edition.downcase.to_sym
+      end
+
+      # Comparison against another instance
+      #
+      # @param other [Saxon::Version::Library] the other version to compare against
+      # @return [Integer] -1 for less, 1 for greater, 0 for equal
+      def <=>(other)
+        return false unless other.is_a?(self.class)
+
+        n_components = [self.components.length, other.components.length].max
+        (0..(n_components - 1)).reduce(0, &comparator(other))
+      end
+
+      # Pessimistic comparison à la rubygems +~>+: do I satisfy the other
+      # version if considered as a pessimistic version constraint
+      #
+      # @param pessimistic_version [Saxon::Version::Library] the version to
+      #   compare pessimistically
+      # @return [Boolean] do I satisfy the constraint?
+      def pessimistic_compare(pessimistic_version)
+        pessimistic_components = pessimistic_version.components
+        pessimistic_components = pessimistic_components + [0] if pessimistic_components.length == 1
+        locked = pessimistic_components[0..-2]
+        locked = locked.zip(components[0..locked.length])
+        variable = [pessimistic_components[-1], components[locked.length]]
+
+        locked_ok = locked.all? { |check, mine|
+          check == mine
+        }
+
+        return false unless locked_ok
+
+        check, mine = variable
+        mine >= check
+      end
+
+      # @return [String] the version string
+      def to_s
+        version
+      end
+
+      private
+
+      def comparator(other)
+        ->(cmp, i) {
+          return cmp unless cmp == 0
+
+          mine = self.components[i].nil? ? 0 : self.components[i]
+          theirs = other.components[i].nil? ? 0 : other.components[i]
+
+          mine <=> theirs
+        }
+      end
+    end
+  end
+end