saxon-rb 0.4.0-java → 0.5.0-java

data/lib/saxon/xdm/empty_sequence.rb

@@ -5,30 +5,43 @@ module Saxon
   module XDM
     # Represents the empty sequence in XDM
     class EmptySequence
+      # Returns an instance. Effectively a Singleton because the EmptySequence
+      # is immutable, and empty. An instance is completely interchangeable with
+      # another. The instance is cached, but multiple instances may exist across
+      # threads. We don't prevent that because it's immaterial.
+      # @return [EmptySequence] The empty sequence
       def self.create
         @instance ||= new
       end
 
       include SequenceLike
 
+      # @return [Enumerator] an enumerator over an empty Array
       def sequence_enum
         [].to_enum
       end
 
+      # @return [Integer] the size of the sequence (always 0)
       def sequence_size
         0
       end
 
+      # All instances of {EmptySequence} are equal to each other.
+      #
+      # @param other [Object] the object to compare self against
+      # @return [Boolean] Whether this object is equal to the other
       def ==(other)
         other.class == self.class
       end
 
       alias_method :eql?, :==
 
+      # @return [Integer] the hash code. All instances have the same hash code.
       def hash
         [].hash
       end
 
+      # @return [net.sf.saxon.s9api.XDMEmptySequence] the underlying Java empty sequence
       def to_java
         @s9_xdm_empty_sequence ||= Saxon::S9API::XdmEmptySequence.getInstance
       end

data/lib/saxon/xdm/external_object.rb

@@ -13,6 +13,7 @@ module Saxon
         @s9_xdm_external_object = s9_xdm_external_object
       end
 
+      # The underlying Saxon XdmExternalObject
       def to_java
         @s9_xdm_external_object
       end

data/lib/saxon/xdm/function_item.rb

@@ -13,6 +13,7 @@ module Saxon
         @s9_xdm_function_item = s9_xdm_function_item
       end
 
+      # The underlying Saxon XdmFunctionItem
       def to_java
         @s9_xdm_function_item
       end

data/lib/saxon/xdm/item.rb

@@ -1,5 +1,12 @@
 module Saxon
   module XDM
+    # Create one of the XdmItem-derived XDM objects from the passed in argument.
+    #
+    # Existing XDM::* objects are passed through. s9api.Xdm* Java objects are
+    # wrapped appropriately and returned. Ruby Arrays and Hashes are converted
+    # to {XDM::Array} and {XDM::Map} instances respectively. Ruby values that
+    # respond to +#each+ are converted to an {XDM::Array} (e.g. {Set}). Other
+    # Ruby values are converted to {XDM::AtomicValue}.
     def self.Item(item)
       case item
       when Value, AtomicValue, Node, Array, Map, ExternalObject

data/lib/saxon/xdm/map.rb

@@ -5,6 +5,12 @@ module Saxon
   module XDM
     # Represents an XDM Map
     class Map
+      # Create an {XDM::Map} from a Ruby Hash, by ensuring each key has been
+      # converted to an {AtomicValue}, and each value has been converted to an
+      # XDM Value of some sort.
+      # @return [XDM::Map] the new Map
+      # @see XDM.AtomicValue
+      # @see XDM.Value
       def self.create(hash)
         case hash
         when Saxon::S9API::XdmMap
@@ -30,39 +36,71 @@ module Saxon
         @s9_xdm_map = s9_xdm_map
       end
 
+      # Compare this Map against another. They're equal if they contain the same
+      # key, value pairs.
       def ==(other)
         return false unless other.is_a?(self.class)
         to_h == other.to_h
       end
 
+      # Fetch the value for the key given. +key+ is converted to an
+      # {XDM::AtomicValue} if it isn't already one.
+      # @param key [Object, XDM::AtomicValue] the key to retrieve
       def [](key)
         cached_hash[XDM.AtomicValue(key)]
       end
 
+      # Fetch the value for the key given, as {Hash#fetch} would. +key+ is
+      # converted to an {XDM::AtomicValue} if it isn't already one.
+      # @param key [XDM::AtomicValue, Object] the key to retrieve.
+      # @see Hash#fetch
       def fetch(key, *args, &block)
         cached_hash.fetch(XDM.AtomicValue(key), *args, &block)
       end
 
