Add function declaration macro

Shares code with function expressions.  These are necessary to be able
to write also, due to various interesting differences:
https://javascriptweblog.wordpress.com/2010/07/06/function-declarations-vs-function-expressions/

Fixes #21.

Author: anko

doc/basics-reference.markdown

@@ -149,31 +149,32 @@ generate arbitrary JavaScript are built in to eslisp.
 
 ### General
 
-| name       | description                  |
-| ---------- | ---------------------------- |
-| `array`    | array literal                |
-| `object`   | object literal               |
-| `regex`    | regular expression literal   |
-| `var`      | variable declaration         |
-| `.`        | member expression            |
-| `get`      | *computed* member expression |
-| `switch`   | switch statement             |
-| `if`       | conditional statement        |
-| `?:`       | ternary expression           |
-| `while`    | while loop                   |
-| `dowhile`  | do-while loop                |
-| `for`      | for loop                     |
-| `forin`    | for-in loop                  |
-| `break`    | break statement              |
-| `continue` | continue statement           |
-| `label`    | labeled statement            |
-| `label`    | labeled statement            |
-| `function` | function expression          |
-| `return`   | return statement             |
-| `new`      | new-expression               |
-| `debugger` | debugger statement           |
-| `throw`    | throw statement              |
-| `try`      | try-catch statement          |
+| name              | description                  |
+| ----------------- | ---------------------------- |
+| `array`           | array literal                |
+| `object`          | object literal               |
+| `regex`           | regular expression literal   |
+| `var`             | variable declaration         |
+| `.`               | member expression            |
+| `get`             | *computed* member expression |
+| `switch`          | switch statement             |
+| `if`              | conditional statement        |
+| `?:`              | ternary expression           |
+| `while`           | while loop                   |
+| `dowhile`         | do-while loop                |
+| `for`             | for loop                     |
+| `forin`           | for-in loop                  |
+| `break`           | break statement              |
+| `continue`        | continue statement           |
+| `label`           | labeled statement            |
+| `label`           | labeled statement            |
+| `function`        | function expression          |
+| `declarefunction` | function declaration         |
+| `return`          | return statement             |
+| `new`             | new-expression               |
+| `debugger`        | debugger statement           |
+| `throw`           | throw statement              |
+| `try`             | try-catch statement          |
 
 #### Structural
 
@@ -414,6 +415,8 @@ the `default`-case clause.
 
 ### Functions
 
+#### Function expressions
+
 The `function` macro creates function expressions.  Its first argument becomes
 the argument list, and the rest become statements in its body.  The `return`
 macro compiles to a return-statement.
@@ -429,7 +432,6 @@ macro compiles to a return-statement.
         return 5 * (a * b);
     };
 
-
 You can also give a name to a function expression as the optional first
 argument, if you so wish.
 
@@ -443,6 +445,20 @@ argument, if you so wish.
         return 'T';
     };
 
+#### Function declarations
+
+These work much like function expressions above, but require a name.
+
+<!-- !test in function declaration -->
+
+    (declarefunction tea () (return "T"))
+
+<!-- !test out function declaration -->
+
+    function tea() {
+        return 'T';
+    }
+
 ### Loops
 
 While-loops (with the `while` macro) take the first argument to be the loop

src/built-in-macros.ls

@@ -81,6 +81,31 @@ optionally-implicit-block-statement = ({compile, compile-many}, body) ->
     type : \BlockStatement
     body : compile-many body .map statementify
 
+# Here's a helper that extracts the common parts to macros for
+# FunctionExpressions and FunctionDeclarations since they're so similar.
+function-type = (type) ->
+  ({compile, compile-many}:env, ...args) ->
+    # The first optional atom argument gives the id that should be attached to
+    # the function expression.  The next argument is the function's argument
+    # list.  All further arguments are statements for the body.
+
+    var id, params
+
+    arg1 = args.shift!
+
+    if arg1 instanceof atom
+      id := type : \Identifier name : arg1.text!
+      params := args.shift! .contents!map compile
+    else
+      # Let's assume it's a list then
+      id := null
+      params := arg1.contents!map compile
+
+    type : type
+    id : id
+    params : params
+    body : optionally-implicit-block-statement env, args
+
 contents =
   \+ : n-ary-expr \+
   \- : n-ary-expr \-
@@ -298,28 +323,9 @@ contents =
         throw Error "dot called with no arguments"
 
 
-  \function : ({compile, compile-many}:env, ...args) ->
+  \function : function-type \FunctionExpression
 
-    # The first optional atom argument gives the id that should be attached to
-    # the function expression.  The next argument is the function's argument
-    # list.  All further arguments are statements for the body.
-
-    var id, params
-
-    arg1 = args.shift!
-
-    if arg1 instanceof atom
-      id := type : \Identifier name : arg1.text!
-      params := args.shift! .contents!map compile
-    else
-      # Let's assume it's a list then
-      id := null
-      params := arg1.contents!map compile
-
-    type : \FunctionExpression
-    id : id
-    params : params
-    body : optionally-implicit-block-statement env, args
+  \declarefunction : function-type \FunctionDeclaration
 
   \new : ({compile}, ...args) ->
     [ newTarget, ...newArgs ] = args

test.ls

@@ -170,6 +170,14 @@ test "function expression with name" ->
   esl "(function f (x) (return (+ x 1)))"
     ..`@equals` "(function f(x) {\n    return x + 1;\n});"
 
+test "function declaration" ->
+  esl "(declarefunction f (x) (return (+ x 1)))"
+    ..`@equals` "function f(x) {\n    return x + 1;\n}"
+
+test "function declaration without name throws error" ->
+  -> esl "(declarefunction (x) (return (+ x 1)))"
+    ..`@throws` Error
+
 test "function with no arguments" ->
   esl "(function () (return 1))"
     ..`@equals` "(function () {\n    return 1;\n});"