saxon-rb 0.4.0-java → 0.7.2-java

data/lib/saxon/feature_flags/helpers.rb

@@ -0,0 +1,15 @@
+module Saxon
+  module FeatureFlags
+    # Helper methods to create feature restrictions in the library. To be mixed
+    # in to library classes.
+    module Helpers
+      # specify that the method named can only run if the version constraint is satisfied
+      #
+      # @param method_name [Symbol] the name of the method
+      # @param version_constraint [String] the version constraint (<tt>'>= 9.9'</tt>)
+      def requires_saxon_version(method_name, version_constraint)
+        Saxon::FeatureFlags::Version.create(self, method_name, version_constraint)
+      end
+    end
+  end
+end

data/lib/saxon/feature_flags/version.rb

@@ -0,0 +1,100 @@
+require_relative '../version/library'
+require_relative 'errors'
+
+module Saxon
+  module FeatureFlags
+    # Restrict a specific method to only work with the specified Saxon version
+    class Version
+      # Modify the method so that it will only run if the version constraint is
+      # satisfied.
+      #
+      # We can't know what version of Saxon is in use at code load time, only
+      # once {Saxon::Loader#load!} has been called, either explicitly or by
+      # calling a method which requires a Saxon Java object. Therefore, we have
+      # to check this the first time someone calls the method.
+      #
+      # Creating this check replaces the method on the target class with one
+      # that checks the version, and runs the original version if its constraint
+      # is satisfied.
+      #
+      # To avoid performing the check every time the method is called, once we
+      # know whether or not the constraint is satisfied, we assume that the
+      # verion of Saxon cannot be unloaded and a new one loaded in its place and
+      # replace our version checking method with the original (if the constraint
+      # is passed), or with one that simply +raise+s the constraint error.
+      #
+      # @param klass [Class] the class the method lives on
+      # @param method_name [Symbol] the name of the method to be constrained
+      # @param version_constraint [String] the version constraint
+      #   (<tt>'>9.9.1.7'</tt> or <tt>'>= 9.9'</tt>)
+      def self.create(klass, method_name, version_constraint)
+        method = klass.instance_method(method_name)
+        version_check = new(version_constraint)
+
+
+        klass.send(:define_method, method_name, ->(*args) {
+          if version_check.ok?
+            klass.send(:define_method, method_name, method)
+            method.bind(self).call(*args)
+          else
+            klass.send(:define_method, method_name, ->(*args) {
+              raise UnavailableInThisSaxonVersionError
+            })
+            raise UnavailableInThisSaxonVersionError
+          end
+        })
+      end
+
+      # @return [String] the complete constraint string
+      attr_reader :constraint_string
+      # @return [Symbol] the extracted comparison operator
+      attr_reader :comparison_operator
+      # @return [String] the extracted version string
+      attr_reader :version_string
+
+      # Create a version constraint check from the supplied constraint string
+      #
+      # @param constraint_string [String] the version constraint
+      def initialize(constraint_string)
+        @constraint_string = constraint_string
+        @comparison_operator, @version_string = parse_version_constraint(constraint_string)
+      end
+
+      # Reports if the version constraint is satisfied or not.
+      #
+      # @return [Boolean] true if the constraint is satisfied, false otherwise
+      def ok?
+        Saxon::Version::Library.loaded_version.send(comparison_operator, constraint_version)
+      end
+
+      # Generates a {Saxon::Version::Library} representing the version specified
+      # in the constraint that can be compared with the loaded Saxon version
+      #
+      # @return [Saxon::Version::Library] the constraint version
+      def constraint_version
+        @constraint_version ||= begin
+          components = version_string.split('.').map { |n| Integer(n, 10) }
+          Saxon::Version::Library.new(version_string, components, 'HE')
+        end
+      end
+
+      private
+
+      def parse_version_constraint(version_constraint)
+        op_string, version_string = version_constraint.split
+
+        comparison_operator = parse_operator_string(op_string)
+        [comparison_operator, version_string]
+      end
+
+      def parse_operator_string(op_string)
+        case op_string
+        when '~>'
+          :pessimistic_compare
+        else
+          op_string.to_sym
+        end
+      end
+    end
+  end
+end

