trimmer 0.3.6

A whitespace- and memory-friendly template engine
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99

Welcome to Trimmer's documentation!
===================================

Trimmer is a template language that was initially created to make configuration
files. Basically it's template renderer for text files which can also do
very small subset of validations to make process of design of template easier
and safer to use.

Github_ | `API Docs`_ | Crate_

.. _api docs: https://docs.rs/trimmer/
.. _github: https://github.com/tailhook/trimmer/
.. _crate: https://crates.io/crates/trimmer

Contents:

.. toctree::
   :maxdepth: 2

   template_syntax
   changelog

.. _showcase:

Quick showcase:

.. code-block:: bash

    ## syntax: indent
    ## validate default: [^;{}]*  # no ; { } to break nginx syntax
    ## validate ne: [^;{}]+       # non-empty (note plus in regex)
    http {
        ## for server in servers
            ## skip if server.hostname == ""
            server {
                root /var/www;
                server_name
                    ## for name in server.hostnames
                       {{+ server.hostname | ne }}.{{ suffix | ne -}}
                    ## endfor
                ;
                ## if server.ip
                    listen {{ server.ip }}:80;
                ## else
                    listen 80;
                ## endif
            }
        ## endfor
    }

Results in (note the indentation):

.. code-block:: nginx

    http {
        server {
            root /var/www;
            server_name apple.local;
            listen 192.168.0.1:80;
        }
        server {
            root /var/www;
            server_name orange.local plum.local;
            listen 80;
        }
    }

Since v0.3.6 it also works well for HTML and has autoescaping,
here is an example:

.. code-block:: html

    ## syntax: indent
    ## filter default: builtin.html_entities  ### autoescape
    ## validate n: [0-9]+
    <!DOCTYPE html>
    <html>
        <body>
            <h1>{{ title }}</h1>               ### auto escaped
            <div class="user_canvas"
                style="position: absolute;     ### note: it's unsafe to just
                       left: {{ x | n }}px;    ### autoescape values here
                       top: {{ y | n }}px;">
            </div>
        </body>
    </html>

While the validation here looks like excessive (you must prevalidate it in
the app) some time ago we thought that escaping values against XSS manually is
a normal practice, now we always use autoescape. We look at validation of other
values directly in the template as another way to minimize human error.


Indices and tables
==================

* :ref:`genindex`
* :ref:`search`