saxon-rb 0.4.0-java → 0.7.2-java

data/lib/saxon/xpath.rb

@@ -3,6 +3,15 @@ require_relative './xpath/compiler'
 module Saxon
   # Classes for compiling, configuring, and executing XPath queries against
   # XDM nodes or documents
+  #
+  # Using an XPath involves creating a compiler, compiling an XPath into an
+  # executable, and then running that XPath executable against an XDM node.
+  #
+  # The easiest way to create an XPath::Compiler instance is by using the {Saxon::Processor#xpath_compiler} method.
+  #
+  # @see Saxon::XPath::Compiler
+  # @see Saxon::XPath::Executable
+  # @see Saxon::Processor#xpath_compiler
   module XPath
   end
 end

data/lib/saxon/xpath/compiler.rb

@@ -4,14 +4,43 @@ require_relative './executable'
 
 module Saxon
   module XPath
-    # Compiles XPath expressions so they can be executed
+    # An {XPath::Compiler} turns XPath expressions into executable queries you
+    # can run against XDM Nodes (like XML documents, or parts of XML documents).
+    #
+    # To compile an XPath requires an +XPath::Compiler+ instance. You can create
+    # one by calling {Compiler.create} and passing a {Saxon::Processor}, with an
+    # optional block for context like bound namespaces and declared variables.
+    # Alternately, and much more easily, you can call {Processor#xpath_compiler}
+    # on the {Saxon::Processor} instance you're already working with.
+    #
+    #     processor = Saxon::Processor.create
+    #     compiler = processor.xpath_compiler {
+    #       namespace a: 'http://example.org/a'
+    #       variable 'a:var', 'xs:string'
+    #     }
+    #     # Or...
+    #     compiler = Saxon::XPath::Compiler.create(processor) {
+    #       namespace a: 'http://example.org/a'
+    #       variable 'a:var', 'xs:string'
+    #     }
+    #     xpath = compiler.compile('//a:element[@attr = $a:var]')
+    #     matches = xpath.evaluate(document_node, {
+    #       'a:var' => 'the value'
+    #     }) #=> Saxon::XDM::Value
+    #
+    # In order to use prefixed QNames in your XPaths, like +/ns:name/+, then you need
+    # to declare prefix/namespace URI bindings when you create a compiler.
+    #
+    # It's also possible to make use of variables in your XPaths by declaring them at
+    # the compiler creation stage, and then passing in values for them as XPath run
+    # time.
     class Compiler
       # Create a new <tt>XPath::Compiler</tt> using the supplied Processor.
       # Passing a block gives access to a DSL for setting up the compiler's
       # 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)
@@ -46,6 +75,12 @@ module Saxon
         Saxon::XPath::Executable.new(new_compiler.compile(expression), static_context)
       end
 
+      # Allows the creation of a new {Compiler} starting from a copy of this
+      # 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
+      # @return [Saxon::XPath::Compiler] the new compiler instance
       def create(&block)
         new_static_context = static_context.define(block)
         self.class.new(@s9_processor, new_static_context)

data/lib/saxon/xpath/executable.rb

@@ -2,7 +2,23 @@ require_relative '../xdm'
 
 module Saxon
   module XPath
-    # Represents a compiled XPath query ready to be executed
+    # Represents a compiled XPath query ready to be executed. An
+    # {XPath::Executable} is created by compiling an XPath expression with
+    # {XPath::Compiler#compile}.
+    #
+    # To run the +XPath::Executable+ you can call {XPath::Executable#evaluate},
+    # to generate an {XDM::Value} of the results, or you can call
+    # {XPath::Executable#as_enum} to return an Enumerator over the results.
+    #
+    #     processor = Saxon::Processor.create
+    #     compiler = processor.xpath_compiler
+    #     xpath = compiler.compile('//element[@attr = $var]')
+    #
+    #     matches = xpath.evaluate(document_node, {'var' => 'the value'}) #=> Saxon::XDM::Value
+    #
+    #     xpath.as_enum(document_node, {'var' => 'the value'}).each do |node|
+    #       ...
+    #     end
     class Executable
       # @return [XPath::StaticContext] the XPath's static context
       attr_reader :static_context
@@ -16,17 +32,34 @@ module Saxon
         @s9_xpath_executable, @static_context = s9_xpath_executable, static_context
       end
 