data/lib/saxon/item_type.rb

@@ -6,13 +6,55 @@ require_relative 'item_type/value_to_ruby'
 module Saxon
   # Represent XDM types abstractly
   class ItemType
-    # Error raised when a Ruby class has no equivalent XDM type to be converted
-    # into
+    # lazy-loading Hash so we can avoid eager-loading saxon Jars, which prevents
+    # using external Saxon Jars unless the user is more careful than they should
+    # have to be.
+    class LazyReadOnlyHash
+      include Enumerable
+
+      attr_reader :loaded_hash, :load_mutex, :init_block
+      private :loaded_hash, :load_mutex, :init_block
+
+      def initialize(&init_block)
+        @init_block = init_block
+        @load_mutex = Mutex.new
+        @loaded_hash = nil
+      end
+
+      def [](key)
+        ensure_loaded!
+        loaded_hash[key]
+      end
+
+      def fetch(*args, &block)
+        ensure_loaded!
+        loaded_hash.fetch(*args, &block)
+      end
+
+      def each(&block)
+        ensure_loaded!
+        loaded_hash.each(&block)
+      end
+
+      private
+
+      def ensure_loaded!
+        return true unless loaded_hash.nil?
+        load_mutex.synchronize do
+          return true unless loaded_hash.nil?
+          @loaded_hash = init_block.call
+        end
+      end
+    end
+
+    # Error raised when a Ruby class has no equivalent XDM type to
+    # be converted into
     class UnmappedRubyTypeError < StandardError
       def initialize(class_name)
         @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 +68,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,88 +88,96 @@ 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
 
     # A mapping of QNames to XDM type constants