+      # Iterate over the Map as {Hash#each} would
+      # @yieldparam key [XDM::AtomicValue] the key
+      # @yieldparam value [XDM::Value] the value
       def each(&block)
         cached_hash.each(&block)
       end
 
+      # Return a new Map containing only key, value pairs for which the block
+      # returns true.
+      # @yieldparam key [XDM::AtomicValue] the key
+      # @yieldparam value [XDM::Value] the value
+      # @see ::Hash#select
       def select(&block)
         self.class.create(each.select(&block).to_h)
       end
 
+      # Return a new Map containing only key, value pairs for which the block
+      # DOES NOT return true.
+      # @yieldparam key [XDM::AtomicValue] the key
+      # @yieldparam value [XDM::Value] the value
+      # @see ::Hash#reject
       def reject(&block)
         self.class.create(each.reject(&block).to_h)
       end
 
+      # Create a new Map from the result of merging another Map into this one.
+      # In the case of duplicate keys, the value in the provided hash will be
+      # used.
+      # @yieldparam key [XDM::AtomicValue] the key
+      # @yieldparam value [XDM::Value] the value
+      # @return [XDM::Map] the new Map
+      # @see ::Hash#merge
       def merge(other)
         self.class.create(to_h.merge(other.to_h))
       end
 
+      # @return [S9API::XdmMap] the underlying Saxon XdmMap
       def to_java
         @s9_xdm_map
       end
 
+      # a (frozen) Ruby hash containing the keys and values from the Map.
+      # @return [Hash] the Map as a Ruby hash.
       def to_h
         cached_hash
       end

data/lib/saxon/xdm/node.rb

@@ -4,7 +4,8 @@ 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.
+    # 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
@@ -23,12 +24,19 @@ module Saxon
         @s9_xdm_node
       end
 
+      # The name of the node, as a {Saxon::QName}, or +nil+ if the node is not
+      # of a kind that has a name
+      # @return [Saxon::QName, null] the name, if there is one
       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
 
+      # What kind of node this is. Returns one of +: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
         when Saxon::S9API::XdmNodeKind::ELEMENT
@@ -48,6 +56,7 @@ module Saxon
         end
       end
 
+      # Does this Node represent the same underlying node as the other?
       def ==(other)
         return false unless other.is_a?(XDM::Node)
         s9_xdm_node.equals(other.to_java)
@@ -55,14 +64,23 @@ module Saxon
 
       alias_method :eql?, :==
 
+      # Compute a hash-code for this {Node}.
+      #
+      # Two {Node}s with the same content will have the same hash code (and will compare using eql?).
+      # @see Object#hash
       def hash
         @hash ||= s9_xdm_node.hashCode
       end
 
+      # Execute the given block for every child node of this
+      # @yieldparam node [Saxon::XDM::Node] the child node
       def each(&block)
         axis_iterator(:child).each(&block)
       end
 
+      # Create an {AxisIterator} over this Node for the given XPath axis
+      # @param axis [Symbol] the axis to iterate along
+      # @see AxisIterator
       def axis_iterator(axis)
         AxisIterator.new(self, axis)
       end

data/lib/saxon/xdm/sequence_like.rb

@@ -1,14 +1,25 @@
 module Saxon
   module XDM
+    # Mixin for objects that are XDM Sequence-like in behaviour
     module SequenceLike
+      # Implementors should return an {Enumerator} over the Sequence. For
+      # {XDM::Value}s, this will just be the items in the sequence. For
+      # XDM::AtomicValue or XDM::Node, this will be a single-item Enumerator so
+      # that Items can be correctly treated as single-item Values.
       def sequence_enum
         raise NotImplementedError
       end
 
+      # Implementors should return the size of the Sequence. For
+      # {XDM::AtomicValue} this will always be 1.
+      # @return [Integer] the sequence size
       def sequence_size
         raise NotImplementedError
       end
 
+      # Return a new XDM::Value from this Sequence with the passed in value
+      # appended to the end.
+      # @return [XDM::Value] the new Value
       def append(other)
         XDM::Value.create([self, other])
       end