-      # Run the compiled query using a passed-in node as the context item.
-      # @param context_item [Saxon::XDM::Node] the context item node
-      # @return [Saxon::XPath::Result] the result of the query as an
-      #   enumerable
-      def run(context_item, variables = {})
-        selector = to_java.load
-        selector.setContextItem(context_item.to_java)
-        variables.each do |qname_or_string, value|
-          selector.setVariable(static_context.resolve_variable_qname(qname_or_string).to_java, Saxon::XDM.Value(value).to_java)
-        end
-        Result.new(selector.iterator)
+
+      # Evaluate the XPath against the context node given and return an
+      # +Enumerator+ over the result.
+      #
+      # @param context_item [Saxon::XDM::Node, Saxon::XDM::AtomicValue] the item
+      #   to be used as the context item for evaluating the XPath from.
+      # @param variables [Hash<Saxon::QName => Saxon::XDM::Value, Saxon::XDM::Node,
+      #   Saxon::XDM::AtomicValue>] any variable values to set within the XPath
+      # @return [Enumerator] an Enumerator over the items in the result sequence
+      def as_enum(context_item, variables = {})
+        generate_selector(context_item, variables).iterator.lazy.
+          map { |s9_xdm_object| Saxon::XDM.Value(s9_xdm_object) }
+      end
+
+      # Evaluate the XPath against the context node given and return the result.
+      #
+      # If the result is a single item, then that will be returned directly
+      # (e.g. an {XDM::Node} or an {XDM::AtomicValue}). If the result is an
+      # empty sequence then {XDM::EmptySequence} is returned.
+      #
+      # @param context_item [Saxon::XDM::Node, Saxon::XDM::AtomicValue] the item
+      #   to be used as the context item for evaluating the XPath from.
+      # @param variables [Hash<Saxon::QName => Saxon::XDM::Value, Saxon::XDM::Node,
+      #   Saxon::XDM::AtomicValue>] any variable values to set within the XPath
+      # @return [Saxon::XDM::Value] the XDM value returned
+      def evaluate(context_item, variables = {})
+        s9_xdm_value = generate_selector(context_item, variables).evaluate
+        Saxon::XDM.Value(s9_xdm_value)
       end
 
       # @return [net.sf.saxon.s9api.XPathExecutable] the underlying Saxon
@@ -34,24 +67,16 @@ module Saxon
       def to_java
         @s9_xpath_executable
       end
-    end
 
-    # The result of executing an XPath query as an enumerable object
-    class Result
-      include Enumerable
+      private
 
-      # @api private
-      # @param result_iterator [java.util.Iterator] the result of calling
-      #   <tt>#iterator</tt> on a Saxon <tt>XPathSelector</tt>
-      def initialize(result_iterator)
-        @result_iterator = result_iterator
-      end
-
-      # Yields <tt>XDM::Node</tt>s from the query result. If no block is passed,
-      # returns an <tt>Enumerator</tt>
-      # @yieldparam xdm_node [Saxon::XDM::Node] the name that is yielded
-      def each(&block)
-        @result_iterator.lazy.map { |s9_xdm_node| Saxon::XDM::Node.new(s9_xdm_node) }.each(&block)
+      def generate_selector(context_item, variables = {})
+        selector = to_java.load
+        selector.setContextItem(context_item.to_java)
+        variables.each do |qname_or_string, value|
+          selector.setVariable(static_context.resolve_variable_qname(qname_or_string).to_java, Saxon::XDM.Value(value).to_java)
+        end
+        selector
       end
     end
   end

data/lib/saxon/xpath/static_context.rb

@@ -1,5 +1,6 @@
 require_relative '../qname'
 require_relative './variable_declaration'
+
 module Saxon
   module XPath
     # Raised when an attempt to declare a variable is made using a string for
@@ -10,11 +11,13 @@ module Saxon
         @variable_name, @prefix = variable_name, prefix
       end
 
+      # error message reports which unbound prefix is a problem, and how it was used
       def to_s
         "Namespace prefix ‘#{@prefix}’ for variable name ‘#{@variable_name}’ is not bound to a URI"
       end
     end
 
+    # @api private
     # Represents the static context for a compiled XPath. {StaticContext}s are immutable.
     class StaticContext
       # methods used by both {StaticContext} and {StaticContext::DSL}
@@ -41,11 +44,12 @@ module Saxon
         end
       end
 
