saxon-rb 0.4.0-java → 0.7.2-java

data/lib/saxon/xslt/evaluation_context.rb

@@ -3,6 +3,7 @@ require_relative '../qname'
 
 module Saxon
   module XSLT
+    # @api private
     # Represents the evaluation context for an XSLT compiler, and stylesheets
     # compiled using one. {EvaluationContext}s are immutable.
     class EvaluationContext
@@ -47,11 +48,12 @@ module Saxon
         end
       end
 
+      # @api public
       # Provides the hooks for constructing a {EvaluationContext} with a DSL.
-      # @api private
       class DSL
         include Common
 
+        # @api private
         # Create an instance based on the args hash, and execute the passed in Proc/lambda against it using <tt>#instance_exec</tt> and return a
         # new {EvaluationContext} with the results
         # @param block [Proc] a Proc/lambda (or <tt>to_proc</tt>'d containing DSL calls
@@ -130,6 +132,7 @@ module Saxon
 
       include Common
 
+      # @api private
       # Executes the Proc/lambda passed in with a new instance of
       # {EvaluationContext} as <tt>self</tt>, allowing the DSL methods to be
       # called in a DSL-ish way
@@ -140,23 +143,46 @@ 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}.
+      #
+      # When passed {nil}, simply return the EvaluationContext unaltered.
       def define(block)
         block.nil? ? self : DSL.define(block, args_hash)
       end
     end
 
+    # Error raised when a global and static parameter of the same name are
+    # declared
     class GlobalAndStaticParameterClashError < StandardError
     end
 
+    # parameter shorthand name/value-to-full QName/XDM::Value helper module
     module ParameterHelper
+      # process shorthand parameter hash into fully-qualified QName / Value hash
+      # @param parameters [Hash<String, Saxon::QName => Object>]
+      # @return [Hash<Saxon::QName => Saxon::XDM::Value>]
+      # @see Saxon::QName.resolve() for more about the QName resolution process
+      # @see Saxon::XDM.Value() for more about the conversion of Object into XDM Values
       def self.process_parameters(parameters)
-        Hash[parameters.map { |qname, value|
+        parameters.map { |qname, value|
           [Saxon::QName.resolve(qname), Saxon::XDM.Value(value)]
-        }]
+        }.to_h
       end
 
+      # generate Java Map from fully qualified parameter hash
       def self.to_java(parameters)
         Hash[parameters.map { |k,v| [k.to_java, v.to_java] }].to_java
       end

data/lib/saxon/xslt/executable.rb

@@ -1,14 +1,60 @@
 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
     # Represents a compiled XSLT stylesheet ready to be executed
+    #
+    # Once you have a compiled stylesheet, then it can be executed against a
+    # source document in a variety of ways.
+    #
+    # First, you can use the traditional *apply templates* ,method, which was
+    # the only way in XSLT 1.
+    #
+    #     input = Saxon::Source.create('input.xml')
+    #     result = xslt.apply_templates(input)
+    #
+    # Next, you can call a specific named template (new in XSLT 2).
+    #
+    #     result = xslt.call_template('template-name')
+    #
+    # Note that there's no input document here. If your XSLT needs a global
+    # context item set when you invoke it via a named template, then you can do
+    # that, too:
+    #
+    #     input = processor.XML('input.xml')
+    #     result = xslt.call_template('template-name', {
+    #       global_context_item: input
+    #     })
+    #
+    # Global and initial template parameters can be set at compiler creation
+    # time, compile time, or execution time.
+    #
+    # Initial template parameters relate to parameters passed to the *first*
+    # template run (either the first template matched when called with
+    # {Executable#apply_templates}, or the named template called with
+    # {Executable#call_template}).
+    #
+    # <b>Initial template parameters</b> are essentially implied +<xsl:with-parameter
+    # tunnel="no">+ elements. <b>Initial template tunnel parameters</b> are implied
+    # +<xsl:with-parameter tunnel="yes">+ elements.
+    #
+    #     xslt.apply_templates(input, {
+    #       global_parameters: {'param' => 'global value'},
+    #       initial_template_parameters: {'param' => 'other value'},
+    #       initial_template_tunnel_parameters: {'param' => 'tunnel value'}
+    #     })
+    #
+    # Remember that if you need to use a parameter name which uses a namespace
+    # 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
@@ -24,16 +70,111 @@ module Saxon
 
       def_delegators :evaluation_context, :global_parameters, :initial_template_parameters, :initial_template_tunnel_parameters
 
