update docs

Readme.md

@@ -1,6 +1,6 @@
 # Meow lang
 
-Meow lang is a programming language that is designed **not** to be easy to learn and use.
+Meow lang is a programming language that compiles to *cat*, another language that is hard to read but easy to execute. Meow's syntax is easier to read than cat, but meow and cat are equivalent.
 
 Its main design purpose is to do experiments with "string substitution".
 
@@ -19,26 +19,20 @@ The only available data type is **String**. (However, you can encode other data
 ```bash
 # First clone this repo and open it
 
-cargo run ./examples/syn.meow
+cargo run repl
 
-# Now you can use the REPL to evaluate expressions
+# Now you can use the REPL to evaluate (cat) expressions
 ```
 
-Examples:
+Example:
 
 ```
-> true()
-T
-> false()
-F
-> {var x = zero();succ(x)}
-S0
-> dr("a","aba","aba")
-aba
-> if("T","xsa","ddd")
-xsa
-> eq("as","asas")
-F
+> "abc"
+abc
+> cat "hello " "world"
+hello world
+> let "apple" "world" "hello apple"
+hello world
 ```
 
 ## Tutorials
@@ -49,4 +43,4 @@ F
 
 ## Examples
 
-See [syn.meow](./examples/syn.meow).
+See [syn.meow](./examples/syn.meow), which has compiling result [syn.cat](./examples/syn.cat).

docs/Syntax.md

@@ -1,12 +1,19 @@
 # Syntax
 
-The layout of the whole program is not stable, but the core expression syntax is (relatively more) stable.
+The layout of the whole language is not yet stable, but the core expression syntax is (relatively more) stable.
 
 ## Expression
 
 **All expressions can be evaluated to a string literal.**
 
-`literal` is simply a string literal, like `"abc"`, `"lol"`.
+`Literal` is simply a string literal, like `"abc"`, `"lol"`.
+
+There are two ways to define a string literal.
+
+- "abc"
+- \`abc\`
+
+It's not allowed to use " inside a "-string and \` inside a \`-string.
 
 Examples.
 
@@ -45,30 +52,49 @@ Evaluation has two modes. The **raw** mode and the **eval** mode.
 
 In raw mode, a string literal will be simply be what it is. In eval mode, a string literal will be changed according to current rules in the context.
 
+The **eval** mode is only used in the last expression in a block.
+
 For example, consider the following macro:
 
 ```meow
 meow() {
     "dd" = "d";
     var x = {"dddd"};
     var y = "dddd";
-    "x=" + x + ",y=" + y
+    "x=" + x + ", y=" + y
 }
 ```
 
-Here `y` is raw mode evaluation while `x` is an eval mode evaluation. The thumb rule is that **only the last expression** in the block ({}) will be evaluated in eval mode.
-
-Therefore, `x` is actually evaluated twice while `y` is evaluated only once.
+The rules will only apply to current context, it will not go into any deeper `{}` block.
 
-The output of the code above:
+The result of `meow()` is:
 
 ```
-x=d,y=dd
+x=dd, y=dd
 ```
 
 ## Variable
 
-You can use `var` to declare a variable. The syntax is like `var x = "abc";`. The variable is only visible in the block where it is declared. The right hand side can be any expressions. Note that the right hand side is evaluated in **raw** mode (unless you use `var x = {"abc"}`).
+You can use `var` to declare a variable. The syntax is like `var x = "abc";`. The variable is only visible in the block where it is declared. The right hand side can be any expressions. Note that the right hand side is evaluated in **raw** mode.
+
+When compiling to cat, the compiler will **remove all `var` declarations**. So `var` is simply a **syntax sugar**.
+
+For example,
+
+```
+meow() {
+    "dd" = "d";
+    var x = {"dddd"};
+    var y = "dddd";
+    x + y
+}
+```
+
+will be compiled to:
+
+```
+meow  = let "dd" "d" cat "dddd" "dddd"
+```
 
 ---
 

docs/i-expr.md

@@ -0,0 +1,32 @@
+# i Expressions
+
+i expressions allow you to evaluate cat expression inside cat expression. This gives us the power to do recursion.
+
+The fibonacci function can be defined as:
+
+```meow
+fib(x) {
+    if(
+        eq(x, zero()),
+        zero(),
+        !(if(
+            leq(x, num("2")),
+            spack(num("1")),
+            `add fib pred x fib pred pred x`
+        ))
+    )
+}
+```
+
+The `!` operator is used to evaluate the expression inside.
+
+You can try it in repl:
+
+```
+> ! `"23"`
+23
+> ! `cat "12" "22"`
+1222
+```
+
+Note that `cat "12" "22"` itself is a string literal rather than many tokens.