saxon-rb 0.4.0-java → 0.5.0-java

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
 
@@ -153,6 +131,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

data/lib/saxon/xslt/evaluation_context.rb

@@ -3,6 +3,7 @@ require_relative '../qname'
 
 module Saxon
   module XSLT
+    # @api private
     # Represents the evaluation context for an XSLT compiler, and stylesheets
     # compiled using one. {EvaluationContext}s are immutable.
     class EvaluationContext
@@ -47,11 +48,12 @@ module Saxon
         end
       end
 
+      # @api public
       # Provides the hooks for constructing a {EvaluationContext} 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 {EvaluationContext} with the results
         # @param block [Proc] a Proc/lambda (or <tt>to_proc</tt>'d containing DSL calls
@@ -130,6 +132,7 @@ module Saxon
 
       include Common
 
+      # @api private
       # Executes the Proc/lambda passed in with a new instance of
       # {EvaluationContext} as <tt>self</tt>, allowing the DSL methods to be
       # called in a DSL-ish way
@@ -142,21 +145,34 @@ module Saxon
 
       attr_reader :default_collation, :static_parameters, :global_parameters, :initial_template_parameters, :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}.
+      #
+      # When passed {nil}, simply return the EvaluationContext unaltered.
       def define(block)
         block.nil? ? self : DSL.define(block, args_hash)
       end
     end
 
+    # Error raised when a global and static parameter of the same name are
+    # declared
     class GlobalAndStaticParameterClashError < StandardError
     end
 
+    # parameter shorthand name/value-to-full QName/XDM::Value helper module
     module ParameterHelper
+      # process shorthand parameter hash into fully-qualified QName / Value hash
+      # @param parameters [Hash<String, Saxon::QName => Object>]
+      # @return [Hash<Saxon::QName => Saxon::XDM::Value>]
+      # @see Saxon::QName.resolve() for more about the QName resolution process
+      # @see Saxon::XDM.Value() for more about the conversion of Object into XDM Values
       def self.process_parameters(parameters)
-        Hash[parameters.map { |qname, value|
+        parameters.map { |qname, value|
           [Saxon::QName.resolve(qname), Saxon::XDM.Value(value)]
-        }]
+        }.to_h
       end
 
+      # generate Java Map from fully qualified parameter hash
       def self.to_java(parameters)
         Hash[parameters.map { |k,v| [k.to_java, v.to_java] }].to_java
       end

data/lib/saxon/xslt/executable.rb

@@ -7,6 +7,49 @@ require_relative '../qname'
 module Saxon
   module XSLT
     # Represents a compiled XSLT stylesheet ready to be executed
+    #
+    # Once you have a compiled stylesheet, then it can be executed against a
+    # source document in a variety of ways.
+    #
+    # First, you can use the traditional *apply templates* ,method, which was
+    # the only way in XSLT 1.
+    #
+    #     input = Saxon::Source.create('input.xml')
+    #     result = xslt.apply_templates(input)
+    #
+    # Next, you can call a specific named template (new in XSLT 2).
+    #
+    #     result = xslt.call_template('template-name')
+    #
+    # Note that there's no input document here. If your XSLT needs a global
+    # context item set when you invoke it via a named template, then you can do
+    # that, too:
+    #
+    #     input = processor.XML('input.xml')
+    #     result = xslt.call_template('template-name', {
+    #       global_context_item: input
+    #     })
+    #
+    # Global and initial template parameters can be set at compiler creation
+    # time, compile time, or execution time.
+    #
+    # Initial template parameters relate to parameters passed to the *first*
+    # template run (either the first template matched when called with
+    # {Executable#apply_templates}, or the named template called with
+    # {Executable#call_template}).
+    #
+    # <b>Initial template parameters</b> are essentially implied +<xsl:with-parameter
+    # tunnel="no">+ elements. <b>Initial template tunnel parameters</b> are implied
+    # +<xsl:with-parameter tunnel="yes">+ elements.
+    #
+    #     xslt.apply_templates(input, {
+    #       global_parameters: {'param' => 'global value'},
+    #       initial_template_parameters: {'param' => 'other value'},
+    #       initial_template_tunnel_parameters: {'param' => 'tunnel value'}
+    #     })
+    #
+    # Remember that if you need to use a parameter name which uses a namespace
+    # prefix, you must use an explicit {Saxon::QName} to refer to it.
     class Executable
       extend Forwardable
 
@@ -24,14 +67,100 @@ module Saxon
 
       def_delegators :evaluation_context, :global_parameters, :initial_template_parameters, :initial_template_tunnel_parameters
 
