saxon 0.1.0-java

data/lib/saxon/xdm_value.rb

@@ -0,0 +1,129 @@
+require_relative 'xdm_node'
+require_relative 'xdm_atomic_value'
+
+module Saxon
+  # An XPath Data Model Value object, representing a Sequence.
+  class XdmValue
+    include Enumerable
+
+    def self.wrap_s9_xdm_value(s9_xdm_value)
+      return new(s9_xdm_value) if s9_xdm_value.instance_of?(Saxon::S9API::XdmValue)
+      case s9_xdm_value
+      when Saxon::S9API::XdmEmptySequence
+        new([])
+      else
+        wrap_s9_xdm_item(s9_xdm_value)
+      end
+    end
+
+    def self.wrap_s9_xdm_item(s9_xdm_item)
+      if s9_xdm_item.isAtomicValue
+        XdmAtomicValue.new(s9_xdm_item)
+      else
+        case s9_xdm_item
+        when Saxon::S9API::XdmNode
+          XdmNode.new(s9_xdm_item)
+        else
+          XdmUnhandledItem.new(s9_xdm_item)
+        end
+      end
+    end
+
+    # Create a new XdmValue sequence containing the items passed in as a Ruby enumerable.
+    #
+    # @param items [Enumerable] A list of XDM Item members
+    # @return [Saxon::XdmValue] The XDM value
+    def self.create(items)
+      new(Saxon::S9API::XdmValue.makeSequence(items.map(&:to_java)))
+    end
+
+    attr_reader :s9_xdm_value
+    private :s9_xdm_value
+
+    # @api private
+    def initialize(s9_xdm_value)
+      @s9_xdm_value = s9_xdm_value
+    end
+
+    # @return [Fixnum] The size of the sequence
+    def size
+      s9_xdm_value.size
+    end
+
+    # Calls the given block once for each Item in the sequence, passing that
+    # item as a parameter. Returns the value itself.
+    #
+    # If no block is given, an Enumerator is returned.
+    #
+    # @overload
+    #   @yield [item] The current XDM Item
+    #   @yieldparam item [Saxon::XdmAtomicValue, Saxon::XdmNode] the item.
+    def each(&block)
+      to_enum.each(&block)
+    end
+
+    # @return [Saxon::S9API::XdmValue] The underlying Saxon Java XDM valuee object.
+    def to_java
+      @s9_xdm_value
+    end
+
+    # Compare this XdmValue with another. Currently this requires iterating
+    # across the sequence, and the other sequence and comparing each member
+    # with the corresponding member in the other sequence.
+    #
+    # @param other [Saxon::XdmValue] The XdmValue to be compare against
+    # @return [Boolean] whether the two XdmValues are equal
+    def ==(other)
+      return false unless other.is_a?(XdmValue)
+      return false unless other.size == size
+      not_okay = to_enum.zip(other.to_enum).find { |mine, theirs|
+        mine != theirs
+      }
+      not_okay.nil? || !not_okay
+    end
+
+    alias_method :eql?, :==
+
+    # The hash code for the XdmValue
+    # @return [Fixnum] The hash code
+    def hash
+      @hash ||= to_a.hash
+    end
+
+    # Returns a lazy Enumerator over the sequence
+    # @return [Enumerator::Lazy] the enumerator
+    def to_enum
+      s9_xdm_value.each.lazy.map { |s9_xdm_item|
+        wrap_s9_xdm_item(s9_xdm_item)
+      }.each
+    end
+
+    alias_method :enum_for, :to_enum
+
+    private
+
+    def wrap_s9_xdm_item(s9_xdm_item)
+      if s9_xdm_item.isAtomicValue
+        XdmAtomicValue.new(s9_xdm_item)
+      else
+        case s9_xdm_item
+        when Saxon::S9API::XdmNode
+          XdmNode.new(s9_xdm_item)
+        else
+          XdmUnhandledItem.new(s9_xdm_item)
+        end
+      end
+    end
+  end
+
+  # Placeholder class for Saxon Items that we haven't gotten to yet
+  class XdmUnhandledItem
+    def initialize(s9_xdm_item)
+      @s9_xdm_item = s9_xdm_item
+    end
+
+    def to_java
+      @s9_xdm_item
+    end
+  end
+end

