saxon-rb 0.4.0-java

data/lib/saxon/xpath/variable_declaration.rb

@@ -0,0 +1,68 @@
+require_relative '../item_type'
+require_relative '../occurrence_indicator'
+
+module Saxon
+  module XPath
+    # Represents an XPath variable declaration in the static context of a compiled XPath, providing an idiomatic Ruby way to deal with these.
+    class VariableDeclaration
+      # @return [Saxon::QName]
+      attr_reader :qname
+      # @return [Saxon::ItemType]
+      attr_reader :item_type
+      # @return [net.sf.saxon.s9api.OccurrenceIndicator]
+      attr_reader :occurrences
+
+      # @param opts [Hash]
+      # @option opts [Saxon::QName] :qname The name of the variable as a {Saxon::QName}
+      def initialize(opts = {})
+        raise VariableDeclarationError, opts.keys if opts.keys.length > 2
+        @qname = opts.fetch(:qname)
+        @item_type, @occurrences = extract_type_decl(opts.reject { |k, v| k == :qname })
+      end
+
+      # VariableDeclarations compare equal if their qname, item_type, and occurrences are equal
+      # @param other [Saxon::VariableDeclaration]
+      # @return [Boolean]
+      def ==(other)
+        VariableDeclaration === other && qname == other.qname && item_type == other.item_type && occurrences == other.occurrences
+      end
+
+      # @api private
+      def compiler_args
+        [qname.to_java, item_type.to_java, occurrences]
+      end
+
+      private
+
+      def self.valid_opt_keys
+        @valid_opt_keys ||= [:qname] + Saxon::OccurrenceIndicator.indicator_names
+      end
+
+      def extract_type_decl(type_decl)
+        raise VariableDeclarationError, type_decl.keys if type_decl.length > 1
+        unless (type_decl.keys - Saxon::OccurrenceIndicator.indicator_names).empty?
+          raise VariableDeclarationError, type_decl.keys
+        end
+
+        return [Saxon::ItemType.get_type('item()'), Saxon::OccurrenceIndicator.zero_or_more] if type_decl.empty?
+        occurrence, type = type_decl.first
+        [Saxon::ItemType.get_type(type), Saxon::OccurrenceIndicator.send(occurrence)]
+      end
+    end
+
+    # Raised when an attempt to declare a variable is made using an occurrence
+    # indicator that does not exist
+    class VariableDeclarationError < StandardError
+      attr_reader :keys
+
+      def initialize(keys)
+        @keys = keys
+      end
+
+      # reports allowable occurrence indicator keys and what was actually passed in
+      def to_s
+        "requires :qname, and optionally one of #{Saxon::OccurrenceIndicator.indicator_names}, was passed #{keys.join(', ')}"
+      end
+    end
+  end
+end

data/lib/saxon/xslt.rb

@@ -0,0 +1,8 @@
+require_relative './xslt/compiler'
+
+module Saxon
+  # Classes for compiling, configuring, and executing XSLT transformations
+  # against XDM nodes or documents
+  module XSLT
+  end
+end

data/lib/saxon/xslt/compiler.rb