+      # Run the XSLT by applying templates against the provided {Saxon::Source}
+      # or {Saxon::XDM::Node}.
+      #
+      # @note Any {QName}s supplied as strings MUST be resolvable as a QName
+      # without extra information, so they must be prefix-less (so, 'name', and
+      # never 'ns:name')
+      #
+      # @param source [Saxon::Source, Saxon::XDM::Node] the Source or Node that
+      #   will be used as the global context item
+      # @param opts [Hash] a hash of options for invoking the transformation
+      # @option opts [Boolean] :raw (false) Whether the transformation should be
+      #   executed 'raw', because it is expected to return a simple XDM Value
+      #   (like a number, or plain text) and not an XML document.
+      # @option opts [String, Saxon::QName] :mode The initial mode to use when
+      #   processing starts.
+      # @option opts [Hash<String, Saxon::QName => Object>] :global_parameters
+      #   Additional global parameters to set. Setting already-defined
+      #   parameters will replace their value for this invocation of the XSLT
+      #   only, it won't affect the {XSLT::Compiler}'s context.
+      # @option opts [Hash<String, Saxon::QName => Object>]
+      #   :initial_template_parameters Additional parameters to pass to the
+      #   first template matched. Setting already-defined parameters will
+      #   replace their value for this invocation of the XSLT only, it won't
+      #   affect the {XSLT::Compiler}'s context.
+      # @option opts [Hash<String, Saxon::QName => Object>]
+      #   :initial_template_tunnel_parameters Additional tunnelling parameters
+      #   to pass to the first template matched. Setting already-defined
+      #   parameters will replace their value for this invocation of the XSLT
+      #   only, it won't affect the {XSLT::Compiler}'s context.
+      # @return [Saxon::XSLT::Result] the transformation result
       def apply_templates(source, opts = {})
         transformation(opts).apply_templates(source)
       end
 
-      def call_template(template_name, opts = {})
+      # Run the XSLT by calling the named template.
+      #
+      # @note Any {QName}s supplied as Strings (e.g. for the template name)
+      # MUST be resolvable as a QName without extra information, so they must be
+      # prefix-less (so, 'name', and never 'ns:name')
+      #
+      # @param template_name [String, Saxon::QName, nil] the name of the
+      #   template to be invoked. Passing +nil+ will invoke the default named
+      #   template (+xsl:default-template+)
+      # @param opts [Hash] a hash of options for invoking the transformation
+      # @option opts [Boolean] :raw (false) Whether the transformation should be
+      #   executed 'raw', because it is expected to return a simple XDM Value
+      #   (like a number, or plain text) and not an XML document.
+      # @option opts [String, Saxon::QName] :mode The name of the initial mode
+      #   to use when processing starts.
+      # @option opts [Hash<String, Saxon::QName => Object>] :global_parameters
+      #   Additional global parameters to set. Setting already-defined
+      #   parameters will replace their value for this invocation of the XSLT
+      #   only, it won't affect the {XSLT::Compiler}'s context.
+      # @option opts [Hash<String, Saxon::QName => Object>]
+      #   :initial_template_parameters Additional parameters to pass to the
+      #   first template matched. Setting already-defined parameters will
+      #   replace their value for this invocation of the XSLT only, it won't
+      #   affect the {XSLT::Compiler}'s context.
+      # @option opts [Hash<String, Saxon::QName => Object>]
+      #   :initial_template_tunnel_parameters Additional tunnelling parameters
+      #   to pass to the first template matched. Setting already-defined
+      #   parameters will replace their value for this invocation of the XSLT
+      #   only, it won't affect the {XSLT::Compiler}'s context.
+      # @return [Saxon::XSLT::Result] the transformation result
+      def call_template(template_name = nil, opts = {})
         transformation(opts).call_template(template_name)
       end
 
+      # Invoke a named function in the XSLT.
+      #
+      # @note Function name {QName}s have to have prefixes, so they can't be
+      #   supplied as {::String}s. Any other {QName}s supplied as {::String}s (e.g.
+      #   for the template name) MUST be resolvable as a QName without extra
+      #   information, so they must be prefix-less (so, 'name', and never
+      #   'ns:name')
+      # @note the function you're calling needs to be have been defined with
+      #   +visibility="public"+ or +visibility="final"+
+      #
+      # @param function_name [Saxon::QName] the name of the function to be
+      #   invoked.
+      # @param opts [Hash] a hash of options for invoking the transformation
+      # @option opts [Boolean] :raw (false) Whether the transformation should be
+      #   executed 'raw', because it is expected to return a simple XDM Value
+      #   (like a number, or plain text) and not an XML document.
+      # @option opts [Hash<String, Saxon::QName => Object>] :global_parameters
+      #   Additional global parameters to set. Setting already-defined
+      #   parameters will replace their value for this invocation of the XSLT
+      #   only, it won't affect the {XSLT::Compiler}'s context.
+      # @return [Saxon::XSLT::Result] the transformation result
+      def call_function(function_name, opts = {})
+        args = opts.fetch(:args, [])
+        transformation(opts.reject { |k, v| k == :args }).call_function(function_name, args)
+      end
+
       # @return [net.sf.saxon.s9api.XsltExecutable] the underlying Saxon
       #   <tt>XsltExecutable</tt>
       def to_java