data/lib/saxon/xpath.rb

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

data/lib/saxon/xpath/compiler.rb

@@ -0,0 +1,69 @@
+require 'forwardable'
+require_relative './static_context'
+require_relative './executable'
+
+module Saxon
+  module XPath
+    # Compiles XPath expressions so they can be executed
+    class Compiler
+      # Create a new <tt>XPath::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 XPath compiler DSL block
+      # @return [Saxon::XPath::Compiler] the new compiler instance
+      def self.create(processor, &block)
+        static_context = XPath::StaticContext.define(block)
+        new(processor.to_java, static_context)
+      end
+
+      extend Forwardable
+
+      attr_reader :static_context
+      private :static_context
+
+      # @api private
+      # @param s9_processor [net.sf.saxon.s9api.Processor] the Saxon
+      #   <tt>Processor</tt> to wrap
+      # @param static_context [Saxon::XPath::StaticContext] the static context
+      #   XPaths compiled using this compiler will have
+      def initialize(s9_processor, static_context)
+        @s9_processor, @static_context = s9_processor, static_context
+      end
+
+      def_delegators :static_context, :default_collation, :declared_namespaces, :declared_variables
+      # @!attribute [r] default_collation
+      #   @return [String] the URI of the default declared collation
+      # @!attribute [r] declared_namespaces
+      #   @return [Hash<String => String>] declared namespaces as prefix => URI hash
+      # @!attribute [r] declared_variables
+      #   @return [Hash<Saxon::QName => Saxon::XPath::VariableDeclaration>] declared variables as QName => Declaration hash
+
+      # @param expression [String] the XPath expression to compile
+      # @return [Saxon::XPath::Executable] the executable query
+      def compile(expression)
+        Saxon::XPath::Executable.new(new_compiler.compile(expression), static_context)
+      end
+
+      def create(&block)
+        new_static_context = static_context.define(block)
+        self.class.new(@s9_processor, new_static_context)
+      end
+
+      private
+
+      def new_compiler
+        compiler = @s9_processor.newXPathCompiler
+        declared_namespaces.each do |prefix, uri|
+          compiler.declareNamespace(prefix, uri)
+        end
+        declared_variables.each do |_, decl|
+          compiler.declareVariable(*decl.compiler_args)
+        end
+        compiler.declareDefaultCollation(default_collation) unless default_collation.nil?
+        compiler
+      end
+    end
+  end
+end

data/lib/saxon/xpath/executable.rb

@@ -0,0 +1,59 @@
+require_relative '../xdm_node'
+require_relative '../xdm_atomic_value'
+
+module Saxon
+  module XPath
+    # Represents a compiled XPath query ready to be executed
+    class Executable
+      # @return [XPath::StaticContext] the XPath's static context
+      attr_reader :static_context
+
+      # @api private
+      # @param s9_xpath_executable [net.sf.saxon.s9api.XPathExecutable] the
+      #   Saxon compiled XPath object
+      # @param static_context [XPath::StaticContext] the XPath's static
+      #   context
+      def initialize(s9_xpath_executable, static_context)
+        @s9_xpath_executable, @static_context = s9_xpath_executable, static_context
+      end
+
+      # Run the compiled query using a passed-in node as the context item.
+      # @param context_item [Saxon::XdmNode] the context item node
+      # @return [Saxon::XPath::Result] the result of the query as an
+      #   enumerable
+      def run(context_item, variables = {})
+        selector = to_java.load
+        selector.setContextItem(context_item.to_java)
+        variables.each do |qname_or_string, value|
+          selector.setVariable(static_context.resolve_variable_qname(qname_or_string).to_java, Saxon::XdmAtomicValue.create(value).to_java)
+        end
+        Result.new(selector.iterator)
+      end
+
+      # @return [net.sf.saxon.s9api.XPathExecutable] the underlying Saxon
+      #   <tt>XPathExecutable</tt>
+      def to_java
+        @s9_xpath_executable
+      end
+    end
+
+    # The result of executing an XPath query as an enumerable object
+    class Result
+      include Enumerable
+
+      # @api private
+      # @param result_iterator [java.util.Iterator] the result of calling
+      #   <tt>#iterator</tt> on a Saxon <tt>XPathSelector</tt>
+      def initialize(result_iterator)
+        @result_iterator = result_iterator
+      end
+
+      # Yields <tt>XdmNode</tt>s from the query result. If no block is passed,
+      # returns an <tt>Enumerator</tt> 
+      # @yieldparam xdm_node [Saxon::XdmNode] the name that is yielded
+      def each(&block)
+        @result_iterator.lazy.map { |s9_xdm_node| Saxon::XdmNode.new(s9_xdm_node) }.each(&block)
+      end
+    end
+  end
+end

