evandrix/API Transformations

## API Transformations
Select		Transformation
Invert		Transformation
End		Transformation
Empty		Transformation
Remove	Transformation
Unwrap	Transformation
Wrap		Transformation
Trace		Transformation
Filter		Transformation
Map		Transformation
Substitute	Transformation
Rename	Transformation
Injector	Transformation
Replace	Transformation

Before	Transformation
After		Transformation
Prepend	Transformation
Append	Transformation
Attr		Transformation
StreamBuffer
	append
	reset
Copy		Transformation
Cut		Transformation

In addition, you can also perform custom transformations. For example, the following defines a transformation that changes the name of a tag:
>>> from genshi import QName
>>> from genshi.filters.transform import ENTER, EXIT

>>> class RenameTransformation(object):
...    def __init__(self, name):
...        self.name = QName(name)
...    def __call__(self, stream):
...        for mark, (kind, data, pos) in stream:
...            if mark is ENTER:
...                data = self.name, data[1]
...            elif mark is EXIT:
...                data = self.name
...            yield mark, (kind, data, pos)
A transformation can be any callable object that accepts an augmented event stream. In this case we define a class, so that we can initialize it with the tag name.
Custom transformations can be applied using the apply() method of a transformer instance:
>>> xform = Transformer('body//em').map(unicode.upper, TEXT) \
>>> xform = xform.apply(RenameTransformation('u'))
>>> print(html | xform)
<html>
  <head><title>Some Title</title></head>
  <body>
    Some <u>BODY</u> text.
  </body>
</html>

SelectTransformation
Select and mark events that match an XPath expression.
InvertTransformation
Invert selection so that marked events become unmarked, and vice versa.
Specifically, all input marks are converted to null marks, and all input null marks are converted to OUTSIDE marks.
EndTransformation
	End the current selection.
EmptyTransformation
	Empty selected elements of all content.
RemoveTransformation
	Remove selection from the stream.
UnwrapTransformation
	Remove outermost enclosing elements from selection.
WrapTransformation
	Wrap selection in an element.
TraceTransformation
	Print events as they pass through the transform.
FilterTransformation
	Apply a normal stream filter to the selection. The filter is called once for each 	selection.
MapTransformation
	Apply a function to the data element of events of kind in the selection.
SubstituteTransformation
	Replace text matching a regular expression.
	Refer to the documentation for re.sub() for details.
RenameTransformation
	Rename matching elements.
InjectorTransformation
Abstract base class for transformations that inject content into a stream.
>>> class Top(InjectorTransformation):
...     def __call__(self, stream):
...         for event in self._inject():
...             yield event
...         for event in stream:
...             yield event
>>> html = HTML('<body>Some <em>test</em> text</body>', encoding='utf-8')
>>> print(html | Transformer('.//em').apply(Top('Prefix ')))
Prefix <body>Some <em>test</em> text</body>
ReplaceTransformation
	Replace selection with content.
BeforeTransformation
	Insert content before selection.
AfterTransformation
	Insert content after selection.
PrependTransformation
	Prepend content to the inside of selected elements.
AppendTransformation
	Append content after the content of selected elements.
AttrTransformation
	Set an attribute on selected elements.
StreamBuffer
	Stream event buffer used for cut and copy transformations.
append(self, event)
Add an event to the buffer.
param event:
the markup event to add
reset(self)
Empty the buffer of events.
CopyTransformation
	Copy selected events into a buffer for later insertion.
CutTransformation
	Cut selected events into a buffer for later insertion and remove the selection.

## genshi.filters.transform.py
"""
   A filter for functional-style transformations of markup streams.

   The //Transformer// filter provides:
   * a variety of transformations
   * applied to parts of streams which match XPath expressions
   * chainable (inspired by jQuery)
"""

