Improve docs

4 files changed, 99 insertions, 81 deletions

diff --git a/README.md b/README.md
index e3527fc..fa1fec0 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,12 @@
 # lang
+
+Check out the language spec  
+[spec.md](spec.md)
+
+Check out the TODO  
+[todo.md](todo.md)
+
+
+## Author
+
+Jan Tuomi <jans.tuomi@gmail.com>
diff --git a/examples/spec.lisp b/examples/spec.lisp
deleted file mode 100644
index 4f4d303..0000000
--- a/examples/spec.lisp
+++ /dev/null
@@ -1,81 +0,0 @@
-; Language spec
-;
-; Dynamically and weakly typed, interpreted
-; Impure functions marked with ! (convention)
-; Boolean functions marked with ? (convention)
-; Loops implemented with recursion
-;
-; Value types:
-;   Number      -3.14
-;   Symbol      PI
-;   Boolean     true
-;   String      "foobar"
-;   Vector      [1 2 3]
-;   Hash map    { a 1 b 2 }
-;   Function    (\[x y] (+ x y))
-;
-; Syntax
-;   Function calls
-;       A sequence of values surrounded by parens is considered a function call
-;       In a function call, the first element must evaluate to a function value.
-;       The function will be invoked with the rest of the elements as arguments to the function.
-;   Function definition
-;       Calling the builtin variadic function '\' constructs a new function. The first argument
-;       must be a vector of symbols (parameter list). The rest of the arguments form the function
-;       body. The evaluated value of the last argument is returned as the return value of the
-;       function.
-;
-; Some builtin functions
-;   let         (let sum2 (\[x y] (+ x y)))    Evaluates second argument and stores value in environment
-;   \           (\[x y] + x y)
-;   print!      (print! PI)
-;   if          (if (lt? 10 5)
-;                   (print "10 is less than 5")
-;                   (print "10 is not less than 5"))
-;   match       (match (sum2 1 1)
-;                   2 (do-thing)
-;                   3 (do-other-thing)
-;                   (do-else))
-;   head        (head vec)
-;   tail        (tail vec)
-;   prep        (prep x xs)
-;
-; Functions are curried
-; E.g.
-;   (let f1 (\[x y] (+ x y)))
-;   (let f2 (\[x] (\[y] (+ x y))))
-;   ; f1 == f2
-
-(let PI 3.14159)
-(let circle-area (\[r]
-    (let rr (mul2 r r))
-    (mul2 PI rr)))
-
-(let fibo (\[n]
-    (let fibo-1 (\[] (fibo (sub2 n 1))))
-    (let fibo-2 (\[] (fibo (sub2 n 2))))
-    (match n
-        0  0
-        1  1
-        (sum2 (fibo-1) (fibo-2)))))
-
-(print! (fibo 5))
-; 5
-
-(let map (\[f lst]
-    (match lst
-        [] []
-        (prepend (f head lst) (map f (tail lst))))))
-
-(print!
-    (map (sum2 1) [1 2 3]))
-; 2 3 4
-
-(let foldr (\[f accumulator lst]
-    (match lst
-        []  accumulator
-        (f (foldr f accumulator (tail lst)) (head lst)))))
-
-(print!
-    (foldr sum2 0 [1 2 3]))
-; 6
diff --git a/spec.md b/spec.md
new file mode 100644
index 0000000..953b672
--- /dev/null
+++ b/spec.md
@@ -0,0 +1,74 @@
+# Language spec
+
+- Dynamically and weakly typed, interpreted
+- Impure functions marked with ! (convention)
+- Boolean functions marked with ? (convention)
+- Loops implemented with recursion
+
+## Value types
+
+  Number      -3.14
+  Symbol      PI
+  Boolean     true
+  String      "foobar"
+  Vector      [1 2 3]
+  Hash map    { a 1 b 2 }
+  Function    (\[x y] (+ x y))
+
+## Syntax
+
+### Function calls
+
+A sequence of values surrounded by parens is considered a function call In a function call, the first element must evaluate to a function value. The function will be invoked with the rest of the elements as arguments to the function.
+
+### Function definition
+Calling the builtin variadic function '\' constructs a new function. The first argument must be a vector of symbols (parameter list). The rest of the arguments form the function body. The evaluated value of the last argument is returned as the return value of the function.
+
+### Currying
+
+Functions are automatically curried  
+E.g.
+
+    (let f1 (\[x y] (+ x y)))
+    (let f2 (\[x] (\[y] (+ x y))))
+    ; f1 equivalent to f2
+
+## Some builtin functions
+
+`let`  
+Evaluates second argument and stores the resulting value in the environment.
+
+    (let sum2 (\[x y] (+ x y)))
+
+`\`  
+Defines a function.
+
+    (\[x y] + x y)
+
+`print!`  
+Prints a value and a newline.
+
+    (print! PI)
+
+`match`  
+Matches first argument (value) to even positioned arguments (matchers). On match (at position i), evaluates the odd positioned argument (branch) right after it (at position i + 1). If given an even number of arguments, the last argument will act as the default branch.
+
+    (match (sum2 1 1)
+        2 (do-thing)
+        3 (do-other-thing)
+        (do-else))
+
+`head`  
+Gets the first element of a vector.
+
+    (head vec)
+
+`tail`  
+Drops the first element of a vector.
+
+    (tail vec)
+
+`prepend`  
+Pushes the first argument to the front of the second argument (vector).
+
+    (prepend x xs)
diff --git a/todo.md b/todo.md
new file mode 100644
index 0000000..baebacf
--- /dev/null
+++ b/todo.md
@@ -0,0 +1,14 @@
+# TODO
+
+In order of priority
+
+- Make builtin math functions support both number types (integer and double)
+- Write tests!
+- Add builtins to convert from int to double and vice versa
+- Add builtin to convert to string
+- Add builtins to compare numbers (eq?, lt?)
+- Add flag to control whether computed values are automatically printed or not
+- Add import function with support for qualified imports
+- Come up with a name for the language
+- Add auto import for standard library (std)
+- Add flag to disable auto import of standard library