docs: Update docs for whitespace

Update docs for whitespace. While at it, remove a bunch of duplicated
sections in grammar. We are now making horizontal whitespace `WS`
significant in certain places which allows us to remove the somewhat
awkward array and map typing in favour of derived and inferred types
for literals.

Remove `term` from grammar as it is not used in code, we only work with
expression. Introduce `<- ->` and  `<+ +>` tokens to annotated
whitespace inside grammar: expressions in expression lists, such as
function calls or array elements may not contain whitespace, as
whitespace is used as list separator.

Invert types so that types read as variables are being access:

	m:[]{}string
	m[0].name = "Joe"

Also add note on pass by reference for maps and arrays and pass by value
for string, num and bool.

Author: juliaogris

docs/syntax_by_example.md

@@ -1,18 +1,17 @@
 # Evy Syntax by Example
 
-The following examples on various aspects of `evy`'s syntax give an
-intuitive understanding of the language. For a formal language
-specification see the [syntax grammar].
+The following examples give an intuitive understanding of various
+aspects of `evy`'s syntax. For a formal language specification see the
+[syntax grammar](syntax_grammar.md).
 
-[syntax grammar]: syntax_grammar.md
 
 ## Comment
 
     // This is comment
 
 ## Declaration
 
-    x:num     // declaration: num, string, bool, any, [] {}
+    x:num     // declaration: num, string, bool, any, []num, {}string
     y := 1    // declaration through type inference (num)
 
 ## Assignment
@@ -55,8 +54,6 @@ specification see the [syntax grammar].
 
 ## Loop statements
 
-
-
 ### `while` loop
 
     x := 0
@@ -80,18 +77,18 @@ specification see the [syntax grammar].
     end
 
     for x := range -10 
-        print x        // nothing. step always 1 by default.
+        print x        // nothing. step is 1 by default.
     end
 
 ### `for` … `range` array
 
-    for x := range num[ 1 2 3 ]
+    for x := range [1 2 3]
         print x        // 1 2 3
     end
 
 ### `for` … `range` map
 
-    m := string{ name:"Mali" sport:"climbing" }
+    m := { name:"Mali" sport:"climbing" }
     for key := range m
         print key m[key]
     end
@@ -133,53 +130,63 @@ specification see the [syntax grammar].
 
 ## Array
 
-    a1:num[]
-    a2:string[][]
-    a1 = num[ 1 2 3 4 ]
-    a2 = string[ ["1" "2"] ["a" "b"] ]
-    a3 := bool[ true false ]
-    a4 := num[ "s1"
-            "s2" ] // linebreak allowed
-    a5 := any[ "chars" 123 ]
+    a1:[]num
+    a2:[][]string
+    a1 = [1 2 3 4]             // type: num[]
+    a2 = [["1" "2"]["a" "b"]]  // type: string[][]
+    a3 := [true false]         // type: bool[]
+    a4 := ["s1"                // line break allowed
+           "s2"]               // type: string[]
+    a5 := ["chars" 123]        // type: any[]
+    a6:[]any                   // type: any[]
 
 ### Array element access
 
+    a1 := [1 2 3 4]
+    a2 := [["1" "2"]["a" "b"]]
     print a1[1]    // 2
     print a2[1][0] // "a"
 
 ### Concatenation, append, prepend
 
-    z = z + num[ 100 ] // [ 1 2 3 4 5 6 100 ]
-    z = append z 101       // [ 1 2 3 4 5 6 100 101 ]
-    z = prepend z 0        // [ 0 1 2 3 4 5 6 100 101 ]
+    z = z + [ 100 ]    // z: [1 2 3 4 5 6 100]; optional extra whitespace 
+    z = z + [101]      // z: [1 2 3 4 5 6 100 101]
+    append z 102       // z: [1 2 3 4 5 6 100 101 102]
+    prepend z 0        // z: [0 1 2 3 4 5 6 100 101 102]
 
 ### Slicing
 
-    x1 := x[:2] // [ 1 2 ]
+    x := [1 2 3]
+    x1 := x[:2] // [1 2]
     x2 = x[2]   // [3]
     x2 = x[1:2] // [2]
-    x2 = x[-1]  // [3]`
-    x2 = x[-2:] // [ 2 3 ]
+    x2 = x[-1]  // [3]
+    x2 = x[-2:] // [2 3]
 
 ## Map
 
-    m:any{}          // keys can only be identifiers
-    m.name = "fox"
-    m.age = 42
+    m1:{}any          // keys can only be identifiers, any value allowed
+    m2.name = "fox"
+    m2.age = 42
 
-    m1 := string{ letters:"abc" nums:"asdf" }
-    m2 := {} // short for any{}
-    m3 := any{
-            letters:"abc"
+    m3 := {letters:"abc" name:"Jill"}   // type: {}string
+    m4 := {}                            // type: {}any
+    m5 := {
+            letters:"abc"               // line break allowed
             nums:123
-          } // linebreak allowed
+          }                             // type: {}any
+    m6:{}[]num                          // map of array of numbers
+    m6.digits = [1 2 3]
+    m7:{}num
+    m7.x = "y"                          // invalid, only num values allows
 
 ### Map value access
 
