feat(syntax) enable top-level HTML comments

Now it's possible to have top-level HTML-style comments in the hsp file:

```
<!--
this is
a comment
-->
```

They're emitted at parse time, and discarded at syntax generation time
(replaced with newlines, to keep the 1:1 line mapping between input and
generated file, we may change that in the future).

docs/samples/component2/nbrfield.hsp

@@ -71,10 +71,7 @@ function getNumber(s) {
 }
 </script>
 
-<script>
-// component template associated with the NbrField controller
-</script>
-
+<!-- component template associated with the NbrField controller -->
 <export template nbrfield using c:NbrField>
   <span class="nbrfield">
     <input type="text" model="{c.internalValue}"
@@ -83,10 +80,7 @@ function getNumber(s) {
   </span>
 </template>
 
-<script>
-// component usage
-</script>
-
+<!-- component usage -->
 <template test(d)>
   Component #1: <#nbrfield value="{d.value1}" min="-10" max="1000"/><br/>
   Value in the data model: <span class="textValue">{d.value1}</span>

docs/samples/conditions/conditions.hsp

@@ -2,9 +2,7 @@
 var klass=require("hsp/klass");
 </script>
 
-<script>
-// nt is an instance of NumberTester
-</script>
+<!-- nt is an instance of NumberTester -->
 <template test(nt)>
     <div>
         Number: <span class="textvalue">{nt.number}</span>

docs/samples/helloworld/hello.hsp

@@ -1,6 +1,6 @@
-<script>
-// edit me!
-</script>
+<!--
+edit me!
+-->
 
 <template hello(name)>
     <div class="msg">

docs/samples/list1/list.hsp

@@ -15,10 +15,7 @@ var ListController = klass({
 });
 </script>
 
-<script>
-// simple list template
-</script>
-
+<!-- simple list template -->
 <template list using lc:ListController>
   // content is the list of attribute sub-elements
   <div class="list {lc.class}">
@@ -41,9 +38,7 @@ var ListController = klass({
   </div>
 </template>
 
-<script>
-// test template
-</script>
+<!-- test template -->
 <template test(d)>
   <#list head="Static list" class="listcpt">
     <@option>First {d.itemName}</@option>

docs/samples/list2/list.hsp

@@ -64,9 +64,7 @@ var ListCtrl = klass({
   </div>
 </template>
 
-<script>
-// test template
-</script>
+<!-- test template -->
 <template test(d)>
   Click on an item to select it:
 

docs/samples/panel/panel.hsp

@@ -9,9 +9,7 @@ var PanelController = klass({
 });
 </script>
 
-<script>
-// sample panel template
-</script>
+<!-- sample panel template -->
 <template panel using c:PanelController>
   <div class="panel">
     {if c.head}

hsp/compiler/parser/hspblocks.pegjs

@@ -8,7 +8,7 @@
  * @see https://github.com/dmajda/pegjs
  */
 TemplateFile
-  = blocks:(TemplateBlock / ScriptBlock / TopLevelWhitespace)*
+  = blocks:(TemplateBlock / ScriptBlock / TopLevelCommentBlock / TopLevelWhitespace)*
   {
    return blocks;
   }
@@ -17,6 +17,14 @@ TopLevelWhitespace
   = lines:(chars:WhiteSpace* eol:EOL {return chars.join("") + eol})+
     {return {type:"plaintext", value:lines.join('')}}
 
+TopLevelCommentBlock "HTML comment"
+ = block:HTMLCommentBlock _ eol:(EOL / EOF)
+  {
+    block.type = "toplevelcomment"; // to differentiate it from a comment inside a template
+    block.value = block.value + (eol || "");
+    return block;
+  }
+
 ScriptBlock "script block"
   = (_ "<script>" eol1:EOL? content:TextBlock "</script>" _ eol2:(EOL / EOF))
   {

hsp/compiler/treebuilder/syntaxTree.js

@@ -264,6 +264,22 @@ var SyntaxTree = klass({
         return index;
     },
 
+    /**
+     * Manages a top level HTML-style, possibily multiline, comment block.
+     * @param {Array} blocks the full list of blocks.
+     * @param {Integer} index the index of the block to manage.
+     * @param {Array} out the output as an array of Node.
+     * @return {Integer} the index of the block where the function stopped or -1 if all blocks have been handled.
+     */
+    __toplevelcomment : function (index, blocks, out) {
+        // let's just emit whitespace with as many newlines as the original comment had,
+        // so that we keep the 1:1 line mapping with the source
+        var node = new Node("plaintext"), block = blocks[index];
+        node.value = block.value.replace(/[^\r\n]/g, "");
+        out.push(node);
+        return index;
+    },
+
     /**
      * Manages a log statement.
      * @param {Array} blocks the full list of blocks.

test/compiler/samples/comment-toplevel1.txt

@@ -0,0 +1,65 @@
+##### Template:
+<!-- this is a comment -->
+<template hello1>
+   Hello World!
+</template>
+
+
+<!-- this is
+yet another comment
+this time it's multiline
+-->
+<script>
+// comment
+function func2(z) {return z;}
+</script>
+
+<!--
+  -- this comment has some dashes and even <!-- in the content --
+  -->
+<template hello2>
+   Hello Again!
+</template>
+##### Parsed Tree:
+
+[
+  { type: 'toplevelcomment', value: ' this is a comment \n'},
+  { type: 'template', name: 'hello1', args: [], content: [
+    { type: 'text', value: 'Hello World!' }
+  ]},
+  { type: 'plaintext', value: '\n\n'},
+  { type: 'toplevelcomment', value: ' this is\nyet another comment\nthis time it\'s multiline\n\n'},
+  { type: 'plaintext', value: '\n// comment\nfunction func2(z) {return z;}\n\n'},
+  { type: 'plaintext', value: '\n'},
+  { type: 'toplevelcomment', value: '\n  -- this comment has some dashes and even <!-- in the content --\n  \n'},
+  { type: 'template', name: 'hello2', args: [], content: [
+    { type: 'text', value: 'Hello Again!' }
+  ]},
+]
+
+##### Syntax Tree:
+
+[
+  { type: 'plaintext', value: '\n'},
+  { type: 'template', name: 'hello1', args: [], content: [
+    { type: 'text', value: 'Hello World!' }
+  ]},
+  { type: 'plaintext', value: '\n\n'},
+  { type: 'plaintext', value: '\n\n\n\n'},
+  { type: 'plaintext', value: '\n// comment\nfunction func2(z) {return z;}\n\n'},
+  { type: 'plaintext', value: '\n'},
+  { type: 'plaintext', value: '\n\n\n'},
+  { type: 'template', name: 'hello2', args: [], content: [
+    { type: 'text', value: 'Hello Again!' }
+  ]},
+]
+
+##### Template Code 1
+hello1=[__s,
+  n.$text(0, ["Hello World!"])
+]
+
+##### Template Code 2
+hello2=[__s,
+  n.$text(0, ["Hello Again!"])
+]