Class: Saxon::XSLT::Executable

Inherits:
Object
  • Object
show all
Extended by:
Forwardable, FeatureFlags::Helpers
Defined in:
lib/saxon/xslt/executable.rb,
lib/saxon/nokogiri.rb

Overview

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 #apply_templates, or the named template called with #call_template).

Initial template parameters are essentially implied <xsl:with-parameter tunnel=“no”> elements. Initial template tunnel parameters 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 QName to refer to it.

Instance Method Summary collapse

Methods included from FeatureFlags::Helpers

requires_saxon_version

Constructor Details

#initialize(s9_xslt_executable, evaluation_context) ⇒ Executable

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of Executable.

Parameters:

  • s9_xslt_executable (net.sf.saxon.s9api.XsltExecutable) —

    the Saxon compiled XSLT object

  • evaluation_context (XSLT::EvaluationContext) —

    the XSLT’s evaluation context



67
68
69
 
# File 'lib/saxon/xslt/executable.rb', line 67

def initialize(s9_xslt_executable, evaluation_context)
  @s9_xslt_executable, @evaluation_context = s9_xslt_executable, evaluation_context
end

Instance Method Details

#apply_templates(source, opts = {}) ⇒ Saxon::XSLT::Invocation

Note:

Any QNames supplied as strings MUST be resolvable as a QName

Run the XSLT by applying templates against the provided Source or Saxon::XDM::Node.

without extra information, so they must be prefix-less (so, ‘name’, and never ‘ns:name’)

Parameters:

  • source (Saxon::Source, Saxon::XDM::Node) —

    the Source or Node that will be used as the global context item

  • opts (Hash) (defaults to: {}) —

    a hash of options for invoking the transformation

Options Hash (opts):

  • :raw (Boolean) — default: 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.

  • :mode (String, Saxon::QName) —

    The initial mode to use when processing starts.

  • :global_parameters (Hash<String, Saxon::QName => Object>) —

    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 Compiler‘s context.

  • :initial_template_parameters (Hash<String, Saxon::QName => Object>) —

    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 Compiler‘s context.

  • :initial_template_tunnel_parameters (Hash<String, Saxon::QName => Object>) —

    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 Compiler‘s context.

Returns:



103
104
105
 
# File 'lib/saxon/xslt/executable.rb', line 103

def apply_templates(source, opts = {})
  transformation(opts).apply_templates(source)
end

#apply_to(doc_node, params = {}) ⇒ String

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

Parameters:

  • doc_node (Saxon::XDM::Node) —

    the document to transform

  • params (Hash, Array) (defaults to: {}) —

    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

Returns:

  • (String) —

    a serialization of the the result document



33
34
35
 
# File 'lib/saxon/nokogiri.rb', line 33

def apply_to(doc_node, params = {})
  apply_templates(doc_node, v1_parameters(params)).to_s
end

#call_function(function_name, opts = {}) ⇒ Saxon::XSLT::Invocation

Note:

Function name QNames have to have prefixes, so they can’t be supplied as Strings. Any other QNames 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’)

Note:

the function you’re calling needs to be have been defined with visibility=“public” or visibility=“final”

Invoke a named function in the XSLT.

Parameters:

  • function_name (Saxon::QName) —

    the name of the function to be invoked.

  • opts (Hash) (defaults to: {}) —

    a hash of options for invoking the transformation

Options Hash (opts):

  • :raw (Boolean) — default: 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.

  • :global_parameters (Hash<String, Saxon::QName => Object>) —

    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 Compiler‘s context.

Returns:



162
163
164
165
 
# File 'lib/saxon/xslt/executable.rb', line 162

def call_function(function_name, opts = {})
  args = opts.fetch(:args, [])
  transformation(opts.reject { |k, v| k == :args }).call_function(function_name, args)
end

#call_template(template_name = nil, opts = {}) ⇒ Saxon::XSLT::Invocation

Note:

Any QNames supplied as Strings (e.g. for the template name)

Run the XSLT by calling the named template.

MUST be resolvable as a QName without extra information, so they must be prefix-less (so, ‘name’, and never ‘ns:name’)

Parameters:

  • template_name (String, Saxon::QName, nil) (defaults to: nil) —

    the name of the template to be invoked. Passing nil will invoke the default named template (xsl:default-template)

  • opts (Hash) (defaults to: {}) —

    a hash of options for invoking the transformation

Options Hash (opts):

  • :raw (Boolean) — default: 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.

  • :mode (String, Saxon::QName) —

    The name of the initial mode to use when processing starts.

  • :global_parameters (Hash<String, Saxon::QName => Object>) —

    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 Compiler‘s context.

  • :initial_template_parameters (Hash<String, Saxon::QName => Object>) —

    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 Compiler‘s context.

  • :initial_template_tunnel_parameters (Hash<String, Saxon::QName => Object>) —

    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 Compiler‘s context.

Returns:



137
138
139
 
# File 'lib/saxon/xslt/executable.rb', line 137

def call_template(template_name = nil, opts = {})
  transformation(opts).call_template(template_name)
end

#serialize(doc_node) ⇒ String

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

Parameters:

Returns:

  • (String) —

    a serialization of the the input document



45
46
47
48
49
 
# File 'lib/saxon/nokogiri.rb', line 45

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

#serializer ⇒ Saxon::Serializer::Object

Create a Serializer::Object configured using the options that were set by <xsl:output>.

Returns:



171
172
173
 
# File 'lib/saxon/xslt/executable.rb', line 171

def serializer
  Saxon::Serializer::Object.new(@s9_xslt_executable.load30.newSerializer)
end

#to_java ⇒ net.sf.saxon.s9api.XsltExecutable

Returns the underlying Saxon XsltExecutable.

Returns:

  • (net.sf.saxon.s9api.XsltExecutable) —

    the underlying Saxon XsltExecutable



178
179
180
 
# File 'lib/saxon/xslt/executable.rb', line 178

def to_java
  @s9_xslt_executable
end

#transform(doc_node, params = {}) ⇒ Saxon::XDM::Value

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

Parameters:

  • doc_node (Saxon::XDM::Node) —

    the document to transform

  • params (Hash, Array) (defaults to: {}) —

    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

Returns:



17
18
19
 
# File 'lib/saxon/nokogiri.rb', line 17

def transform(doc_node, params = {})
  apply_templates(doc_node, v1_parameters(params)).xdm_value
end