+      # @api public
       # Provides the hooks for constructing a {StaticContext} with a DSL.
-      # @api private
       class DSL
         include Common
 
+        # @api private
         # Create an instance based on the args hash, and execute the passed in Proc/lambda against it using <tt>#instance_exec</tt> and return a
         # new {StaticContext} with the results
         # @param block [Proc] a Proc/lambda (or <tt>to_proc</tt>'d containing DSL calls
@@ -70,28 +74,23 @@ module Saxon
         #
         # @param namespaces [Hash{String, Symbol => String}]
         def namespace(namespaces = {})
-          @declared_namespaces = @declared_namespaces.merge(namespaces.transform_keys(&:to_s)).freeze
+          @declared_namespaces = @declared_namespaces.merge(namespaces.map { |k, v| [k.to_s, v] }.to_h).freeze
         end
 
         # Declare a XPath variable's existence in the context
         #
         # @param qname [String, Saxon::QName] The name of the variable as
-        # explicit QName or prefix:name string form. The string form requires
-        # the namespace prefix to have already been declared with {#namespace}
-        # @param type [String, Hash{Symbol => String, Class}, null] The type of the
-        # variable, either as a string using the same form as an XSLT
-        # <tt>as=""</tt> type definition, or as a hash of one key/value where
-        # that key is a Symbol taken from {Saxon::OccurenceIndicator} and the
-        # value is either a Class that {Saxon::ItemType} can convert to its
-        # XDM equivalent (e.g. {::String}), or a string that {Saxon::ItemType}
-        # can parse into an XDM type (e.g. <tt>xs:string</tthat
-        # {Saxon::ItemType} can parse into an XDM type (e.g.
-        # <tt>xs:string</tt> or <tt>element()</tt>).
-        # If it's nil, then the default <tt>item()*</tt> – anything – type declaration is used
-        def variable(qname, type = nil)
+        #   explicit QName or prefix:name string form. The string form requires
+        #   the namespace prefix to have already been declared with {#namespace}
+        # @param sequence_type [String, Saxon::SequenceType, null] The type of
+        #   the variable, either as a string using the same form as an XSLT
+        #   <tt>as=""</tt> type definition, or as a {Saxon::SequenceType} directly.
+        #
+        #   If it's nil, then the default <tt>item()*</tt> – anything – type declaration is used
+        def variable(qname, sequence_type = nil)
           qname = resolve_variable_qname(qname)
           @declared_variables = @declared_variables.merge({
-            qname => resolve_variable_declaration(qname, type)
+            qname => resolve_variable_declaration(qname, sequence_type)
           }).freeze
         end
 
@@ -101,29 +100,8 @@ module Saxon
           Saxon::QName.resolve(qname_or_string, @declared_namespaces)
         end
 
-        def resolve_variable_type_decl(type_decl)
-          case type_decl
-          when String
-            occurence_char = type_decl[-1]
-            occurence = case occurence_char
-            when '?'
-              {zero_or_one: type_decl[0..-2]}
-            when '+'
-              {one_or_more: type_decl[0..-2]}
-            when '*'
-              {zero_or_more: type_decl[0..-2]}
-            else
-              {one: type_decl}
-            end
-          when Hash
-            type_decl
-          end
-        end
-
-        def resolve_variable_declaration(qname, type)
-          args_hash = resolve_variable_type_decl(type) || {}
-          args_hash[:qname] = qname
-          Saxon::XPath::VariableDeclaration.new(args_hash)
+        def resolve_variable_declaration(qname, sequence_type = nil)
+          Saxon::XPath::VariableDeclaration.new(qname, Saxon.SequenceType(sequence_type || 'item()*'))
         end
       end
 
@@ -139,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)
@@ -153,6 +136,8 @@ module Saxon
         Saxon::QName.resolve(qname_or_string, declared_namespaces)
       end
 
+      # @api private
+      # Create a new {StaticContext} based on this one. Passed Proc is evaluated in the same way as {DSL.define}
       def define(block)
         DSL.define(block, args_hash)
       end

data/lib/saxon/xpath/variable_declaration.rb

@@ -1,67 +1,34 @@
-require_relative '../item_type'
-require_relative '../occurrence_indicator'
+require_relative '../sequence_type'
 
 module Saxon
   module XPath
