saxon-rb 0.6.0-java → 0.8.0-java

data/lib/saxon/item_type/value_to_ruby.rb

@@ -8,6 +8,7 @@ module Saxon
       # Regexp patterns to assist in converting XDM typed values into Ruby
       # native types
       module Patterns
+        # @see https://www.w3.org/TR/xmlschema-2/#dateTime-lexical-representation
         DATE_TIME = /\A(-?[0-9]{4,})-([0-9]{2})-([0-9]{2})T([0-9]{2}):([0-9]{2}):([0-9]{2}(?:\.[0-9]+)?)(Z|[-+][0-9]{2}:[0-9]{2})?\z/
       end
 
@@ -54,34 +55,45 @@ module Saxon
       # A collection of Lambdas (or objects responding to +#call+) for
       # converting XDM typed values to native Ruby types.
       module Convertors
+        # @see https://www.w3.org/TR/xmlschema-2/#integer
         INTEGER = INT = SHORT = LONG = UNSIGNED_INT = UNSIGNED_SHORT = UNSIGNED_LONG = \
         POSITIVE_INTEGER = NON_POSITIVE_INTEGER = NEGATIVE_INTEGER = NON_NEGATIVE_INTEGER = ->(xdm_atomic_value) {
           xdm_atomic_value.to_java.getValue
         }
+        # @see https://www.w3.org/TR/xmlschema-2/#decimal
         DECIMAL = ->(xdm_atomic_value) {
           BigDecimal(xdm_atomic_value.to_s)
         }
+        # @see https://www.w3.org/TR/xmlschema-2/#float
         FLOAT = DOUBLE = ->(xdm_atomic_value) {
           xdm_atomic_value.to_java.getValue
         }
+        # @see https://www.w3.org/TR/xmlschema-2/#dateTime
         DATE_TIME = DATE_TIME_STAMP = ValueToRuby::DateTimeConvertor
+        # @see https://www.w3.org/TR/xmlschema-2/#boolean
         BOOLEAN = ->(xdm_atomic_value) {
           xdm_atomic_value.to_java.getValue
         }
+        # @see https://www.w3.org/TR/xmlschema-2/#NOTATION
+        # @see https://www.w3.org/TR/xmlschema-2/#QName
         NOTATION = QNAME = ->(xdm_atomic_value) {
           Saxon::QName.new(xdm_atomic_value.to_java.getQNameValue)
         }
+        # @see https://www.w3.org/TR/xmlschema-2/#base64Binary
         BASE64_BINARY = ->(xdm_atomic_value) {
           Base64.decode64(xdm_atomic_value.to_s)
         }
+        # @see https://www.w3.org/TR/xmlschema-2/#hexBinary
         HEX_BINARY = ->(xdm_atomic_value) {
           bytes = []
           xdm_atomic_value.to_s.scan(/../) { |x| bytes << x.hex.chr(Encoding::ASCII_8BIT) }
           bytes.join
         }
+        # @see https://www.w3.org/TR/xmlschema-2/#byte
         BYTE = ->(xdm_atomic_value) {
           [xdm_atomic_value.to_java.getLongValue].pack('c')
         }
+        # @see https://www.w3.org/TR/xmlschema-2/#unsignedByte
         UNSIGNED_BYTE = ->(xdm_atomic_value) {
           [xdm_atomic_value.to_java.getLongValue].pack('C')
         }

data/lib/saxon/jruby_bug_6197_workaround.rb

@@ -0,0 +1,5 @@
+unless Java::net::sf::saxon::s9api::Xslt30Transformer.instance_methods.include?(:setInitialMode)
+  class Java::net::sf::saxon::s9api::Xslt30Transformer
+    java_alias :setInitialMode, :setInitialMode, [Java::net::sf::saxon::s9api::QName]
+  end
+end

data/lib/saxon/loader.rb

@@ -19,6 +19,7 @@ module Saxon
         @path = path
       end
 
