saxon-rb 0.5.0-java → 0.7.3-java

data/lib/saxon/serializer/object.rb

@@ -0,0 +1,93 @@
+require_relative '../s9api'
+require_relative './output_properties'
+require 'stringio'
+
+module Saxon
+  module Serializer
+    # A Saxon Serializer to be used directly with XDM Values rather than being
+    # called as a Destination for a transformation.
+    class Object
+      # Create a serializer from the passed in +Processor+. When called with a
+      # block, the block will be executed via instance-exec so that output
+      # properties can be set, e.g.
+      #
+      #     Serializer::Object.create(processor) {
+      #       output_property[:indent] = 'yes'
+      #     }
+      #
+      # @param processor [Saxon::Processor] the processor to create this
+      #   +Serializer::Object+ from
+      # @yield the passed block bound via instance-exec to the new serializer
+      def self.create(processor, &block)
+        new(processor.to_java.newSerializer, &block)
+      end
+
+      include OutputProperties
+
+      attr_reader :s9_serializer
+      private :s9_serializer
+
+      # @api private
+      def initialize(s9_serializer, &block)
+        @s9_serializer = s9_serializer
+        if block_given?
+          instance_exec(&block)
+        end
+      end
+
+      # @overload serialize(xdm_value, io)
+      #   Serialize an XdmValue to an IO
+      #   @param [Saxon::XdmValue] xdm_value The XdmValue to serialize
+      #   @param [File, IO] io The IO to serialize to
+      #   @return [nil]
+      # @overload serialize(xdm_value, path)
+      #   Serialize an XdmValue to file <tt>path</tt>
+      #   @param [Saxon::XdmValue] xdm_value The XdmValue to serialize
+      #   @param [String, Pathname] path The path of the file to serialize to
+      #   @return [nil]
+      # @overload serialize(xdm_value)
+      #   Serialize an XdmValue to a String
+      #   @param [Saxon::XdmValue] xdm_value The XdmValue to serialize
+      #   @return [String] The serialized XdmValue
+      def serialize(xdm_value, io_or_path = nil)
+        case io_or_path
+        when nil
+          serialize_to_string(xdm_value)
+        when String, Pathname
+          serialize_to_file(xdm_value, io_or_path)
+        else
+          serialize_to_io(xdm_value, io_or_path)
+        end
+      end
+
+      # @return [Saxon::S9API::Serializer] The underlying Saxon Serializer object
+      def to_java
+        s9_serializer
+      end
+
+      private
+
+      def serialize_to_io(xdm_value, io)
+        s9_serializer.setOutputStream(io.to_outputstream)
+        s9_serializer.serializeXdmValue(xdm_value.to_java)
+        nil
+      end
+
+      def serialize_to_string(xdm_value)
+        str_encoding = output_property.fetch(:encoding, Encoding.default_internal || Encoding.default_external)
+        StringIO.open { |io|
+          io.binmode
+          serialize_to_io(xdm_value, io)
+          io.string.force_encoding(str_encoding)
+        }
+      end
+
+      def serialize_to_file(xdm_value, path)
+        file = Java::JavaIO::File.new(path.to_s)
+        s9_serializer.setOutputFile(file)
+        s9_serializer.serializeXdmValue(xdm_value.to_java)
+        nil
+      end
+    end
+  end
+end

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/version.rb

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

@@ -33,9 +33,10 @@ module Saxon
         @node_name = node_name.nil? ? nil : Saxon::QName.new(node_name)
       end
 
-      # What kind of node this is. Returns one of +:element+, +:text+,
-      # +:attribute+, +:namespace+, +:comment+, +:processing_instruction+, or
-      # +:comment+
+      # What kind of node this is. Returns one of +:document+, +:element+,
+      # +:text+, +:attribute+, +:namespace+, +:comment+,
+      # +:processing_instruction+, or +:comment+
+      #
       # @return [Symbol] the kind of node this is
       def node_kind
         @node_kind ||= case s9_xdm_node.nodeKind
@@ -84,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

data/lib/saxon/xpath/compiler.rb

@@ -40,7 +40,7 @@ module Saxon
       # static context.
       #
       # @param processor [Saxon::Processor] the {Saxon::Processor} to use
-      # @yield An XPath compiler DSL block
+      # @yield An XPath::StaticContext::DSL block
       # @return [Saxon::XPath::Compiler] the new compiler instance
       def self.create(processor, &block)
         static_context = XPath::StaticContext.define(block)
@@ -79,7 +79,7 @@ module Saxon
       # Compiler's static context. As with {.create}, passing a block gives
       # access to a DSL for setting up the compiler's static context.
       #
