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