+      # returns an error message including the missing path
       def to_s
         "The path ('#{@path}') you supplied for the Saxon .jar files doesn't exist, sorry"
       end
@@ -31,65 +32,77 @@ module Saxon
         @path = path
       end
 
+      # returns an error message including the path looked in and jars we were looking for
       def to_s
         "One of saxon9he.jar, saxon9pe.jar, or saxon9ee.jar must be present in the path ('#{@path}') you supplied, sorry"
       end
     end
 
-    # @param saxon_home [String, Pathname] the path to the dir containing
-    #   Saxon's .jars. Defaults to the vendored Saxon HE
-    # @return [true, false] Returns true if Saxon had not been loaded and
-    #   is now, and false if Saxon was already loaded
-    def self.load!(saxon_home = nil)
-      return false if instance_variable_defined?(:@saxon_loaded) && @saxon_loaded
-      LOAD_SEMAPHORE.synchronize do
-        if Saxon::S9API.const_defined?(:Processor)
+    class << self
+      # Are the Saxon jars missing from the Classpath?
+      # @return [Boolean] true if the Jars are not on the Classpath
+      def jars_not_on_classpath?
+        begin
+          Java::net.sf.saxon.s9api.Processor
           false
-        else
-          if jars_not_on_classpath?
-            if saxon_home.nil?
-              require 'saxon-rb_jars'
-            else
-              saxon_home = Pathname.new(saxon_home)
-              raise NoJarsError, saxon_home unless saxon_home.directory?
-              jars = [main_jar(saxon_home)].compact
-              raise MissingJarError if jars.empty?
-              jars += extra_jars(saxon_home)
+        rescue
+          true
+        end
+      end
+
+      # Are the Saxon JARs on the Classpath?
+      # @return [Boolean] whether the Jars are on the Classpath already
+      def jars_on_classpath?
+        !jars_not_on_classpath?
+      end
+
+      # @param saxon_home [String, Pathname] the path to the dir containing
+      #   Saxon's .jars. Defaults to the vendored Saxon HE
+      # @return [true, false] Returns true if Saxon had not been loaded and
+      #   is now, and false if Saxon was already loaded
+      def load!(saxon_home = nil)
+        return false if instance_variable_defined?(:@saxon_loaded) && @saxon_loaded
+        LOAD_SEMAPHORE.synchronize do
+          if Saxon::S9API.const_defined?(:Processor)
+            false
+          else
+            if jars_not_on_classpath?
+              if saxon_home.nil?
+                require 'saxon-rb_jars'
+              else
+                saxon_home = Pathname.new(saxon_home)
+                raise NoJarsError, saxon_home unless saxon_home.directory?
+                jars = [main_jar(saxon_home)].compact
+                raise MissingJarError if jars.empty?
+                jars += extra_jars(saxon_home)
 
-              add_jars_to_classpath!(saxon_home, jars)
+                add_jars_to_classpath!(saxon_home, jars)
+              end
             end
-          end
 
-          @saxon_loaded = true
-          true
+            require_relative 'jruby_bug_6197_workaround'
+            @saxon_loaded = true
+            true
+          end
         end
       end
-    end
 
-    private
-
-    def self.main_jar(path)
-      ['saxon9he.jar', 'saxon9pe.jar', 'saxon9ee.jar'].map { |jar| path.join(jar) }.find { |jar| jar.file? }
-    end
+      private
 
-    def self.extra_jars(path)
-      optional = ['saxon9-unpack.jar', 'saxon9-sql.jar'].map { |jar| path.join(jar) }.select { |jar| jar.file? }
-      icu = path.children.find { |jar| jar.extname == '.jar' && !jar.basename.to_s.match(/^saxon-icu|^icu4j/).nil? }
-      ([icu] + optional).compact
-    end
+      def main_jar(path)
+        ['saxon9he.jar', 'saxon9pe.jar', 'saxon9ee.jar'].map { |jar| path.join(jar) }.find { |jar| jar.file? }
+      end
 