-      # @yield An {XPath::StaticContext::DSL} block
+      # @yield An XPath::StaticContext::DSL block
       # @return [Saxon::XPath::Compiler] the new compiler instance
       def create(&block)
         new_static_context = static_context.define(block)

data/lib/saxon/xpath/static_context.rb

@@ -117,7 +117,12 @@ module Saxon
         DSL.define(block)
       end
 
-      attr_reader :declared_variables, :declared_namespaces, :default_collation
+      # @return [String] The default collation URI as a String
+      attr_reader :default_collation
+      # @return [Hash<Saxon::QName => Saxon::XPath::VariableDeclaration] the declared variables
+      attr_reader :declared_variables
+      # @return [Hash<String => String>] the declared namespaces, as a prefix => uri hash
+      attr_reader :declared_namespaces
 
       # @return [Saxon::QName]
       # @overload resolve_variable_qname(qname)

data/lib/saxon/xslt/evaluation_context.rb

@@ -143,7 +143,17 @@ module Saxon
         DSL.define(block)
       end
 
-      attr_reader :default_collation, :static_parameters, :global_parameters, :initial_template_parameters, :initial_template_tunnel_parameters
+
+      # @return [String] The default collation URI as a String
+      attr_reader :default_collation
+      # @return [Hash<Saxon::QName => Saxon::XDM::Value>] All the static parameters
+      attr_reader :static_parameters
+      # @return [Hash<Saxon::QName => Saxon::XDM::Value>] All the global parameters
+      attr_reader :global_parameters
+      # @return [Hash<Saxon::QName => Saxon::XDM::Value>] All the initial template parameters
+      attr_reader :initial_template_parameters
+      # @return [Hash<Saxon::QName => Saxon::XDM::Value>] All the initial template parameters with tunnelling = "yes"
+      attr_reader :initial_template_tunnel_parameters
 
       # @api private
       # When passed a Proc, create a new EvaluationContext based on this one, with the same DSL available as in {.define}.

data/lib/saxon/xslt/executable.rb

@@ -1,8 +1,10 @@
 require 'forwardable'
 require_relative 'evaluation_context'
+require_relative 'invocation'
 require_relative '../serializer'
 require_relative '../xdm'
 require_relative '../qname'
+require_relative '../feature_flags'
 
 module Saxon
   module XSLT
@@ -52,6 +54,7 @@ module Saxon
     # prefix, you must use an explicit {Saxon::QName} to refer to it.
     class Executable
       extend Forwardable
+      extend Saxon::FeatureFlags::Helpers
 
       attr_reader :evaluation_context
       private :evaluation_context
@@ -96,7 +99,7 @@ module Saxon
       #   to pass to the first template matched. Setting already-defined
       #   parameters will replace their value for this invocation of the XSLT
       #   only, it won't affect the {XSLT::Compiler}'s context.
-      # @return [Saxon::XSLT::Result] the transformation result
+      # @return [Saxon::XSLT::Invocation] the transformation result
       def apply_templates(source, opts = {})
         transformation(opts).apply_templates(source)
       end
@@ -130,7 +133,7 @@ module Saxon
       #   to pass to the first template matched. Setting already-defined
       #   parameters will replace their value for this invocation of the XSLT
       #   only, it won't affect the {XSLT::Compiler}'s context.
-      # @return [Saxon::XSLT::Result] the transformation result
+      # @return [Saxon::XSLT::Invocation] the transformation result
       def call_template(template_name = nil, opts = {})
         transformation(opts).call_template(template_name)
       end
@@ -155,14 +158,23 @@ module Saxon
       #   Additional global parameters to set. Setting already-defined
       #   parameters will replace their value for this invocation of the XSLT
       #   only, it won't affect the {XSLT::Compiler}'s context.
-      # @return [Saxon::XSLT::Result] the transformation result
+      # @return [Saxon::XSLT::Invocation] the transformation result
       def call_function(function_name, opts = {})
         args = opts.fetch(:args, [])
         transformation(opts.reject { |k, v| k == :args }).call_function(function_name, args)
       end
 
+      # Create a {Serializer::Object} configured using the options that were set
+      # by +<xsl:output>+.
+      #
+      # @return [Saxon::Serializer::Object] the Serializer
+      def serializer
+        Saxon::Serializer::Object.new(@s9_xslt_executable.load30.newSerializer)
+      end
+      requires_saxon_version :serializer, '>= 9.9'
+
       # @return [net.sf.saxon.s9api.XsltExecutable] the underlying Saxon
-      #   <tt>XsltExecutable</tt>
+      #   +XsltExecutable+
       def to_java
         @s9_xslt_executable
       end