-    # Represents an XPath variable declaration in the static context of a compiled XPath, providing an idiomatic Ruby way to deal with these.
+    # Represents an XPath variable declaration in the static context of a
+    # compiled XPath, providing an idiomatic Ruby way to deal with these.
     class VariableDeclaration
       # @return [Saxon::QName]
       attr_reader :qname
-      # @return [Saxon::ItemType]
-      attr_reader :item_type
-      # @return [net.sf.saxon.s9api.OccurrenceIndicator]
-      attr_reader :occurrences
-
-      # @param opts [Hash]
-      # @option opts [Saxon::QName] :qname The name of the variable as a {Saxon::QName}
-      def initialize(opts = {})
-        raise VariableDeclarationError, opts.keys if opts.keys.length > 2
-        @qname = opts.fetch(:qname)
-        @item_type, @occurrences = extract_type_decl(opts.reject { |k, v| k == :qname })
+      # @return [Saxon::SequenceType]
+      attr_reader :sequence_type
+
+      # @param qname [Saxon::QName] the name of the variable
+      # @param sequence_type [Saxon::SequenceType] the SequenceType of the
+      #   variable
+      def initialize(qname, sequence_type)
+        @qname = qname
+        @sequence_type = sequence_type || Saxon.SequenceType('item()*')
       end
 
-      # VariableDeclarations compare equal if their qname, item_type, and occurrences are equal
+      # VariableDeclarations compare equal if their qname and sequence_type are equal
       # @param other [Saxon::VariableDeclaration]
       # @return [Boolean]
       def ==(other)
-        VariableDeclaration === other && qname == other.qname && item_type == other.item_type && occurrences == other.occurrences
+        VariableDeclaration === other && qname == other.qname && sequence_type == other.sequence_type
       end
 
       # @api private
+      # return the arguments XPathCompiler.declareVariable expects
       def compiler_args
-        [qname.to_java, item_type.to_java, occurrences]
-      end
-
-      private
-
-      def self.valid_opt_keys
-        @valid_opt_keys ||= [:qname] + Saxon::OccurrenceIndicator.indicator_names
-      end
-
-      def extract_type_decl(type_decl)
-        raise VariableDeclarationError, type_decl.keys if type_decl.length > 1
-        unless (type_decl.keys - Saxon::OccurrenceIndicator.indicator_names).empty?
-          raise VariableDeclarationError, type_decl.keys
-        end
-
-        return [Saxon::ItemType.get_type('item()'), Saxon::OccurrenceIndicator.zero_or_more] if type_decl.empty?
-        occurrence, type = type_decl.first
-        [Saxon::ItemType.get_type(type), Saxon::OccurrenceIndicator.send(occurrence)]
-      end
-    end
-
-    # Raised when an attempt to declare a variable is made using an occurrence
-    # indicator that does not exist
-    class VariableDeclarationError < StandardError
-      attr_reader :keys
-
-      def initialize(keys)
-        @keys = keys
-      end
-
-      # reports allowable occurrence indicator keys and what was actually passed in
-      def to_s
-        "requires :qname, and optionally one of #{Saxon::OccurrenceIndicator.indicator_names}, was passed #{keys.join(', ')}"
+        [qname.to_java, sequence_type.item_type.to_java, sequence_type.occurrence_indicator.to_java]
       end
     end
   end

data/lib/saxon/xslt.rb

@@ -3,6 +3,18 @@ require_relative './xslt/compiler'
 module Saxon
   # Classes for compiling, configuring, and executing XSLT transformations
   # against XDM nodes or documents
+  #
+  # Using XSLT involves creating a compiler, compiling an XSLT file into an
+  # executable, and then invoking that executable through applying templates
+  # against an XML document, calling a named template, or calling a named
+  # function.
+  #
+  # The easiest way to create an {XSLT::Compiler} instance is by using the
+  # {Saxon::Processor#xslt_compiler} method.
+  #
+  # @see Saxon::XSLT::Compiler
+  # @see Saxon::XSLT::Executable
+  # @see Saxon::Processor#xslt_compiler
   module XSLT
   end
 end

data/lib/saxon/xslt/compiler.rb

@@ -4,7 +4,67 @@ require_relative './executable'
 
 module Saxon
   module XSLT
