saxon-rb 0.4.0-java

data/lib/saxon/xdm/node.rb

@@ -0,0 +1,71 @@
+require_relative '../axis_iterator'
+require_relative '../s9api'
+require_relative 'sequence_like'
+
+module Saxon
+  module XDM
+    # An XPath Data Model Node object, representing an XML document, or an element or one of the other node chunks in the XDM.
+    class Node
+      include XDM::SequenceLike
+      include XDM::ItemSequenceLike
+      include Enumerable
+
+      attr_reader :s9_xdm_node
+      private :s9_xdm_node
+
+      # @api private
+      def initialize(s9_xdm_node)
+        @s9_xdm_node = s9_xdm_node
+      end
+
+      # @return [Saxon::S9API::XdmNode] The underlying Saxon Java XDM node object.
+      def to_java
+        @s9_xdm_node
+      end
+
+      def node_name
+        return @node_name if instance_variable_defined?(:@node_name)
+        node_name = s9_xdm_node.getNodeName
+        @node_name = node_name.nil? ? nil : Saxon::QName.new(node_name)
+      end
+
+      def node_kind
+        @node_kind ||= case s9_xdm_node.nodeKind
+        when Saxon::S9API::XdmNodeKind::ELEMENT
+          :element
+        when Saxon::S9API::XdmNodeKind::TEXT
+          :text
+        when Saxon::S9API::XdmNodeKind::ATTRIBUTE
+          :attribute
+        when Saxon::S9API::XdmNodeKind::NAMESPACE
+          :namespace
+        when Saxon::S9API::XdmNodeKind::COMMENT
+          :comment
+        when Saxon::S9API::XdmNodeKind::PROCESSING_INSTRUCTION
+          :processing_instruction
+        when Saxon::S9API::XdmNodeKind::DOCUMENT
+          :document
+        end
+      end
+
+      def ==(other)
+        return false unless other.is_a?(XDM::Node)
+        s9_xdm_node.equals(other.to_java)
+      end
+
+      alias_method :eql?, :==
+
+      def hash
+        @hash ||= s9_xdm_node.hashCode
+      end
+
+      def each(&block)
+        axis_iterator(:child).each(&block)
+      end
+
+      def axis_iterator(axis)
+        AxisIterator.new(self, axis)
+      end
+    end
+  end
+end

data/lib/saxon/xdm/sequence_like.rb

@@ -0,0 +1,30 @@
+module Saxon
+  module XDM
+    module SequenceLike
+      def sequence_enum
+        raise NotImplementedError
+      end
+
+      def sequence_size
+        raise NotImplementedError
+      end
+
+      def append(other)
+        XDM::Value.create([self, other])
+      end
+
+      alias_method :<<, :append
+      alias_method :+, :append
+    end
+
+    module ItemSequenceLike
+      def sequence_enum
+        [self].to_enum
+      end
+
+      def sequence_size
+        1
+      end
+    end
+  end
+end

data/lib/saxon/xdm/value.rb

@@ -0,0 +1,145 @@
+require_relative '../s9api'
+require_relative 'sequence_like'
+
+module Saxon
+  module XDM
+    # An XPath Data Model Value object, representing a Sequence.
+    class Value
+      include XDM::SequenceLike
+      include Enumerable
+
+      class << self
+        # Create a new XDM::Value sequence containing the items passed in as a Ruby enumerable.
+        #
+        # @param items [Enumerable] A list of members
+        # @return [Saxon::XDM::Value] The XDM value
+        def create(*items)
+          items = items.flatten
+          case items.size
+          when 0
+            XDM.EmptySequence()
+          when 1
+            if existing_value = maybe_xdm_value(items.first)
+              return existing_value
+            end
+            XDM.Item(items.first)
+          else
+            new(Saxon::S9API::XdmValue.new(wrap_items(items)))
+          end
+        end
+
+        private
+
+        def maybe_xdm_value(item)
+          return item if item.is_a?(self)
+          return new(item) if item.instance_of?(Saxon::S9API::XdmValue)
+          false
+        end
+
+        def wrap_items(items)
+          result = []
+          items.map { |item|
+            wrap_item(item, result)
+          }
+          result
+        end
+
+        def wrap_item(item, result)
+          if item.respond_to?(:sequence_enum)
+            item.sequence_enum.each do |item|
+              result << item.to_java
+            end
+          elsif item.respond_to?(:each)
+            item.each do |item|
+              result << XDM.Item(item).to_java
+            end
+          else
+            result << XDM.Item(item).to_java
+          end
+        end
+      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::XDM::AtomicValue, Saxon::XDM::Node] 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 XDM::Value 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::XDM::Value] The XDM::Value to be compare against
+      # @return [Boolean] whether the two XDM::Values are equal
+      def ==(other)
+        return false unless other.is_a?(XDM::Value)
+        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 XDM::Value
+      # @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.enum_for(:each).lazy.map { |s9_xdm_item|
+          XDM.Item(s9_xdm_item)
+        }.each
+      end
+
+      alias_method :enum_for, :to_enum
+
+      def sequence_enum
+        to_enum
+      end
+
+      def sequence_size
+        s9_xdm_value.size
+      end
+    end
+
+    # Placeholder class for Saxon Items that we haven't gotten to yet
+    class XDM::UnhandledItem
+      def initialize(s9_xdm_item)
+        @s9_xdm_item = s9_xdm_item
+      end
+
+      def to_java
+        @s9_xdm_item
+      end
+    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,58 @@
+require_relative '../xdm'
+
+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::XDM::Node] 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::XDM.Value(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>XDM::Node</tt>s from the query result. If no block is passed,
+      # returns an <tt>Enumerator</tt>
+      # @yieldparam xdm_node [Saxon::XDM::Node] the name that is yielded
+      def each(&block)
+        @result_iterator.lazy.map { |s9_xdm_node| Saxon::XDM::Node.new(s9_xdm_node) }.each(&block)
+      end
+    end
+  end
+end

data/lib/saxon/xpath/static_context.rb

@@ -0,0 +1,161 @@
+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
+
+      # 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)
+          Saxon::QName.resolve(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)
+        Saxon::QName.resolve(qname_or_string, declared_namespaces)
+      end
+
+      def define(block)
+        DSL.define(block, args_hash)
+      end
+    end
+  end
+end