-    QNAME_MAPPING = Hash[{
-      'anyAtomicType' => :ANY_ATOMIC_VALUE,
-      'anyURI' => :ANY_URI,
-      'base64Binary' => :BASE64_BINARY,
-      'boolean' => :BOOLEAN,
-      'byte' => :BYTE,
-      'date' => :DATE,
-      'dateTime' => :DATE_TIME,
-      'dateTimeStamp' => :DATE_TIME_STAMP,
-      'dayTimeDuration' => :DAY_TIME_DURATION,
-      'decimal' => :DECIMAL,
-      'double' => :DOUBLE,
-      'duration' => :DURATION,
-      'ENTITY' => :ENTITY,
-      'float' => :FLOAT,
-      'gDay' => :G_DAY,
-      'gMonth' => :G_MONTH,
-      'gMonthDay' => :G_MONTH_DAY,
-      'gYear' => :G_YEAR,
-      'gYearMonth' => :G_YEAR_MONTH,
-      'hexBinary' => :HEX_BINARY,
-      'ID' => :ID,
-      'IDREF' => :IDREF,
-      'int' => :INT,
-      'integer' => :INTEGER,
-      'language' => :LANGUAGE,
-      'long' => :LONG,
-      'Name' => :NAME,
-      'NCName' => :NCNAME,
-      'negativeInteger' => :NEGATIVE_INTEGER,
-      'NMTOKEN' => :NMTOKEN,
-      'nonNegativeInteger' => :NON_NEGATIVE_INTEGER,
-      'nonPositiveInteger' => :NON_POSITIVE_INTEGER,
-      'normalizedString' => :NORMALIZED_STRING,
-      'NOTATION' => :NOTATION,
-      'numeric' => :NUMERIC,
-      'positiveInteger' => :POSITIVE_INTEGER,
-      'QName' => :QNAME,
-      'short' => :SHORT,
-      'string' => :STRING,
-      'time' => :TIME,
-      'token' => :TOKEN,
-      'unsignedByte' => :UNSIGNED_BYTE,
-      'unsignedInt' => :UNSIGNED_INT,
-      'unsignedLong' => :UNSIGNED_LONG,
-      'unsignedShort' => :UNSIGNED_SHORT,
-      'untypedAtomic' => :UNTYPED_ATOMIC,
-      'yearMonthDuration' => :YEAR_MONTH_DURATION
-    }.map { |local_name, constant|
-      qname = Saxon::QName.create({
-        prefix: 'xs', uri: 'http://www.w3.org/2001/XMLSchema',
-        local_name: local_name
-      })
-      [qname, constant]
-    }].freeze
+    QNAME_MAPPING = LazyReadOnlyHash.new do
+      {
+        'anyAtomicType' => :ANY_ATOMIC_VALUE,
+        'anyURI' => :ANY_URI,
+        'base64Binary' => :BASE64_BINARY,
+        'boolean' => :BOOLEAN,
+        'byte' => :BYTE,
+        'date' => :DATE,
+        'dateTime' => :DATE_TIME,
+        'dateTimeStamp' => :DATE_TIME_STAMP,
+        'dayTimeDuration' => :DAY_TIME_DURATION,
+        'decimal' => :DECIMAL,
+        'double' => :DOUBLE,
+        'duration' => :DURATION,
+        'ENTITY' => :ENTITY,
+        'float' => :FLOAT,
+        'gDay' => :G_DAY,
+        'gMonth' => :G_MONTH,
+        'gMonthDay' => :G_MONTH_DAY,
+        'gYear' => :G_YEAR,
+        'gYearMonth' => :G_YEAR_MONTH,
+        'hexBinary' => :HEX_BINARY,
+        'ID' => :ID,
+        'IDREF' => :IDREF,
+        'int' => :INT,
+        'integer' => :INTEGER,
+        'language' => :LANGUAGE,
+        'long' => :LONG,
+        'Name' => :NAME,
+        'NCName' => :NCNAME,
+        'negativeInteger' => :NEGATIVE_INTEGER,
+        'NMTOKEN' => :NMTOKEN,
+        'nonNegativeInteger' => :NON_NEGATIVE_INTEGER,
+        'nonPositiveInteger' => :NON_POSITIVE_INTEGER,
+        'normalizedString' => :NORMALIZED_STRING,
+        'NOTATION' => :NOTATION,
+        'numeric' => :NUMERIC,
+        'positiveInteger' => :POSITIVE_INTEGER,
+        'QName' => :QNAME,
+        'short' => :SHORT,
+        'string' => :STRING,
+        'time' => :TIME,
+        'token' => :TOKEN,
+        'unsignedByte' => :UNSIGNED_BYTE,
+        'unsignedInt' => :UNSIGNED_INT,
+        'unsignedLong' => :UNSIGNED_LONG,
+        'unsignedShort' => :UNSIGNED_SHORT,
+        'untypedAtomic' => :UNTYPED_ATOMIC,
+        'yearMonthDuration' => :YEAR_MONTH_DURATION
+      }.map { |local_name, constant|
+        qname = Saxon::QName.create({
+          prefix: 'xs', uri: 'http://www.w3.org/2001/XMLSchema',
+          local_name: local_name
+        })
+        [qname, constant]
+      }.to_h.freeze
+    end
 
     # A mapping of type names/QNames to XDM type constants
-    STR_MAPPING = {
-      'array(*)' => :ANY_ARRAY,
-      'item()' => :ANY_ITEM,
-      'map(*)' => :ANY_MAP,
-      'node()' => :ANY_NODE
-    }.merge(
-      Hash[QNAME_MAPPING.map { |qname, v| [qname.to_s, v] }]
-    ).freeze
-
-    ATOMIC_VALUE_LEXICAL_STRING_CONVERTORS = Hash[
+    STR_MAPPING = LazyReadOnlyHash.new do
+      {
+        'array(*)' => :ANY_ARRAY,
+        'item()' => :ANY_ITEM,
+        'map(*)' => :ANY_MAP,
+        'node()' => :ANY_NODE
+      }.merge(
+        Hash[QNAME_MAPPING.map { |qname, v| [qname.to_s, v] }]
+      ).freeze
+    end
+
+    # convertors to generate lexical strings for a given {ItemType}, as a hash keyed on the ItemType
+    ATOMIC_VALUE_LEXICAL_STRING_CONVERTORS = LazyReadOnlyHash.new do
       LexicalStringConversion::Convertors.constants.map { |const|
         [S9API::ItemType.const_get(const), LexicalStringConversion::Convertors.const_get(const)]
-      }
-    ].freeze
+      }.to_h.freeze
+    end
 
