saxon-rb

saxon-rb – An idiomatic Ruby wrapper for Saxon

saxon-rb aims to be a fully-featured idiomatic wrapper for the Saxon XML processing and transformation library. Built after several years experience with writing, using, and maintaining the saxon-xslt XSLT-focussed wrapper, saxon-rb aims to keep that ease-of-use for those most common cases, while making the less-common cases easy as well.

Saxon provides a massive amount of valuable functionality beyond simple XSLT compilation and invocation, and a lot of that is very hard to use from Ruby. The facilities provided by it, and by the XSLT 2 and 3 specs, rely heavily on the XDM values and types system, which saxon-rb makes easy to work with.

Parameter creation and passing, are richer and more expressive; results from XSLT, or XPath, that aren't just result trees can be worked with directly in Ruby.

You can find Saxon HE at http://saxon.sourceforge.net/ and Saxonica at http://www.saxonica.com/

Saxon HE is (c) Michael H. Kay and released under the Mozilla MPL 1.0 (http://www.mozilla.org/MPL/1.0/)

Installation

Add this line to your application's Gemfile:

gem 'saxon-rb'

And then execute:

$ bundle

Or install it yourself as:

$ gem install saxon-rb

Simple usage

Parse an XML document

Using a default document builder from the default processor:

document_node = Saxon::Processor.create.document_builder.build(Saxon::Source.from_path('/path/to/your.xml'))

Or

document_node = Saxon.XML('/path/to/your.xml')

Transform an XML document with XSLT

transformer = Saxon::Processor.create.xslt_compiler.compile(Saxon::Source.from_path('/path/to/your.xsl'))
# Or
transformer = Saxon.XSLT('/path/to/your.xsl')

# Apply templates against a document
result_1 = transformer.apply_templates(document_node)

# Call a template without a context item to process
result_2 = transformer.call_template('main-template')

Run XPath queries against an XML document

processor = Saxon::Processor.create
xpath = processor.xpath_compiler.compile('//element[@attr = $a:var]')

matches = xpath.evaluate(document_node)

Migrating from saxon-xslt (or Nokogiri)

saxon-xslt wrapped Saxon and provided a Nokogiri-esque API. Nokogiri is built on XSLT 1 processors, and the APIs support XSLT 1 features, but won't allow XSLT 2/3 features (like setting initial tunnel parameters, starting processing by calling a named template, or a function). The main API for invoking XSLT in saxon-rb needs to be different from Nokogiri's so that full use of XSLT 2/3 features is possible.

By default, the original saxon-xslt API (on Saxon::XSLT::Stylesheet) is not available. If you need those methods, then you can load the legacy API by requiring saxon/nokogiri.

That gives you back the #transform, #apply_to, and #serialize methods on the object you get back after compiling an XSLT: Saxon::XSLT::Executable in saxon-rb. They work the same way, and you should be able to drop in saxon-rb as a replacement for XSLT processing.

require 'saxon-rb'
require 'saxon/nokogiri'

xslt = Saxon.XSLT('/path/to/my.xsl')
xslt.apply_to(Saxon.XML('/path/to/my.xml')) #=> "<result-xml/>"

Usage

XSLT

Using XSLT involves creating a compiler, compiling an XSLT document, and then using that compiled document to transform something.

Constructing a Compiler

The simplest way is to call #xslt_compiler on a Saxon::Processor instance.

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 the DSL RDoc for complete details):

compiler = processor.xslt_compiler {
  static_parameters 'param' => 'value'
  default_collation 'https://www.w3.org/2005/xpath-functions/collation/html-ascii-case-insensitive/'
}

The static context for a Compiler cannot be changed, you must create a new one with the context you want. We make it very simple to create a new Compiler based on an existing one. Declaring a parameter again overwrites the 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

Compiling an XSLT stylesheet

Once you have a compiler, call #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.

Executing an XSLT stylesheet

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. See Setting parameters for details.

To serialize the document you can, of course, just call #to_s on the result:

result = xslt.apply_templates(input)
puts result.to_s #=> '<?xml version="1.0"...'

You can also serialize directly to a file path or to any IO instance.

result = xslt.apply_templates(input)
result.serialize('/path/to/output.xml')

result_2 = xslt.apply_templates(input)
result_2.serialize($stderr)