+      # Run the XSLT by applying templates against the provided {Saxon::Source}
+      # or {Saxon::XDM::Node}.
+      #
+      # @note Any {QName}s supplied as strings MUST be resolvable as a QName
+      # without extra information, so they must be prefix-less (so, 'name', and
+      # never 'ns:name')
+      #
+      # @param source [Saxon::Source, Saxon::XDM::Node] the Source or Node that
+      #   will be used as the global context item
+      # @param opts [Hash] a hash of options for invoking the transformation
+      # @option opts [Boolean] :raw (false) Whether the transformation should be
+      #   executed 'raw', because it is expected to return a simple XDM Value
+      #   (like a number, or plain text) and not an XML document.
+      # @option opts [String, Saxon::QName] :mode The initial mode to use when
+      #   processing starts.
+      # @option opts [Hash<String, Saxon::QName => Object>] :global_parameters
+      #   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.
+      # @option opts [Hash<String, Saxon::QName => Object>]
+      #   :initial_template_parameters Additional parameters 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.
+      # @option opts [Hash<String, Saxon::QName => Object>]
+      #   :initial_template_tunnel_parameters Additional tunnelling parameters
+      #   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::Invocation] the transformation result
       def apply_templates(source, opts = {})
         transformation(opts).apply_templates(source)
       end
 
-      def call_template(template_name, opts = {})
+      # Run the XSLT by calling the named template.
+      #
+      # @note Any {QName}s supplied as Strings (e.g. for the template name)
+      # MUST be resolvable as a QName without extra information, so they must be
+      # prefix-less (so, 'name', and never 'ns:name')
+      #
+      # @param template_name [String, Saxon::QName, nil] the name of the
+      #   template to be invoked. Passing +nil+ will invoke the default named
+      #   template (+xsl:default-template+)
+      # @param opts [Hash] a hash of options for invoking the transformation
+      # @option opts [Boolean] :raw (false) Whether the transformation should be
+      #   executed 'raw', because it is expected to return a simple XDM Value
+      #   (like a number, or plain text) and not an XML document.
+      # @option opts [String, Saxon::QName] :mode The name of the initial mode
+      #   to use when processing starts.
+      # @option opts [Hash<String, Saxon::QName => Object>] :global_parameters
+      #   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.
+      # @option opts [Hash<String, Saxon::QName => Object>]
+      #   :initial_template_parameters Additional parameters 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.
+      # @option opts [Hash<String, Saxon::QName => Object>]
+      #   :initial_template_tunnel_parameters Additional tunnelling parameters
+      #   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::Invocation] the transformation result
+      def call_template(template_name = nil, opts = {})
         transformation(opts).call_template(template_name)
       end
 
+      # Invoke a named function in the XSLT.
+      #
+      # @note Function name {QName}s have to have prefixes, so they can't be
+      #   supplied as {::String}s. Any other {QName}s supplied as {::String}s (e.g.
+      #   for the template name) MUST be resolvable as a QName without extra
+      #   information, so they must be prefix-less (so, 'name', and never
+      #   'ns:name')
+      # @note the function you're calling needs to be have been defined with
+      #   +visibility="public"+ or +visibility="final"+
+      #
+      # @param function_name [Saxon::QName] the name of the function to be
+      #   invoked.
+      # @param opts [Hash] a hash of options for invoking the transformation
+      # @option opts [Boolean] :raw (false) Whether the transformation should be
+      #   executed 'raw', because it is expected to return a simple XDM Value
+      #   (like a number, or plain text) and not an XML document.
+      # @option opts [Hash<String, Saxon::QName => Object>] :global_parameters
+      #   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::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
@@ -69,22 +210,23 @@ module Saxon
       end
     end
 
-    class Result
-      attr_reader :xdm_value
+    # @api private
+    # 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]
 
-      def initialize(xdm_value, s9_transformer)
-        @xdm_value, @s9_transformer = xdm_value, s9_transformer
-      end
+      attr_reader :s9_transformer, :opts
+      private :s9_transformer, :opts
 
-      def to_s
-        serializer = Serializer.new(@s9_transformer.newSerializer)
-        serializer.serialize(xdm_value.to_java)
+      # Return the default initial template namne for XSLT 3 named-template invocation
+      # @return [Saxon::QName] the default initial template QName
+      def self.default_initial_template
+        @default_initial_template ||= Saxon::QName.clark('{http://www.w3.org/1999/XSL/Transform}initial-template')
       end
-    end
-
-    class Transformation
-      attr_reader :s9_transformer, :opts
 
+      # @api private
       def initialize(args)
         @s9_transformer = args.fetch(:s9_transformer)
         @destination = args.fetch(:destination, nil)
@@ -94,36 +236,54 @@ module Saxon
         @raw = false
       end
 