-    def self.jars_not_on_classpath?
-      begin
-        Java::net.sf.saxon.s9api.Processor
-        false
-      rescue
-        true
+      def extra_jars(path)
+        optional = ['saxon9-unpack.jar', 'saxon9-sql.jar'].map { |jar| path.join(jar) }.select { |jar| jar.file? }
+        icu = path.children.find { |jar| jar.extname == '.jar' && !jar.basename.to_s.match(/^saxon-icu|^icu4j/).nil? }
+        ([icu] + optional).compact
       end
-    end
 
-    def self.add_jars_to_classpath!(saxon_home, jars)
-      jars.each do |jar|
-        $CLASSPATH << jar.to_s
+      def add_jars_to_classpath!(saxon_home, jars)
+        jars.each do |jar|
+          $CLASSPATH << jar.to_s
+        end
       end
     end
   end

data/lib/saxon/processor.rb

@@ -46,12 +46,14 @@ module Saxon
       @s9_processor = s9_processor
     end
 
-    # Generate a new DocumentBuilder that uses this Processor.
-    # Sharing DocumentBuilders across threads is not recommended/
+    # Generate a new DocumentBuilder that uses this Processor. Sharing
+    # DocumentBuilders across threads is not safe.
     #
+    # @yield A DocumentBuilder configuration DSL block, see
+    #   {Saxon::DocumentBuilder.create}
     # @return [Saxon::DocumentBuilder] A new Saxon::DocumentBuilder
-    def document_builder
-      Saxon::DocumentBuilder.new(@s9_processor.newDocumentBuilder)
+    def document_builder(&block)
+      Saxon::DocumentBuilder.create(self, &block)
     end
 
     # Declare custom collations for use by XSLT, XPath, and XQuery processors

data/lib/saxon/s9api.rb

@@ -11,28 +11,28 @@ module Saxon
       # alternate location for them, if they don't want to use the bundled Saxon
       # HE
       def const_missing(name)
-        Saxon::Loader.load!
-        begin
-          const_set(name, imported_classes.const_get(name))
-        rescue NameError
-          msg = "uninitialized constant Saxon::S9API::#{name}"
-          e = NameError.new(msg, name)
-          raise e
-        end
+        CLASS_IMPORT_SEMAPHORE.synchronize {
+          return const_get(name) if const_defined?(name)
+          Saxon::Loader.load!
+          begin
+            const_set(name, imported_classes.const_get(name))
+          rescue NameError
+            msg = "uninitialized constant Saxon::S9API::#{name}"
+            e = NameError.new(msg, name)
+            raise e
+          end
+        }
       end
 
       private
 
       def imported_classes
-        return @imported_classes if instance_variable_defined?(:@imported_classes)
-        CLASS_IMPORT_SEMAPHORE.synchronize do
-          @imported_classes = Module.new {
-            include_package 'net.sf.saxon.s9api'
-            java_import Java::net.sf.saxon.Configuration
-            java_import Java::net.sf.saxon.lib.FeatureKeys
-            java_import Java::net.sf.saxon.lib.ParseOptions
-          }
-        end
+        @imported_classes ||= Module.new {
+          include_package 'net.sf.saxon.s9api'
+          java_import Java::net.sf.saxon.Configuration
+          java_import Java::net.sf.saxon.lib.FeatureKeys
+          java_import Java::net.sf.saxon.lib.ParseOptions
+        }
       end
     end
   end

data/lib/saxon/version.rb

@@ -1,3 +1,9 @@
+require 'saxon/version/library'
+
 module Saxon
-  VERSION = "0.6.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.8.0"
+  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

data/lib/saxon/xdm/atomic_value.rb

@@ -20,6 +20,7 @@ module Saxon
       # them imlpicitly through the XDM::AtomicValue creation process doesn't really
       # work. They need to be created explicitly and then handed in to be wrapped.
       class CannotCreateQNameFromString < StandardError