-    ATOMIC_VALUE_TO_RUBY_CONVERTORS = Hash[
+    # convertors from {XDM::AtomicValue} to a ruby primitve value, as a hash keyed on the ItemType
+    ATOMIC_VALUE_TO_RUBY_CONVERTORS = LazyReadOnlyHash.new do
       ValueToRuby::Convertors.constants.map { |const|
         [S9API::ItemType.const_get(const), ValueToRuby::Convertors.const_get(const)]
-      }
-    ].freeze
+      }.to_h.freeze
+    end
 
     class << self
       # Get an appropriate {ItemType} for a Ruby type or given a type name as a
@@ -155,6 +190,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 +218,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 +288,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,24 +200,31 @@ 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
+        # The time part of the XSD Duration format allows T0H1M1S, T1H1M, T1M1S, T1H1S, T1H, T1M, T1S
         TIME_DURATION = /(?:T
           (?:
-            # The time part of the format allows T0H1M1S, T1H1M, T1M1S, T1H1S, T1H, T1M, T1S
             [0-9]+[HM]|
             [0-9]+(?:\.[0-9]+)?S|
             [0-9]+H[0-9]+M|
@@ -123,43 +233,78 @@ module Saxon
             [0-9]+H[0-9]+M[0-9]+(?:\.[0-9]+)?S
           )
         )?/x
+        # XSD Date
         DATE = /-?[0-9]{4}-[0-9]{2}-[0-9]{2}/
+        # XSD DateTime Time
         TIME = /[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\.[0-9]+)?/
+        # XSD DateTime Timezone
         TIME_ZONE = /(?:[\-+][0-9]{2}:[0-9]{2}|Z)?/
+        # Valid first characers in an NCName
         NCNAME_START_CHAR = '[A-Z]|_|[a-z]|[\u{C0}-\u{D6}]|[\u{D8}-\u{F6}]|[\u{F8}-\u{2FF}]|[\u{370}-\u{37D}]|[\u{37F}-\u{1FFF}]|[\u{200C}-\u{200D}]|[\u{2070}-\u{218F}]|[\u{2C00}-\u{2FEF}]|[\u{3001}-\u{D7FF}]|[\u{F900}-\u{FDCF}]|[\u{FDF0}-\u{FFFD}]|[\u{10000}-\u{EFFFF}]'
+        # Valid first characters in an XML Name
         NAME_START_CHAR = ":|" + NCNAME_START_CHAR
+        # Valid characters within an NCName
         NCNAME_CHAR = NCNAME_START_CHAR + '|-|\.|[0-9]|\u{B7}|[\u{0300}-\u{036F}]|[\u{203F}-\u{2040}]'
+        # Valid characters within an XML Name
         NAME_CHAR = ":|" + NCNAME_CHAR
       end
 
+      # A collection of lexical space patterns for XDM types
       module Patterns
+        # Construct a Regexp from an array of patterns
+        # @param patterns [Array<String>]
+        # @return [Regexp]
         def self.build(*patterns)
           Regexp.new((['\A'] + patterns.map(&:to_s) + ['\z']).join(''))
         end
+        # @see https://www.w3.org/TR/xmlschema-2/#date-lexical-representation
         DATE = build(PatternFragments::DATE, PatternFragments::TIME_ZONE)
+        # @see https://www.w3.org/TR/xmlschema-2/#dateTime-lexical-representation
         DATE_TIME = build(PatternFragments::DATE, 'T', PatternFragments::TIME, PatternFragments::TIME_ZONE)
+        # @see https://www.w3.org/TR/xmlschema-2/#time-lexical-repr
         TIME = build(PatternFragments::TIME, PatternFragments::TIME_ZONE)
+        # @see https://www.w3.org/TR/xmlschema-2/#duration-lexical-repr
         DURATION = build(/-?P(?!\z)(?:[0-9]+Y)?(?:[0-9]+M)?(?:[0-9]+D)?/, PatternFragments::TIME_DURATION)