@@ -69,21 +198,20 @@ module Saxon
       end
     end
 
-    class Result
-      attr_reader :xdm_value
+    # @api private
+    # Represents a loaded XSLT transformation ready to be applied against a
+    # context node.
+    class Transformation
+      VALID_OPTS = [:raw, :mode, :global_context_item, :global_parameters, :initial_template_parameters, :initial_template_tunnel_parameters]
 
-      def initialize(xdm_value, s9_transformer)
-        @xdm_value, @s9_transformer = xdm_value, s9_transformer
-      end
+      attr_reader :s9_transformer, :opts
+      private :s9_transformer, :opts
 
-      def to_s
-        serializer = Serializer.new(@s9_transformer.newSerializer)
-        serializer.serialize(xdm_value.to_java)
+      # Return the default initial template namne for XSLT 3 named-template invocation
+      # @return [Saxon::QName] the default initial template QName
+      def self.default_initial_template
+        @default_initial_template ||= Saxon::QName.clark('{http://www.w3.org/1999/XSL/Transform}initial-template')
       end
-    end
-
-    class Transformation
-      attr_reader :s9_transformer, :opts
 
       def initialize(args)
         @s9_transformer = args.fetch(:s9_transformer)
@@ -94,12 +222,24 @@ module Saxon
         @raw = false
       end
 
+      # Apply templates to Source, using all the context set up when we were
+      # created.
       def apply_templates(source)
         transformation_result(:applyTemplates, source)
       end
 
+      # Call the named template, using all the context set up when we were
+      # created.
       def call_template(template_name)
-        transformation_result(:callTemplate, Saxon::QName.resolve(template_name))
+        transformation_result(:callTemplate, resolve_template_name(template_name))
+      end
+
+      # Call the named function, using all the context set up when we were
+      # created.
+      def call_function(function_name, args)
+        function_name = Saxon::QName.resolve(function_name).to_java
+        args = function_args(args)
+        call_function_result(function_name, args)
       end
 
       private
@@ -110,12 +250,26 @@ module Saxon
         Result.new(result_xdm_value(s9_transformer.send(*transformer_args)), s9_transformer)
       end
 
+      def call_function_result(name, args)
+        set_opts!
+        Result.new(result_xdm_value(s9_transformer.callFunction(*[name, args, destination].compact)), s9_transformer)
+      end
+
       def result_xdm_value(transformer_return_value)
         XDM.Value(
           transformer_return_value.nil? ? destination.getXdmNode : transformer_return_value
         )
       end
 
+      def resolve_template_name(template_name)
+        return self.class.default_initial_template if template_name.nil?
+        Saxon::QName.resolve(template_name)
+      end
+
+      def function_args(args = [])
+        args.map { |val| Saxon::XDM.Value(val).to_java }.to_java(S9API::XdmValue)
+      end
+
       def destination
         @destination ||= begin
           Saxon::S9API::XdmDestination.new unless raw?
@@ -124,6 +278,7 @@ module Saxon
 
       def set_opts!
         opts.each do |opt, value|
+          raise BadOptionError, opt unless VALID_OPTS.include?(opt)
           send(opt, value)
         end
       end
@@ -140,6 +295,10 @@ module Saxon
         s9_transformer.setInitialMode(Saxon::QName.resolve(mode_name).to_java)
       end
 
+      def global_context_item(xdm_item)
+        s9_transformer.setGlobalContextItem(xdm_item.to_java)
+      end
+
       def global_parameters(parameters)
         s9_transformer.setStylesheetParameters(XSLT::ParameterHelper.to_java(parameters))
       end
@@ -152,5 +311,36 @@ module Saxon
         s9_transformer.setInitialTemplateParameters(XSLT::ParameterHelper.to_java(parameters) , true)
       end
     end
+
+    # Represents the result of a transformation, providing a simple default
+    # serializer as well
+    class Result
+      attr_reader :xdm_value
+
+      # @api private
+      def initialize(xdm_value, s9_transformer)
+        @xdm_value, @s9_transformer = xdm_value, s9_transformer
+      end
+
+      # Serialize the result to a string using the options specified in
+      # +<xsl:output/>+ in the XSLT
+      def to_s
+        serializer = Serializer.new(@s9_transformer.newSerializer)
+        serializer.serialize(xdm_value.to_java)
+      end
+    end
+
+    # Raised if a bad option name is passed in the options hash to
+    # Executable#apply_templates et al
+    class BadOptionError < StandardError
+      def initialize(option_name)
+        @option_name = option_name
+      end
+
+      # return error message including the option name
+      def to_s
+        "Option :#{@option_name} is not a recognised option."
+      end
+    end
   end
 end