Saxon::Xslt

Wraps the Saxon 9 XSLT processor Java API so it's easy to use from your JRuby project, with an API modelled on Nokogiri's.

Saxon is a Java library, so saxon-xslt only runs under JRuby.

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-xslt'

And then execute:

$ bundle

Or install it yourself as:

$ gem install saxon-xslt

Simple usage

require 'saxon-xslt'
transformer = Saxon.XSLT(File.open('/path/to/your.xsl'))
input = Saxon.XML(File.open('/path/to/your.xml'))
output = transformer.transform(input)

XSL parameters can be passed to #transform as a flat array of name, value pairs, or as a hash. name can be either a string or a symbol, e.g.

output = transformer.transform(input, ["my-param", "'my-value'",
                                       :'my-other-param', "/take-from@id"])

# or

output = transformer.transform(input, {"my-param" => "'my-value'",
                                       :'my-other-param' => "/select-from@id",
                                       my_third_param: "'value-again'"})

For those familiar with the Saxon API, names are passed directly to the QName constructor.

Values are evaluated as XPath expressions in context of the document being transformed; this means that, to pass a string, you must pass an XPath that resolves to a string, i.e. "'You must wrap strings in quotes'"

Differences between Saxon and Nokogiri

Saxon uses a Processor class as its central object: it holds configuration information and acts as a Factory for creating documents or XSLT stylesheet compilers. Unless you need to tweak the config you don't need to worry about this – saxon-xslt creates a shared instance behind the scenes when you call Saxon.XSLT or Saxon.XML. If you need to change the configuration you can create your own instance of Saxon::Processor and pass it an open File pointing at a Saxon configuration file. (See http://www.saxonica.com/documentation/index.html#!configuration/configuration-file for details of the configuration file.) Once you have a Saxon::Processor instance you can call the XML and XSLT methods on it directly:

require 'saxon-xslt'
processor = Saxon::Processor.create(File.open('/path/to/config.xml'))
transformer = processor.XSLT(File.open('/path/to/your.xsl'))
input = processor.XML(File.open('/path/to/your.xml'))
output = transformer.transform(input)

System IDs

XML has this idea of 'Public' and 'System' identifiers for documents. The public ID is a kind of abstract name and the system ID is a URI, for example:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
            "http://www.w3.org/TR/html4/loose.dtd">

There the Public ID is -//W3C//DTD HTML 4.01 Transitional//EN and the System ID is http://www.w3.org/TR/html4/loose.dtd. An XML or XSLT processor uses the System ID as a base URI for resolving linked objects, e.g. <xsl:import> or <xsl:include> calls with relative URIs.

With Nokogiri the System ID for a document is inferred from its file path, if you hand in a File object to Nokogiri::XML. With saxon-xslt you can also explicitly set the System ID:

xslt = Saxon.XSLT("<xsl:stylesheet>...</xsl:stylesheet>",
  system_id: "/path/to/resources/file.xsl")

So, if you have other XSLT stylesheets in /path/to/resources/ then your dynamically generated XSLT can refer to them with import statements like <xsl:import href="other_stylesheet.xsl"/>.

Saxon versions (HE, PE, EE)

saxon-xslt 0.8.2 includes Saxon HE 9.8.0.6 - you don't need to download Saxon yourself. Saxon PE and EE are paid-for versions with more features.

If you have a license for Saxon PE or EE, then you can use them by passing their location and the location of your .lic license file in as follows:

require 'saxon-xslt'

# Tell us where your Saxon Jars are.
Saxon::Loader.load!('/path/to/dir/containing/saxon-jars')
# Create a licensed Configuration object
config = Saxon::Configuration.create_licensed('/path/to/saxon-license.lic')
# Create a Processor from your licensed Configuration
processor = Saxon::Processor.create(config)
# Go!
transformer = processor.XSLT(File.open('/path/to/your.xsl'))

Contributing

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request

saxon-xslt