Source

templ / misc / README.core.templ

The default branch has multiple heads

Full commit
{#
    Copyright 2013 Brian Mearns

    This file is part of templ.

    templ is free software: you can redistribute it and/or modify
    it under the terms of the GNU Affero General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    templ is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU Affero General Public License for more details.

    You should have received a copy of the GNU Affero General Public License
    along with templ.  If not, see <http://www.gnu.org/licenses/>.
}{
}{v
    {$ EXAMPLE-TEMPLATE {lambda
        {' :SYNTAX :INTRO :OUTRO :TEMPLATE }
        {implode <<<
            {p {' {$ :INTRO}}}
            {pre
                {' :syntax templ}
                {$ :TEMPLATE}
            }

            {p {' {$ :OUTRO}}}
            {pre
                {' :syntax {$ :SYNTAX}}
                {buffer {eval {$ :TEMPLATE}}}
            }
        >>> }
    }}
}{doc "templ - Template Processing Language"

%Body content
{'

    {section "Introduction" {'

        {p 
<<<{b templ} is the {b Tem}plate {b P}rocessing {b L}anguage. >>>
        }
        
        {p
<<<{code templ} is a (Turing complete) programming language, used for content generation
from text-based template files and a simple but powerful processing language
({code templ} itself) which is embedded directly in the template file. >>>
        }
        
        {p <<<{code templ} can be used for: {ul {'
    "Code generation."
    "Form letters."
    "Server-side scripting for web servers."
    "Customized markup with variant output formats."
    "Any other kind of dynamic text-based content generation."
            }}>>>     
        }


        {section "Contact Information" {'

            {p <<<This project is currently hosted on {link bitbucket "https://bitbucket.org"}, 
at {link "https://bitbucket.org/bmearns/templ/"}. The primary author is Brian Mearns:
you can contact Brian through bitbucket at {link "https://bitbucket.org/bmearns"}. >>>
            }

        }}

        {section "Copyright and License" {'

            {p <<<{code templ} is {em "free software"}: you can redistribute it and/or modify
it under the terms of the {b GNU Affero General Public License} as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version. >>> }

            {p <<<{code templ} is distributed in the hope that it will be useful,
but {b without any warranty}; without even the implied warranty of
{em merchantability} or {em fitness for a particular purpose}.  See the
GNU Affero General Public License for more details. >>> }

            {p <<<A copy of the GNU Affero General Public License is available in the templ
distribution under the file LICENSE.txt. If you did not receive a copy of
this file, see {link "http://www.gnu.org/licenses/"}. >>> }
        }}



    }} %end section intro

    {section "Examples" {'

        {p
    <<<The following show some simple example templates and they're output, to give
an idea of what can be done with templ.>>>
        }


        {section "Templ Basics"
            <<< {EXAMPLE-TEMPLATE
                "text"
                {implode <<<The following template shows some of the basic elements of {code templ} templates:>>>}
                "The output looks like this:"
"Hello, World!
My Name is {set :NAME \"templ\"}. I am the TEMplate Processing Language.
Sometimes, {$ :NAME} likes to speak in the third person.

{$ :NAME} can do math:
    1 + 1 = {+ 1 1}
    1 + 2 = {+ 1 2}
    2 + 3 = {+ 2 3}
    3 + 5 = {+ 3 5}
    etc...

{$ :NAME} can operate on strings and lists:
    {implode \"a\" {' b n n s}}
    {str {cat {' a b c } {' d e f } }}

{$ :NAME} can do conditional processing:
    {if
        {== {+ 2 2} 5}
        \"Oh No!\"

        {== {+ 2 2} 4}
        \"Phew!\"

        \"How did I get here?\"
    }

{$ :NAME} can loop (and do trig):
{for :THETA {range 0 40 10} {
    echo \"    sin(\" {$ :THETA} \") = \" {sin {rad {$ :THETA}}} {eol}}
}

{$ :NAME} can even do list comprehensions and user defined functions:
{v {set
    :MY-FUNC
    {lambda
        {' :THETA }
        {:
            {let :RADS}
            {$ :RADS {rad {$ :THETA}}}

            {echo \"Processing theta=\" {$ :THETA} \"...\" {eol}}

            %return value
            {+ {cos {$ :RADS}} {sin {$ :RADS}} }
        }
    }
}}{wrap \"{\" \"}\" {implode {glue \",\" {eol} \"    \"} {gen
    :T
    {range 40 80 10}
    {join \":\" {$ :T} {:MY-FUNC {$ :T}}}
}}}
"
        }
        
>>> } % end section "Basics"

        {section "Code Generation - A Sine Lookup Table"
            <<< {EXAMPLE-TEMPLATE
                c
                {implode
<<<The following template shows an example of how to use {code templ}
to generate C-code, in this case a sine lookup table.>>>
                }
                "The output looks like this:"
"{v
    {set :SIZE 10}
}const double sine_lut[{get :SIZE}] =
\\{
{for i {range {get :SIZE}} {::
    {let :THETA}
    {$ :THETA {mult
        {$ i}
        {div 360 {$ :SIZE}}
    }}
    {spit {'
        \"    \"
        {round 
            {sin {rad {$ :THETA}}}
            4
        }
        ,
        {\\t}
        \"// i = \"
        {get i}
        \", theta = \"
        {$ :THETA}
        \" deg\"
        {eol}
    }}
}}\\};
" }

>>> } % end section "Code Generation..."


        {section "Embedded Data"
            <<< {EXAMPLE-TEMPLATE
                c
                {implode
<<<The next example shows how {code templ} allows you to easily embed data
directly in the template file that uses it, allowing you to keep just
one file under version control, for instance. >>>
                }
                "It produces this:"
                "
{v
    %Embedded data
    {$ :DATA {'
        %   Name            Year    Month (-1)      Date
        {'  \"Alan T.\"     1912    05              23 }
        {'  \"John V.\"     1903    11              28 }
        {'  \"Claude S.\"   1916    03              30 }
        {'  \"George B.\"   1815    10              2  }
        {'  \"George B.\"   1815    10              2  }
        {'  \"Ada L.\"      1815    11              15 }
        {'  \"Charles B.\"  1791    11              26 }
        {'  \"Donald K.\"   1938    0               10 }
        {'  \"Dennis R.\"   1941    8               9  }
    }}
}{for :ROW {$ :DATA} {:
    {$ :STAMP {stamp {slice 1 {$ :ROW}}}}
    {$ :NOW {stamp}}
    {$ :AGE {floor {div {- {$ :NOW} {$ :STAMP}} {* 60 60 24 365.25}}}}
    {echo {@ 0 {$ :ROW}} \", age \" {$ :AGE} \" years.\" {eol} }
}}"
    }
    
>>> } % end section "Embedded Data"


        {section "Programmatic Invocation"
            <<<{p 
<<<The real power of {code templ} comes from the programmatic interface,
which allows you to predefine symbols, and even executables (functions, macros
and operators) in python, which are then accessible from the template.
Because, although {code templ} {em is} Turing complete, and you {em could} do all
of your processing directly in the template (or a separate included template), doing
advanced data processing in python can help keep your template files simpler. >>>
            }>>>}

    }} %end section Examples

}}{#
 vim: set ft=templ:
}