saxon-rb 0.4.0-java → 0.5.0-java

data/lib/saxon/item_type/value_to_ruby.rb

@@ -5,11 +5,18 @@ 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
         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 +28,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,6 +51,8 @@ module Saxon
         end
       end
 
+      # A collection of Lambdas (or objects responding to +#call+) for
+      # converting XDM typed values to native Ruby types.
       module Convertors
         INTEGER = INT = SHORT = LONG = UNSIGNED_INT = UNSIGNED_SHORT = UNSIGNED_LONG = \
         POSITIVE_INTEGER = NON_POSITIVE_INTEGER = NEGATIVE_INTEGER = NON_NEGATIVE_INTEGER = ->(xdm_atomic_value) {

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
@@ -45,7 +48,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.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

@@ -76,7 +76,7 @@ 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)
@@ -98,5 +98,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

data/lib/saxon/sequence_type.rb

@@ -0,0 +1,131 @@
+require_relative './item_type'
+require_relative './occurrence_indicator'
+
+module Saxon
+  # Represents a type definition for an XDM Sequence: an {ItemType} plus an
+  # {OccurrenceIndicator} as a restriction on the cardinality (length) of the
+  # sequence. Used most often to define variables in XPath or XSLT, plus in
+  # extension function definition.
+  class SequenceType
+    class << self
+      # Generate a {SequenceType} from a type declaration string (see
+      # {.from_type_decl}), or some combination of type name/Ruby class (see
+      # {ItemType.get_type}), and an {OccurrenceIndicator} or symbol referencing
+      # an OccurenceIndicator (one of +:zero_or_more+, +:one_or_more+,
+      # +:zero_or_one+, or +:one+)
+      #
+      # @return [Saxon::SequenceType] the resulting SequenceType
+      def create(type_name, occurrence_indicator = nil)
+        case type_name
+        when SequenceType
+          return type_name
+        when S9API::SequenceType
+          return new(type_name)
+        else
+          check_for_complete_decl!(type_name, occurrence_indicator)
+          return from_type_decl(type_name) if type_name.is_a?(String) && occurrence_indicator.nil?
+          item_type = ItemType.get_type(type_name)
+          occurrence_indicator = OccurrenceIndicator.get_indicator(occurrence_indicator)
+          new(item_type, occurrence_indicator)
+        end
+      end
+
+      # Generate a {SequenceType} from a declaration string following the rules
+      # of parameter and function +as=+ declarations in XSLT, like
+      # <tt><xsl:variable ... as="xs:string+"/></tt>
+      #
+      # @param type_decl [String] the declaration string
+      # @return [Saxon::SequenceType] the resulting SequenceType
+      def from_type_decl(type_decl)
+        occurence_char = type_decl[-1]
+        occurence = case occurence_char
+        when '?'
+          new(ItemType.get_type(type_decl[0..-2]), OccurrenceIndicator.zero_or_one)
+        when '+'
+          new(ItemType.get_type(type_decl[0..-2]), OccurrenceIndicator.one_or_more)
+        when '*'
+          new(ItemType.get_type(type_decl[0..-2]), OccurrenceIndicator.zero_or_more)
+        else
+          new(ItemType.get_type(type_decl), OccurrenceIndicator.one)
+        end
+      end
+
+      private
+
+      def check_for_complete_decl!(type_name, occurrence_indicator)
+        return true if occurrence_indicator.nil?
+        if type_name_is_complete_decl?(type_name)
+          raise ArgumentError, "Cannot pass a complete type declaration (#{type_name}) and an OccurrenceIndicator"
+        end
+      end
+
+      def type_name_is_complete_decl?(type_name)
+        !!(type_name.is_a?(String) && type_name.match(/[+*?]$/))
+      end
+    end
+
+    # @overload initialize(item_type, occurrence_indicator)
+    #   creates new instance using item type and occurrence indicator
+    #   @param item_type [Saxon::ItemType] the sequence's item type
+    #   @param occurrence_indicator [net.sf.saxon.s9api.OccurrenceIndicator] the
+    #     occurrence indicator (cardinality) of the sequence
+    # @overload initialize(s9_sequence_type)
+    #   create a new instance by wrapping one of Saxon's underlying Java
+    #   +SequenceType+s
+    #   @param s9_sequence_type [net.sf.saxon.s9api.SequenceType]
+    # @return [Saxon::SequenceType] the new SequenceType
+    def initialize(item_type, occurrence_indicator = nil)
+      if occurrence_indicator.nil? && !item_type.is_a?(S9API::SequenceType)
+        raise ArgumentError, "Expected a Java s9api.SequenceType when handed a single argument, but got a #{item_type.class}"
+      end
+
+      if occurrence_indicator.nil?
+        @s9_sequence_type = item_type
+      else
+        @item_type = item_type
+        @occurrence_indicator = occurrence_indicator
+      end
+    end
+
+    # @return [Saxon::ItemType] the type's ItemType
+    def item_type
+      @item_type ||= Saxon::ItemType.get_type(s9_sequence_type.getItemType)
+    end
+
+    # @return [net.sf.saxon.s9api.OccurrenceIndicator] the type's OccurrenceIndicator
+    def occurrence_indicator
+      @occurrence_indicator ||= s9_sequence_type.getOccurrenceIndicator
+    end
+
+    # @return [net.sf.saxon.s9api.SequenceType] the underlying Saxon SequenceType
+    def to_java
+      s9_sequence_type
+    end
+
+    # Compare equal with another SequenceType
+    # @param other [Saxon::SequenceType]
+    # @return [Boolean] the result of comparing +self+ and +other+
+    def ==(other)
+      return false if other.class != self.class
+      item_type == other.item_type && occurrence_indicator == other.occurrence_indicator
+    end
+    alias_method :eql?, :==
+
+    # Generated hash code for use as keys in Hashes
+    def hash
+      @hash ||= item_type.hash ^ occurrence_indicator.hash
+    end
+
+    private
+
+    def s9_sequence_type
+      @s9_sequence_type ||= S9API::SequenceType.makeSequenceType(item_type.to_java, occurrence_indicator.to_java)
+    end
+  end
+
+  # Convenience wrapper for {SequenceType.create}
+  # @see SequenceType.create
+  def self.SequenceType(*args)
+    SequenceType.create(*args)
+  end
+end