Skip to content
Browse files

DRAFT-1: All core syntax docs are available.

  • Loading branch information...
1 parent fbcd7b5 commit 631e923d80101f31c11f7f2c36328d4b9a571777 @supernovus committed Nov 30, 2011
Showing with 318 additions and 24 deletions.
  1. +2 −0 TODO
  2. +1 −1 VERSION
  3. +33 −16 bin/build.pl
  4. +39 −1 src/comments.tmpl
  5. +4 −0 src/common.tmpl
  6. +30 −3 src/conditional.tmpl
  7. +25 −2 src/nested.tmpl
  8. +184 −1 src/syntax.tmpl
View
2 TODO
@@ -0,0 +1,2 @@
+* Write the Extension specs.
+* Clean up specs to use newer template methods introduced during writing.
View
2 VERSION
@@ -1 +1 @@
-VERSION 1-PREDRAFT5
+VERSION 1-DRAFT1
View
49 bin/build.pl
@@ -24,10 +24,24 @@ sub output_html {
$garden->addGlobal('VERSION', $version);
-my $only; ## If this is set we only build this page.
-if (@ARGV) { $only = $ARGV[0]; }
+my $toc = 0; ## Build table of contents?
+my $sp = 0; ## Build single page?
+my $all = 0; ## Build ALL pages?
+my %build; ## Specific pages to build.
+if (@ARGV) {
+ for my $arg (@ARGV) {
+ given ($arg) {
+ when (/^\-t/) { $toc = 1; }
+ when (/^\-s/) { $sp = 1; }
+ when (/^\-a/) { $all = 1; }
+ default {
+ $build{$_} = 1;
+ }
+ }
+ }
+}
-if (!defined $only) {
+if ($toc || $all) {
say "Building table of contents.";
my $tocpage = $garden->get('index');
my $tochtml = $tocpage->render(sections=>$pages);
@@ -37,23 +51,26 @@ sub output_html {
for my $section (@{$pages}) {
for my $page (@{$section->{pages}}) {
if (exists $page->{file}) {
- if (defined $only && $only ne $page->{file}) { next; }
- say "Building " . $page->{file} . '.';
- my $tempname = $page->{file} . "/Page";
- my $title = $page->{name};
- my $template = $garden->get($tempname);
- my $html = $template->render(title=>$title);
- output_html($page->{file}, $html);
+ if ($all || exists $build{$page->{file}}) {
+ say "Building " . $page->{file} . '.';
+ my $tempname = $page->{file} . "/Page";
+ my $title = $page->{name};
+ my $template = $garden->get($tempname);
+ my $html = $template->render(title=>$title);
+ output_html($page->{file}, $html);
+ }
}
}
}
-say "Building single page version.";
-my $single = $garden->get('single_page/index');
-$garden->addGlobal('lookup', sub { return $_[0]."/content"; } );
-pop(@{$pages});
-my $single_html = $single->render(sections=>$pages);
-output_html('single_page', $single_html);
+if ($sp || $all) {
+ say "Building single page version.";
+ my $single = $garden->get('single_page/index');
+ $garden->addGlobal('lookup', sub { return $_[0]."/content"; } );
+ pop(@{$pages});
+ my $single_html = $single->render(sections=>$pages);
+ output_html('single_page', $single_html);
+}
say "Done building pages.";
View
40 src/comments.tmpl
@@ -2,7 +2,45 @@ import "common" :export
content () {{
<p>
-Describe how comments and notes work here.
+The ability to make notes in your templates, either for documentation
+or to add a private TODO note for yourself, is very useful.
+Sometimes you even want to be able to comment out an entire section of your
+template while testing things. Both of these abilities are possible in
+Garden, with a configurable syntax too boot.
</p>
+<p class="note">
+All of the comment related syntax below applies inside template and
+dictionary blocks.
+You can use them outside of blocks, but it's not really necessary, as
+any text outside a block that isn't a statement, or a block definition,
+is ignored.
+</p>
+<h4>Notes</h4>
+<p>
+A note is a quick comment, that ends with a newline character.
+In Garden, the note prefix must either be the first character of the
+line, or have white space in front of it to be recognized.
+</p>
+<code class="block">
+<i class="t">myTemplate</i> () `st()`
+Hello World `note()` <tt>Everything after the `note()` marks is a note comment.</tt>
+`note()` <tt>This line in its entirety is a note comment.</tt>
+This is not a comment.
+`et()`
+</code>
+`custOne(symb=syntax.note)`
+<h4>Comment Blocks</h4>
+<p>
+If you want to comment out an entire block, you can do so with special
+comment symbols:
+</p>
+<code class="block">
+<i class="t">myTemplate</i> () `st()`
+Hello `sc()` <tt>Everything past that symbol is a comment.
+Including this line.
+And this text.</tt> `ec()` World. (This is not a comment.)
+`et()`
+</code>
+`custTwo(start=syntax.sc, end=syntax.ec)`
}}
View
4 src/common.tmpl
@@ -92,3 +92,7 @@ The <i class="s">`symb`</i> symbol is customizable. `refOver()`
</p>
}}
+var (x) {{ <i class="v">`x`</i> }}
+tmpl (x) {{ <i class="t">`x`</i> }}
+stmt (x) {{ <code class="b">`x`</code> }}
+
View
33 src/conditional.tmpl
@@ -69,11 +69,37 @@ variables as you want between the separator (`csep()`), as long as you have
at least that many templates after the apply symbol (`apply()`). You can always
supply one extra template to be used if none of the variables are true.
</p>
+<h4>Negative Conditions</h4>
+<p>
+Sometimes instead of testing to see if something is true, you may want to
+see if it is false instead. This is possible by prefixing the condition
+variable with the negation symbol (`neg()`).
+</p>
+<code class="block">
+`ask3()``tem1()``csep()``tem2()``csep()``temf()``es()`
+</code>
+<p>
+This is similar to the elseif example, except that instead of testing to see
+if `var2()` is true, it tests to see if it is false. So the only way the
+`temf()` template will ever be called is if `var1()` is false and `var2()` is
+true.
+</p>
+
+<h4>Chained Comparisions</h4>
+
<p class="note">
-This version of Garden has no support for comparison operators. In a future
-version, I may add an extension to allow something that allows a limited
+This version of Garden has no support for comparison operators, or
+chained (complex) tests. So there's no way to do things like
+<code class="block">
+if ((var1 &gt; var2) and (var2 &lt; var3)) { show_this_template; }
+</code>
+without putting the comparison logic in the controller. I'm not really sure
+if this is something that belongs in the template language. At this point
+I've left it out, as something that is best handled in the controller.
+In a future version, I may add an extension to allow something
+that allows a limited
form of chained comparison operators into the template language itself.
-What form it will take is yet undecided.
+If I add it, and what form it will take is yet undecided.
</p>
}}
@@ -83,6 +109,7 @@ var1 () {{ <i class="v">var1</i> }}
var2 () {{ <i class="v">var2</i> }}
ask1 () {{ `ask()``var()``apply()` }}
ask2 () {{ `ask()``var1()``csep()``var2()``apply()` }}
+ask3 () {{ `ask()``var1()``csep()``neg()``var2()``apply()` }}
temt () {{ <i class="t">trueTemplate()</i> }}
temf () {{ <i class="t">falseTemplate()</i> }}
tem1 () {{ <i class="t">templateOne()</i> }}
View
27 src/nested.tmpl
@@ -35,10 +35,33 @@ To do this, we specify the parameters in the template call signature.
<p>
Here our <i class="t">firstTemplate</i> is making a call to
<i class="t">secondTemplate</i>, passing the <i class="v">company</i>
-variable through directly (as long as two templates have variables of
-the same name, this is possible) and passing the <i class="v">user.name</i>
+variable through directly and passing the <i class="v">user.name</i>
variable through as <i class="v">name</i> which is what
<i class="t">secondTemplate</i> is looking for.
</p>
+<p>
+Using named parameters when possible is recommended. If you don't use named
+parameters, then how what you pass is determined to be a parameter will
+depend on context. If you pass a variable with the same name as a parameter
+in the template you are calling, it will be assumed to be that parameter,
+regardless of order. If it isn't, it will be assumed to be a positional
+parameter. This can be used with literals to create easy template sections.
+For instance:
+</p>
+<code class="block">
+`tmpl(myTemplate)` (`var(name)`) `st()`
+Yeah, so `ss()`name`es()` said: `ss()`b(Hello)`es()`
+`et()`
+
+`tmpl(text)` (`var(y)`) `st()` &lt;strong&gt;`ss()`text`es()`&lt;/strong&gt; `et()`
+
+`sc()` <tt>Given a name of Bob, will result in:
+ Yeah, so Bob said: &lt;strong&gt;Hello&lt;/strong&gt;</tt> `ec()`
+</code>
+<p class="note">
+Using literal text as parameters rather than variables, has several
+limitations, and does not handle text with spaces in it.
+The use of dictionaries is recommended instead of literal text.
+</p>
}}
View
185 src/syntax.tmpl
@@ -2,7 +2,190 @@ import "common" :export
content () {{
<p>
-Describe how to customize the syntax here.
+So, in all of the documentation up to now, you've probably seen notes
+saying that certain symbols are overridable. This is to make it so that
+your templates can customize what characters are considered <em>syntax</em>
+versus <em>content</em>. The default have been designed to be fairly
+non-conflicting with most markup languages, but I can't claim to forsee every
+possible use of Garden, so making it as flexible as possible was a primary
+design principle.
</p>
+
+<h4>Template Block Markers</h4>
+<p>
+The <code class="b">block</code> statement is used to override
+the `st()` and `et()` symbols:
+</p>
+<code class="block">
+<b>block</b> "`cst()`", "`cet()`"
+
+<i class="t">myTemplate</i> (name) `cst()`
+Hello `ss()`name`es()`
+`cet()`
+</code>
+
+<h4>Dictionary Block Markers</h4>
+<p>
+The <code class="b">dictblock</code> statement is used to override
+the `sd()` and `ed()` symbols:
+</p>
+<code class="block">
+<b>dictblock</b> "`csd()`", "`ced()`"
+
+<i class="d">myDict</i> `csd()`
+ "<i>name</i>" : "Tim"
+ "<i>job</i>" : "Programmer"
+`ced()`
+</code>
+
+<h4>Template Statements Markers</h4>
+<p>
+The <code class="b">delimiters</code> statement is used to override
+the `ss()` and `es()` symbols:
+</p>
+<code class="block">
+<b>delimiters</b> "`css()`", "`ces()`"
+
+<i class="t">myTemplate</i> (name) `st()`
+Hello `css()`name`ces()`
+`et()`
+</code>
+
+<h4>Note Symbol</h4>
+<p>
+The <code class="b">note</code> statement is used to override
+the `note()` symbol:
+</p>
+<code class="block">
+<b>note</b> "`cnote()`"
+
+<i class="t">myTemplate</i> () `st()`
+Hello World `cnote()` This is a note-style comment.
+`et()`
+</code>
+
+<h4>Comment Block Markers</h4>
+<p>
+The <code class="b">comment</code> statement is used to override
+the `sc()` and `ec()` symbols:
+</p>
+<code class="block">
+<b>comment</b> "`csc()`", "`cec()`"
+
+<i class="t">myTemplate</i> () `st()`
+`csc()` <tt>This is a long
+multilined comment
+that goes on for a while.</tt> `cec()`
+Hello World
+`et()`
+</code>
+
+<h4>The Apply Symbol</h4>
+<p>
+The apply symbol ( `apply()` ) is used both in conditional statement, and in
+recursive template application. The <code class="b">apply</code> statement
+is used to override it:
+</p>
+<code class="block">
+<b>apply</b> "`capply()`"
+
+<i class="t">myTemplate</i> (alist) `st()`
+The list:
+`ss()`alist`capply()`listTemplate(*item)`es()`
+`et()`
+</code>
+
+<h4>Conditional statement marker and separator</h4>
+<p>
+In conditional statements, there are three symbols used, the
+conditional marker: ( `cond()` ), the separator for conditions and templates:
+( `csep()` ), and the apply symbol: ( `apply()` ). We've already seen how
+to override the apply symbol, so we're going to skip it in this example.
+The <code class="b">condition</code> statement allows you to override
+the first two:
+</p>
+<code class="block">
+<b>condition</b> "`ccond()`" "`ccsep()`"
+
+<i class="t">myTemplate</i> (<i class="v">yes</i>, <i class="v">maybe</i>) `st()`
+Are we ready? `ss()``ccond()`<i class="v">yes</i>`ccsep()`<i class="v">maybe</i>`apply()`<i class="t">yesTemplate()</i>`ccsep()`<i class="t">maybeTemplate()</i>`ccsep()`<i class="t">noTemplate()</i>`es()`
+`et()`
+</code>
+
+<h4>Alias Symbol</h4>
+<p>
+The <code class="b">alias</code> statement is used to override
+the alias symbol ( `alias()` ):
+</p>
+<code class="block">
+<b>alias</b> "`calias()`"
+
+`tmpl(myTemplate)` (`var(obj)`) `st()`
+`ss()``var(var)``calias()`<i class="v">obj.nested.member</i>`es()`
+Hello `ss()``var(var)``es()`
+`et()`
+</code>
+
+<h4>Recursive Positional Parameters</h4>
+<p>
+The special recursive parameters all start with the ( `pos()` ) prefix.
+This can be override using the `stmt(positional)` statement:
+</p>
+<code class="block">
+<b>positional</b> "`cpos()`"
+
+`tmpl(myTemplate)` (`var(myarray)`) `st()`
+List:
+`ss()``var(myarray)``apply()``tmpl(listItem)`(`cpos()``var(item)`)`es()`
+`et()`
+
+`tmpl(listItem)` (`var(item)`) `st()`
+* `ss()``var(item)``es()`
+`et()`
+</code>
+
+<h4>Condition Negation Prefix</h4>
+<p>
+To negate a condition in a conditional statement, you use the negation
+prefix ( `neg()` ). This can be overriden using the `stmt(negate)`
+statement:
+</p>
+<code class="block">
+<b>negate</b> "`cneg()`"
+
+`tmpl(myTemplate)` (`var(mytest)`) `st()`
+`ss()``cond()``cneg()``var(mytest)``apply()``tmpl(falseTemplate)``csep()``tmpl(trueTemplate)``es()`
+`et()`
+</code>
+
+<h4>Other Overrides</h4>
+<p>
+Extensions may add additional override statements. They will be listed
+in the description of the extension, and are only available if you use
+the extension.
+</p>
+
}}
+cst () {{ <u>&lt;&lt;&lt;</u> }}
+cet () {{ <u>&gt;&gt;&gt;</u> }}
+csd () {{ <u>[[[</u> }}
+ced () {{ <u>]]]</u> }}
+css () {{ <u>$</u> }}
+ces () {{ <u>$</u> }}
+csc () {{ <u>&lt;--</u> }}
+cec () {{ <u>--&gt;</u> }}
+
+cnote () {{ <u>//</u> }}
+
+capply () {{ <u>-&gt;</u> }}
+
+ccond () {{ <u>if </u> }}
+ccsep () {{ <u>|</u> }}
+
+calias () {{ <u>@</u> }}
+
+cpos () {{ <u>&amp;</u> }}
+
+cneg () {{ <u>-</u> }}
+

0 comments on commit 631e923

Please sign in to comment.
Something went wrong with that request. Please try again.