+    m := {letters:"abc" name:"Jill"}   
     s := "letters"
-    print m2.letters    // abc
-    print m2[s]         // abc
-    print m2["letters"] // abc
+    print m.letters    // abc
+    print m[s]         // abc
+    print m["letters"] // abc
 
 ### Map value existence
 
@@ -190,33 +197,34 @@ specification see the [syntax grammar].
 
 ## Any
 
-    x:any  // any type
-    m1:{}  // any map value type
+    x:any     // any type
+    m1:{}any  // map with any value type
     m2 := { letter:"a" number:1 }
-    arr := any[ "b" 2 ]
+    arr1:[]any
+    arr2 := [ "b" 2 ]
 
 ## Type reflection
 
-    reflect "abc"              // {type: "string"}
-    reflect true               // {type: "bool"}
-    reflect num[ 1 2 ]         // {type: "array",
-                               //  sub:  {type: "num"}
-                               // }
-    reflect num[ [1 2] [3 4] ] // {
-                               //   type: "array",
-                               //   sub:  {
-                               //     type: "array"
-                               //     sub: {
-                               //       type: "num"
-                               //     }
-                               //   }
-                               // }
+    reflect "abc"         // {type: "string"}
+    reflect true          // {type: "bool"}
+    reflect [ 1 2 ]       // {type: "array",
+                          //  sub:  {type: "num"}
+                          // }
+    reflect [[1 2] [3 4]] // {
+                          //   type: "array",
+                          //   sub:  {
+                          //     type: "array"
+                          //     sub: {
+                          //       type: "num"
+                          //     }
+                          //   }
+                          // }
 
 ### Type reflection Usage Example
 
     v:any
     v = "asdf"
-    if (reflect v).type == "string" 
+    if (reflect v) == {type: "string"}
         print "v is a string:" v
     end
 
@@ -230,8 +238,8 @@ specification see the [syntax grammar].
 ## Type assertion
 
     x:any
-    x = num[ 1 2 3 4 ]  // concrete type num[]
-    s := num[] x
+    x = [ 1 2 3 4 ]  // concrete type num[]
+    s := x.([]num)
 
 ## Variadic functions
 
@@ -249,7 +257,7 @@ specification see the [syntax grammar].
 
 ## Event handling 
 
-    on animate
+    on frame
         draw
     end
 
@@ -265,16 +273,22 @@ specification see the [syntax grammar].
 
 ### Print
 
-    print  "abc" 123 // abc 123 \n
+    print  "abc" 123 // abc 123\n
     prints "abc" 123 // print string: abc123
-    printq "abc"     // print quoted, reuse as value: "abc"
+    printq "abc" 123  // print quoted, reuse as value: "abc"
+
+Returning a string:
+
+    sprint  "abc" 123 // returns "abc 123\n"
+    sprints "abc" 123 // returns "abc123"
+    sprintq "abc"     // returns "\"abc\""
 
 ### Strings
 
     "Hello"[2]                // "l"
     "Hello world"[1:5]        // "ello"
     join [ "one" "two" ] ", " // "one, two"
-    split "hi there" " "      // [ "hi" "there" ]
+    split "hi there"          // [ "hi" "there" ]
 
 ### Length
 
@@ -285,6 +299,13 @@ specification see the [syntax grammar].
     append x 100   // [ 1 2 3 100 ]
     prepend x -100 // [ -100 1 2 3 100 ]
 
+### Maps
+ 
+    m := {name: "abc"}
+    has m "abc" // true
+    del m "abc"
+    has m "abc" // false
+
 ### Conversion
 
     str2bool "true" // true
@@ -303,9 +324,9 @@ specification see the [syntax grammar].
 
     now                                 // return unix time in seconds
     format_time now                     // "2022-08-28T23:59:05Z" Z is time zone zero
-    format_time2 now "06/01/02 15:04"   // "22/01/02 15:04" 
+    format_timef now "06/01/02 15:04"   // "22/01/02 15:04" 
     parse_time "2022-08-28T23:59:05Z"   // internal representation as unix seconds
-    parse_time2 value format
+    parse_timef value format
     sleep 10                            // sleep 10 seconds
 
 See Go's [time.Layout] for further details on formatting and parsing.
@@ -327,9 +348,9 @@ No support for custom events.
     circle radius
     line end_x end_y
     rect width height
-    curve ?
-    polygon num[ x1 y2 x2 y2 x3 y3 ]
-    polyline num[ x1 y1 x2 y2 x3 y3 ]
+    curve // TBD
+    polygon [x1 y2] [x2 y2] [x3 y3]
+    polyline [x1 y1] [x2 y2] [x3 y3]
 
     color  900   // CSS    #ff0000
     colors "red" // CSS color keywords:     #ff0000