The Transformer filter provides a variety of transformations that can be
applied to parts of streams that match given XPath expressions. These
transformations can be chained to achieve results that would be comparitively
tedious to achieve by writing stream filters by hand. The approach of chaining
node selection and transformation has been inspired by the jQuery Javascript
library.

For example, the following transformation removes the <title> element from
the <head> of the input document:

Stream filter that can apply a variety of different transformations to
a stream.

This is achieved by selecting the events to be transformed using XPath,
then applying the transformations to the events matched by the path
expression. Each marked event is in the form (mark, (kind, data, pos)),
where mark can be any of ENTER, INSIDE, EXIT, OUTSIDE, or None.

The first three marks match START and END events, and any events
contained INSIDE any selected XML/HTML element. A non-element match
outside a START/END container (e.g. text()) will yield an OUTSIDE
mark.

Each XPath expression determines the set of tags that will be acted upon by
subsequent transformations. In this example we select the <title> text,
copy it into a buffer, then select the <body> element and paste the
copied text into the body as <h1> enclosed text:

Copy (and cut) copy each individual selected object into the
buffer before passing to the next transform. For example, the
XPath *|text() will select all elements and text, each
instance of which will be copied to the buffer individually
before passing to the next transform. This has implications for
how StreamBuffer objects can be used, so some
experimentation may be required.

Specifying accumulate=True, appends all selected intervals onto the
buffer. Combining this with the .buffer() operation allows us operate
on all copied events rather than per-segment. See the documentation on
buffer() for more information.