@@ -0,0 +1,70 @@
+require 'forwardable'
+require_relative './evaluation_context'
+require_relative './executable'
+
+module Saxon
+  module XSLT
+    # Compiles XSLT stylesheets so they can be executed
+    class Compiler
+      # Create a new <tt>XSLT::Compiler</tt> using the supplied Processor.
+      # Passing a block gives access to a DSL for setting up the compiler's
+      # static context.
+      #
+      # @param processor [Saxon::Processor] the {Saxon::Processor} to use
+      # @yield An XSLT compiler DSL block
+      # @return [Saxon::XSLT::Compiler] the new compiler instance
+      def self.create(processor, &block)
+        evaluation_context = XSLT::EvaluationContext.define(block)
+        new(processor.to_java, evaluation_context)
+      end
+
+      extend Forwardable
+
+      attr_reader :evaluation_context
+      private :evaluation_context
+
+      # @api private
+      # @param s9_processor [net.sf.saxon.s9api.Processor] the Saxon
+      #   <tt>Processor</tt> to wrap
+      # @param evaluation_context [Saxon::XSLT::EvaluationContext] the static context
+      #   XPaths compiled using this compiler will have
+      def initialize(s9_processor, evaluation_context)
+        @s9_processor, @evaluation_context = s9_processor, evaluation_context
+      end
+
+      def_delegators :evaluation_context, :default_collation, :static_parameters, :global_parameters, :initial_template_parameters, :initial_template_tunnel_parameters
+      # @!attribute [r] declared_collations
+      #   @return [Hash<String => java.text.Collator>] declared collations as URI => Collator hash
+      # @!attribute [r] default_collation
+      #   @return [String] the URI of the default declared collation
+      # @!attribute [r] static_parameters
+      #   @return [Hash<Saxon::QName => Saxon::XDM::Value, Saxon::XDM::Node,
+      #   Saxon::XDM::AtomicValue>] parameters required at compile time as QName => value hash
+
+      # @param source [Saxon::Source] the Source to compile
+      # @return [Saxon::XSLT::Executable] the executable stylesheet
+      def compile(source, &block)
+        Saxon::XSLT::Executable.new(
+          new_compiler.compile(source.to_java),
+          evaluation_context.define(block)
+        )
+      end
+
+      def create(&block)
+        new_evaluation_context = evaluation_context.define(block)
+        self.class.new(@s9_processor, new_evaluation_context)
+      end
+
+      private
+
+      def new_compiler
+        compiler = @s9_processor.newXsltCompiler
+        compiler.declareDefaultCollation(default_collation) unless default_collation.nil?
+        static_parameters.each do |qname, value|
+          compiler.setParameter(qname.to_java, value.to_java)
+        end
+        compiler
+      end
+    end
+  end
+end

data/lib/saxon/xslt/evaluation_context.rb

