Commits

Brian Mearns committed ae077df

Lots more in the tutorial.

  • Participants
  • Parent commits fc4c621

Comments (0)

Files changed (3)

File templ/tbuiltin.py

 class xBlock(texec.TOperator):
     """
     {block [EXPR0 [EXPR1 [...]]]}
-        Aliases "::"
-        :Like scope except that a new scope is NOT created.
+        Like scope except that a new scope is NOT created.
     """
     __mnemonics__ = ("block", ":", "exp.block")
     def execute(self, name, args, ostream, stack):

File templ/test.templ

-{quote "foo\"bar"}
+{dont
+    Block comments are good for long comments,
+    Because they can span multiple lines.
+    {
+        They need to be well-formed, but not necessarily valid code.
+    }
+    {dont
+        You can nest them as well, which is helpful for commenting out large
+        blocks of code, even if the block already includes comments.
+    }
+    % For malformed code, like if you have an extra } or {, for instance,
+    % you can also include end-of-line comments in block comments.
+}

File templ/tutorial.templ

 }{
 }{include rest.itmpl}{
 }{v {:
+    {$ TEMPLATE-CODE {lambda
+        {' :TEMPLATE }
+        {pre {' :syntax templ} {$ :TEMPLATE }}
+    }}
+
     {$ EXAMPLE-TEMPLATE {lambda
         {' :SYNTAX :INTRO :OUTRO :TEMPLATE }
         {implode <<<
             {p {' {$ :INTRO}}}
-            {pre
-                {' :syntax templ}
-                {$ :TEMPLATE}
-            }
+            {TEMPLATE-CODE {$ :TEMPLATE}}
 
             {p {' {$ :OUTRO}}}
             {pre
 Text is simply raw (more-or-less) content that will be written to the output stream. Statements are
 {templ} code that the processor will evaluate in order to determine the output, as well as its own
 behavior. What distinguishes a statement from text is that statements are wrapped in curly braces: "\{" and "\}".
-Anything that's not wrapped in curly braces is treated as text and is copied very nearly verbatim to the
+Anything that's not wrapped in curly braces is treated as text and is copied very-nearly verbatim to the
 output (more on all of these qualifications later).>>>
             }
 
 
                 }}
             }}
-
         }} % end section "...Processing Routine"
 
+        {section "Comments" {'
+
+            {p
+<<<Sometimes, even the best formatting can't make the intentions of your code clear, and it helps to be able to explain yourself
+in prose. Most programming languages provide a syntax for comments, and {templ} is no exception. When the {templ} parser encounters
+a percent-sign character, "%", anywhere inside an expression except for in a quoted string, the subsequent characters up to and
+including the end of the current line is treated as a comment. The comment is ignored by the processor, as if the entire thing
+(including the initial "%" character) was just whitespace. One thing to note is that comments do function as {em separators}
+between String values, just like whitespace characters.>>>
+            }
+
+            {EXAMPLE-TEMPLATE "text"
+                {implode
+<<<You can put whatever you want in a comment: the processor won't attempt to evaluate it, and the parser won't try to parse it, 
+except to find the end of the line. That means you don't have to worry about it being well formed, and you can use comments
+to comment out mis-formed code during debugging.>>>
+                }
+
+                {}
+
+"If you're having trouble with malformed code, for instance if you've lost track of
+whether or not a string is properly escaped or not, {echo 
+    %\"like \\\"this\\\" one for instance, \\\"
+}you can comment it out for debugging."
+            }
+
+            {section "Block Comments - The \"Dont\" Operator" {'
+
+                {p
+<<<End-of-line comments are helpful for short comments and because the contents don't need to be well formed, but they're tedious
+if you want to write long comments across multiple lines. {templ} provides an operator called {code dont} which can be used for multi-line, or 
+{em block} comments. The argument elements in a {code dont} expression are {em not evaluated}, and the result of the entire expression
+is a special {code Null} value which we'll learn more about later. In other words, a {code dont} expression doesn't do anything, which
+makes it useful for long comments.>>>
+                }
+
+                {p
+<<<However, unlike end-of-line comments, the parser doesn't know about the {code dont} operator, so the entire expression must be wellformed.
+The contents of the expression don't need to be evaluatable, but they do need to be parseable. The upside is that {code dont} expressions can
+be nested without any issues, unlike block-comments in certain other programming languages.>>>
+                }
+
+                {p
+<<<For instance, the following template is {em malformed}: {templ} will err if you try to process this template, even though the malformed code
+is in a {code dont} expression.>>>
+                }
+
+                {TEMPLATE-CODE
+"{dont
+    Please don't evaluate {this code
+}"
+                }
+
+                {p
+<<<This next template, on the other hand, works fine, because we used an end-of-line comment to take care of that extra open curly brace.>>>
+                }
+
+                {TEMPLATE-CODE
+"{dont
+    % Please don't parse {this code
+}"
+                }
+
+                {p
+<<<Finally, here is an in-depth example of a {em working} block comment:>>>
+                }
+
+                {TEMPLATE-CODE
+"{dont
+    Block comments are good for long comments,
+    Because they can span multiple lines.
+    {
+        They need to be well-formed, but not necessarily valid code.
+    }
+    {dont
+        You can nest them as well, which is helpful for commenting out large
+        blocks of code, even if the block already includes comments.
+    }
+    % For malformed code, like if you have an extra } or {, for instance,
+    % you can also include end-of-line comments in block comments.
+}"
+                }
+
+                {p
+<<<As mentioned, {code dont} expressions evaluate to a Null type value. Despite being null, the result is still
+a value, and {em will} act as an element in an element in a List, so you have to be careful about where you place
+them. For instance, assuming the {code one-arg} executable only accepts one argument, the following template will
+err because the {code dont} expression looks like another argument:>>>
+                }
+
+                {TEMPLATE-CODE
+"{one-arg Foobar {dont ...Block Comment... }}"
+                }
+
+                {p
+<<<At the top level, Null typed values simply act as empty strings, so you can put {code dont} expressions
+at the top level of your template without any harm. We'll see other places it's safe to use them later when we learn about
+the {code block} operator.>>>
+                }
+
+            }} % end section "Block Comments"
+
+        }} %end section "Comments"
+
+        {section "About all Those Qualifications on Text Elements" {'
+
+            {p
+<<<So we mentioned that text elements at the top level of a template file are just a nice easy way to specify content to put
+in the output stream when there's no special processing that requires {templ} expressions. But we also kept qualifying them
+as "more-or-less [raw]" and "very-nearly verbatim".>>>
+            }
+
+            {p
+<<<Hopefully you're getting an idea now of why we needed to add all of these qualifications, small as they may be. There's
+one particular character that can't be used directly in text elements: the open curly brace. If you try to just stick an
+open curly brace in a text element, the {templ} parser will see it as the start of a List expression. So if you want to put
+an open curly brace in the text, you need to escape it with a leading backslash, just like you escape double-quote characters
+in quoted-strings.>>>
+            }
+
+            {p
+<<<But backslash escaping does not work in general in text elements: that would be too much of a burden when you're writing
+a text element if you have to escape every occurence of a backslash. Instead, a backslash in a text element only serves as
+an escape when it immediately precedes an open curly brace or, for symmetry, a closing curly brace. Note that it is not
+{em necessary} to escape closing curly braces, but it is recommended just for visual consistency with open curly braces.>>>
+            }
+
+            {EXAMPLE-TEMPLATE "text"
+                {implode
+<<<Otherwise, a backslash in a text element is simply a backslash: no need to escape it and it doesn't have any effect on
+non-curly brace subsequent characters. Take a look at this example which only contains a text element:>>>
+                }
+
+                {implode
+<<<The output is shown below. It looks a lot like the input template: the only difference is that the backslashes before the
+curly braces at the end of the template are not included in the output, because they were only used to escape the curly braces.>>>
+                }
+
+"Unix paths use (forward) slashes: \"/usr/bin/templ\". Windows uses backslashes: \"C:\\Windows\\\".
+templ uses a lot (a LOT) of curly braces, which look like \\{ and \\}."
+            }
+        }} % end section "All those Qualifications..."
+
     }} %end section "Introduction"
+
+
+    {section "Variables" {'
+
+        {p
+<<<It wouldn't be much of a programming language without a way to store and recall data. {templ} uses a structure
+called {em the stack} to store what are effectively variables. We'll see more about this later, but >>>
+        }
+
+    '}}
         
 }}{#