saxon-rb 0.6.0-java → 0.8.0-java

data/.rspec-jar-loading

@@ -0,0 +1,2 @@
+--format progress
+--color

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/Rakefile

@@ -25,7 +25,7 @@ task :circleci do
       end
     end
     def jruby_image_tags
-      %w{9.2.9.0 9.1.17.0 9.2.10.0-SNAPSHOT-latest}
+      %w{9.2.9.0 9.1.17.0 9.2.10.0 9.2.11.1 9.2.12.0 9.2.13.0-SNAPSHOT-latest}
     end
 
     def jdk_image_tags
@@ -51,7 +51,7 @@ task :circleci do
 
     def codeclimate_jobs
       (alt_saxon_urls.keys << nil).map { |alt_saxon_url|
-        ["9.2.9.0", "8-jdk-slim", alt_saxon_url]
+        ["9.2.12.0", "8-jdk-slim", alt_saxon_url]
       }
     end
 
@@ -190,12 +190,18 @@ task :circleci do
     def run_tests_step(opts)
       command = [
         "mkdir -p /tmp/test-results",
-        "bundle exec rspec spec --profile 10 --format RspecJunitFormatter --out /tmp/test-results/rspec.xml --format progress"
+        "VERIFY_SAXON_LAZY_LOADING=1 bundle exec rspec spec/jar_loading_spec.rb --options .rspec-jar-loading --profile 10 --format RspecJunitFormatter --out /tmp/test-results/rspec-jar-loading.xml"
       ]
       if opts.fetch(:run_codeclimate)
         command.prepend("./cc-test-reporter before-build")
-        command.append("if [ $? -eq 0 ]; then ./cc-test-reporter format-coverage -t simplecov -o \"cc-coverage#{"-alt-saxon" if opts.fetch(:alt_saxon_url)}.json\"; fi")
+        command.append("if [ $? -eq 0 ]; then ./cc-test-reporter format-coverage -t simplecov -o \"cc-coverage-jar-loading#{"-alt-saxon" if opts.fetch(:alt_saxon_url)}.json\"; fi")
       end
+      command.append("rm -rf coverage")
+      command.append("bundle exec rspec spec --profile 10 --format RspecJunitFormatter --out /tmp/test-results/rspec.xml --format progress")
+      if opts.fetch(:run_codeclimate)
+        command.append("if [ $? -eq 0 ]; then ./cc-test-reporter format-coverage -t simplecov -o \"cc-coverage-main#{"-alt-saxon" if opts.fetch(:alt_saxon_url)}.json\"; fi")
+      end
+
       {
         "run" => {
           "name" => "Run the tests" + (opts.fetch(:run_codeclimate) ? ", and upload coverage data to Code Climate" : ""),

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

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

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