+        # @see https://www.w3.org/TR/xmlschema-2/#duration-lexical-repr
         DAY_TIME_DURATION = build(/-?P(?!\z)(?:[0-9]+D)?/, PatternFragments::TIME_DURATION)
+        # @see https://www.w3.org/TR/xmlschema-2/#duration-lexical-repr
         YEAR_MONTH_DURATION = /\A-?P(?!\z)(?:[0-9]+Y)?(?:[0-9]+M)?\z/
+        # @see https://www.w3.org/TR/xmlschema-2/#gDay-lexical-repr
         G_DAY = build(/---([0-9]{2})/, PatternFragments::TIME_ZONE)
+        # @see https://www.w3.org/TR/xmlschema-2/#gMonth-lexical-repr
         G_MONTH = build(/--([0-9]{2})/, PatternFragments::TIME_ZONE)
+        # @see https://www.w3.org/TR/xmlschema-2/#gYear-lexical-repr
         G_YEAR = build(/(-?[0-9]{4,})/, PatternFragments::TIME_ZONE)
+        # @see https://www.w3.org/TR/xmlschema-2/#gYearMonth-lexical-repr
         G_YEAR_MONTH = build(/-?([0-9]{4,})-([0-9]{2})/, PatternFragments::TIME_ZONE)
+        # @see https://www.w3.org/TR/xmlschema-2/#gMonthDay-lexical-repr
         G_MONTH_DAY = build(/--([0-9]{2})-([0-9]{2})/, PatternFragments::TIME_ZONE)
+        # @see https://www.w3.org/TR/xmlschema-2/#integer-lexical-representation
         INTEGER = /\A[+-]?[0-9]+\z/
+        # @see https://www.w3.org/TR/xmlschema-2/#decimal-lexical-representation
         DECIMAL = /\A[+-]?[0-9]+(?:\.[0-9]+)?\z/
+        # @see https://www.w3.org/TR/xmlschema-2/#float-lexical-representation
         FLOAT = /\A(?:[+-]?[0-9]+(?:\.[0-9]+)?(?:[eE][0-9]+)?|-?INF|NaN)\z/
+        # @see https://www.w3.org/TR/xmlschema-2/#NCName
         NCNAME = build("(?:#{PatternFragments::NCNAME_START_CHAR})", "(?:#{PatternFragments::NCNAME_CHAR})*")
+        # @see https://www.w3.org/TR/xmlschema-2/#Name
         NAME = build("(?:#{PatternFragments::NAME_START_CHAR})", "(?:#{PatternFragments::NAME_CHAR})*")
+        # @see https://www.w3.org/TR/xmlschema-2/#token
         TOKEN = /\A[^\u0020\u000A\u000D\u0009]+(?: [^\u0020\u000A\u000D\u0009]+)*\z/
+        # @see https://www.w3.org/TR/xmlschema-2/#normalizedString
         NORMALIZED_STRING = /\A[^\u000A\u000D\u0009]+\z/
+        # @see https://www.w3.org/TR/xmlschema-2/#NMTOKEN
         NMTOKEN = build("(?:#{PatternFragments::NAME_CHAR})+")
+        # @see https://www.w3.org/TR/xmlschema-2/#language
         LANGUAGE = /\A[a-zA-Z]{1,8}(-[a-zA-Z0-9]{1,8})*\z/
+        # @see https://www.w3.org/TR/xmlschema-2/#base64Binary
         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
+        # @see https://www.w3.org/TR/xmlschema-2/#anyURI
         ANY_URI = ->(value, item_type) {
           uri_classes = [URI::Generic]
           case value
@@ -173,17 +318,17 @@ module Saxon
             end
           end
         }
+        # @see https://www.w3.org/TR/xmlschema-2/#base64Binary
         BASE64_BINARY = ->(value, item_type) {
           Base64.strict_encode64(value.to_s.force_encoding(Encoding::ASCII_8BIT))
         }
+        # @see https://www.w3.org/TR/xmlschema-2/#boolean
         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
