saxon-rb 0.4.0-java → 0.5.0-java

data/lib/saxon-rb.rb

@@ -0,0 +1 @@
+require_relative 'saxon'

data/lib/{saxon_jars.rb → saxon-rb_jars.rb}

@@ -2,9 +2,9 @@
 begin
   require 'jar_dependencies'
 rescue LoadError
-  require 'net/sf/saxon/Saxon-HE/9.9.1-5/Saxon-HE-9.9.1-5.jar'
+  require 'net/sf/saxon/Saxon-HE/9.9.1-6/Saxon-HE-9.9.1-6.jar'
 end
 
 if defined? Jars
-  require_jar 'net.sf.saxon', 'Saxon-HE', '9.9.1-5'
+  require_jar 'net.sf.saxon', 'Saxon-HE', '9.9.1-6'
 end

data/lib/saxon.rb

@@ -3,4 +3,17 @@ require_relative 'saxon/processor'
 
 # An idiomatic Ruby wrapper around the Saxon XML processing library.
 module Saxon
+  # Parse an XML document using a vanilla {DocumentBuilder} from the default
+  # {Processor}
+  # @see Saxon::Processor#XML
+  def self.XML(input, opts = {})
+    Processor.default.XML(input, opts)
+  end
+
+  # Compile an XSLT Stylesheet using a new {XSLT::Compiler} from the default
+  # {Processor}
+  # @see Saxon::Processor#XSLT
+  def self.XSLT(input, opts = {}, &block)
+    Processor.default.XSLT(input, opts, &block)
+  end
 end

data/lib/saxon/axis_iterator.rb

@@ -1,7 +1,12 @@
 require_relative 's9api'
 
 module Saxon
-  # An XPath Data Model Node object, representing an XML document, or an element or one of the other node chunks in the XDM.
+  # An iterator across an XPath axis of an XDM document, e.g. down to children
+  # (+child+), up to the root (+ancestor+)
+  # @example iterate over child nodes
+  #   AxisIterator.new(node, :child).each do |child_node|
+  #     puts child_node.node_name
+  #   end
   class AxisIterator
     include Enumerable
 
@@ -18,6 +23,8 @@ module Saxon
       s9_sequence_iterator
     end
 
+    # yields each node in the sequence
+    # @yieldparam [Saxon::XDM::Node] the next node in the sequence
     def each(&block)
       s9_sequence_iterator.lazy.map { |s9_xdm_node| Saxon::XDM::Node.new(s9_xdm_node) }.each(&block)
     end

data/lib/saxon/configuration.rb

@@ -10,6 +10,7 @@ module Saxon
   # for details of the constant names used to access the values
   class Configuration
     DEFAULT_SEMAPHORE = Mutex.new
+    private_constant :DEFAULT_SEMAPHORE
 
     # Provides a processor with default configuration. Essentially a singleton
     # instance

data/lib/saxon/item_type.rb

@@ -13,6 +13,7 @@ module Saxon
         @class_name = class_name
       end
 
+      # error message including class name no type equivalent found for
       def to_s
         "Ruby class <#{@class_name}> has no XDM type equivalent"
       end
@@ -26,29 +27,14 @@ module Saxon
         @type_str = type_str
       end
 
+      # error message including type string with no matching built-in type
       def to_s
         "'#{@type_str}' is not recognised as an XSD built-in type"
       end
     end
 
-    class Factory
-      DEFAULT_SEMAPHORE = Mutex.new
-
-      attr_reader :processor
-
-      def initialize(processor)
-        @processor = processor
-      end
-
-      def s9_factory
-        return @s9_factory if instance_variable_defined?(:@s9_factory)
-        DEFAULT_SEMAPHORE.synchronize do
-          @s9_factory = S9API::ItemTypeFactory.new(processor.to_java)
-        end
-      end
-    end
-
     TYPE_CACHE_MUTEX = Mutex.new
+    private_constant :TYPE_CACHE_MUTEX
     # A mapping of Ruby types to XDM type constants
     TYPE_MAPPING = {
       'String' => :STRING,
@@ -61,6 +47,8 @@ module Saxon
       'Time' => :DATE_TIME,
       'BigDecimal' => :DECIMAL,
       'Integer' => :INTEGER,
+      'Fixnum' => :INTEGER, # Fixnum/Bignum needed for JRuby 9.1/Ruby 2.3
+      'Bignum' => :INTEGER,
       'Float' => :FLOAT,
       'Numeric' => :NUMERIC
     }.freeze
@@ -132,12 +120,14 @@ module Saxon
       Hash[QNAME_MAPPING.map { |qname, v| [qname.to_s, v] }]
     ).freeze
 