@@ -0,0 +1,165 @@
+require 'set'
+require_relative '../qname'
+
+module Saxon
+  module XSLT
+    # Represents the evaluation context for an XSLT compiler, and stylesheets
+    # compiled using one. {EvaluationContext}s are immutable.
+    class EvaluationContext
+      # methods used by both {EvaluationContext} and {EvaluationContext::DSL}
+      module Common
+        # @param args [Hash]
+        # @option args [String] default_collation URI of the default collation
+        # @option args [Hash<String,Symbol,Saxon::QName =>
+        #   Object,Saxon::XDM::Value] static_parameters Hash of QName => value
+        #   bindings for static (compile-time) parameters for this compiler
+        def initialize(args = {})
+          @default_collation = args.fetch(:default_collation, nil).freeze
+          @static_parameters = args.fetch(:static_parameters, {}).freeze
+          @global_parameters = args.fetch(:global_parameters, {}).freeze
+          @initial_template_parameters = args.fetch(:initial_template_parameters, {}).freeze
+          @initial_template_tunnel_parameters = args.fetch(:initial_template_tunnel_parameters, {}).freeze
+        end
+
+        # returns the context details in a hash suitable for initializing a new one
+        # @return [Hash<Symbol => Hash,null>] the args hash
+        def args_hash
+          check_for_clashing_parameters!
+          {
+            default_collation: @default_collation,
+            static_parameters: @static_parameters,
+            global_parameters: @global_parameters,
+            initial_template_parameters: @initial_template_parameters,
+            initial_template_tunnel_parameters: @initial_template_tunnel_parameters
+          }
+        end
+
+        private
+
+        def check_for_clashing_parameters!
+          @checked ||= begin
+            if Set.new(@static_parameters.keys).intersect?(Set.new(@global_parameters.keys))
+              raise GlobalAndStaticParameterClashError
+            else
+              true
+            end
+          end
+        end
+      end
+
+      # Provides the hooks for constructing a {EvaluationContext} with a DSL.
+      # @api private
+      class DSL
+        include Common
+
+        # 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
+        # @return [Saxon::XSLT::EvaluationContext]
+        def self.define(block, args = {})
+          dsl = new(args)
+          dsl.instance_exec(&block) unless block.nil?
+          EvaluationContext.new(dsl.args_hash)
+        end
+
+        # Set the default Collation to use. This should be one of the special
+        # collation URIs Saxon recognises, or one that has been registered
+        # using Saxon::Processor#declare_collations on the Processor that
+        # created the {XSLT::Compiler} this context is for.
+        #
+        # @param collation_uri [String] The URI of the Collation to set as the default
+        def default_collation(collation_uri)
+          @default_collation = collation_uri
+        end
+
+        # Set the value for static parameters (those that must be known at
+        # compile-time to avoid an error), as a hash of QName => Value pairs.
+        # Parameter QNames can be declared as Strings or Symbols if they are
+        # not in any namespace, otherwise an explicit {Saxon::QName} must be
+        # used. Values can be provided as explicit XDM::Values:
+        # {Saxon::XDM::Value}, {Saxon::XDM::Node}, and {Saxon::XDM::AtomicValue}, or
+        # as Ruby objects which will be converted to {Saxon::XDM::AtomicValue}s
+        # in the usual way.
+        #
+        # @param parameters [Hash<String,Symbol,Saxon::QName =>
+        #   Object,Saxon::XDM::Value>] Hash of QName => value
+        def static_parameters(parameters = {})
+          @static_parameters = @static_parameters.merge(process_parameters(parameters)).freeze
+        end
+
+        # Set the values for global parameters (those that are available to all templates and functions).
+        #
+        # @see EvaluationContext#static_parameters for details of the argument format
+        #
+        # @param parameters [Hash<String,Symbol,Saxon::QName =>
+        #   Object,Saxon::XDM::Value>] Hash of QName => value
+        def global_parameters(parameters = {})
+          @global_parameters = @global_parameters.merge(process_parameters(parameters)).freeze
+        end
+
+        # Set the values for parameters made available only to the initial
+        # template invoked (either via apply_templates or call_template),
+        # effectively as if <tt><xsl:with-param tunnel="no"></tt> was being used.
+        #
+        # @see EvaluationContext#static_parameters for details of the argument format
+        #
+        # @param parameters [Hash<String,Symbol,Saxon::QName =>
+        #   Object,Saxon::XDM::Value>] Hash of QName => value
+        def initial_template_parameters(parameters = {})
+          @initial_template_parameters = @initial_template_parameters.merge(process_parameters(parameters))
+        end
+
+        # Set the values for tunneling parameters made available only to the initial
+        # template invoked (either via apply_templates or call_template),
+        # effectively as if <tt><xsl:with-param tunnel="yes"></tt> was being used.
+        #
+        # @see EvaluationContext#static_parameters for details of the argument format
+        #
+        # @param parameters [Hash<String,Symbol,Saxon::QName =>
+        #   Object,Saxon::XDM::Value>] Hash of QName => value
+        def initial_template_tunnel_parameters(parameters = {})
+          @initial_template_tunnel_parameters = @initial_template_tunnel_parameters.merge(process_parameters(parameters))
+        end
+
+        private
+
+        def process_parameters(parameters)
+          XSLT::ParameterHelper.process_parameters(parameters)
+        end
+      end
+
+      include Common
+
+      # 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
+      #
+      # @param block [Proc] the block of DSL calls to be executed
+      # @return [Saxon::XSLT::EvaluationContext] the static context created by the block
+      def self.define(block)
+        DSL.define(block)
+      end
+
+      attr_reader :default_collation, :static_parameters, :global_parameters, :initial_template_parameters, :initial_template_tunnel_parameters
+
+      def define(block)
+        block.nil? ? self : DSL.define(block, args_hash)
+      end
+    end
+
+    class GlobalAndStaticParameterClashError < StandardError
+    end
+
+    module ParameterHelper
+      def self.process_parameters(parameters)
+        Hash[parameters.map { |qname, value|
+          [Saxon::QName.resolve(qname), Saxon::XDM.Value(value)]
+        }]
+      end
+
+      def self.to_java(parameters)
+        Hash[parameters.map { |k,v| [k.to_java, v.to_java] }].to_java
+      end
+    end
+  end
+end

data/lib/saxon/xslt/executable.rb