You can override serialization options that were set by <xsl:output/> in your XSLT:

result = xslt.apply_templates(input)
result.serialize('/path/to/output.xml') {
  output_property[:indent] = 'yes'
}

You can also obtain the result of the transform as an XDM Value:

result = xslt.apply_templates(input)
result.xdm_value #=> #<Saxon::XDM::Node...>

You also have easy access to provide an instance of a class implementing Saxon's net.sf.saxon.s9api.Destination interface:

dom_document = javax.xml.parsers.DocumentBuilderFactory.newInstance.builder.newDocument
destination = Saxon::S9API::DOMDestination.new(dom_document)
result = xslt.apply_templates(input).to_destination(destination)

Setting parameters

There are four kinds of parameters you can set: Static parameters, which are set at stylesheet compile time and cannot be changed after compilation. Global parameters defined by top-level <xsl:parameter/> are available throughout an XSLT, and they can be set when the compiled XSLT is run. The other two kinds of 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.

# At 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'
}

# At execution time
xslt.apply_templates(input, {
  global_parameters: {'param' => 'global value'},
  initial_template_parameters: {'param' => 'other value'},
  initial_template_tunnel_parameters: {'param' => 'tunnel value'}
})

Multiple parameters can be set:

# At compile time
xslt = compiler.compile(source) {
  global_parameters 'param-1' => 'a', 'param-2' => 'b'
}

# At execution time
xslt.apply_templates(input, {
  global_parameters: {'param-1' => 'a', 'param-2' => 'b'}
})

Parameter names in XSLT are QNames, and values are an XDM Value. saxon-rb will convert Ruby values (see {Saxon::QName.resolve} and {Saxon::XDM.Value}). You can also use explicit {Saxon::QName} or XDM values:

compiler.compile(source) {
  global_parameters Saxon::QName.clark('{http://example.org/#ns}name') => Saxon::XDM.Value(1)
}

If you need to use parameter names which use a namespace prefix, you must use an explicit {Saxon::QName} to refer to it.

XPath

Using an XPath involves creating a compiler, compiling an XPath into an executable, and then running that XPath executable against an XDM node.

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.

processor = Saxon::Processor.create
xpath = processor.xpath_compiler {
  namespace a: 'http://example.org/a'
  variable 'a:var', 'xs:string'
}.compile('//a:element[@attr = $a:var]')

matches = xpath.evaluate(document_node, {
  'a:var' => 'the value'
}) #=> Saxon::XDM::Value

The {XPath::Executable#evaluate} method returns an XDM Value containing the result sequence. For a result sequence with multiple items then it'll be a {Saxon::XDM::Value}. A single-item sequence will return an appropriate item instance - a {Saxon::XDM::Node} or a {Saxon::XDM::AtomicValue}.

You can also use the {XPath::Executable#as_enum} to return a lazy enumerator over the result.

Using your Saxon PE license and .jars instead of the bundled Saxon HE

Saxon 9.9 HE is bundled with the gem. To use Saxon PE or EE (the commercial versions) you need to make the .jars available, and then create a licensed Saxon::Configuration object. To make the .jars available is simply a matter of adding them to the CLASS_PATH. The version of Saxon downloaded directly provides several .jar files. We provide a Saxon::Loader method for adding the .jars within the directory correctly. Saxon is distributed through Maven as a single .jar, which you can just add to the LOAD_PATH/CLASS_PATH. If you're adding to the CLASS_PATH directly, or calling Saxon::Loader.load!, then you need to do it before you try and use the library.

Loading a Saxon PE you downloaded directly from Saxonica

require 'saxon-rb'

Saxon::Loader.load!('/path/to/SaxonPE9-9-1-2J') # The folder that contains the .jars, like $SAXON_HOME
config = Saxon::Configuration.create_licensed('/path/to/saxon.lic')
processor = Saxon::Processor.create(config)

processor.xslt_compiler...

Loading a Saxon PE installed via Maven (e.g. with JBundler)

require 'jbundler'
require 'saxon-rb'

config = Saxon::Configuration.create_licensed('/path/to/saxon.lic')
processor = Saxon::Processor.create(config)

...

See https://github.com/mkristian/jbundler for more on loading Java deps from Maven.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/fidothe/saxon-rb. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Saxon-rb project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.