@@ -202,6 +214,7 @@ module Saxon
     # Represents a loaded XSLT transformation ready to be applied against a
     # context node.
     class Transformation
+      # A list of valid option names for the transform
       VALID_OPTS = [:raw, :mode, :global_context_item, :global_parameters, :initial_template_parameters, :initial_template_tunnel_parameters]
 
       attr_reader :s9_transformer, :opts
@@ -213,6 +226,7 @@ module Saxon
         @default_initial_template ||= Saxon::QName.clark('{http://www.w3.org/1999/XSL/Transform}initial-template')
       end
 
+      # @api private
       def initialize(args)
         @s9_transformer = args.fetch(:s9_transformer)
         @destination = args.fetch(:destination, nil)
@@ -225,57 +239,48 @@ module Saxon
       # Apply templates to Source, using all the context set up when we were
       # created.
       def apply_templates(source)
-        transformation_result(:applyTemplates, source)
+        transformation_invocation(:applyTemplates, source.to_java)
       end
 
       # Call the named template, using all the context set up when we were
       # created.
       def call_template(template_name)
-        transformation_result(:callTemplate, resolve_template_name(template_name))
+        transformation_invocation(:callTemplate, resolve_template_name(template_name))
       end
 
       # Call the named function, using all the context set up when we were
       # created.
       def call_function(function_name, args)
         function_name = Saxon::QName.resolve(function_name).to_java
-        args = function_args(args)
-        call_function_result(function_name, args)
+        transformation_invocation(:callFunction, function_name, function_args(args))
       end
 
       private
 
-      def transformation_result(invocation_method, invocation_arg)
+      def transformation_invocation(invocation_method, *invocation_args)
         set_opts!
-        transformer_args = [invocation_method, invocation_arg.to_java, destination].compact
-        Result.new(result_xdm_value(s9_transformer.send(*transformer_args)), s9_transformer)
+        XSLT::Invocation.new(s9_transformer, invocation_lambda(invocation_method, invocation_args), raw?)
       end
 
-      def call_function_result(name, args)
-        set_opts!
-        Result.new(result_xdm_value(s9_transformer.callFunction(*[name, args, destination].compact)), s9_transformer)
-      end
-
-      def result_xdm_value(transformer_return_value)
-        XDM.Value(
-          transformer_return_value.nil? ? destination.getXdmNode : transformer_return_value
-        )
+      def invocation_lambda(invocation_method, invocation_args)
+        ->(destination) {
+          if destination.nil?
+            s9_transformer.send(invocation_method, *invocation_args)
+          else
+            s9_transformer.send(invocation_method, *invocation_args, destination.to_java)
+          end
+        }
       end
 
       def resolve_template_name(template_name)
-        return self.class.default_initial_template if template_name.nil?
-        Saxon::QName.resolve(template_name)
+        return self.class.default_initial_template.to_java if template_name.nil?
+        Saxon::QName.resolve(template_name).to_java
       end
 
       def function_args(args = [])
         args.map { |val| Saxon::XDM.Value(val).to_java }.to_java(S9API::XdmValue)
       end
 
-      def destination
-        @destination ||= begin
-          Saxon::S9API::XdmDestination.new unless raw?
-        end
-      end
-
       def set_opts!
         opts.each do |opt, value|
           raise BadOptionError, opt unless VALID_OPTS.include?(opt)
@@ -304,29 +309,11 @@ module Saxon
       end
 
       def initial_template_parameters(parameters)
-        s9_transformer.setInitialTemplateParameters(XSLT::ParameterHelper.to_java(parameters) , false)
+        s9_transformer.setInitialTemplateParameters(XSLT::ParameterHelper.to_java(parameters), false)
       end
 
       def initial_template_tunnel_parameters(parameters)
-        s9_transformer.setInitialTemplateParameters(XSLT::ParameterHelper.to_java(parameters) , true)
-      end
-    end
-
-    # Represents the result of a transformation, providing a simple default
-    # serializer as well
-    class Result
-      attr_reader :xdm_value
-
-      # @api private
-      def initialize(xdm_value, s9_transformer)
-        @xdm_value, @s9_transformer = xdm_value, s9_transformer
-      end
-
-      # Serialize the result to a string using the options specified in
-      # +<xsl:output/>+ in the XSLT
-      def to_s
-        serializer = Serializer.new(@s9_transformer.newSerializer)
-        serializer.serialize(xdm_value.to_java)
+        s9_transformer.setInitialTemplateParameters(XSLT::ParameterHelper.to_java(parameters), true)
       end
     end