Permalink
Browse files

Add notes on whitespace handling to README, add whitespace example

  • Loading branch information...
benhoyt committed Oct 11, 2012
1 parent 234d7a8 commit 7c7891dbaf6a7eeca8c520e69577968301b9ab3e
Showing with 63 additions and 2 deletions.
  1. +35 −1 README.md
  2. +8 −0 examples/symplates/whitespace.symp
  3. +19 −0 examples/whitespace.py
  4. +1 −1 symplate.py
View
@@ -7,7 +7,7 @@ Symplate is a very simple and very fast Python template language.
* [FAQ](#faq) -- [Who](#who-uses-symplate) | [Why](#why-use-symplate) | [Performance](#isnt-worrying-about-performance-silly)
* [Basic usage](#basic-usage)
* [Compiled Python output](#compiled-python-output)
-* [Syntax](#syntax) -- [Directives](#directives) | [Comments](#comments) | [Literals](#outputting-a-literal----or-)
+* [Syntax](#syntax) -- [Directives](#directives) | [Whitespace](#whitespace-handling) | [Comments](#comments) | [Literals](#outputting-a-literal----or-)
* [Filters](#filters) -- [Default](#the-default-filter) | [Raw](#outputting-raw-strings) | [Setting](#setting-the-filter) | [Overriding](#overriding-the-default-filter)
* [Including sub-templates](#including-sub-templates)
* [Customizing Renderer](#customizing-renderer)
@@ -259,6 +259,40 @@ like in Python. However, there's a special case for the `elif`, `else`,
`except` and `finally` keywords -- they dedent for the line the keyword is on,
and then indent again (just like you would when writing Python).
+### Whitespace handling
+
+Symplate has some very simple rules for whitespace handling. The idea is to do
+what's normal for the common case, but you can always insert extra whitespace
+to get what you want if this doesn't suit. The rules are:
+
+* Eat spaces and tabs at the beginning of `{% ... %}` lines
+* Eat newline character immediately after a closing `%}`, except when the code
+ block is "inline" (that is, when there are non-whitespace characters before
+ the `{%` on the line)
+* All other whitespace Symplate leaves alone
+
+An example which shows all this in action is:
+
+ {% template %}
+ <ul>
+ {% for i in range(10): %}
+ {% if i % 2 == 0: %}
+ <li>{% if i == 0: %}zero{% else: %}{{ str(i) }}{% end if %}</li>
+ {% end if %}
+ {% end for %}
+ </ul>
+
+The above template produces the following output.
+
+ <ul>
+ <li>zero</li>
+ <li>2</li>
+ <li>4</li>
+ <li>6</li>
+ <li>8</li>
+ </ul>
+
+
### Comments
Because `{% ... %}` blocks are simply copied to the compiled template as
@@ -0,0 +1,8 @@
+{% template %}
+<ul>
+{% for i in range(10): %}
+ {% if i % 2 == 0: %}
+ <li>{% if i == 0: %}zero{% else: %}{{ str(i) }}{% end if %}</li>
+ {% end if %}
+{% end for %}
+</ul>
View
@@ -0,0 +1,19 @@
+"""Script to render Symplate whitespace example."""
+
+import os
+import sys
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..'))
+import symplate
+
+renderer = symplate.Renderer(
+ os.path.join(os.path.dirname(__file__), 'symplates'),
+ output_dir=os.path.join(os.path.dirname(__file__), 'symplouts'),
+ check_mtimes=True)
+
+def main():
+ output = renderer.render('whitespace')
+ sys.stdout.write(output.encode('utf-8'))
+
+if __name__ == '__main__':
+ main()
View
@@ -237,7 +237,7 @@ def _render(_renderer, %s):
eol_pos = text.rfind('\n')
if eol_pos >= 0 and text[eol_pos + 1:].isspace():
text = text.rstrip(' \t')
- # eat EOL immediately after a closing %}
+ # eat EOL immediately after a closing %}, unless inline code block
if (text.startswith('\n') and
prev_text.rstrip(' \t').endswith('\n')):
text = text[1:]

0 comments on commit 7c7891d

Please sign in to comment.