cmlenz@1: # -*- coding: utf-8 -*-
cmlenz@1: #
cmlenz@1: # Copyright (C) 2006 Christopher Lenz
cmlenz@1: # All rights reserved.
cmlenz@1: #
cmlenz@1: # This software is licensed as described in the file COPYING, which
cmlenz@1: # you should have received as part of this distribution. The terms
cmlenz@27: # are also available at http://markup.cmlenz.net/wiki/License.
cmlenz@1: #
cmlenz@1: # This software consists of voluntary contributions made by many
cmlenz@1: # individuals. For the exact contribution history, see the revision
cmlenz@27: # history and logs, available at http://markup.cmlenz.net/log/.
cmlenz@1: 
cmlenz@19: from markup.core import Attributes, Namespace, QName, Stream
cmlenz@1: 
cmlenz@1: __all__ = ['Fragment', 'Element', 'tag']
cmlenz@1: 
cmlenz@1: 
cmlenz@1: class Fragment(object):
cmlenz@28:     """Represents a markup fragment, which is basically just a list of element
cmlenz@28:     or text nodes.
cmlenz@28:     """
cmlenz@1:     __slots__ = ['children']
cmlenz@1: 
cmlenz@1:     def __init__(self):
cmlenz@1:         self.children = []
cmlenz@1: 
cmlenz@65:     def __add__(self, other):
cmlenz@65:         return Fragment()(self, other)
cmlenz@65: 
cmlenz@65:     def __call__(self, *args):
cmlenz@65:         for arg in args:
cmlenz@65:             self.append(arg)
cmlenz@65:         return self
cmlenz@65: 
cmlenz@65:     def __iter__(self):
cmlenz@65:         return iter(self.generate())
cmlenz@65: 
cmlenz@65:     def __repr__(self):
cmlenz@65:         return '<%s>' % self.__class__.__name__
cmlenz@65: 
cmlenz@65:     def __str__(self):
cmlenz@65:         return str(self.generate())
cmlenz@65: 
cmlenz@65:     def __unicode__(self):
cmlenz@65:         return unicode(self.generate())
cmlenz@65: 
cmlenz@1:     def append(self, node):
cmlenz@1:         """Append an element or string as child node."""
cmlenz@1:         if isinstance(node, (Element, basestring, int, float, long)):
cmlenz@1:             # For objects of a known/primitive type, we avoid the check for
cmlenz@1:             # whether it is iterable for better performance
cmlenz@1:             self.children.append(node)
cmlenz@1:         elif isinstance(node, Fragment):
cmlenz@1:             self.children += node.children
cmlenz@1:         elif node is not None:
cmlenz@1:             try:
cmlenz@1:                 children = iter(node)
cmlenz@1:             except TypeError:
cmlenz@1:                 self.children.append(node)
cmlenz@1:             else:
cmlenz@1:                 for child in node:
cmlenz@1:                     self.append(children)
cmlenz@1: 
cmlenz@1:     def generate(self):
cmlenz@28:         """Return a markup event stream for the fragment."""
cmlenz@1:         def _generate():
cmlenz@1:             for child in self.children:
cmlenz@1:                 if isinstance(child, Fragment):
cmlenz@1:                     for event in child.generate():
cmlenz@1:                         yield event
cmlenz@1:                 else:
cmlenz@17:                     yield Stream.TEXT, unicode(child), (-1, -1)
cmlenz@1:         return Stream(_generate())
cmlenz@1: 
cmlenz@1: 
cmlenz@1: class Element(Fragment):
cmlenz@1:     """Simple XML output generator based on the builder pattern.
cmlenz@1: 
cmlenz@1:     Construct XML elements by passing the tag name to the constructor:
cmlenz@1: 
cmlenz@1:     >>> print Element('strong')
cmlenz@1:     <strong/>
cmlenz@1: 
cmlenz@1:     Attributes can be specified using keyword arguments. The values of the
cmlenz@1:     arguments will be converted to strings and any special XML characters
cmlenz@1:     escaped:
cmlenz@1: 
cmlenz@1:     >>> print Element('textarea', rows=10, cols=60)
cmlenz@1:     <textarea rows="10" cols="60"/>
cmlenz@1:     >>> print Element('span', title='1 < 2')
cmlenz@1:     <span title="1 &lt; 2"/>
cmlenz@1:     >>> print Element('span', title='"baz"')
cmlenz@1:     <span title="&#34;baz&#34;"/>
cmlenz@1: 
cmlenz@1:     The " character is escaped using a numerical entity.
cmlenz@1:     The order in which attributes are rendered is undefined.
cmlenz@1: 
cmlenz@1:     If an attribute value evaluates to `None`, that attribute is not included
cmlenz@1:     in the output:
cmlenz@1: 
cmlenz@1:     >>> print Element('a', name=None)
cmlenz@1:     <a/>
cmlenz@1: 
cmlenz@1:     Attribute names that conflict with Python keywords can be specified by
cmlenz@1:     appending an underscore:
cmlenz@1: 
cmlenz@1:     >>> print Element('div', class_='warning')
cmlenz@1:     <div class="warning"/>
cmlenz@1: 
cmlenz@1:     Nested elements can be added to an element using item access notation.
cmlenz@1:     The call notation can also be used for this and for adding attributes
cmlenz@1:     using keyword arguments, as one would do in the constructor.
cmlenz@1: 
cmlenz@1:     >>> print Element('ul')(Element('li'), Element('li'))
cmlenz@1:     <ul><li/><li/></ul>
cmlenz@1:     >>> print Element('a')('Label')
cmlenz@1:     <a>Label</a>
cmlenz@1:     >>> print Element('a')('Label', href="target")
cmlenz@1:     <a href="target">Label</a>
cmlenz@1: 
cmlenz@1:     Text nodes can be nested in an element by adding strings instead of
cmlenz@1:     elements. Any special characters in the strings are escaped automatically:
cmlenz@1: 
cmlenz@1:     >>> print Element('em')('Hello world')
cmlenz@1:     <em>Hello world</em>
cmlenz@1:     >>> print Element('em')(42)
cmlenz@1:     <em>42</em>
cmlenz@1:     >>> print Element('em')('1 < 2')
cmlenz@1:     <em>1 &lt; 2</em>
cmlenz@1: 
cmlenz@1:     This technique also allows mixed content:
cmlenz@1: 
cmlenz@1:     >>> print Element('p')('Hello ', Element('b')('world'))
cmlenz@1:     <p>Hello <b>world</b></p>
cmlenz@1: 
mgood@34:     Quotes are not escaped inside text nodes:
mgood@34:     >>> print Element('p')('"Hello"')
mgood@34:     <p>"Hello"</p>
mgood@34: 
cmlenz@1:     Elements can also be combined with other elements or strings using the
cmlenz@1:     addition operator, which results in a `Fragment` object that contains the
cmlenz@1:     operands:
cmlenz@1:     
cmlenz@1:     >>> print Element('br') + 'some text' + Element('br')
cmlenz@1:     <br/>some text<br/>
cmlenz@1:     
cmlenz@1:     Elements with a namespace can be generated using the `Namespace` and/or
cmlenz@1:     `QName` classes:
cmlenz@1:     
cmlenz@1:     >>> from markup.core import Namespace
cmlenz@1:     >>> xhtml = Namespace('http://www.w3.org/1999/xhtml')
cmlenz@1:     >>> print Element(xhtml.html, lang='en')
cmlenz@1:     <html lang="en" xmlns="http://www.w3.org/1999/xhtml"/>
cmlenz@1:     """
cmlenz@1:     __slots__ = ['tag', 'attrib']
cmlenz@1: 
cmlenz@1:     def __init__(self, tag_, **attrib):
cmlenz@1:         Fragment.__init__(self)
cmlenz@1:         self.tag = QName(tag_)
cmlenz@1:         self.attrib = Attributes()
cmlenz@1:         self(**attrib)
cmlenz@1: 
cmlenz@1:     def __call__(self, *args, **kwargs):
cmlenz@1:         for attr, value in kwargs.items():
cmlenz@1:             if value is None:
cmlenz@1:                 continue
cmlenz@1:             attr = attr.rstrip('_').replace('_', '-')
cmlenz@1:             self.attrib.set(attr, value)
cmlenz@1:         return Fragment.__call__(self, *args)
cmlenz@1: 
cmlenz@65:     def __repr__(self):
cmlenz@65:         return '<%s "%s">' % (self.__class__.__name__, self.tag)
cmlenz@65: 
cmlenz@1:     def generate(self):
cmlenz@28:         """Return a markup event stream for the fragment."""
cmlenz@1:         def _generate():
cmlenz@1:             yield Stream.START, (self.tag, self.attrib), (-1, -1)
cmlenz@1:             for kind, data, pos in Fragment.generate(self):
cmlenz@1:                 yield kind, data, pos
cmlenz@1:             yield Stream.END, self.tag, (-1, -1)
cmlenz@1:         return Stream(_generate())
cmlenz@1: 
cmlenz@1: 
cmlenz@1: class ElementFactory(object):
cmlenz@28:     """Factory for `Element` objects.
cmlenz@28:     
cmlenz@28:     A new element is created simply by accessing a correspondingly named
cmlenz@28:     attribute of the factory object:
cmlenz@28:     
cmlenz@28:     >>> factory = ElementFactory()
cmlenz@28:     >>> print factory.foo
cmlenz@28:     <foo/>
cmlenz@28:     >>> print factory.foo(id=2)
cmlenz@28:     <foo id="2"/>
cmlenz@28:     
cmlenz@28:     A factory can also be bound to a specific namespace:
cmlenz@28:     
cmlenz@28:     >>> factory = ElementFactory('http://www.w3.org/1999/xhtml')
cmlenz@28:     >>> print factory.html(lang="en")
cmlenz@28:     <html lang="en" xmlns="http://www.w3.org/1999/xhtml"/>
cmlenz@28:     
cmlenz@28:     The namespace for a specific element can be altered on an existing factory
cmlenz@28:     by specifying the new namespace using item access:
cmlenz@28:     
cmlenz@28:     >>> factory = ElementFactory()
cmlenz@28:     >>> print factory.html(factory['http://www.w3.org/2000/svg'].g(id=3))
cmlenz@28:     <html><g id="3" xmlns="http://www.w3.org/2000/svg"/></html>
cmlenz@28:     
cmlenz@28:     Usually, the `ElementFactory` class is not be used directly. Rather, the
cmlenz@28:     `tag` instance should be used to create elements.
cmlenz@28:     """
cmlenz@1: 
cmlenz@19:     def __init__(self, namespace=None):
cmlenz@28:         """Create the factory, optionally bound to the given namespace.
cmlenz@28:         
cmlenz@28:         @param namespace: the namespace URI for any created elements, or `None`
cmlenz@28:             for no namespace
cmlenz@28:         """
cmlenz@20:         if namespace and not isinstance(namespace, Namespace):
cmlenz@19:             namespace = Namespace(namespace)
cmlenz@19:         self.namespace = namespace
cmlenz@19: 
cmlenz@19:     def __getitem__(self, namespace):
cmlenz@28:         """Return a new factory that is bound to the specified namespace."""
cmlenz@19:         return ElementFactory(namespace)
cmlenz@19: 
cmlenz@19:     def __getattr__(self, name):
cmlenz@28:         """Create an `Element` with the given name."""
cmlenz@19:         return Element(self.namespace and self.namespace[name] or name)
cmlenz@1: 
cmlenz@1: 
cmlenz@1: tag = ElementFactory()