- //Transformer//
  """
     Stream filter that can apply a variety of different transformations to a stream.

     This is achieved by:
     * select events to be transformed, using XPath
     * apply the transformations to selected elements
     * `Marked Event` = { (mark, (kind, data, pos)) }
          - mark = { ENTER | INSIDE | EXIT | OUTSIDE | None }
     * `builder` module generates streams: `tag.h1('Title')`
     * buffered: `buffer = StreamBuffer()`
     * can be assigned to vars / reused +clear buffer between transforms if necessary
  """
  == Instance Methods ==
  - apply(self, function)
	"""Apply a transformation to the stream."""

  == Selection operations ==
  - select(self, path)
	"""Mark events matching the given XPath expression, within the current selection.	"""
  - invert(self)
	"""Invert selection so that marked events become unmarked, and vice versa.	"""
  - end(self)
	"""End current selection, allowing all events to be selected.	"""

  == Deletion operations ==
  - empty(self)
	"""Empty selected elements of all content.	"""
  - remove(self)
	"""Remove selection from the stream.	"""

  == Direct element operations ==
  - unwrap(self)
	"""Remove outermost enclosing elements from selection.	"""
  - wrap(self, element)
	"""Wrap selection in an element.	"""

  == Content insertion operations ==
  - replace(self, content)
	"""Replace selection with content.	"""
  - before(self, content)
	"""Insert content before selection.	"""
  - after(self, content)
	"""Insert content after selection.	"""
  - prepend(self, content)
	"""Insert content after the ENTER event of the selection.	"""
  - append(self, content)
	"""Insert content before the END event of the selection.	"""

  == Attribute manipulation ==
  - attr(self, name, value)
	"""Add, replace or delete an attribute on selected elements.	"""

  == Buffer operations ==
  - copy(self, buffer, accumulate=False)
	"""Copy selection into buffer.	"""
  - cut(self, buffer, accumulate=False)
	"""Copy selection into buffer and remove the selection from the stream.	"""
  - buffer(self)
	"""Buffer the entire stream (can consume a considerable amount of memory).	"""

  == Miscellaneous operations ==
  - filter(self, filter)
	"""Apply a normal stream filter to the selection.	"""
  - map(self, function, kind)
	"""Applies a function to the data element of events of kind in the selection.	"""
  - substitute(self, pattern, replace, count=1)
	"""Replace text matching a regular expression.	"""
  - rename(self, name)
	"""Rename matching elements.	"""
  - trace(self, prefix='', fileobj=None)
	"""Print events as they pass through the transform.	"""

  == Properties ==
	"""transforms"""

== Helper methods ==
- TransformMark:
     """A mark on a transformation stream."""
