Overview

=== PFFT - Python Flexible Functional Templating ===
--- (in lack of a decent acronym) ---

*** Introduction
A quick proof-of-concept that generates (X)HTML using a functional-style 
syntax. The goal is to make the syntax follow the structure of the resulting
document, making it visually similar to a templating engine while providing
the full range of functional programming goodness.

*** Requirements
- Python 2.6 or later
- Mercurial if you want to check out the project directly
- Optional: CherryPy 3 (needed for example01)
- Any OS that supports the above

*** Installing
To download from bitbucket using mercurial:
1. cd into the directory of your choice:
	$ cd /where/you/want/it
2. Clone the repository:
	$ hg clone https://bitbucket.org/tdammers/pfft
3. Run the first example:
	$ cd pfft/examples
	$ python ex_simple.py
   This should output a valid HTML document.
   ex_cherry is a small CherryPy web site; if you have CherryPy installed,
   then you can start the server like this:
	$ python ex_cherry.py
   ...and then point a web browser to http://localhost:8080/html

If you want to use PFFT in your own project, copy the pfft directory to a
suitable location - either somewhere on your system's python library path,
or under your project's path.

*** Usage
Import the desired class (HtmlRenderer for HTML 4.01 or XhtmlRenderer for 
XHTML 1.0) from the pfft.renderer module. To generate a document, call
the renderer's html() method. For each element defined by the HTML standard,
the renderer provides a method of the same name, for example, the div() 
method renders a <div> tag. The only exception is the <del> tag; the 
corresponding method is named del_(), because del() would be an illegal name
for a regular method. 
These methods all have the same signature; the first argument may be a 
dictionary of attributes, e.g. {'href':'http://www.example.com/'}. All 
subsequent arguments can be strings, or the return values from other 
methods. If you pass a string, the renderer automatically HTML-encodes it 
to avoid XSS vulnerabilities.
Look at the examples to see how it works.

Additionally, some extra methods are provided to render non-tags:

- HtmlRenderer.ai(text) renders text as-is, bypassing the automatic HTML-
	encoding. Use with precaution.
- HtmlRenderer.comment(text) renders an XML-style comment (<!-- text -->)

*** Examples
There are a few examples in the /examples directory:

- ex_simple.py
A simple command line script that outputs a valid HTML document, touching
pretty much all of PFFT's features.

- ex_cherry.py
Shows how PFFT can be used in a CherryPy website; the html() and xhtml()
methods both render the same document, in HTML 4.01 mode and XHTML 1.0 mode
respectively.

- ex_reuse.py
Demonstrates template reuse through function calls, as well as the use of
python's list comprehension construct for filling a <ul> list.

- ex_inherit.py
Demonstrates template reuse through polymorphic inheritance. It implements
the same web site as the previous example, but uses a different approach.

*** Contributing
For contributions, suggestions, feedback etc., contact the author: 

	Tobias Dammers <tdammers@gmail.com>

*** Licence

Copyright (c) 2011 Tobias Dammers
All rights reserved.

Redistribution and use in source and binary forms, with or without 
modification, are permitted provided that the following conditions are 
met:
1. Redistributions of source code must retain the above copyright notice, 
this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright 
notice, this list of conditions and the following disclaimer in the 
documentation and/or other materials provided with the distribution.
3. Neither the name of the Author nor the names of its contributors may be 
used to endorse or promote products derived from this software without 
specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND ANY 
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 
DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR 
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH 
DAMAGE.