saxon-rb 0.4.0-java → 0.7.2-java

data/lib/saxon/xdm.rb

@@ -9,24 +9,31 @@ require_relative 'xdm/empty_sequence'
 require_relative 'xdm/item'
 
 module Saxon
+  # Classes for representing, creating, and working with the XPath Data Model
+  # type system used in XPath 2+, XSLT 2+, and XQuery.
   module XDM
     class << self
+      # Convenience function for creating a new {AtomicValue}. See {AtomicValue.create}
       def AtomicValue(*args)
         XDM::AtomicValue.create(*args)
       end
 
+      # Convenience function for creating a new {Value}. See {Value.create}
       def Value(*args)
         XDM::Value.create(*args)
       end
 
+      # Returns the XDM {EmptySequence}. See {EmptySequence.create}
       def EmptySequence()
         XDM::EmptySequence.create
       end
 
+      # Convenience function for creating a new {Array}. See {Array.create}
       def Array(*args)
         XDM::Array.create(*args)
       end
 
+      # Convenience function for creating a new {Map}. See {Map.create}
       def Map(*args)
         XDM::Map.create(*args)
       end

data/lib/saxon/xdm/array.rb

@@ -5,6 +5,11 @@ module Saxon
   module XDM
     # Represents an XDM Array
     class Array
+      # Create a new {XDM::Array} from a Ruby Array. The contents of the array
+      # will be converted to {XDM::Value}s using {XDM.Value()}. An existing
+      # {S9API::XdmArray} will simply be wrapped and returned.
+      #
+      # @return [XDM::Array] the new XDM Array
       def self.create(array)
         case array
         when S9API::XdmArray
@@ -28,14 +33,19 @@ module Saxon
         @s9_xdm_array = s9_xdm_array
       end
 
+      # Iterate over the Array, yielding each element.
+      # @yieldparam value [XDM::Value] the current value from the Array
       def each(&block)
         cached_array.each(&block)
       end
 
+      # Fetch element at index +i+ in the array.
+      # @param i [Integer] the index of the element to retrieve.
       def [](i)
         cached_array[i]
       end
 
+      # @return [Integer] the length of the array
       def length
         s9_xdm_array.arrayLength
       end
@@ -53,16 +63,22 @@ module Saxon
         cached_array == other.to_a
       end
 
+      # Return a (frozen) Ruby {::Array} containing all the elements of the {XDM::Array}
       def to_a
         cached_array
       end
 
       alias_method :eql?, :==
 
+      # Compute a hash-code for this {Array}.
+      #
+      # Two {XDM::Array}s with the same content will have the same hash code (and will compare using eql?).
+      # @see Object#hash
       def hash
         @hash ||= cached_array.hash
       end
 
+      # @return the underlying Java XdmArray
       def to_java
         s9_xdm_array
       end

data/lib/saxon/xdm/atomic_value.rb

@@ -20,6 +20,7 @@ module Saxon
       # them imlpicitly through the XDM::AtomicValue creation process doesn't really
       # work. They need to be created explicitly and then handed in to be wrapped.
       class CannotCreateQNameFromString < StandardError
+        # returns an error message
         def to_s
           "QName XDM::AtomicValues must be created using an instance of Saxon::QName, not a string like 'prefix:name': Prefix URI binding is undefined at this point"
         end
@@ -29,19 +30,22 @@ module Saxon
       # isn't a way to create these outside of parsing an XML document within
       # Saxon, so attempting to do so raises this error.
       class NotationCannotBeDirectlyCreated < StandardError
-        def to_s
+         # returns an error message
+         def to_s
           "xs:NOTATION XDM::AtomicValues cannot be directly created outside of XML parsing."
         end
       end
 
+      # ItemType representing QNames
       XS_QNAME = ItemType.get_type('xs:QName')
+      # ItemType representing NOTATION
       XS_NOTATION = ItemType.get_type('xs:NOTATION')
 
       class << self
         # Convert a single Ruby value into an XDM::AtomicValue
         #
         # If no explicit {ItemType} is passed, the correct type is guessed based
-        # on the class of the value. (e.g. <tt>xs:date</tt> for {Date}.)
+        # on the class of the value. (e.g. <tt>xs:date</tt> for {::Date}.)
         #
         # Values are converted based on Ruby idioms and operations, so an explicit
         # {ItemType} of <tt>xs:boolean</tt> will use truthyness to evaluate the
@@ -165,6 +169,10 @@ module Saxon
 
       alias_method :eql?, :==
 
+      # Compute a hash-code for this {AtomicValue}.
+      #
+      # Two {AtomicValue}s with the same content will have the same hash code (and will compare using eql?).
+      # @see Object#hash
       def hash
         @hash ||= s9_xdm_atomic_value.hashCode
       end

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,20 @@ 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 +:document+, +: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 +57,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,17 +65,56 @@ 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
+
+      # Use Saxon's naive XDM Node serialisation to serialize the node and its
+      # descendants. Saxon uses a new Serializer with default options to
+      # serialize the node. In particular, if the Node was produced by an XSLT
+      # that used +<xsl:character-map>+ through +<xsl:output>+ to modify the
+      # contents, then they *WILL* *NOT* have been applied.
+      #
+      # +<xsl:output>+ has its effect at serialization time, not at XDM tree
+      # creation time, so it won't be applied until you serialize the document.
+      #
+      # Even then, unless you use a {Serializer} configured with the XSLT's
+      # +<xsl:output>+. We make a properly configured serializer available in
+      # the result of any XSLT transform (a {Saxon::XSLT::Invocation}), e.g.:
+      #
+      #   result = xslt.apply_templates(input)
+      #   result.to_s
+      #   # or
+      #   result.serialize('/path/to/output.xml')
+      #
+      # You can also get that {Serializer} directly from {XSLT::Executable},
+      # should you want to use the serialization options from a particular XSLT
+      # to serialize arbitrary XDM values:
+      #
+      #   serializer = xslt.serializer
+      #   serializer.serialize(an_xdm_value)
+      #
+      # @see http://www.saxonica.com/documentation9.9/index.html#!javadoc/net.sf.saxon.s9api/XdmNode@toString
+      def to_s
+        s9_xdm_node.toString
+      end
     end
   end
 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