- PushBackStream
     """Allows a single event to be pushed back onto the stream and re-consumed."""
     `push(self, event)`
	Select Transformation
	Invert Transformation
	End Transformation
	Empty Transformation
	Remove Transformation
	Unwrap Transformation
	Wrap Transformation
	Trace Transformation
	Filter Transformation
	Map Transformation
	Substitute Transformation
	Rename Transformation
	Injector Transformation
	Replace Transformation

	Before Transformation
	After Transformation
	Prepend Transformation
	Append Transformation
	Attr Transformation
	StreamBuffer
	append
	reset
	Copy Transformation
	Cut Transformation

	In addition, you can also perform custom transformations. For example, the following defines a transformation that changes the name of a tag:
	>>> from genshi import QName
	>>> from genshi.filters.transform import ENTER, EXIT

	>>> class RenameTransformation(object):
	... def __init__(self, name):
	... self.name = QName(name)
	... def __call__(self, stream):
	... for mark, (kind, data, pos) in stream:
	... if mark is ENTER:
	... data = self.name, data[1]
	... elif mark is EXIT:
	... data = self.name
	... yield mark, (kind, data, pos)
	A transformation can be any callable object that accepts an augmented event stream. In this case we define a class, so that we can initialize it with the tag name.
	Custom transformations can be applied using the apply() method of a transformer instance:
	>>> xform = Transformer('body//em').map(unicode.upper, TEXT) \
	>>> xform = xform.apply(RenameTransformation('u'))
	>>> print(html \| xform)
	<html>
	<head><title>Some Title</title></head>
	<body>
	Some <u>BODY</u> text.
	</body>
	</html>

	SelectTransformation
	Select and mark events that match an XPath expression.
	InvertTransformation
	Invert selection so that marked events become unmarked, and vice versa.
	Specifically, all input marks are converted to null marks, and all input null marks are converted to OUTSIDE marks.
	EndTransformation
	End the current selection.
	EmptyTransformation
	Empty selected elements of all content.
	RemoveTransformation
	Remove selection from the stream.
	UnwrapTransformation
	Remove outermost enclosing elements from selection.
	WrapTransformation
	Wrap selection in an element.
	TraceTransformation
	Print events as they pass through the transform.
	FilterTransformation
	Apply a normal stream filter to the selection. The filter is called once for each selection.
	MapTransformation
	Apply a function to the data element of events of kind in the selection.
	SubstituteTransformation
	Replace text matching a regular expression.
	Refer to the documentation for re.sub() for details.
	RenameTransformation
	Rename matching elements.
	InjectorTransformation
	Abstract base class for transformations that inject content into a stream.
	>>> class Top(InjectorTransformation):
	... def __call__(self, stream):
	... for event in self._inject():
	... yield event
	... for event in stream:
	... yield event
	>>> html = HTML('<body>Some <em>test</em> text</body>', encoding='utf-8')
	>>> print(html \| Transformer('.//em').apply(Top('Prefix ')))
	Prefix <body>Some <em>test</em> text</body>
	ReplaceTransformation
	Replace selection with content.
	BeforeTransformation
	Insert content before selection.
	AfterTransformation
	Insert content after selection.
	PrependTransformation
	Prepend content to the inside of selected elements.
	AppendTransformation
	Append content after the content of selected elements.
	AttrTransformation
	Set an attribute on selected elements.
	StreamBuffer
	Stream event buffer used for cut and copy transformations.
	append(self, event)
	Add an event to the buffer.
	param event:
	the markup event to add
	reset(self)
	Empty the buffer of events.
	CopyTransformation
	Copy selected events into a buffer for later insertion.
	CutTransformation
	Cut selected events into a buffer for later insertion and remove the selection.
	"""
	A filter for functional-style transformations of markup streams.

	The //Transformer// filter provides:
	* a variety of transformations
	* applied to parts of streams which match XPath expressions
	* chainable (inspired by jQuery)
	"""

	- //Transformer//
	"""
	Stream filter that can apply a variety of different transformations to a stream.

	This is achieved by:
	* select events to be transformed, using XPath
	* apply the transformations to selected elements
	* `Marked Event` = { (mark, (kind, data, pos)) }
	- mark = { ENTER \| INSIDE \| EXIT \| OUTSIDE \| None }
	* `builder` module generates streams: `tag.h1('Title')`
	* buffered: `buffer = StreamBuffer()`
	* can be assigned to vars / reused +clear buffer between transforms if necessary
	"""
	== Instance Methods ==
	- apply(self, function)
	"""Apply a transformation to the stream."""

	== Selection operations ==
	- select(self, path)
	"""Mark events matching the given XPath expression, within the current selection. """
	- invert(self)
	"""Invert selection so that marked events become unmarked, and vice versa. """
	- end(self)
	"""End current selection, allowing all events to be selected. """

	== Deletion operations ==
	- empty(self)
	"""Empty selected elements of all content. """
	- remove(self)
	"""Remove selection from the stream. """

	== Direct element operations ==
	- unwrap(self)
	"""Remove outermost enclosing elements from selection. """
	- wrap(self, element)
	"""Wrap selection in an element. """

	== Content insertion operations ==
	- replace(self, content)
	"""Replace selection with content. """
	- before(self, content)
	"""Insert content before selection. """
	- after(self, content)
	"""Insert content after selection. """
	- prepend(self, content)
	"""Insert content after the ENTER event of the selection. """
	- append(self, content)
	"""Insert content before the END event of the selection. """

	== Attribute manipulation ==
	- attr(self, name, value)
	"""Add, replace or delete an attribute on selected elements. """

	== Buffer operations ==
	- copy(self, buffer, accumulate=False)
	"""Copy selection into buffer. """
	- cut(self, buffer, accumulate=False)
	"""Copy selection into buffer and remove the selection from the stream. """
	- buffer(self)
	"""Buffer the entire stream (can consume a considerable amount of memory). """

	== Miscellaneous operations ==
	- filter(self, filter)
	"""Apply a normal stream filter to the selection. """
	- map(self, function, kind)
	"""Applies a function to the data element of events of kind in the selection. """
	- substitute(self, pattern, replace, count=1)
	"""Replace text matching a regular expression. """
	- rename(self, name)
	"""Rename matching elements. """
	- trace(self, prefix='', fileobj=None)
	"""Print events as they pass through the transform. """

	== Properties ==
	"""transforms"""

	== Helper methods ==
	- TransformMark:
	"""A mark on a transformation stream."""
	- PushBackStream
	"""Allows a single event to be pushed back onto the stream and re-consumed."""
	`push(self, event)`