-        }
+        # @see https://www.w3.org/TR/xmlschema-2/#byte
+        BYTE = ByteConversion.new
+        # @see https://www.w3.org/TR/xmlschema-2/#date
         DATE = ->(value, item_type) {
           if value.respond_to?(:strftime)
             value.strftime('%F')
@@ -191,6 +336,7 @@ module Saxon
             LexicalStringConversion.validate(value, item_type, Patterns::DATE)
           end
         }
+        # @see https://www.w3.org/TR/xmlschema-2/#dateTime
         DATE_TIME = ->(value, item_type) {
           if value.respond_to?(:strftime)
             value.strftime('%FT%T%:z')
@@ -198,25 +344,15 @@ module Saxon
             LexicalStringConversion.validate(value, item_type, Patterns::DATE_TIME)
           end
         }
+        # @see https://www.w3.org/TR/xmlschema-2/#time
         TIME = ->(value, item_type) {
           LexicalStringConversion.validate(value, item_type, Patterns::TIME)
         }
+        # @see https://www.w3.org/TR/xmlschema-2/#dateTime
         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
-        }
+        # @see https://www.w3.org/TR/xmlschema-2/#duration
+        DAY_TIME_DURATION = DurationConversion.new(Patterns::DAY_TIME_DURATION)
+        # @see https://www.w3.org/TR/xmlschema-2/#decimal
         DECIMAL = ->(value, item_type) {
           case value
           when ::Integer
@@ -229,33 +365,25 @@ module Saxon
             LexicalStringConversion.validate(value, item_type, Patterns::DECIMAL)
           end
         }
+        # @see https://www.w3.org/TR/xmlschema-2/#double
         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
-        }
+        # @see https://www.w3.org/TR/xmlschema-2/#duration
+        DURATION = DurationConversion.new(Patterns::DURATION)
+        # @see https://www.w3.org/TR/xmlschema-2/#float
         FLOAT = FloatConversion.new
+        # @see https://www.w3.org/TR/xmlschema-2/#gDay
         G_DAY = GDateConversion.new({
           bounds: 1..31,
           validation_pattern: Patterns::G_DAY,
           integer_formatter: ->(value) { '---%02d' }
         })
+        # @see https://www.w3.org/TR/xmlschema-2/#gMonth
         G_MONTH = GDateConversion.new({
           bounds: 1..12,
           validation_pattern: Patterns::G_MONTH,
           integer_formatter: ->(value) { '--%02d' }
         })
+        # @see https://www.w3.org/TR/xmlschema-2/#gMonthDay
         G_MONTH_DAY = ->(value, item_type) {
           month_days = {
              1 => 31,
@@ -278,6 +406,7 @@ module Saxon
           raise Errors::RubyValueOutOfBounds.new(value, item_type) if day > month_days[month]
           formatted_value
         }
+        # @see https://www.w3.org/TR/xmlschema-2/#gYear
         G_YEAR = GDateConversion.new({
           bounds: ->(value) { value != 0 },
           validation_pattern: Patterns::G_YEAR,
@@ -285,6 +414,7 @@ module Saxon
             value.negative? ? '%05d' : '%04d'
           }
         })
