Permalink
Browse files

DRAFT-1: All core syntax docs are available.

  • Loading branch information...
supernovus committed Nov 30, 2011
1 parent fbcd7b5 commit 631e923d80101f31c11f7f2c36328d4b9a571777
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
@@ -1 +1 @@
-VERSION 1-PREDRAFT5
+VERSION 1-DRAFT1
View
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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>
}}
Oops, something went wrong.

0 comments on commit 631e923

Please sign in to comment.