+      # 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, Saxon::QName.resolve(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
+        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 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 destination
-        @destination ||= begin
-          Saxon::S9API::XdmDestination.new unless raw?
-        end
+      def resolve_template_name(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 set_opts!
         opts.each do |opt, value|
+          raise BadOptionError, opt unless VALID_OPTS.include?(opt)
           send(opt, value)
         end
       end
@@ -140,16 +300,33 @@ module Saxon
         s9_transformer.setInitialMode(Saxon::QName.resolve(mode_name).to_java)
       end
 
+      def global_context_item(xdm_item)
+        s9_transformer.setGlobalContextItem(xdm_item.to_java)
+      end
+
       def global_parameters(parameters)
         s9_transformer.setStylesheetParameters(XSLT::ParameterHelper.to_java(parameters))
       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)
+        s9_transformer.setInitialTemplateParameters(XSLT::ParameterHelper.to_java(parameters), true)
+      end
+    end
+
+    # Raised if a bad option name is passed in the options hash to
+    # Executable#apply_templates et al
+    class BadOptionError < StandardError
+      def initialize(option_name)
+        @option_name = option_name
+      end
+
+      # return error message including the option name
+      def to_s
+        "Option :#{@option_name} is not a recognised option."
       end
     end
   end

data/lib/saxon/xslt/invocation.rb

@@ -0,0 +1,97 @@
+require_relative '../serializer'
+require_relative '../xdm/value'
+
+
+module Saxon
+  module XSLT
+    # Represents the invocation of a compiled and loaded transformation,
+    # providing an idiomatic way to send the result a transformation to a
+    # particular Destination, or to serialize it directly to a file, string, or
+    # IO.
+    class Invocation
+      attr_reader :s9_transformer, :invocation_lambda
+      private :s9_transformer, :invocation_lambda
+
+      # @api private
+      def initialize(s9_transformer, invocation_lambda, raw)
+        @s9_transformer, @invocation_lambda, @raw = s9_transformer, invocation_lambda, raw
+      end
+
+      # Serialize the result to a string using the options specified in
+      # +<xsl:output/>+ in the XSLT
+      #
+      # @return [String] the serialized result of the transformation
+      def to_s
+        serializer_destination.serialize
+      end
+
+      # Serialize the result of the transformation. When called with a
+      # block, the block will be executed via instance-exec so that output
+      # properties can be set, e.g.
+      #
+      #     result.serialize {
+      #       output_property[:indent] = 'yes'
+      #     }
+      #
+      # @overload serialize(io)
+      #   Serialize the transformation to an IO
+      #   @param [File, IO] io The IO to serialize to
+      #   @return [nil]
+      #   @yield the passed block bound via instance-exec to the new serializer
+      # @overload serialize(path)
+      #   Serialize the transformation to file <tt>path</tt>
+      #   @param [String, Pathname] path The path of the file to serialize to
+      #   @return [nil]
+      #   @yield the passed block bound via instance-exec to the new serializer
+      # @overload serialize
+      #   Serialize the transformation to a String
+      #   @return [String] The serialized XdmValue
+      def serialize(path_or_io = nil, &block)
+        serializer_destination(&block).serialize(path_or_io)
+      end
+
+      # Return the result of the transformation as an XDM Value, either as it is
+      # returned (if the XSLT::Executable was created with :raw => true), or
+      # wrapped in a Document node and sequence normalized.
+      #
+      # @return [Saxon::XDM::Value] the XDM value returned by the transformation
+      def xdm_value
+        if raw?
+          XDM.Value(invocation_lambda.call(nil))
+        else
+          invocation_lambda.call(s9_xdm_destination)
+          XDM.Value(s9_xdm_destination.getXdmNode)
+        end
+      end
+
+      # Send the result of the transformation to the supplied Destination
+      #
+      # @param s9_destination [net.sf.saxon.s9api.Destination] the Saxon
+      #   destination to use
+      # @return [nil]
+      def to_destination(s9_destination)
+        invocation_lambda.call(s9_destination)
+        nil
+      end
+
+      # Whether the transformation was invoked as a 'raw' transformation, where
+      # an XDM Value result will be returned without being wrapped in a Document
+      # node, and without sequence normalization.
+      #
+      # @return [Boolean] whether the transformation was invoked 'raw' or not
+      def raw?
+        @raw
+      end
+
+      private
+
+      def serializer_destination(&block)
+        Saxon::Serializer::Destination.new(s9_transformer.newSerializer, invocation_lambda, &block)
+      end
+
+      def s9_xdm_destination
+        @s9_xdm_destination ||= Saxon::S9API::XdmDestination.new
+      end
+    end
+  end
+end