@@ -0,0 +1,156 @@
+require 'forwardable'
+require_relative 'evaluation_context'
+require_relative '../serializer'
+require_relative '../xdm'
+require_relative '../qname'
+
+module Saxon
+  module XSLT
+    # Represents a compiled XSLT stylesheet ready to be executed
+    class Executable
+      extend Forwardable
+
+      attr_reader :evaluation_context
+      private :evaluation_context
+
+      # @api private
+      # @param s9_xslt_executable [net.sf.saxon.s9api.XsltExecutable] the
+      #   Saxon compiled XSLT object
+      # @param evaluation_context [XSLT::EvaluationContext] the XSLT's evaluation
+      #   context
+      def initialize(s9_xslt_executable, evaluation_context)
+        @s9_xslt_executable, @evaluation_context = s9_xslt_executable, evaluation_context
+      end
+
+      def_delegators :evaluation_context, :global_parameters, :initial_template_parameters, :initial_template_tunnel_parameters
+
+      def apply_templates(source, opts = {})
+        transformation(opts).apply_templates(source)
+      end
+
+      def call_template(template_name, opts = {})
+        transformation(opts).call_template(template_name)
+      end
+
+      # @return [net.sf.saxon.s9api.XsltExecutable] the underlying Saxon
+      #   <tt>XsltExecutable</tt>
+      def to_java
+        @s9_xslt_executable
+      end
+
+      private
+
+      def transformation(opts)
+        Transformation.new(params_merged_opts(opts).merge({
+          s9_transformer: @s9_xslt_executable.load30,
+        }))
+      end
+
+      def params_merged_opts(opts)
+        merged_opts = params_hash.dup
+        opts.each do |key, value|
+          if [:global_parameters, :initial_template_parameters, :initial_template_tunnel_parameters].include?(key)
+            merged_opts[key] = merged_opts.fetch(key, {}).merge(XSLT::ParameterHelper.process_parameters(value))
+          else
+            merged_opts[key] = value
+          end
+        end
+        merged_opts
+      end
+
+      def params_hash
+        @params_hash ||= begin
+          params_hash = {}
+          params_hash[:global_parameters] = global_parameters unless global_parameters.empty?
+          params_hash[:initial_template_parameters] = initial_template_parameters unless initial_template_parameters.empty?
+          params_hash[:initial_template_tunnel_parameters] = initial_template_tunnel_parameters unless initial_template_tunnel_parameters.empty?
+          params_hash
+        end.freeze
+      end
+    end
+
+    class Result
+      attr_reader :xdm_value
+
+      def initialize(xdm_value, s9_transformer)
+        @xdm_value, @s9_transformer = xdm_value, s9_transformer
+      end
+
+      def to_s
+        serializer = Serializer.new(@s9_transformer.newSerializer)
+        serializer.serialize(xdm_value.to_java)
+      end
+    end
+
+    class Transformation
+      attr_reader :s9_transformer, :opts
+
+      def initialize(args)
+        @s9_transformer = args.fetch(:s9_transformer)
+        @destination = args.fetch(:destination, nil)
+        @opts = args.reject { |opt, _|
+          [:s9_transformer, :destination].include?(opt)
+        }
+        @raw = false
+      end
+
+      def apply_templates(source)
+        transformation_result(:applyTemplates, source)
+      end
+
+      def call_template(template_name)
+        transformation_result(:callTemplate, Saxon::QName.resolve(template_name))
+      end
+
+      private
+
+      def transformation_result(invocation_method, invocation_arg)
+        set_opts!
+        transformer_args = [invocation_method, invocation_arg.to_java, destination].compact
+        Result.new(result_xdm_value(s9_transformer.send(*transformer_args)), s9_transformer)
+      end
+
+      def result_xdm_value(transformer_return_value)
+        XDM.Value(
+          transformer_return_value.nil? ? destination.getXdmNode : transformer_return_value
+        )
+      end
+
+      def destination
+        @destination ||= begin
+          Saxon::S9API::XdmDestination.new unless raw?
+        end
+      end
+
+      def set_opts!
+        opts.each do |opt, value|
+          send(opt, value)
+        end
+      end
+
+      def raw(value)
+        @raw = value
+      end
+
+      def raw?
+        @raw
+      end
+
+      def mode(mode_name)
+        s9_transformer.setInitialMode(Saxon::QName.resolve(mode_name).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)
+      end
+
+      def initial_template_tunnel_parameters(parameters)
+        s9_transformer.setInitialTemplateParameters(XSLT::ParameterHelper.to_java(parameters) , true)
+      end
+    end
+  end
+end