+    # convertors to generate lexical strings for a given {ItemType}, as a hash keyed on the ItemType
     ATOMIC_VALUE_LEXICAL_STRING_CONVERTORS = Hash[
       LexicalStringConversion::Convertors.constants.map { |const|
         [S9API::ItemType.const_get(const), LexicalStringConversion::Convertors.const_get(const)]
       }
     ].freeze
 
+    # convertors from {XDM::AtomicValue} to a ruby primitve value, as a hash keyed on the ItemType
     ATOMIC_VALUE_TO_RUBY_CONVERTORS = Hash[
       ValueToRuby::Convertors.constants.map { |const|
         [S9API::ItemType.const_get(const), ValueToRuby::Convertors.const_get(const)]
@@ -155,6 +145,7 @@ module Saxon
       # @overload get_type(type_name)
       #   Get the {ItemType} for the name
       #   @param type_name [String] name of the built-in {ItemType} to fetch
+      #   (e.g. +xs:string+ or +element()+)
       # @overload get_type(item_type)
       #   Given an instance of {ItemType}, simply return the instance
       #   @param item_type [Saxon::ItemType] an existing ItemType instance
@@ -182,6 +173,8 @@ module Saxon
 
       def get_s9_type(arg)
         case arg
+        when S9API::ItemType
+          arg
         when Saxon::QName
           get_s9_qname_mapped_type(arg)
         when Class
@@ -250,6 +243,8 @@ module Saxon
 
     alias_method :eql?, :==
 
+    # Return a hash code so this can be used as a key in a {::Hash}.
+    # @return [Fixnum] the hash code
     def hash
       @hash ||= s9_item_type.hashCode
     end

data/lib/saxon/item_type/lexical_string_conversion.rb

@@ -5,12 +5,26 @@ module Saxon
     # A collection of lamba-like objects for converting Ruby values into
     # lexical strings for specific XSD datatypes
     module LexicalStringConversion
+      # Simple validation helper that checks if a value string matches an
+      # allowed lexical string pattern space or not.
+      #
+      # @param value [Object] the value whose to_s representation should be
+      #   checked
+      # @param item_type [Saxon::ItemType] the ItemType whose lexical pattern
+      #   space should be checked against
+      # @param pattern [Regexp] the lexical pattern space Regexp to use in the
+      #   checking
+      # @return [String] the lexical string for the value and type
+      # @raise [Errors::BadRubyValue] if the ruby value doesn't produce a string
+      #   which validates against the allowed pattern
       def self.validate(value, item_type, pattern)
         str = value.to_s
-        raise Errors::BadRubyValue.new(value, item_type) unless str.match?(pattern)
+        raise Errors::BadRubyValue.new(value, item_type) if str.match(pattern).nil?
         str
       end
 
+      # Helper class for performing conversion and validation to XDM integer
+      # types from Ruby's Fixnum/Bignum/Integer classes
       class IntegerConversion
         attr_reader :min, :max
 
@@ -18,20 +32,40 @@ module Saxon
           @min, @max = min, max
         end
 
+        # Returns whether the Ruby integer is within the range allowed for the
+        # XDM type
+        # @param integer_value [Integer] the ruby integer to check
+        # @return [Boolean] whether the value is within bounds
         def in_bounds?(integer_value)
           gte_min?(integer_value) && lte_max?(integer_value)
         end
 
+        # Returns whether the Ruby integer is >= the lower bound of the range
+        # allowed for the XDM type
+        # @param integer_value [Integer] the ruby integer to check
+        # @return [Boolean] whether the value is okay
         def gte_min?(integer_value)
           return true if min.nil?
           integer_value >= min
         end
 
+        # Returns whether the Ruby integer is <= the upper bound of the range
+        # allowed for the XDM type
+        # @param integer_value [Integer] the ruby integer to check
+        # @return [Boolean] whether the value is okay
         def lte_max?(integer_value)
           return true if max.nil?
           integer_value <= max
         end
 
+        # Check a value against our type constraints, and return the lexical
+        # string representation if it's okay.
+        #
+        # @param value [Integer] the ruby value
+        # @param item_type [Saxon::ItemType] the item type
+        # @return [String] the lexical string representation of the value
+        # @raise [Errors::RubyValueOutOfBounds] if the value is outside the
+        #   type's permitted bounds
         def call(value, item_type)
           integer_value = case value
           when ::Numeric
@@ -44,15 +78,42 @@ module Saxon
         end
       end
 
+      # Helper class for performing conversion and validation to XDM
+      # Floating-point types from Ruby's Float class
       class FloatConversion
         def initialize(size = :double)
           @double = size == :double
         end
 
+        # Check a value against our type constraints, and return the lexical
+        # string representation if it's okay.
+        #
+        # @param value [Float] the ruby value
+        # @param item_type [Saxon::ItemType] the item type
+        # @return [String] the lexical string representation of the value
+        def call(value, item_type)
+          case value
+          when ::Float::INFINITY
+            'INF'
+          when -::Float::INFINITY
+            '-INF'
+          when Numeric
+            float_value(value).to_s
+          else
+            LexicalStringConversion.validate(value, item_type, Patterns::FLOAT)
+          end
+        end
+
+        private
+
+        # Is this a double-precision XDM float?
+        # @return [Boolean] true if we're converting a double-precision float
         def double?
           @double
         end
 
+        # Return the float as either a double-precision or single-precision
+        # float as needed
         def float_value(float_value)
           return float_value if double?
           convert_to_single_precision(float_value)
@@ -61,30 +122,72 @@ module Saxon
         def convert_to_single_precision(float_value)
           [float_value].pack('f').unpack('f').first
         end
+      end
+
+      # Convert a value in seconds into an XDM Duration string
+      class DurationConversion
+        attr_reader :pattern
 
+        def initialize(pattern)
+          @pattern = pattern
+        end
+
+        # Produce a lexical Duration string from a numeric Ruby value
+        # representing seconds
         def call(value, item_type)
+          return numeric(value) if Numeric === value
+          LexicalStringConversion.validate(value, item_type, pattern)
+        end
+
+        private
+
+        def numeric(value)
+          sign = value.negative? ? '-' : ''
           case value
-          when ::Float::INFINITY
-            'INF'
-          when -::Float::INFINITY
-            '-INF'
-          when Numeric
-            float_value(value).to_s
+          when Integer
+            "#{sign}PT#{value.abs}S"
+          when BigDecimal
+            "#{sign}PT#{value.abs.to_s('F')}S"
           else
-            LexicalStringConversion.validate(value, item_type, Patterns::FLOAT)
+            sprintf("%sPT%0.9fS", sign, value.abs)
           end
         end
       end
 
+      # Helper class for creating convertors for the various G* Date-related
+      # types that allow single values (GDay, GMonth, GYear).
       class GDateConversion
         attr_reader :bounds, :integer_formatter, :validation_pattern
 
-        def initialize(args = {})
+      # @param args [Hash]
+      # @option args [Range] :bounds the integer bounds for values of this type
+      # @option args [Regexp] :validation_pattern the pattern used to validate the
+      #   value when it's a String not an Integer
+      # @option args [Proc] :integer_formatter a proc/lambda that will produce a
+      #   correctly-formatted lexical string from an Integer value
+      def initialize(args = {})
           @bounds = args.fetch(:bounds)
           @validation_pattern = args.fetch(:validation_pattern)
           @integer_formatter = args.fetch(:integer_formatter)
         end
 
+        # @param value [String, Integer] the value to convert
+        # @param item_type [XDM::ItemType] the type being converted to
+        # @return [String] a correctly formatted String
+        def call(value, item_type)
+          case value
+          when Integer
+            check_value_bounds!(value, item_type)
+            sprintf(integer_formatter.call(value), value)
+          else
+            formatted_value = LexicalStringConversion.validate(value, item_type, validation_pattern)
+            extract_and_check_value_bounds!(formatted_value, item_type)
+            formatted_value
+          end
+        end
+
+        private
+
         def extract_value_from_validated_format(formatted_value)
           Integer(formatted_value.gsub(validation_pattern, '\1'), 10)
         end
@@ -97,20 +200,27 @@ module Saxon
         def extract_and_check_value_bounds!(formatted_value, item_type)
           check_value_bounds!(extract_value_from_validated_format(formatted_value), item_type)
         end
+      end
+
+      # Convert Bytes. Idiomatically, Ruby uses +ASCII_8BIT+ encoded strings to
+      # represent bytes, and so a single character represents a single byte. XDM
+      # uses the decimal value of a signed or unsigned 8 bit integer
+      class ByteConversion
+        attr_reader :unpack_format
+
+        def initialize(kind = :signed)
+          @unpack_format = kind == :unsigned ? 'C' : 'c'
+        end
 
         def call(value, item_type)
-          case value
-          when Integer
-            check_value_bounds!(value, item_type)
-            sprintf(integer_formatter.call(value), value)
-          else
-            formatted_value = LexicalStringConversion.validate(value, item_type, validation_pattern)
-            extract_and_check_value_bounds!(formatted_value, item_type)
-            formatted_value
-          end
+          raise Errors::RubyValueOutOfBounds.new(value, item_type) if value.bytesize != 1
+          value = value.to_s.force_encoding(Encoding::ASCII_8BIT)
+          value.unpack(unpack_format).first.to_s
         end
       end
 
+      # Pattern fragments that can be combined to help create the lexical space
+      # patterns in {Patterns}
       module PatternFragments
         TIME_DURATION = /(?:T
           (?:
@@ -132,6 +242,7 @@ module Saxon
         NAME_CHAR = ":|" + NCNAME_CHAR
       end
 
+      # A collection of lexical space patterns for XDM types
       module Patterns
         def self.build(*patterns)
           Regexp.new((['\A'] + patterns.map(&:to_s) + ['\z']).join(''))
@@ -159,6 +270,8 @@ module Saxon
         BASE64_BINARY = /\A(?:(?:[A-Za-z0-9+\/] ?){4})*(?:(?:[A-Za-z0-9+\/] ?){3}[A-Za-z0-9+\/]|(?:[A-Za-z0-9+\/] ?){2}[AEIMQUYcgkosw048] ?=|[A-Za-z0-9+\/] ?[AQgw] ?= ?=)?\z/
       end
 
+      # Convertors from Ruby values to lexical string representations for a
+      # particular XDM type
       module Convertors
         ANY_URI = ->(value, item_type) {
           uri_classes = [URI::Generic]
@@ -179,11 +292,7 @@ module Saxon
         BOOLEAN = ->(value, item_type) {
           value ? 'true' : 'false'
         }
-        BYTE = ->(value, item_type) {
-          raise Errors::RubyValueOutOfBounds.new(value, item_type) if value.bytesize != 1
-          value = value.to_s.force_encoding(Encoding::ASCII_8BIT)
-          value.unpack('c').first.to_s
-        }
+        BYTE = ByteConversion.new
         DATE = ->(value, item_type) {
           if value.respond_to?(:strftime)
             value.strftime('%F')
@@ -202,21 +311,7 @@ module Saxon
           LexicalStringConversion.validate(value, item_type, Patterns::TIME)
         }
         DATE_TIME_STAMP = DATE_TIME
-        DAY_TIME_DURATION = ->(value, item_type) {
-          case value
-          when Integer
-            sign = value.negative? ? '-' : ''
-            "#{sign}PT#{value.abs}S"
-          when BigDecimal
-            sign = value.negative? ? '-' : ''
-            "#{sign}PT#{value.abs.to_s('F')}S"
-          when Numeric
-            sign = value.negative? ? '-' : ''
-            sprintf("%sPT%0.9fS", sign, value.abs)
-          else
-            LexicalStringConversion.validate(value, item_type, Patterns::DAY_TIME_DURATION)
-          end
-        }
+        DAY_TIME_DURATION = DurationConversion.new(Patterns::DAY_TIME_DURATION)
         DECIMAL = ->(value, item_type) {
           case value
           when ::Integer
@@ -230,21 +325,7 @@ module Saxon
           end
         }
         DOUBLE = FloatConversion.new(:single)
-        DURATION = ->(value, item_type) {
-          case value
-          when Integer
-            sign = value.negative? ? '-' : ''
-            "#{sign}PT#{value.abs}S"
-          when BigDecimal
-            sign = value.negative? ? '-' : ''
-            "#{sign}PT#{value.abs.to_s('F')}S"
-          when Numeric
-            sign = value.negative? ? '-' : ''
-            sprintf("%sPT%0.9fS", sign, value.abs)
-          else
-            LexicalStringConversion.validate(value, item_type, Patterns::DURATION)
-          end
-        }
+        DURATION = DurationConversion.new(Patterns::DURATION)
         FLOAT = FloatConversion.new
         G_DAY = GDateConversion.new({
           bounds: 1..31,
@@ -325,11 +406,7 @@ module Saxon
         TOKEN = ->(value, item_type) {
           LexicalStringConversion.validate(value, item_type, Patterns::TOKEN)
         }
-        UNSIGNED_BYTE = ->(value, item_type) {
-          raise Errors::RubyValueOutOfBounds.new(value, item_type) if value.bytesize != 1
-          value = value.to_s.force_encoding(Encoding::ASCII_8BIT)
-          value.unpack('C').first.to_s
-        }
+        UNSIGNED_BYTE = ByteConversion.new(:unsigned)
         UNSIGNED_INT = IntegerConversion.new(0, 4294967295)
         UNSIGNED_LONG = IntegerConversion.new(0, 18446744073709551615)
         UNSIGNED_SHORT = IntegerConversion.new(0, 65535)
@@ -341,6 +418,7 @@ module Saxon
         }
       end
 
+      # Conversion process error classes
       module Errors
         # Raised during conversion from Ruby value to XDM Type lexical string
         # when the ruby value does not conform to the Type's string