+        # returns an error message
         def to_s
           "QName XDM::AtomicValues must be created using an instance of Saxon::QName, not a string like 'prefix:name': Prefix URI binding is undefined at this point"
         end
@@ -29,17 +30,23 @@ module Saxon
       # isn't a way to create these outside of parsing an XML document within
       # Saxon, so attempting to do so raises this error.
       class NotationCannotBeDirectlyCreated < StandardError
-        def to_s
+         # returns an error message
+         def to_s
           "xs:NOTATION XDM::AtomicValues cannot be directly created outside of XML parsing."
         end
       end
 
-      # ItemType representing QNames
-      XS_QNAME = ItemType.get_type('xs:QName')
-      # ItemType representing NOTATION
-      XS_NOTATION = ItemType.get_type('xs:NOTATION')
-
       class << self
+        # ItemType representing QNames
+        def xs_qname
+          @xs_qname ||= ItemType.get_type('xs:QName')
+        end
+
+        # ItemType representing NOTATION
+        def xs_notation
+          @xs_notation ||= ItemType.get_type('xs:NOTATION')
+        end
+
         # Convert a single Ruby value into an XDM::AtomicValue
         #
         # If no explicit {ItemType} is passed, the correct type is guessed based
@@ -69,8 +76,8 @@ module Saxon
 
             item_type = ItemType.get_type(item_type)
 
-            return new(Saxon::S9API::XdmAtomicValue.new(value.to_java)) if item_type == XS_QNAME && value_is_qname?(value)
-            raise NotationCannotBeDirectlyCreated if item_type == XS_NOTATION
+            return new(Saxon::S9API::XdmAtomicValue.new(value.to_java)) if item_type == xs_qname && value_is_qname?(value)
+            raise NotationCannotBeDirectlyCreated if item_type == xs_notation
 
             value_lexical_string = item_type.lexical_string(value)
             new(new_s9_xdm_atomic_value(value_lexical_string, item_type))
@@ -89,7 +96,7 @@ module Saxon
         # @return [Saxon::XDM::AtomicValue]
         def from_lexical_string(value, item_type)
           item_type = ItemType.get_type(item_type)
-          raise CannotCreateQNameFromString if item_type == XS_QNAME
+          raise CannotCreateQNameFromString if item_type == xs_qname
           new(new_s9_xdm_atomic_value(value.to_s, item_type))
         end
 

data/lib/saxon/xdm/node.rb

@@ -85,6 +85,36 @@ module Saxon
       def axis_iterator(axis)
         AxisIterator.new(self, axis)
       end
+
+      # Use Saxon's naive XDM Node serialisation to serialize the node and its
+      # descendants. Saxon uses a new Serializer with default options to
+      # serialize the node. In particular, if the Node was produced by an XSLT
+      # that used +<xsl:character-map>+ through +<xsl:output>+ to modify the
+      # contents, then they *WILL* *NOT* have been applied.
+      #
+      # +<xsl:output>+ has its effect at serialization time, not at XDM tree
+      # creation time, so it won't be applied until you serialize the document.
+      #
+      # Even then, unless you use a {Serializer} configured with the XSLT's
+      # +<xsl:output>+. We make a properly configured serializer available in
+      # the result of any XSLT transform (a {Saxon::XSLT::Invocation}), e.g.:
+      #
+      #   result = xslt.apply_templates(input)
+      #   result.to_s
+      #   # or
+      #   result.serialize('/path/to/output.xml')
+      #
+      # You can also get that {Serializer} directly from {XSLT::Executable},
+      # should you want to use the serialization options from a particular XSLT
+      # to serialize arbitrary XDM values:
+      #
+      #   serializer = xslt.serializer
+      #   serializer.serialize(an_xdm_value)
+      #
+      # @see http://www.saxonica.com/documentation9.9/index.html#!javadoc/net.sf.saxon.s9api/XdmNode@toString
+      def to_s
+        s9_xdm_node.toString
+      end
     end
   end
 end