saxon-rb 0.6.0-java → 0.7.0-java

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2e9afbc5a2644034bc285b3c3cd4e78f852b715d7a096ff8f7a6386730501598
-  data.tar.gz: fe9c135af6356690fcca7b4f1dc2d9656cce44018806c3b5f6c9f4b6407c576d
+  metadata.gz: 11d57a8924dff1a6f260b5496fcbc0c693d3bc4818b782acf0329950952ad1c6
+  data.tar.gz: 67353b0bd7ffc1a2d350019ee20c41713d69e1f5a5bbfa4c42a0d420456401c1
 SHA512:
-  metadata.gz: c59e0f986b8bbf4de77b18feba99a61c8e724df537679b0e674bc142a0d2b476026bb01579dcd2ec6e9b4f246493db3b892fbe7e997848eb06bf5c7bd8e2f5ea
-  data.tar.gz: 182d383aced898a376d37eaedb60ff80461910d3451e119f2bf6e97ebe37d8c64e600563ba968efec22f49ae02f025ec3725f00a2cb9af10813af8e20fc13100
+  metadata.gz: 26f99187a484b68f55bb9fd7e0e49cbd4dd87bf2d1b366ed178140c24965a9ef9d61185e26f904b5f4aaea2cf9722bd3a842995e32fda036c9b17e38c55d5cac
+  data.tar.gz: 837e3e4f0e4bbdd70f88ed21c595ea4b5416a615362ad663f84a4b23956349bbce813528b20e783f5b2664560337be30b964bceb756e1c5554656939dd71ecbf

data/.ruby-version

@@ -1 +1 @@
-jruby-9.2.6.0
+jruby-9.2.9.0

data/.yardopts

@@ -0,0 +1 @@
+-e docs/templates/plugin.rb

data/README.md

@@ -78,7 +78,7 @@ result_2 = transformer.call_template('main-template')
 processor = Saxon::Processor.create
 xpath = processor.xpath_compiler.compile('//element[@attr = $a:var]')
 
