2004
Colin Adams and others
Colin
Adams
colin@colina.demon.co.uk Sunday, October 31st, 2004

# Creating a Transformer

Once the XSLT processor is configured, you then need to create an executable version of your XSLT stylesheet or transform, and an `XM_XSLT_TRANSFORMER` to use it.

The first step is to create an an `XM_XSLT_TRANSFORMER_FACTORY`. You simply call make, passing it the configuration you created in the previous step. By default, this caches compiled stylesheets for you. You can change this behaviour at any time by calling set_caching (on_or_off: BOOLEAN).

Then you call create_new_transformer. This takes a `XM_XSLT_SOURCE` as a parameter, so you first have to create one to represent your stylesheet. If you are starting with a URI, then you do this by creating a `XM_XSLT_URI_SOURCE`, passing it the URI of your text file, as an absolute URI.

If instead, you wish to transform a source document according to any xml-stylesheet processing instructions contained within it, then you should first call associated_stylesheet to create the `XM_XSLT_SOURCE`. This takes the URI of the source document as the first argument, the medium for the transformed document as the second argument, and an `XM_XSLT_PI_CHOOSER` as the third argument. This last argument is to allow choosing between alternate stylesheets. See Associating Style Sheets with XML documents for an understanding of what is involved.

The transformer factory either sets was_error, or else the new transformer is made available in created_transformer.

The compiled stylesheets are re-usable (which is why they are cached). To re-use one, simply call create_new_transformer again with an `XM_XSLT_SOURCE` that has the same URI.

However, you should not attempt to run two transformations at once (not even if they involve different stylesheets).

If you reuse a transformer, then before calling transform a second time, you may wish to call clear_document_pool. This clears all document nodes from memory, and destroys the mapping of URIs to document nodes. The reasons you might want to do this are:

- To save memory (and hence garbage collection cycles) by throwing away documents which will not be used again.

- If you reuse the same URIs to refer to different documents from one transformation to another. This is a doubtful practice, but if you insist on doing it then you must call clear_document_pool otherwise you will get incorrect results.

In general, it is better to not call clear_document_pool, as you will then get better performance if you reuse a document (for example, by using the document() function), as the transformer will not have to parse the document afresh.