@@ -17,11 +28,15 @@ module Saxon
       alias_method :+, :append
     end
 
+    # Mixin for objects that are Sequence-like but only contain a single item,
+    # like {XDM::AtomicValue} or {XDM::Node}
     module ItemSequenceLike
+      # return a single-item Enumerator containing +self+
       def sequence_enum
         [self].to_enum
       end
 
+      # Returns the sequence size, which will always be 1.
       def sequence_size
         1
       end

data/lib/saxon/xdm/value.rb

@@ -19,8 +19,8 @@ module Saxon
           when 0
             XDM.EmptySequence()
           when 1
-            if existing_value = maybe_xdm_value(items.first)
-              return existing_value
+            if value = maybe_xdm_value(items.first)
+              return value
             end
             XDM.Item(items.first)
           else
@@ -30,12 +30,25 @@ module Saxon
 
         private
 
-        def maybe_xdm_value(item)
-          return item if item.is_a?(self)
-          return new(item) if item.instance_of?(Saxon::S9API::XdmValue)
+        def maybe_xdm_value(value)
+          return value if value.is_a?(self)
+          return value if value === XDM.EmptySequence()
+          return XDM.EmptySequence() if value.instance_of?(Saxon::S9API::XdmEmptySequence)
+          return check_for_empty_or_single_item_value(value) if value.instance_of?(Saxon::S9API::XdmValue)
           false
         end
 
+        def check_for_empty_or_single_item_value(s9_value)
+          case s9_value.size
+          when 0
+            XDM.EmptySequence()
+          when 1
+            XDM.Item(s9_value.item_at(0))
+          else
+            new(s9_value)
+          end
+        end
+
         def wrap_items(items)
           result = []
           items.map { |item|
@@ -122,10 +135,12 @@ module Saxon
 
       alias_method :enum_for, :to_enum
 
+      # Returns an enumerator over the Sequence
       def sequence_enum
         to_enum
       end
 
+      # @return [Integer] the size of the sequence
       def sequence_size
         s9_xdm_value.size
       end
@@ -137,6 +152,7 @@ module Saxon
         @s9_xdm_item = s9_xdm_item
       end
 
+      # Return the underlying s9api XdmItem
       def to_java
         @s9_xdm_item
       end

data/lib/saxon/xpath.rb

@@ -3,6 +3,15 @@ require_relative './xpath/compiler'
 module Saxon
   # Classes for compiling, configuring, and executing XPath queries against
   # XDM nodes or documents
+  #
+  # Using an XPath involves creating a compiler, compiling an XPath into an
+  # executable, and then running that XPath executable against an XDM node.
+  #
+  # The easiest way to create an XPath::Compiler instance is by using the {Saxon::Processor#xpath_compiler} method.
+  #
+  # @see Saxon::XPath::Compiler
+  # @see Saxon::XPath::Executable
+  # @see Saxon::Processor#xpath_compiler
   module XPath
   end
 end

data/lib/saxon/xpath/compiler.rb

@@ -4,7 +4,36 @@ require_relative './executable'
 
 module Saxon
   module XPath
-    # Compiles XPath expressions so they can be executed
+    # An {XPath::Compiler} turns XPath expressions into executable queries you
+    # can run against XDM Nodes (like XML documents, or parts of XML documents).
+    #
+    # To compile an XPath requires an +XPath::Compiler+ instance. You can create
+    # one by calling {Compiler.create} and passing a {Saxon::Processor}, with an
+    # optional block for context like bound namespaces and declared variables.
+    # Alternately, and much more easily, you can call {Processor#xpath_compiler}
+    # on the {Saxon::Processor} instance you're already working with.
+    #
+    #     processor = Saxon::Processor.create
+    #     compiler = processor.xpath_compiler {
+    #       namespace a: 'http://example.org/a'
+    #       variable 'a:var', 'xs:string'
+    #     }
+    #     # Or...
+    #     compiler = Saxon::XPath::Compiler.create(processor) {
+    #       namespace a: 'http://example.org/a'
+    #       variable 'a:var', 'xs:string'
+    #     }
+    #     xpath = compiler.compile('//a:element[@attr = $a:var]')
+    #     matches = xpath.evaluate(document_node, {
+    #       'a:var' => 'the value'
+    #     }) #=> Saxon::XDM::Value
+    #
+    # In order to use prefixed QNames in your XPaths, like +/ns:name/+, then you need
+    # to declare prefix/namespace URI bindings when you create a compiler.
+    #
+    # It's also possible to make use of variables in your XPaths by declaring them at
+    # the compiler creation stage, and then passing in values for them as XPath run
+    # time.
     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
@@ -46,6 +75,12 @@ module Saxon
         Saxon::XPath::Executable.new(new_compiler.compile(expression), static_context)
       end
 
+      # Allows the creation of a new {Compiler} starting from a copy of this
+      # 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
+      # @return [Saxon::XPath::Compiler] the new compiler instance
       def create(&block)
         new_static_context = static_context.define(block)
         self.class.new(@s9_processor, new_static_context)

data/lib/saxon/xpath/executable.rb

@@ -2,7 +2,23 @@ require_relative '../xdm'
 
 module Saxon
   module XPath
-    # Represents a compiled XPath query ready to be executed
+    # Represents a compiled XPath query ready to be executed. An
+    # {XPath::Executable} is created by compiling an XPath expression with
+    # {XPath::Compiler#compile}.
+    #
+    # To run the +XPath::Executable+ you can call {XPath::Executable#evaluate},
+    # to generate an {XDM::Value} of the results, or you can call
+    # {XPath::Executable#as_enum} to return an Enumerator over the results.
+    #
+    #     processor = Saxon::Processor.create
+    #     compiler = processor.xpath_compiler
+    #     xpath = compiler.compile('//element[@attr = $var]')
+    #
+    #     matches = xpath.evaluate(document_node, {'var' => 'the value'}) #=> Saxon::XDM::Value
+    #
+    #     xpath.as_enum(document_node, {'var' => 'the value'}).each do |node|
+    #       ...
+    #     end
     class Executable
       # @return [XPath::StaticContext] the XPath's static context
       attr_reader :static_context
@@ -16,17 +32,34 @@ module Saxon
         @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)
