saxon-rb 0.4.0-java → 0.7.2-java

data/lib/saxon/item_type/value_to_ruby.rb

@@ -5,11 +5,19 @@ module Saxon
     # A collection of lamba-like objects for converting XDM::AtomicValues into
     # appropriate Ruby values
     module ValueToRuby
+      # 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
 
+      # Helper class that converts XDM Date/Time strings into something Ruby's {Time} class can
+      # handle
       class DateTimeConvertor
+        # Convert an XDM Date/Time value into a native Ruby {Time} object.
+        # @return [Time, String] the converted Time, or the original XDM lexical
+        #   string if conversion isn't possible
         def self.call(xdm_atomic_value)
           new(xdm_atomic_value).convert
         end
@@ -21,11 +29,15 @@ module Saxon
           @match = ValueToRuby::Patterns::DATE_TIME.match(@timestring)
         end
 
+        # Return a {Time} instance if possible, otherwise return the string value from the XDM.
+        # @return [Time, String] the converted Time, or the original string
         def convert
           return timestring if match.nil?
           Time.new(*integer_parts, decimal_part, tz_part)
         end
 
+        private
+
         def integer_parts
           match[1..5].map { |n| Integer(n, 10) }
         end
@@ -40,35 +52,48 @@ module Saxon
         end
       end
 
+      # 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

@@ -6,8 +6,11 @@ module Saxon
   module S9API
   end
 
+  # The mechanism for adding the JARs for either the bundled Saxon HE, or an
+  # external Saxon HE/PE/EE version, into the CLASSPATH and requiring them.
   module Loader
     LOAD_SEMAPHORE = Mutex.new
+    private_constant :LOAD_SEMAPHORE
 
     # Error raised if Saxon::Loader.load! is called but the path handed
     # in does not exist or is not a directory
@@ -16,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
@@ -28,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
@@ -45,7 +50,7 @@ module Saxon
         else
           if jars_not_on_classpath?
             if saxon_home.nil?
-              require 'saxon_jars'
+              require 'saxon-rb_jars'
             else
               saxon_home = Pathname.new(saxon_home)
               raise NoJarsError, saxon_home unless saxon_home.directory?

data/lib/saxon/nokogiri.rb

