1. Brian Mearns
  2. templ

Commits

Brian Mearns  committed 4182dae

Replaced README with output from README.templ with rest.

  • Participants
  • Parent commits 74bd410
  • Branches default

Comments (0)

Files changed (1)

File README.txt

View file
-..
-    Copyright 2012 Brian Mearns
-    See the end of this file for additional copyright and license information.
-
-===========
-templ
-===========
-
-templ is the TEMplate Processing Language.
-
-templ is a (Turing complete) programming language, used for content generation
-from text-based template files and a simple but powerful processing language
-(**templ** itself) which is embedded directly in the template file.
-
-templ can be used for:
-
-- 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.
-
-Contact Information
-===================
-This project is currently hosted on `bitbucket <https://bitbucket.org>`_, 
-at https://bitbucket.org/bmearns/templ/. The primary author is Brian Mearns:
-you can contact Brian through bitbucket at https://bitbucket.org/bmearns.
-
-Copyright and License
-=====================
-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.
-
-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 http://www.gnu.org/licenses/.
-
-
-
-
-
-===============
-Examples
-===============
-
-Here is an example of basic usage::
-
-    #!/usr/bin/env python
-
-    import templ.templ
-    import templ.functions
-
-    #First, pre-load the stack with a global scope containing all
-    # of the builtin functions, macros, and operators.
-    globs = templ.functions.getGlobalScope()
-
-    #globs is now a dictionary. You could now fill it with your own predefined
-    # data as well, to prepulate variables and functions. but make sure the keys
-    # are instances of ttypes.String, and the values are all TType values.
-
-    #Invoke the templ processor.
-    templ.templ.process(sys.stdin, sys.stdout, [globs], "<stdin>")
-
-The current home of this project is https://bitbucket.org/bmearns/templ/
-
-Template Examples
-=================
-
-The following show some simple example templates and they're output, to give
-an idea of what can be done with templ.
-
-What you can do with templ
---------------------------
-
-The following template is taken from the demo.template file. It just enumerates
-a few of the things you can use templ for.
-
-Here's the code::
-
-    {v {
-        for EXAMPLE {'
-            "Code generation."
-            "Form letters."
-            "Server-side scripting for web servers."
-            "Any other kind of dynamic text-based content generation."
-        }
-        {:
-            {echo "    * "}
-            {echo {get EXAMPLE}}
-            {echo {\n}}
-        }
-    }}
-
-And here's the output::
-
-        * Code generation.
-        * Form letters.
-        * Server-side scripting for web servers.
-        * Any other kind of dynamic text-based content generation.
-
-A Sine Lookup Table
--------------------
-
-Also from demo.template, here's a template that will generate C code that defines
-a lookup table for values of sine::
-
-    /**********************************************/
-    {v {set SIZE 10}
-    }const double sine_lut[{get SIZE}] =
-    \{
-    {for i {range {get SIZE}} {:
-        {echo {join "" {'
-            "    "
-            {round 
-                {sin {div
-                    {mult {get i} 2 {pi}}
-                    {get SIZE}
-                }}
-                4
-            }
-            , {tab} "// i = " {get i}
-            {lnbrk}
-        }}}
-    }}
-    \};
-    /**********************************************/
-
-And the outut::
-
-    /**********************************************/
-    const double sine_lut[10] =
-    {
-        0.0,	// i = 0
-        0.5878,	// i = 1
-        0.9511,	// i = 2
-        0.9511,	// i = 3
-        0.5878,	// i = 4
-        -0.0,	// i = 5
-        -0.5878,	// i = 6
-        -0.9511,	// i = 7
-        -0.9511,	// i = 8
-        -0.5878,	// i = 9
-
-    };
-    /**********************************************/
-
-
-Embedded Data
--------------
-
-And a final example from demo.template, this shows how you can embed data directly
-in the template file, so that, for instance, only one file needs to be kept under
-source control instead of one for the data, and one for the template that uses it::
-
-    ###############################################
-    {v {set YEAR 2012}
-    }{v
-    {set DATA {'
-        %   Name            Month       Year        Score
-        {'  "Alan T."       June        1912        61  }
-        {'  "John B."       December    1924        53  }
-        {'  "John von N."   December    1903        47  }
-        {'  "Claude S"      April       1916        59  }
-    }}
-    }{
-       for ROW {get DATA}
-       {echo {join "" 
-    <<<User "{at 0 {get ROW}}" (age {
-        sub {get YEAR} {at 2 {get ROW}}
-        }) has a score of: {at 3 {get ROW}}
-    >>>
-        }}
-    }###############################################
-
-The output::
-
-    ###############################################
-    User "Alan T." (age 100) has a score of: 61
-    User "John B." (age 88) has a score of: 53
-    User "John von N." (age 109) has a score of: 47
-    User "Claude S" (age 96) has a score of: 59
-    ###############################################
-
-
-..
-    Copyright and License information.
-..
-    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/>.
-
-
+1: Introduction
+---------------
+
+\ **templ**\  is the \ **Tem**\ plate \ **P**\ rocessing \ **L**\ anguage. 
+
+
+
+\ ``templ``\  is a (Turing complete) programming language, used for content generation
+from text-based template files and a simple but powerful processing language
+(\ ``templ``\  itself) which is embedded directly in the template file. 
+
+
+
+\ ``templ``\  can be used for: 
+
+- 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.
+
+1.1: Contact Information
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+This project is currently hosted on `bitbucket <https://bitbucket.org>`_, 
+at `https://bitbucket.org/bmearns/templ/ <https://bitbucket.org/bmearns/templ/>`_. The primary author is Brian Mearns:
+you can contact Brian through bitbucket at `https://bitbucket.org/bmearns <https://bitbucket.org/bmearns>`_. 
+
+1.2: Copyright and License
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+\ ``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. 
+
+
+
+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 `http://www.gnu.org/licenses/ <http://www.gnu.org/licenses/>`_. 
+
+2: Examples
+-----------
+
+The following show some simple example templates and they're output, to give
+an idea of what can be done with templ.
+
+2.1: Templ Basics
+~~~~~~~~~~~~~~~~~ 
+            
+
+The following template shows some of the basic elements of \ ``templ``\  templates:
+
+
+            
+
+::
+
+    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}}} {\n}}
+    }
+    
+    {$ :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} "..." {\n}}
+    
+                %return value
+                {+ {cos {$ :RADS}} {sin {$ :RADS}} }
+            }
+        }
+    }}{wrap "{" "}" {implode {glue "," {\n} "    "} {gen
+        :T
+        {range 40 80 10}
+        {join ":" {$ :T} {:MY-FUNC {$ :T}}}
+    }}}
+    
+
+            
+
+The output looks like this:
+
+
+            
+
+::
+
+    Hello, World!
+    My Name is templ. I am the TEMplate Processing Language.
+    Sometimes, templ likes to speak in the third person.
+    
+    templ can do math:
+        1 + 1 = 2
+        1 + 2 = 3
+        2 + 3 = 5
+        3 + 5 = 8
+        etc...
+    
+    templ can operate on strings and lists:
+        bananas
+        [a, b, c, d, e, f]
+    
+    templ can do conditional processing:
+        Phew!
+    
+    templ can loop (and do trig):
+        sin(0) = 0.0
+        sin(10) = 0.173648177667
+        sin(20) = 0.342020143326
+        sin(30) = 0.5
+    
+    
+    templ can even do list comprehensions and user defined functions:
+    Processing theta=40...
+    Processing theta=50...
+    Processing theta=60...
+    Processing theta=70...
+    {40:1.40883205281,
+        50:1.40883205281,
+        60:1.36602540378,
+        70:1.28171276411}
+        
+        
+2.2: Code Generation - A Sine Lookup Table
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
+            
+
+The following template shows an example of how to use \ ``templ``\ 
+                    to generate C-code, in this case a sine lookup table.
+
+
+            
+
+::
+
+    {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"
+            {lnbrk}
+        }}
+    }}\};
+    
+
+            
+
+The output looks like this:
+
+
+            
+
+::
+
+    const double sine_lut[10] =
+    {
+        0.0,	// i = 0, theta = 0 deg
+        0.5878,	// i = 1, theta = 36 deg
+        0.9511,	// i = 2, theta = 72 deg
+        0.9511,	// i = 3, theta = 108 deg
+        0.5878,	// i = 4, theta = 144 deg
+        -0.0,	// i = 5, theta = 180 deg
+        -0.5878,	// i = 6, theta = 216 deg
+        -0.9511,	// i = 7, theta = 252 deg
+        -0.9511,	// i = 8, theta = 288 deg
+        -0.5878,	// i = 9, theta = 324 deg
+    };
+        
+
+2.3: Embedded Data
+~~~~~~~~~~~~~~~~~~ 
+            
+
+
+                    The next example shows how \ ``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.
+                    
+
+
+            
+
+::
+
+    
+    {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." {\n} }
+    }}
+
+            
+
+It produces this:
+
+
+            
+
+::
+
+    
+    Alan T., age 100 years.
+    John V., age 108 years.
+    Claude S., age 96 years.
+    George B., age 196 years.
+    George B., age 196 years.
+    Ada L., age 196 years.
+    Charles B., age 220 years.
+    Donald K., age 74 years.
+    Dennis R., age 70 years.
+    
+        
+    
+2.4: Programmatic Invocation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
+
+The real power of \ ``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 \ ``templ``\  \ *is*\  Turing complete, and you \ *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.
+                
+
+
+