+
+      # Evaluate the XPath against the context node given and return an
+      # +Enumerator+ over the result.
+      #
+      # @param context_item [Saxon::XDM::Node, Saxon::XDM::AtomicValue] the item
+      #   to be used as the context item for evaluating the XPath from.
+      # @param variables [Hash<Saxon::QName => Saxon::XDM::Value, Saxon::XDM::Node,
+      #   Saxon::XDM::AtomicValue>] any variable values to set within the XPath
+      # @return [Enumerator] an Enumerator over the items in the result sequence
+      def as_enum(context_item, variables = {})
+        generate_selector(context_item, variables).iterator.lazy.
+          map { |s9_xdm_object| Saxon::XDM.Value(s9_xdm_object) }
+      end
+
+      # Evaluate the XPath against the context node given and return the result.
+      #
+      # If the result is a single item, then that will be returned directly
+      # (e.g. an {XDM::Node} or an {XDM::AtomicValue}). If the result is an
+      # empty sequence then {XDM::EmptySequence} is returned.
+      #
+      # @param context_item [Saxon::XDM::Node, Saxon::XDM::AtomicValue] the item
+      #   to be used as the context item for evaluating the XPath from.
+      # @param variables [Hash<Saxon::QName => Saxon::XDM::Value, Saxon::XDM::Node,
+      #   Saxon::XDM::AtomicValue>] any variable values to set within the XPath
+      # @return [Saxon::XDM::Value] the XDM value returned
+      def evaluate(context_item, variables = {})
+        s9_xdm_value = generate_selector(context_item, variables).evaluate
+        Saxon::XDM.Value(s9_xdm_value)
       end
 
       # @return [net.sf.saxon.s9api.XPathExecutable] the underlying Saxon
@@ -34,24 +67,16 @@ module Saxon
       def to_java
         @s9_xpath_executable
       end
-    end
 
-    # The result of executing an XPath query as an enumerable object
-    class Result
-      include Enumerable
+      private
 
-      # @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)
+      def generate_selector(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
+        selector
       end
     end
   end