@@ -0,0 +1,78 @@
+require 'saxon/xslt'
+
+module Saxon
+  module XSLT
+    class Executable
+      # Provided for Nokogiri API compatibility. Cannot use many XSLT 2 and 3
+      # features as a result.
+      #
+      # Transform the input document by applying templates as in XSLT 1. All
+      # parameters will be interpreted as Strings
+      #
+      # @param doc_node [Saxon::XDM::Node] the document to transform
+      # @param params [Hash, Array] a Hash of param name => value, or an Array
+      #   of param names and values of the form +['param', 'value', 'param2',
+      #   'value']+. The array must be of an even-numbered length
+      # @return [Saxon::XDM::Value] the result document
+      def transform(doc_node, params = {})
+        apply_templates(doc_node, v1_parameters(params)).xdm_value
+      end
+
+      # Provided for Nokogiri API compatibility. Cannot use many XSLT 2 and 3
+      # features as a result.
+      #
+      # Transform the input document by applying templates as in XSLT 1, and
+      # then serializing the result to a string using the serialization options
+      # set in the XSLT stylesheet's +<xsl:output/>+.
+      #
+      # @param doc_node [Saxon::XDM::Node] the document to transform
+      # @param params [Hash, Array] a Hash of param name => value, or an Array
+      #   of param names and values of the form +['param', 'value', 'param2',
+      #   'value']+. The array must be of an even-numbered length
+      # @return [String] a serialization of the the result document
+      def apply_to(doc_node, params = {})
+        apply_templates(doc_node, v1_parameters(params)).to_s
+      end
+
+      # Provided for Nokogiri API compatibility. Cannot use many XSLT 2 and 3
+      # features as a result.
+      #
+      # Serialize the input document to a string using the serialization options
+      # set in the XSLT stylesheet's +<xsl:output/>+.
+      #
+      # @param doc_node [Saxon::XDM::Node] the document to serialize
+      # @return [String] a serialization of the the input document
+      def serialize(doc_node)
+        s9_transformer = @s9_xslt_executable.load30
+        serializer = Saxon::Serializer::Object.new(s9_transformer.newSerializer)
+        serializer.serialize(doc_node.to_java)
+      end
+
+      private
+
+      def v1_parameters(params = [])
+        v1_params = v1_params_hash(params).map { |qname, value|
+          [Saxon::QName.resolve(qname), Saxon::XDM.AtomicValue(v1_param_value(value))]
+        }.to_h
+        return {} if v1_params.empty?
+        {global_parameters: v1_params}
+      end
+
+      def v1_params_hash(params = [])
+        return params if params.is_a?(Hash)
+        params.each_slice(2).map { |k,v|
+          raise ArgumentError.new("Odd number of values passed as params: #{params}") if v.nil?
+          [k, v]
+        }.to_h
+      end
+
+      def v1_param_value(value)
+        if /\A(['"]).+\1\z/.match(value)
+          value.slice(1..-2)
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/saxon/occurrence_indicator.rb

@@ -1,32 +1,61 @@
 require_relative 's9api'
 
 module Saxon
-  # Provides simple access to Saxon's OccurrenceIndicator constants,
-  # for use in declaring variable types
+  # Provides simple access to Saxon's OccurrenceIndicator constants, for
+  # declaring restrictions on the cardinality (length) of a sequence when, for
+  # example, defining a variable's type
   module OccurrenceIndicator
     class << self
+      # One thing
       def one
         @one ||= Saxon::S9API::OccurrenceIndicator::ONE
       end
 
+      # One or more things
       def one_or_more
         @one_or_more ||= Saxon::S9API::OccurrenceIndicator::ONE_OR_MORE
       end
 
+      # no things (the empty sequence)
       def zero
         @zero ||= Saxon::S9API::OccurrenceIndicator::ZERO
       end
 
+      # zero or more things
       def zero_or_more
         @zero_or_more ||= Saxon::S9API::OccurrenceIndicator::ZERO_OR_MORE
       end
 
+      # an optional thing
       def zero_or_one
         @zero_or_one ||= Saxon::S9API::OccurrenceIndicator::ZERO_OR_ONE
       end
 
+      # The list of valid occurence indicator names, as symbols. These
+      # correspond directly to the methods returning OccurrenceIndicators in
+      # this module.
+      #
+      # @return [Array<Symbol>] the indicator names
       def indicator_names
-        @indicator_names ||= (public_methods(false) - Object.public_methods - [:indicator_names])
+        # .refine gets added to modules that have methods, so it's not in
+        # Module's public_methods list
+        @indicator_names ||= (public_methods(false) - Module.public_methods - [:indicator_names, :get_indicator, :refine])
+      end
+
+      # Return an OccurrenceIndicator given a name as a symbol. Passes through
+      # existing OccurrenceIndicator instances: this method is primarily for API
+      # use, most people will find it easier to directly call one of the
+      # methods, as in +OccurrenceIndicator.one+ rather than
+      # +OccurrenceIndicator.get_indicator(:one)+.
+      #
+      # @param indicator_name [Symbol, Saxon::S9API::OccurrenceIndicator] the name of the OccurrenceIndicator to return
+      # @return [Saxon::S9API::OccurrenceIndicator] the OccurrenceIndicator
+      def get_indicator(indicator_name)
+        return indicator_name if indicator_name.is_a?(Saxon::S9API::OccurrenceIndicator)
+        unless indicator_names.include?(indicator_name)
+          raise ArgumentError, "#{indicator_name.inspect} is not a valid indicator name (one of #{indicator_names.map(&:inspect).join(', ')})"
+        end
+        OccurrenceIndicator.send(indicator_name)
       end
     end
   end

data/lib/saxon/processor.rb

@@ -4,6 +4,7 @@ require 'saxon/configuration'
 require 'saxon/document_builder'
 require 'saxon/xpath'
 require 'saxon/xslt'
+require 'saxon/serializer'
 
 module Saxon
   # Saxon::Processor wraps the S9API::Processor object. This is the object
@@ -45,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
@@ -76,12 +79,23 @@ module Saxon
     # <tt>Processor</tt>. Sharing <tt>XSLT::Compiler</tt>s across threads is
     # fine as long as the static context is not changed.
     #
-    # @yield An XPath compiler DSL block, see {Saxon::XSLT::Compiler.create}
+    # @yield An XSLT compiler DSL block, see {Saxon::XSLT::Compiler.create}
     # @return [Saxon::XSLT::Compiler] a new XSLT compiler
     def xslt_compiler(&block)
       Saxon::XSLT::Compiler.create(self, &block)
     end
 
+    # Generate a new +Serializer+ for directly serializing XDM Values that uses
+    # this +Processor+. +Serializer+s are effectively one-shot objects, and
+    # shouldn't be reused.
+    #
+    # @yield the block passed will be called bound to the serializer instance. See
+    #   {Saxon::Serializer::Object.create}
+    # @return [Saxon::Serializer::Object]
+    def serializer(&block)
+      Saxon::Serializer::Object.create(self, &block)
+    end
+
     # @return [net.sf.saxon.s9api.Processor] The underlying Saxon processor
     def to_java
       @s9_processor
@@ -98,5 +112,36 @@ module Saxon
     def config
       @config ||= Saxon::Configuration.create(self)
     end
+
+    # Create a {DocumentBuilder} and construct a {Source} and parse some XML.
+    # The args are passed to {Saxon::Source.create}, and the returned {Source}
+    # is parsed using {DocumentBuilder#build}. If a {Source} is passed in, parse
+    # that. Any options in +opts+ will be ignored in that case.
+    #
+    # @param input [Saxon::Source, IO, File, String, Pathname, URI] the input to
+    #   be turned into a {Source} and parsed.
+    # @param opts [Hash] for Source creation. See {Saxon::Source.create}.
+    # @return [Saxon::XDM::Node] the XML document
+    def XML(input, opts = {})
+      source = Source.create(input, opts)
+      document_builder.build(source)
+    end
+
+    # Construct a {Source} containing an XSLT stylesheet, create an
+    # {XSLT::Compiler}, and compile the source, returning the {XSLT::Executable}
+    # produced. If a {Source} is passed as +input+, then it will be passed
+    # through to the compiler and any source-related options in +opts+ will be
+    # ignored.
+    #
+    # @param input [Saxon::Source, IO, File, String, Pathname, URI] the input to
+    #   be turned into a {Source} and parsed.
+    # @param opts [Hash] for Source creation. See {Saxon::Source.create}.
+    # @yield the block is executed as an {XSLT::EvaluationContext::DSL} instance
+    #   and applied to the compiler
+    # @return [Saxon::XSLT::Executable] the XSLT Executable
+    def XSLT(input, opts = {}, &block)
+      source = Source.create(input, opts)
+      xslt_compiler(&block).compile(source)
+    end
   end
 end

data/lib/saxon/qname.rb

@@ -3,16 +3,39 @@ require 'saxon/s9api'
 module Saxon
   # Represents QNames
   class QName
+    # Create a {QName} from a Clark-notation string.
+    #
+    # Clark-notation for QNames uses +{}+ to delimit the namespace, so for a
+    # QName not in a namespace it's simply +local-name+, and for one in a
+    # namespace it's +{http://example.org/ns}local-name+
+    #
+    # @param clark_string [String] A QName in Clark notation.
+    # @return [Saxon::QName] A QName
     def self.clark(clark_string)
       s9_qname = Saxon::S9API::QName.fromClarkName(clark_string)
       new(s9_qname)
     end
 
+    # Create a {QName} from an Expanded QName string.
+    #
+    # Expanded QNames uses +Q{}+ to delimit the namespace, so for a
+    # QName not in a namespace it's simply +Q{}local-name+ (or +local-name}), and for one in a
+    # namespace it's +Q{http://example.org/ns}local-name+
+    #
+    # @param eqname_string [String] A QName in Expanded QName notation.
+    # @return [Saxon::QName] A QName
     def self.eqname(eqname_string)
       s9_qname = Saxon::S9API::QName.fromEQName(eqname_string)
       new(s9_qname)
     end
 
+    # Create a {QName} from prefix, uri, and local name options
+    #
+    # @param opts [Hash]
+    # @option [String] :prefix the namespace prefix to use (optional, requires +:uri+ passed too)
+    # @option [String] :uri the namespace URI to use (only required for QNames in a namespace)
+    # @option [String] :local_name the local-part of the QName. Required.
+    # @return [Saxon::QName] the QName
     def self.create(opts = {})
       prefix = opts[:prefix]
       uri = opts[:uri]
@@ -32,7 +55,7 @@ module Saxon
     # it's an instance of the underlying Saxon Java QName, it'll be wrapped
     # into a {Saxon::QName}
     #
-    # If the arg is a string, it's resolved by using {resolve_variable_name}
+    # If the arg is a string, it's resolved by using {resolve_qname_string}
     #
     # @param qname_or_string [String, Symbol, Saxon::QName] the qname to resolve
     # @param namespaces [Hash<String => String>] the set of namespaces as a hash of <tt>"prefix" => "namespace-uri"</tt>
@@ -48,7 +71,7 @@ module Saxon
       end
     end
 
-    # Resolve a QName string of the form <tt>"prefix:local-name"</tt> into a
+    # Resolve a QName string of the form +"prefix:local-name"+ into a
     # {Saxon::QName} by looking up the namespace URI in a hash of
     # <tt>"prefix" => "namespace-uri"</tt>
     #
@@ -110,12 +133,21 @@ module Saxon
       @s9_qname.getEQName
     end
 
+    # Compare this QName with another. They compare equal if they have same URI
+    # and local name. Prefix is ignored.
+    #
+    # @param other [Saxon::QName] the QName to compare against
+    # @return [Boolean] whether the two compare equal
     def ==(other)
       return false unless other.is_a?(QName)
       s9_qname.equals(other.to_java)
     end
     alias_method :eql?, :==
 
+    # Compute a hash-code for this {QName}.
+    #
+    # Two {QNames}s with the same local name and URI will have the same hash code (and will compare using eql?).
+    # @see Object#hash
     def hash
       @hash ||= (local_name + uri).hash
     end
@@ -134,6 +166,8 @@ module Saxon
       s9_qname.to_s
     end
 
+    # Returns a more detailed string representation of the object, showing
+    # prefix, uri, and local_name instance variables
     def inspect
       "<Saxon::QName @prefix=#{prefix} @uri=#{uri} @local_name=#{local_name}>"
     end
@@ -145,6 +179,7 @@ module Saxon
         @qname_string, @prefix = qname_string, prefix
       end
 
+      # The error message reports the unbound prefix and complete QName
       def to_s
         "Namespace prefix ‘#{@prefix}’ for QName ‘#{@qname_string}’ is not bound to a URI"
       end

data/lib/saxon/s9api.rb

@@ -3,8 +3,13 @@ require 'saxon/loader'
 module Saxon
   module S9API
     CLASS_IMPORT_SEMAPHORE = Mutex.new
+    private_constant :CLASS_IMPORT_SEMAPHORE
 
     class << self
+      # Override the +const_missing+ hook in {S9API} so that we can delay
+      # loading the Saxon JARs until the user has had a chance to set an
+      # alternate location for them, if they don't want to use the bundled Saxon
+      # HE
       def const_missing(name)
         Saxon::Loader.load!
         begin