data/lib/saxon/xpath/static_context.rb

@@ -0,0 +1,204 @@
+require_relative '../qname'
+require_relative './variable_declaration'
+module Saxon
+  module XPath
+    # Raised when an attempt to declare a variable is made using a string for
+    # the qname with a namespace prefix that has not been declared in the
+    # context yet
+    class MissingVariableNamespaceError < StandardError
+      def initialize(variable_name, prefix)
+        @variable_name, @prefix = variable_name, prefix
+      end
+
+      def to_s
+        "Namespace prefix ‘#{@prefix}’ for variable name ‘#{@variable_name}’ is not bound to a URI"
+      end
+    end
+
+    # Represents the static context for a compiled XPath. {StaticContext}s are immutable.
+    class StaticContext
+      # methods used by both {StaticContext} and {StaticContext::DSL}
+      module Common
+        # @param args [Hash]
+        # @option args [Hash<Saxon::QName => Saxon::XPath::VariableDeclaration>] :declared_variables Hash of declared variables
+        # @option args [Hash<String => String>] :declared_namespaces Hash of namespace bindings prefix => URI
+        # @option args [Hash<String => java.text.Collator>] :declared_collations Hash of URI => Collator bindings
+        # @option args [String] :default_collation URI of the default collation
+        def initialize(args = {})
+          @declared_variables = args.fetch(:declared_variables, {}).freeze
+          @declared_namespaces = args.fetch(:declared_namespaces, {}).freeze
+          @default_collation = args.fetch(:default_collation, nil).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
+          {
+            declared_namespaces: @declared_namespaces,
+            declared_variables: @declared_variables,
+            default_collation: @default_collation
+          }
+        end
+      end
+
+      # methods for resolving a QName represented as a <tt>prefix:local-name</tt> string into a {Saxon::QName} by looking the prefix up in declared namespaces
+      module Resolver
+        # Resolve a QName string into a {Saxon::QName}.
+        #
+        # If the arg is a {Saxon::QName} already, it just gets returned. If
+        # it's an instance of the underlying Saxon Java QName, it'll be wrapped
+        # into a {Saxon::QName}
+        #
+        # If the arg is a string, it's resolved by using {resolve_variable_name}
+        #
+        # @param qname_or_string [String, Saxon::QName] the qname to resolve
+        # @return [Saxon::QName]
+        def self.resolve_variable_qname(qname_or_string, namespaces)
+          case qname_or_string
+          when String
+            resolve_variable_name(qname_or_string, namespaces)
+          when Saxon::QName
+            qname_or_string
+          when Saxon::S9API::QName
+            Saxon::QName.new(qname_or_string)
+          end
+        end
+
+        # Resolve a QName string of the form <tt>"prefix:local-name"</tt> into a
+        # {Saxon::QName} by looking up the namespace URI in a hash of
+        # <tt>"prefix" => "namespace-uri"</tt>
+        #
+        # @param qname_string [String] the QName as a <tt>"prefix:local-name"</tt> string
+        # @param namespaces [Hash<String => String>] the set of namespaces as a hash of <tt>"prefix" => "namespace-uri"</tt>
+        # @return [Saxon::QName]
+        def self.resolve_variable_name(qname_string, namespaces)
+          local_name, prefix = qname_string.split(':').reverse
+          uri = nil
+
+          if prefix
+            uri = namespaces[prefix]
+            raise MissingVariableNamespaceError.new(qname_string, prefix) if uri.nil?
+          end
+
+          Saxon::QName.create(prefix: prefix, uri: uri, local_name: local_name)
+        end
+      end
+
+      # Provides the hooks for constructing a {StaticContext} 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 {StaticContext} with the results
+        # @param block [Proc] a Proc/lambda (or <tt>to_proc</tt>'d containing DSL calls
+        # @return [Saxon::XPath::StaticContext]
+        def self.define(block, args = {})
+          dsl = new(args)
+          dsl.instance_exec(&block) unless block.nil?
+          StaticContext.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 {XPath::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
+
+        # Bind prefixes to namespace URIs
+        #
+        # @param namespaces [Hash{String, Symbol => String}]
+        def namespace(namespaces = {})
+          @declared_namespaces = @declared_namespaces.merge(namespaces.transform_keys(&:to_s)).freeze
+        end
+
+        # Declare a XPath variable's existence in the context
+        #
+        # @param qname [String, Saxon::QName] The name of the variable as
+        # explicit QName or prefix:name string form. The string form requires
+        # the namespace prefix to have already been declared with {#namespace}
+        # @param type [String, Hash{Symbol => String, Class}, null] The type of the
+        # variable, either as a string using the same form as an XSLT
+        # <tt>as=""</tt> type definition, or as a hash of one key/value where
+        # that key is a Symbol taken from {Saxon::OccurenceIndicator} and the
+        # value is either a Class that {Saxon::ItemType} can convert to its
+        # XDM equivalent (e.g. {::String}), or a string that {Saxon::ItemType}
+        # can parse into an XDM type (e.g. <tt>xs:string</tthat
+        # {Saxon::ItemType} can parse into an XDM type (e.g.
+        # <tt>xs:string</tt> or <tt>element()</tt>).
+        # If it's nil, then the default <tt>item()*</tt> – anything – type declaration is used
+        def variable(qname, type = nil)
+          qname = resolve_variable_qname(qname)
+          @declared_variables = @declared_variables.merge({
+            qname => resolve_variable_declaration(qname, type)
+          }).freeze
+        end
+
+        private
+
+        def resolve_variable_qname(qname_or_string)
+          Resolver.resolve_variable_qname(qname_or_string, @declared_namespaces)
+        end
+
+        def resolve_variable_type_decl(type_decl)
+          case type_decl
+          when String
+            occurence_char = type_decl[-1]
+            occurence = case occurence_char
+            when '?'
+              {zero_or_one: type_decl[0..-2]}
+            when '+'
+              {one_or_more: type_decl[0..-2]}
+            when '*'
+              {zero_or_more: type_decl[0..-2]}
+            else
+              {one: type_decl}
+            end
+          when Hash
+            type_decl
+          end
+        end
+
+        def resolve_variable_declaration(qname, type)
+          args_hash = resolve_variable_type_decl(type) || {}
+          args_hash[:qname] = qname
+          Saxon::XPath::VariableDeclaration.new(args_hash)
+        end
+      end
+
+      include Common
+
+      # Executes the Proc/lambda passed in with a new instance of
+      # {StaticContext} 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::XPath::StaticContext] the static context created by the block
+      def self.define(block)
+        DSL.define(block)
+      end
+
+      attr_reader :declared_variables, :declared_namespaces, :default_collation
+
+      # @return [Saxon::QName]
+      # @overload resolve_variable_qname(qname)
+      #   returns the QName
+      #   @param qname_or_string [Saxon::QName] the name as a QName
+      # @overload resolve_variable_qname(string)
+      #   resolve the <tt>prefix:local_name</tt> string into a proper QName by
+      #   looking up the prefix in the {#declared_namespaces}
+      #   @param qname_or_string [String] the name as a string
+      def resolve_variable_qname(qname_or_string)
+        Resolver.resolve_variable_qname(qname_or_string, declared_namespaces)
+      end
+
+      def define(block)
+        DSL.define(block, args_hash)
+      end
+    end
+  end
+end