-    # Compiles XSLT stylesheets so they can be executed
+    # The simplest way to construct an {XSLT::Compiler} is to call
+    # {Saxon::Processor#xslt_compiler}.
+    #
+    #     processor = Saxon::Processor.create
+    #     # Simplest, default options
+    #     compiler = processor.xslt_compiler
+    #
+    # In order to set compile-time options, declare static compile-time
+    # parameters then pass a block to the method using the DSL syntax (see
+    # {Saxon::XSLT::EvaluationContext::DSL}
+    #
+    #     compiler = processor.xslt_compiler {
+    #       static_parameters 'param' => 'value'
+    #       default_collation 'https://www.w3.org/2005/xpath-functions/collation/html-ascii-case-insensitive/'
+    #     }
+    #
+    # The static evaluation context for a Compiler cannot be changed, you must
+    # create a new one with the context you want. It’s very simple to create a
+    # new Compiler based on an existing one. Declaring a parameter with a an
+    # existing name overwrites the old value.
+    #
+    #     new_compiler = compiler.create {
+    #       static_parameters 'param' => 'new value'
+    #     }
+    #     new_compiler.default_collation #=> "https://www.w3.org/2005/xpath-functions/collation/html-ascii-case-insensitive/"
+    #
+    # If you wanted to remove a value, you need to start from scratch. You can,
+    # of course, extract any data you want from a compiler instance separately
+    # and use that to create a new one.
+    #
+    #     params = compiler.static_parameters
+    #     new_compiler = processor.xslt_compiler {
+    #       static_parameters params
+    #     }
+    #     new_compiler.default_collation #=> nil
+    #
+    # Once you have a compiler, call {Compiler#compile} and pass in a
+    # {Saxon::Source} or an existing {Saxon::XDM::Node}. Parameters and other
+    # run-time configuration options can be set using a block in the same way as
+    # creating a compiler. You'll be returned a {Saxon::XSLT::Executable}.
+    #
+    #     source = Saxon::Source.create('my.xsl')
+    #     xslt = compiler.compile(source) {
+    #       initial_template_parameters 'param' => 'other value'
+    #     }
+    #
+    # You can also pass in (or override) parameters at stylesheet execution
+    # time, but if you'll be executing the same stylesheet against many
+    # documents with the same initial parameters then setting them at compile
+    # time is simpler.
+    #
+    # Global and initial template parameters can be set at compiler creation
+    # time, compile time, or execution time. Static parameters can only be set
+    # at compiler creation or compile time.
+    #
+    #     xslt = compiler.compile(source) {
+    #       static_parameters 'static-param' => 'static value'
+    #       global_parameters 'param' => 'global value'
+    #       initial_template_parameters 'param' => 'other value'
+    #       initial_template_tunnel_parameters 'param' => 'tunnel value'
+    #     }
     class Compiler
       # Create a new <tt>XSLT::Compiler</tt> using the supplied Processor.
       # Passing a block gives access to a DSL for setting up the compiler's
@@ -42,14 +102,23 @@ module Saxon
       #   Saxon::XDM::AtomicValue>] parameters required at compile time as QName => value hash
 
       # @param source [Saxon::Source] the Source to compile
+      # @yield the block is executed in the context of an {XSLT::EvaluationContext} DSL instance
       # @return [Saxon::XSLT::Executable] the executable stylesheet
       def compile(source, &block)
+        new_evaluation_context = evaluation_context.define(block)
+        s9_compiler = new_compiler(new_evaluation_context)
         Saxon::XSLT::Executable.new(
-          new_compiler.compile(source.to_java),
-          evaluation_context.define(block)
+          s9_compiler.compile(source.to_java),
+          new_evaluation_context
         )
       end
 
+      # Allows the creation of a new {Compiler} starting from a copy of this
+      # 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 XSLT compiler DSL block
+      # @return [Saxon::XSLT::Compiler] the new compiler instance
       def create(&block)
         new_evaluation_context = evaluation_context.define(block)
         self.class.new(@s9_processor, new_evaluation_context)
@@ -57,10 +126,10 @@ module Saxon
 
       private
 
-      def new_compiler
+      def new_compiler(evaluation_context)
         compiler = @s9_processor.newXsltCompiler
-        compiler.declareDefaultCollation(default_collation) unless default_collation.nil?
-        static_parameters.each do |qname, value|
+        compiler.declareDefaultCollation(evaluation_context.default_collation) unless evaluation_context.default_collation.nil?
+        evaluation_context.static_parameters.each do |qname, value|
           compiler.setParameter(qname.to_java, value.to_java)
         end
         compiler