Portal Transforms section
=========================

A portal transforms pipeline section lets you use Portal Transforms to
transform item values. The portal transforms section blueprint name is
``plone.app.transmogrifier.portaltransforms``.

What values to transform is determined by the ``keys`` option, which takes a
set of newline-separated key names. If a key name starts with ``re:`` or
``regexp:`` it is treated as a regular expression instead.

You can specify what transformation to apply in two ways. Firstly, you can
directly specify a transformation by naming it with the ``transform`` option;
the named transformation is run directly. Alternatively you can let the portal
transforms tool figure out what transform to use by specifying ``target`` and
an optional ``from`` mimetype. The portal transforms tool will select one or
more transforms based on these mimetypes, and if no ``from`` option is given
the original item value is used to determine one.

Also optional is the ``condition`` option, which lets you specify a TALES
expression that when evaluating to False will prevent any transformations from
happening. The condition is evaluated for every matched key.

>>> ptransforms = """
... [transmogrifier]
... pipeline =
...     source
...     transform-id
...     transform-title
...     transform-status
...     printer
... 
... [source]
... blueprint = collective.transmogrifier.sections.tests.samplesource
... encoding = utf8
... 
... [transform-id]
... blueprint = plone.app.transmogrifier.portaltransforms
... transform = identity
... keys = id
...
... [transform-title]
... blueprint = plone.app.transmogrifier.portaltransforms
... target = text/plain
... keys = title
... 
... [transform-status]
... blueprint = plone.app.transmogrifier.portaltransforms
... from = text/plain
... target = text/plain
... keys = status
... 
... [printer]
... blueprint = collective.transmogrifier.sections.tests.pprinter
... """
>>> registerConfig(u'plone.app.transmogrifier.tests.ptransforms',
...                ptransforms)
>>> transmogrifier(u'plone.app.transmogrifier.tests.ptransforms')
{'id': "Transformed 'foo' using the identity transform",
 'status': "Transformed '\\xe2\\x84\\x97' from text/plain to text/plain",
 'title': "Transformed 'The Foo Fighters \\xe2\\x84\\x97' to text/plain"}
{'id': "Transformed 'bar' using the identity transform",
 'status': "Transformed '\\xe2\\x84\\xa2' from text/plain to text/plain",
 'title': "Transformed 'Brand Chocolate Bar \\xe2\\x84\\xa2' to text/plain"}
{'id': "Transformed 'monty-python' using the identity transform",
 'status': "Transformed '\\xc2\\xa9' from text/plain to text/plain",
 'title': 'Transformed "Monty Python\'s Flying Circus \\xc2\\xa9" to text/plain'}

The ``condition`` expression has access to the following:

=================== ==========================================================
 ``item``            the current pipeline item
 ``key``             the name of the matched key
 ``match``           if the key was matched by a regular expression, the match
                     object, otherwise boolean True
 ``transmogrifier``  the transmogrifier
 ``name``            the name of the splitter section
 ``options``         the splitter options
 ``modules``         sys.modules
=================== ==========================================================