-matches = xpath.run(document_node)
+matches = xpath.evaluate(document_node)
 ```
 
 ## Migrating from `saxon-xslt` (or Nokogiri)

data/docs/templates/plugin.rb

@@ -0,0 +1,73 @@
+include YARD
+include Templates
+
+module JavadocHtmlHelper
+  JAVA_TYPE_MATCHER = /\A(?:[a-z_$](?:[a-z0-9_$]*)\.)+[A-Z][A-Za-z_$]*/
+  RUBY_COLLECTION_TYPE_MATCHER = /\A(?:[A-Z][A-Za-z0-9_])(?:::[A-Z][A-Za-z0-9_]*)*</
+  SAXON_TYPE_MATCHER = /\A(?:net\.sf\.saxon|com\.saxonica)/
+
+  def format_types(typelist, brackets = true)
+    return unless typelist.is_a?(Array)
+    list = typelist.map { |type|
+      case type
+      when JAVA_TYPE_MATCHER
+        format_java_type(type)
+      else
+        super([type], false)
+      end
+    }
+    list.empty? ? "" : (brackets ? "(#{list.join(", ")})" : list.join(", "))
+  end
+
+  def format_java_type(type)
+    "<tt>" + linkify_saxon_type(type) + "</tt>"
+  end
+
+  def linkify_saxon_type(type)
+    case type
+    when SAXON_TYPE_MATCHER
+      link = url_for_java_object(type)
+    else
+      link = nil
+    end
+    link ? link_url(link, type, :title => h(type)) : type
+  end
+
+  def linkify(*args)
+    if args.first.is_a?(String)
+      case args.first
+      when JAVA_TYPE_MATCHER
+        link = url_for_java_object(args.first)
+        title = args.first
+        link ? link_url(link, title, :title => h(title)) : title
+      else
+        super
+      end
+    else
+      super
+    end
+  end
+
+  def url_for(obj, anchor = nil, relative = true)
+    case obj
+    when JAVA_TYPE_MATCHER
+      url_for_java_object(obj, anchor, relative)
+    else
+      super
+    end
+  end
+
+  def url_for_java_object(obj, anchor = nil, relative = nil)
+    case obj
+    when SAXON_TYPE_MATCHER
+      package, _, klass = obj.rpartition(".")
+      "http://saxonica.com/documentation/index.html#!javadoc/#{package}/#{klass}"
+    else
+      path = obj.split(".").join("/")
+      "https://docs.oracle.com/javase/8/docs/api/index.html?#{path}.html"
+    end
+  end
+end
+
+Template.extra_includes << proc { |opts| JavadocHtmlHelper if opts.format == :html }
+# Engine.register_template_path(File.dirname(__FILE__))

data/lib/saxon/configuration.rb

@@ -2,12 +2,13 @@ require 'saxon/s9api'
 require 'saxon/parse_options'
 
 module Saxon
-  # Wraps the <tt>net.saxon.Configuration</tt> class. See
-  # http://saxonica.com/documentation9.5/javadoc/net/sf/saxon/Configuration.html
-  # for details of what configuration options are available and what values
-  # they accept. See
-  # http://saxonica.com/documentation9.5/javadoc/net/sf/saxon/lib/FeatureKeys.html
-  # for details of the constant names used to access the values
+  # Wraps the <tt>net.sf.saxon.Configuration</tt> class.
+  #
+  # See {net.sf.saxon.Configuration} for details of what configuration options
+  # are available and what values they accept.
+  #
+  # See {net.sf.saxon.lib.FeatureKeys} for details of the constant names used to
+  # access the values
   class Configuration
     DEFAULT_SEMAPHORE = Mutex.new
     private_constant :DEFAULT_SEMAPHORE
@@ -60,22 +61,23 @@ module Saxon
     end
 
     # Get a configuration option value
-    # See https://www.saxonica.com/html/documentation/javadoc/net/sf/saxon/lib/FeatureKeys.html
-    # for details of the available options. Use the constant name as a string
-    # or symbol as the option
+    #
+    # See {net.sf.saxon.lib.FeatureKeys} for details of the available options.
+    # Use the constant name as a string or symbol as the option, e.g.
+    # +:allow_multhreading+, +'ALLOW_MULTITHREADING'+, +'allow_multithreading'+.
     #
     # @param option [String, Symbol]
     # @return [Object] the value of the configuration option
     # @raise [NameError] if the option name does not exist
+    # @see net.sf.saxon.lib.FeatureKeys
     def [](option)
       @config.getConfigurationProperty(option_url(option))
     end
 
-    # Get a configuration option value
-    # See http://saxonica.com/documentation9.5/javadoc/net/sf/saxon/lib/FeatureKeys.html
-    # for details of the available options. Use the constant name as a string
-    # or symbol as the option
+    # Set a configuration option value. See {#[]} for details about the option
+    # names.
     #
+    # @see #[]
     # @param option [String, Symbol]
     # @param value [Object] the value of the configuration option
     # @return [Object] the value you passed in

data/lib/saxon/document_builder.rb

@@ -4,11 +4,217 @@ module Saxon
   # Builds XDM objects from XML sources, for use in XSLT or for query and
   # access
   class DocumentBuilder
+    # Provides a simple configuraion DSL for DocumentBuilders.
+    # @see DocumentBuilder.create
+    class ConfigurationDSL
+      # @api private
+      #
+      # Create a new instance and +instance_exec+ the passed-in block against it
+      def self.define(document_builder, block)
+        new(document_builder).instance_exec(&block)
+      end
+
+      # @api private
+      def initialize(document_builder)
+        @document_builder = document_builder
+      end
+
+      # Sets line numbering on or off
+      #
+      # @see DocumentBuilder#line_numbering=
+      #
+      # @param value [Boolean] on (true) or off (false)
+      def line_numbering(value)
+        @document_builder.line_numbering = value
+      end
+
+      # Sets the base URI of documents created using this instance.
+      #
+      # @see DocumentBuilder.base_uri=
+      #
+      # @param value [String, URI::File, URI::HTTP] The (absolute) base URI to use
+      def base_uri(value)
+        @document_builder.base_uri = value
+      end
+
+      # Sets the base URI of documents created using this instance.
+      #
+      # @see DocumentBuilder.base_uri=
+      #
+      # @param value [String, URI::File, URI::HTTP] The (absolute) base URI to use
+      def whitespace_stripping_policy(value)
+        @document_builder.whitespace_stripping_policy = value
+      end
+
+      # Sets the base URI of documents created using this instance.
+      #
+      # @see DocumentBuilder.base_uri=
+      #
+      # @param value [String, URI::File, URI::HTTP] The (absolute) base URI to use
+      def dtd_validation(value)
+        @document_builder.dtd_validation = value
+      end
+    end
+
+
+    # Create a new DocumentBuilder that can be used to build new XML documents
+    # with the passed-in {Saxon::Processor}. If a block is passed in it's
+    # executed as a DSL for configuring the builder instance.
+    #
+    # @param processor [Saxon::Processor] the Processor
+    # @yield An DocumentBuilder configuration DSL block
+    # @return [Saxon::DocumentBuilder] the new instance
+    def self.create(processor, &block)
+      new(processor.to_java.newDocumentBuilder, &block)
+    end
+
+    attr_reader :s9_document_builder
+    private :s9_document_builder
+
     # @api private
     # @param [net.sf.saxon.s9api.DocumentBuilder] s9_document_builder The
-    # Saxon DocumentBuilder instance to wrap
-    def initialize(s9_document_builder)
+    #   Saxon DocumentBuilder instance to wrap
+    def initialize(s9_document_builder, &block)
       @s9_document_builder = s9_document_builder
+      if block_given?
+        ConfigurationDSL.define(self, block)
+      end
+    end
+
+    # Report whether documents created using this instance will keep track of
+    # the line and column numbers of elements.
+    #
+    # @return [Boolean] whether line numbering will be tracked
+    def line_numbering?
+      s9_document_builder.isLineNumbering
+    end
+
+
+    # Switch tracking of line and column numbers for elements in documents
+    # created by this instance on or off
+    #
+    # @see https://www.saxonica.com/documentation9.9/index.html#!javadoc/net.sf.saxon.s9api/DocumentBuilder@setLineNumbering
+    #
+    # @param on_or_not [Boolean] whether or not to track line numbering
+    def line_numbering=(on_or_not)
+      s9_document_builder.setLineNumbering(on_or_not)
+    end
+
+    # Return the default base URI to be used when building documents using this
+    # instance. This value will be ignored if the source being parsed has an
+    # intrinsic base URI (e.g. a File).
+    #
+    # Returns +nil+ if no URI is set (the default).
+    #
+    # @return [nil, URI::File, URI::HTTP] the default base URI (or nil)
+    def base_uri
+      uri = s9_document_builder.getBaseURI
+      uri.nil? ? uri : URI(uri.to_s)
+    end
+
+    # Set the base URI of documents created using this instance. This value will
+    # be ignored if the source being parsed has an intrinsic base URI (e.g. a
+    # File)
+    #
+    # @see https://www.saxonica.com/documentation9.9/index.html#!javadoc/net.sf.saxon.s9api/DocumentBuilder@setBaseURI
+    #
+    # @param uri [String, URI::File, URI::HTTP] The (absolute) base URI to use
+    def base_uri=(uri)
+      s9_document_builder.setBaseURI(java.net.URI.new(uri.to_s))
+    end
+
+    # Return the Whitespace stripping policy for this instance. Returns one of
+    # the standard policy names as a symbol, or the custom Java
+    # WhitespaceStrippingPolicy if one was defined using
+    # +#whitespace_stripping_policy = ->(qname) { ... }+. (See
+    # {#whitespace_stripping_policy=} for more.)
+    #
+    # +:all+: All whitespace-only nodes will be discarded
+    #
+    # +:none+: No whitespace-only nodes will be discarded (the default if DTD or
+    # schema validation is not in effect)
+    #
+    # +:ignorable+: Whitespace-only nodes inside elements defined as
+    # element-only in the DTD or schema being used will be discarded (the
+    # default if DTD or schema validation is in effect)
+    #
+    # +:unspecified+: the default, which in practice means :ignorable if DTD or
+    # schema validation is in effect, and :none otherwise.
+    #
+    # @return [:all, :none, :ignorable, :unspecified, Proc]
+    def whitespace_stripping_policy
+      s9_policy = s9_document_builder.getWhitespaceStrippingPolicy
+      case s9_policy
+      when Saxon::S9API::WhitespaceStrippingPolicy::UNSPECIFIED
+        :unspecified
+      when Saxon::S9API::WhitespaceStrippingPolicy::NONE
+        :none
+      when Saxon::S9API::WhitespaceStrippingPolicy::IGNORABLE
+        :ignorable
+      when Saxon::S9API::WhitespaceStrippingPolicy::ALL
+        :all
+      else
+        s9_policy
+      end
+    end
+
+    # Set the whitespace stripping policy to be used for documents built with
+    # this instance.
+    #
+    # Possible values are:
+    #
+    # * One of the standard policies, as a symbol (+:all+, +:none+,
+    #   +:ignorable+, +:unspecified+, see {#whitespace_stripping_policy}).
+    # * A Java +net.sf.saxon.s9api.WhitesapceStrippingPolicy+ instance
+    # * A Proc/lambda that is handed an element name as a {Saxon::QName}, and
+    #   should return true (if whitespace should be stripped for this element)
+    #   or false (it should not).
+    # @example
+    #   whitespace_stripping_policy = ->(element_qname) {
+    #     element_qname == Saxon::QName.clark("{http://example.org/}element-name")
+    #   }
+    #
+    # @see https://www.saxonica.com/documentation9.9/index.html#!javadoc/net.sf.saxon.s9api/DocumentBuilder@setWhitespaceStrippingPolicy
+    # @see https://www.saxonica.com/documentation9.9/index.html#!javadoc/net.sf.saxon.s9api/WhitespaceStrippingPolicy
+    # @param policy [Symbol, Proc, Saxon::S9API::WhitespaceStrippingPolicy] the
+    #   policy to use
+    def whitespace_stripping_policy=(policy)
+      case policy
+      when :unspecified, :none, :ignorable, :all
+        s9_policy = Saxon::S9API::WhitespaceStrippingPolicy.const_get(policy.to_s.upcase.to_sym)
+      when Proc
+        wrapped_policy = ->(s9_qname) {
+          policy.call(Saxon::QName.new(s9_qname))
+        }
+        s9_policy = Saxon::S9API::WhitespaceStrippingPolicy.makeCustomPolicy(wrapped_policy)
+      when Saxon::S9API::WhitespaceStrippingPolicy
+        s9_policy = policy
+      else
+        raise InvalidWhitespaceStrippingPolicyError, "#{policy.inspect} is not one of the allowed Symbols, or a custom policy"
+      end
+      s9_document_builder.setWhitespaceStrippingPolicy(s9_policy)
+    end
+
+    # @return [Boolean] whether DTD Validation is enabled
+    def dtd_validation?
+      s9_document_builder.isDTDValidation
+    end
+
+    # Switches DTD validation on or off.
+    #
+    # It's important to note that DTD validation only applies to documents that
+    # contain a +<!doctype>+, but switching DTD validation off doesn't stop the
+    # XML parser Saxon uses from trying to retrieve the DTD that's referenced,
+    # which can mean network requests. By default, the SAX parser Saxon uses
+    # (Xerces) doesn't make use of XML catalogs, which causes problems when documents reference a DTD with a relative path as in:
+    #   <!DOCTYPE root-element SYSTEM "example.dtd">
+    # This can be controlled through a configuration option, however.
+    #
+    # @see https://www.saxonica.com/documentation9.9/index.html#!javadoc/net.sf.saxon.s9api/DocumentBuilder@setDTDValidation
+    # @see https://www.saxonica.com/documentation9.9/index.html#!sourcedocs/controlling-parsing
+    # @param on [Boolean] whether DTD Validation should be enabled
+    def dtd_validation=(on)
+      s9_document_builder.setDTDValidation(on)
     end
 
     # @param [Saxon::Source] source The Saxon::Source containing the source
@@ -16,13 +222,18 @@ module Saxon
     # @return [Saxon::XDM::Node] The Saxon::XDM::Node representing the root of the
     #   document tree
     def build(source)
-      XDM::Node.new(@s9_document_builder.build(source.to_java))
+      XDM::Node.new(s9_document_builder.build(source.to_java))
     end
 
-    # @return [net.sf.saxon.s9api.DocumentBuilder] The underlying Java Saxon
+    # @return [Java::NetSfSaxonS9api::DocumentBuilder] The underlying Java Saxon
     #   DocumentBuilder instance
     def to_java
-      @s9_document_builder
+      s9_document_builder
     end
   end
+
+  # Error raised when someone tries to set an invalid whitespace stripping
+  # policy on a {DocumentBuilder}
+  class InvalidWhitespaceStrippingPolicyError < RuntimeError
+  end
 end

data/lib/saxon/feature_flags/errors.rb

@@ -0,0 +1,8 @@
+module Saxon
+  module FeatureFlags
+    # Error raised if a feature is not available under the loaded version of
+    # Saxon
+    class UnavailableInThisSaxonVersionError < StandardError
+    end
+  end
+end

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/feature_flags.rb

@@ -0,0 +1,11 @@
+require_relative 'feature_flags/version'
+require_relative 'feature_flags/helpers'
+
+module Saxon
+  # Allows saxon-rb features to be switched off if they can't be used under one
+  # of the otherwise-supported Saxon versions
+  #
+  # @api private
+  module FeatureFlags
+  end
+end

data/lib/saxon/item_type/lexical_string_conversion.rb

@@ -222,9 +222,9 @@ module Saxon
       # 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|
@@ -233,46 +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
@@ -286,13 +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'
         }
+        # @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')
@@ -300,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')
@@ -307,11 +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
+        # @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
@@ -324,19 +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)
+        # @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,
@@ -359,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,
@@ -366,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|
@@ -376,43 +425,68 @@ 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)
         }
+        # @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
         }
@@ -430,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
@@ -446,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

data/lib/saxon/item_type/value_to_ruby.rb

@@ -8,6 +8,7 @@ module Saxon
       # Regexp patterns to assist in converting XDM typed values into Ruby
       # native types
       module Patterns
+        # @see https://www.w3.org/TR/xmlschema-2/#dateTime-lexical-representation
         DATE_TIME = /\A(-?[0-9]{4,})-([0-9]{2})-([0-9]{2})T([0-9]{2}):([0-9]{2}):([0-9]{2}(?:\.[0-9]+)?)(Z|[-+][0-9]{2}:[0-9]{2})?\z/
       end
 
@@ -54,34 +55,45 @@ module Saxon
       # A collection of Lambdas (or objects responding to +#call+) for
       # converting XDM typed values to native Ruby types.
       module Convertors
+        # @see https://www.w3.org/TR/xmlschema-2/#integer
         INTEGER = INT = SHORT = LONG = UNSIGNED_INT = UNSIGNED_SHORT = UNSIGNED_LONG = \
         POSITIVE_INTEGER = NON_POSITIVE_INTEGER = NEGATIVE_INTEGER = NON_NEGATIVE_INTEGER = ->(xdm_atomic_value) {
           xdm_atomic_value.to_java.getValue
         }
+        # @see https://www.w3.org/TR/xmlschema-2/#decimal
         DECIMAL = ->(xdm_atomic_value) {
           BigDecimal(xdm_atomic_value.to_s)
         }
+        # @see https://www.w3.org/TR/xmlschema-2/#float
         FLOAT = DOUBLE = ->(xdm_atomic_value) {
           xdm_atomic_value.to_java.getValue
         }
+        # @see https://www.w3.org/TR/xmlschema-2/#dateTime
         DATE_TIME = DATE_TIME_STAMP = ValueToRuby::DateTimeConvertor
+        # @see https://www.w3.org/TR/xmlschema-2/#boolean
         BOOLEAN = ->(xdm_atomic_value) {
           xdm_atomic_value.to_java.getValue
         }
+        # @see https://www.w3.org/TR/xmlschema-2/#NOTATION
+        # @see https://www.w3.org/TR/xmlschema-2/#QName
         NOTATION = QNAME = ->(xdm_atomic_value) {
           Saxon::QName.new(xdm_atomic_value.to_java.getQNameValue)
         }
+        # @see https://www.w3.org/TR/xmlschema-2/#base64Binary
         BASE64_BINARY = ->(xdm_atomic_value) {
           Base64.decode64(xdm_atomic_value.to_s)
         }
+        # @see https://www.w3.org/TR/xmlschema-2/#hexBinary
         HEX_BINARY = ->(xdm_atomic_value) {
           bytes = []
           xdm_atomic_value.to_s.scan(/../) { |x| bytes << x.hex.chr(Encoding::ASCII_8BIT) }
           bytes.join
         }
+        # @see https://www.w3.org/TR/xmlschema-2/#byte
         BYTE = ->(xdm_atomic_value) {
           [xdm_atomic_value.to_java.getLongValue].pack('c')
         }
+        # @see https://www.w3.org/TR/xmlschema-2/#unsignedByte
         UNSIGNED_BYTE = ->(xdm_atomic_value) {
           [xdm_atomic_value.to_java.getLongValue].pack('C')
         }

data/lib/saxon/loader.rb

@@ -19,6 +19,7 @@ module Saxon
         @path = path
       end
 
+      # returns an error message including the missing path
       def to_s
         "The path ('#{@path}') you supplied for the Saxon .jar files doesn't exist, sorry"
       end
@@ -31,6 +32,7 @@ module Saxon
         @path = path
       end
 
+      # returns an error message including the path looked in and jars we were looking for
       def to_s
         "One of saxon9he.jar, saxon9pe.jar, or saxon9ee.jar must be present in the path ('#{@path}') you supplied, sorry"
       end

data/lib/saxon/processor.rb

@@ -46,12 +46,14 @@ module Saxon
       @s9_processor = s9_processor
     end
 
-    # Generate a new DocumentBuilder that uses this Processor.
-    # Sharing DocumentBuilders across threads is not recommended/
+    # Generate a new DocumentBuilder that uses this Processor. Sharing
+    # DocumentBuilders across threads is not safe.
     #
+    # @yield A DocumentBuilder configuration DSL block, see
+    #   {Saxon::DocumentBuilder.create}
     # @return [Saxon::DocumentBuilder] A new Saxon::DocumentBuilder
-    def document_builder
-      Saxon::DocumentBuilder.new(@s9_processor.newDocumentBuilder)
+    def document_builder(&block)
+      Saxon::DocumentBuilder.create(self, &block)
     end
 
     # Declare custom collations for use by XSLT, XPath, and XQuery processors

data/lib/saxon/version/library.rb

@@ -0,0 +1,89 @@
+require 'saxon/s9api'
+
+module Saxon
+  module Version
+    # The version of the underlying Saxon library, which we need to discover at
+    # runtime based on what version is on the Classpath
+    class Library
+      # The loaded version of the Saxon Java library
+      #
+      # @return [Saxon::Version::Library] the version of the loaded library
+      def self.loaded_version
+        Saxon::Loader.load!
+
+        sv = Java::net.sf.saxon.Version
+        new(sv.getProductVersion, sv.getStructuredVersionNumber, sv.softwareEdition)
+      end
+
+      include Comparable
+
+      # @return [String] the version string (e.g. '9.9.1.6', '10.0')
+      attr_reader :version
+      # @return [String] the version components (e.g. <tt>[9, 9, 1, 6]</tt>, <tt>[10, 0]</tt>)
+      attr_reader :components
+      # @return [Symbol] the edition (+:he+, +:pe+, or +:ee+)
+      attr_reader :edition
+
+      # @param version [String] the version string
+      # @param components [Array<Integer>] the version components separated
+      # @param edition [String, Symbol] the name of the Saxon edition (e.g. +:he+, +'HE'+)
+      def initialize(version, components, edition)
+        @version = version.dup.freeze
+        @components = components.dup.freeze
+        @edition = edition.downcase.to_sym
+      end
+
+      # Comparison against another instance
+      #
+      # @param other [Saxon::Version::Library] the other version to compare against
+      # @return [Integer] -1 for less, 1 for greater, 0 for equal
+      def <=>(other)
+        return false unless other.is_a?(self.class)
+
+        n_components = [self.components.length, other.components.length].max
+        (0..(n_components - 1)).reduce(0, &comparator(other))
+      end
+
+      # Pessimistic comparison à la rubygems +~>+: do I satisfy the other
+      # version if considered as a pessimistic version constraint
+      #
+      # @param pessimistic_version [Saxon::Version::Library] the version to
+      #   compare pessimistically
+      # @return [Boolean] do I satisfy the constraint?
+      def pessimistic_compare(pessimistic_version)
+        pessimistic_components = pessimistic_version.components
+        pessimistic_components = pessimistic_components + [0] if pessimistic_components.length == 1
+        locked = pessimistic_components[0..-2]
+        locked = locked.zip(components[0..locked.length])
+        variable = [pessimistic_components[-1], components[locked.length]]
+
+        locked_ok = locked.all? { |check, mine|
+          check == mine
+        }
+
+        return false unless locked_ok
+
+        check, mine = variable
+        mine >= check
+      end
+
+      # @return [String] the version string
+      def to_s
+        version
+      end
+
+      private
+
+      def comparator(other)
+        ->(cmp, i) {
+          return cmp unless cmp == 0
+
+          mine = self.components[i].nil? ? 0 : self.components[i]
+          theirs = other.components[i].nil? ? 0 : other.components[i]
+
+          mine <=> theirs
+        }
+      end
+    end
+  end
+end

data/lib/saxon/version.rb

@@ -1,3 +1,9 @@
+require 'saxon/s9api'
+
 module Saxon
-  VERSION = "0.6.0"
+  # Provides the saxon-rb and underlying Saxon library versions
+  module Version
+    # The version of the saxon-rb gem (not of Saxon itself)
+    WRAPPER = "0.7.0"
+  end
 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,7 +30,8 @@ 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

data/lib/saxon/xdm/node.rb

@@ -85,6 +85,36 @@ module Saxon
       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/xpath/compiler.rb

@@ -40,7 +40,7 @@ module Saxon
       # static context.
       #
       # @param processor [Saxon::Processor] the {Saxon::Processor} to use
-      # @yield An XPath compiler DSL block
+      # @yield An XPath::StaticContext::DSL block
       # @return [Saxon::XPath::Compiler] the new compiler instance
       def self.create(processor, &block)
         static_context = XPath::StaticContext.define(block)
@@ -79,7 +79,7 @@ module Saxon
       # 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
+      # @yield An XPath::StaticContext::DSL block
       # @return [Saxon::XPath::Compiler] the new compiler instance
       def create(&block)
         new_static_context = static_context.define(block)

data/lib/saxon/xpath/static_context.rb

@@ -117,7 +117,12 @@ module Saxon
         DSL.define(block)
       end
 
-      attr_reader :declared_variables, :declared_namespaces, :default_collation
+      # @return [String] The default collation URI as a String
+      attr_reader :default_collation
+      # @return [Hash<Saxon::QName => Saxon::XPath::VariableDeclaration] the declared variables
+      attr_reader :declared_variables
+      # @return [Hash<String => String>] the declared namespaces, as a prefix => uri hash
+      attr_reader :declared_namespaces
 
       # @return [Saxon::QName]
       # @overload resolve_variable_qname(qname)

data/lib/saxon/xslt/evaluation_context.rb

@@ -143,7 +143,17 @@ module Saxon
         DSL.define(block)
       end
 
-      attr_reader :default_collation, :static_parameters, :global_parameters, :initial_template_parameters, :initial_template_tunnel_parameters
+
+      # @return [String] The default collation URI as a String
+      attr_reader :default_collation
+      # @return [Hash<Saxon::QName => Saxon::XDM::Value>] All the static parameters
+      attr_reader :static_parameters
+      # @return [Hash<Saxon::QName => Saxon::XDM::Value>] All the global parameters
+      attr_reader :global_parameters
+      # @return [Hash<Saxon::QName => Saxon::XDM::Value>] All the initial template parameters
+      attr_reader :initial_template_parameters
+      # @return [Hash<Saxon::QName => Saxon::XDM::Value>] All the initial template parameters with tunnelling = "yes"
+      attr_reader :initial_template_tunnel_parameters
 
       # @api private
       # When passed a Proc, create a new EvaluationContext based on this one, with the same DSL available as in {.define}.

data/lib/saxon/xslt/executable.rb

@@ -4,6 +4,7 @@ require_relative 'invocation'
 require_relative '../serializer'
 require_relative '../xdm'
 require_relative '../qname'
+require_relative '../feature_flags'
 
 module Saxon
   module XSLT
@@ -53,6 +54,7 @@ module Saxon
     # prefix, you must use an explicit {Saxon::QName} to refer to it.
     class Executable
       extend Forwardable
+      extend Saxon::FeatureFlags::Helpers
 
       attr_reader :evaluation_context
       private :evaluation_context
@@ -162,6 +164,15 @@ module Saxon
         transformation(opts.reject { |k, v| k == :args }).call_function(function_name, args)
       end
 
+      # Create a {Serializer::Object} configured using the options that were set
+      # by +<xsl:output>+.
+      #
+      # @return [Saxon::Serializer::Object] the Serializer
+      def serializer
+        Saxon::Serializer::Object.new(@s9_xslt_executable.load30.newSerializer)
+      end
+      requires_saxon_version :serializer, '>= 9.9'
+
       # @return [net.sf.saxon.s9api.XsltExecutable] the underlying Saxon
       #   +XsltExecutable+
       def to_java
@@ -203,6 +214,7 @@ module Saxon
     # Represents a loaded XSLT transformation ready to be applied against a
     # context node.
     class Transformation
+      # A list of valid option names for the transform
       VALID_OPTS = [:raw, :mode, :global_context_item, :global_parameters, :initial_template_parameters, :initial_template_tunnel_parameters]
 
       attr_reader :s9_transformer, :opts
@@ -297,11 +309,11 @@ module Saxon
       end
 
       def initial_template_parameters(parameters)
-        s9_transformer.setInitialTemplateParameters(XSLT::ParameterHelper.to_java(parameters) , false)
+        s9_transformer.setInitialTemplateParameters(XSLT::ParameterHelper.to_java(parameters), false)
       end
 
       def initial_template_tunnel_parameters(parameters)
-        s9_transformer.setInitialTemplateParameters(XSLT::ParameterHelper.to_java(parameters) , true)
+        s9_transformer.setInitialTemplateParameters(XSLT::ParameterHelper.to_java(parameters), true)
       end
     end
 

data/lib/saxon/xslt/invocation.rb

@@ -10,6 +10,7 @@ module Saxon
     # IO.
     class Invocation
       attr_reader :s9_transformer, :invocation_lambda
+      private :s9_transformer, :invocation_lambda
 
       # @api private
       def initialize(s9_transformer, invocation_lambda, raw)
@@ -65,7 +66,7 @@ module Saxon
 
       # Send the result of the transformation to the supplied Destination
       #
-      # @param destination [net.sf.saxon.s9api.Destination] the Saxon
+      # @param s9_destination [net.sf.saxon.s9api.Destination] the Saxon
       #   destination to use
       # @return [nil]
       def to_destination(s9_destination)

data/saxon-rb.gemspec

@@ -5,7 +5,7 @@ require 'saxon/version'
 
 Gem::Specification.new do |spec|
   spec.name          = 'saxon-rb'
-  spec.version       = Saxon::VERSION
+  spec.version       = Saxon::Version::WRAPPER
   spec.authors       = ['Matt Patterson']
   spec.email         = ['matt@werkstatt.io']
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: saxon-rb
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: java
 authors:
 - Matt Patterson
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-02-19 00:00:00.000000000 Z
+date: 2020-05-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   requirement: !ruby/object:Gem::Requirement
@@ -164,6 +164,7 @@ files:
 - ".gitignore"
 - ".rspec"
 - ".ruby-version"
+- ".yardopts"
 - CODE_OF_CONDUCT.md
 - Gemfile
 - LICENSE.txt
@@ -171,6 +172,7 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- docs/templates/plugin.rb
 - lib/net/sf/saxon/Saxon-HE/9.9.1-6/Saxon-HE-9.9.1-6.jar
 - lib/saxon-rb.rb
 - lib/saxon-rb_jars.rb
@@ -178,6 +180,10 @@ files:
 - lib/saxon/axis_iterator.rb
 - lib/saxon/configuration.rb
 - lib/saxon/document_builder.rb
+- lib/saxon/feature_flags.rb
+- lib/saxon/feature_flags/errors.rb
+- lib/saxon/feature_flags/helpers.rb
+- lib/saxon/feature_flags/version.rb
 - lib/saxon/item_type.rb
 - lib/saxon/item_type/lexical_string_conversion.rb
 - lib/saxon/item_type/value_to_ruby.rb
@@ -196,6 +202,7 @@ files:
 - lib/saxon/serializer/output_properties.rb
 - lib/saxon/source.rb
 - lib/saxon/version.rb
+- lib/saxon/version/library.rb
 - lib/saxon/xdm.rb
 - lib/saxon/xdm/array.rb
 - lib/saxon/xdm/atomic_value.rb
@@ -238,8 +245,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements:
 - jar net.sf.saxon, Saxon-HE, 9.9.1-6
-rubyforge_project:
-rubygems_version: 2.7.10
+rubygems_version: 3.1.3
 signing_key:
 specification_version: 4
 summary: Saxon 9.9 for JRuby, with an idiomatic Ruby API