+        # @see https://www.w3.org/TR/xmlschema-2/#gYearMonth
         G_YEAR_MONTH = ->(value, item_type) {
           formatted_value = LexicalStringConversion.validate(value, item_type, Patterns::G_YEAR_MONTH)
           year, month = Patterns::G_YEAR_MONTH.match(formatted_value).captures.take(2).map { |i|
@@ -295,52 +425,74 @@ module Saxon
           end
           value
         }
+        # @see https://www.w3.org/TR/xmlschema-2/#hexBinary
         HEX_BINARY = ->(value, item_type) {
           value.to_s.force_encoding(Encoding::ASCII_8BIT).each_byte.map { |b| b.to_s(16) }.join
         }
+        # @see https://www.w3.org/TR/xmlschema-2/#int
         INT = IntegerConversion.new(-2147483648, 2147483647)
+        # @see https://www.w3.org/TR/xmlschema-2/#integer
         INTEGER = IntegerConversion.new(nil, nil)
+        # @see https://www.w3.org/TR/xmlschema-2/#language
         LANGUAGE = ->(value, item_type) {
           LexicalStringConversion.validate(value, item_type, Patterns::LANGUAGE)
         }
+        # @see https://www.w3.org/TR/xmlschema-2/#long
         LONG = IntegerConversion.new(-9223372036854775808, 9223372036854775807)
+        # @see https://www.w3.org/TR/xmlschema-2/#Name
         NAME = ->(value, item_type) {
           LexicalStringConversion.validate(value, item_type, Patterns::NAME)
         }
+        # @see https://www.w3.org/TR/xmlschema-2/#ID
+        # @see https://www.w3.org/TR/xmlschema-2/#IDREF
+        # @see https://www.w3.org/TR/xmlschema-2/#ENTITY
+        # @see https://www.w3.org/TR/xmlschema-2/#NCName
         ID = IDREF = ENTITY = NCNAME = ->(value, item_type) {
           LexicalStringConversion.validate(value, item_type, Patterns::NCNAME)
         }
+        # @see https://www.w3.org/TR/xmlschema-2/#negativeInteger
         NEGATIVE_INTEGER = IntegerConversion.new(nil, -1)
+        # @see https://www.w3.org/TR/xmlschema-2/#NMTOKEN
         NMTOKEN = ->(value, item_type) {
           LexicalStringConversion.validate(value, item_type, Patterns::NMTOKEN)
         }
+        # @see https://www.w3.org/TR/xmlschema-2/#nonNegativeInteger
         NON_NEGATIVE_INTEGER = IntegerConversion.new(0, nil)
+        # @see https://www.w3.org/TR/xmlschema-2/#nonPositiveInteger
         NON_POSITIVE_INTEGER = IntegerConversion.new(nil, 0)
+        # @see https://www.w3.org/TR/xmlschema-2/#normalizedString
         NORMALIZED_STRING = ->(value, item_type) {
           LexicalStringConversion.validate(value, item_type, Patterns::NORMALIZED_STRING)
         }
+        # @see https://www.w3.org/TR/xmlschema-2/#positiveInteger
         POSITIVE_INTEGER = IntegerConversion.new(1, nil)
+        # @see https://www.w3.org/TR/xmlschema-2/#short
         SHORT = IntegerConversion.new(-32768, 32767)
         # STRING (It's questionable whether anything needs doing here)
+        # @see https://www.w3.org/TR/xmlschema-2/#token
         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
-        }
+        # @see https://www.w3.org/TR/xmlschema-2/#unsignedByte
+        UNSIGNED_BYTE = ByteConversion.new(:unsigned)
+        # @see https://www.w3.org/TR/xmlschema-2/#unsignedInt
         UNSIGNED_INT = IntegerConversion.new(0, 4294967295)
+        # @see https://www.w3.org/TR/xmlschema-2/#unsignedLong
         UNSIGNED_LONG = IntegerConversion.new(0, 18446744073709551615)
+        # @see https://www.w3.org/TR/xmlschema-2/#unsignedShort
         UNSIGNED_SHORT = IntegerConversion.new(0, 65535)
+        # @see https://www.w3.org/TR/xmlschema-2/#duration
         YEAR_MONTH_DURATION = ->(value, item_type) {
           LexicalStringConversion.validate(value, item_type, Patterns::YEAR_MONTH_DURATION)
         }
+        # @see https://www.w3.org/TR/xmlschema-2/#QName
+        # @see https://www.w3.org/TR/xmlschema-2/#NOTATION
         QNAME = NOTATION = ->(value, item_type) {
           raise Errors::UnconvertableNamespaceSensitveItemType
         }
       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
@@ -352,6 +504,8 @@ module Saxon
             @value, @item_type = value, item_type
           end
 
+          # error message includes Ruby value and the XDM type conversion was
+          # being attempted to
           def to_s
             "Ruby value #{value.inspect} cannot be converted to an XDM #{item_type.type_name.to_s}"
           end
@@ -368,6 +522,7 @@ module Saxon
             @value, @item_type = value, item_type
           end
 
+          # error message includes Ruby value and the XDM type whose bounds it is outside of
           def to_s
             "Ruby value #{value.inspect} is outside the allowed bounds of an XDM #{item_type.type_name.to_s}"
           end