kc3-lang/kc3

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..700b30b
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,31 @@
+# Contributing to KC3
+
+## Adding or removing files from the source tree
+```sh
+make gen
+./update_sources
+```
+
+The last command will show the path to `sources.mk` and
+`sources.sh` if they were modified.
+
+Don't forget to commit your files and the modified `sources.mk` and
+`sources.sh` files.
+
+After updating `sources.sh` and `sources.mk` you need to run
+`./configure` again.
+
+## Pull requests
+
+Please send pull requests on the
+[KC3 Github repository](https://github.com/kc3-lang/kc3)
+or
+[KC3 Codeberg repository](https://codeberg.org/kc3-lang/kc3)
+.
+
+Please note that according to the copyright notice in all KC3 source
+files, you are not allowed to fork and redistribute the project, but
+still you can send pull request for incorporation.
+
+After careful reviewing the pull request will be accepted into master
+or rejected.
diff --git a/INSTALL.md b/INSTALL.md
new file mode 100644
index 0000000..e08ab8d
--- /dev/null
+++ b/INSTALL.md
@@ -0,0 +1,73 @@
+# KC3 installation
+
+There are no binary release from now, you must install from sources.
+
+## Get the sources
+
+### From git
+
+#### From [kmx.io git forge](https://git.kmx.io/kc3-lang/kc3)
+
+```sh
+git clone https://git.kmx.io/kc3-lang/kc3.git
+```
+
+#### From [Github](https://github.com/kc3-lang/kc3)
+
+```sh
+git clone https://github/kc3-lang/kc3.git
+```
+
+### Clone submodules also
+
+```sh
+cd kc3
+git submodule init
+git submodule update
+cd fonts
+git submodule init
+git submodule update
+cd ..
+```
+
+## Install from sources
+
+### Install dependencies
+
+#### Debian / Ubuntu / PopOS / Mint
+
+```sh
+# install build tools
+sudo apt install pkg-config clang libtool-bin make ruby time
+
+# install dependencies
+sudo apt install libffi-dev libbsd-dev libevent-dev
+
+# install demo dependencies
+sudo apt install glew libfreetype-dev libsdl2-dev libxkbcommon-dev
+```
+
+
+### Compilation
+```sh
+./configure
+make -j8
+```
+
+### Add the sources to `LD_LIBRARY_PATH`
+```sh
+. ./env
+```
+
+### Create symlinks to libs
+```sh
+make lib_links
+```
+
+---
+
+Top : [KC3 README.md](README.md)
+
+Previous : [KC3 README.md](README.md)
+
+Next : [KC3 testing guide](TESTING.md)
diff --git a/README.md b/README.md
index 1ed7b39..e279df3 100644
--- a/README.md
+++ b/README.md
@@ -32,515 +32,33 @@ Supported architectures :
 [Join us on kmx.io Discord server !](https://discord.gg/A4MWkpUDsG)
 
 
-## Usage
+## Guides
 
-### Install dependencies
+### [Installation](INSTALL.md)
 
-#### Debian / Ubuntu / PopOS / Mint
+Follow the [KC3 installation guide](INSTALL.md).
 
-```
-# install build tools
-sudo apt install pkg-config clang libtool-bin make ruby time
 
-# install dependencies
-sudo apt install libffi-dev libbsd-dev libevent-dev
+### [Tests](TESTING.md)
 
-# install demo dependencies
-sudo apt install glew libfreetype-dev libsdl2-dev libxkbcommon-dev
+Follow the [KC3 testing guide](TESTING.md)
 
-# use clang
-export CC=clang
-```
 
+### [Usage](USAGE.md)
 
-### Compilation
-```sh
-git clone https://git.kmx.io/kc3-lang/kc3.git
-cd kc3
-git submodule init
-git submodule update
-cd fonts
-git submodule init
-git submodule update
-cd ..
-./configure
-make
-```
+Follow the [KC3 usage guide](USAGE.md)
 
-### Add the sources to `LD_LIBRARY_PATH`
-```sh
-. ./env
-```
 
-### Create symlinks to libs
-```sh
-make lib_links
-```
+### [Structure](STRUCTURE.md)
 
-### Running the OpenGL demo
-```sh
-make demo_gl
-```
+Follow the [KC3 structure guide](STRUCTURE.md)
 
-Press Q to quit, F for fullscreen, Left and Right arrows to move
-through sequences.
 
-Other targets exist :
-```sh
-make demo_gl_asan
-make gdb_demo_gl
-make lldb_demo_gl
-```
+### [Tutorial and examples](TUTORIAL.md)
 
-### Running the Cairo demo
-```sh
-make demo
-```
+Follow the [KC3 tutorial and examples guide](TUTORIAL.md) .
 
-Press Q to quit, Left and Right arrows to move through sequences.
 
-Other targets exist :
-```sh
-make demo_asan
-make gdb_demo
-make lldb_demo
-```
-
-### Running the HTTPd demo
-```sh
-make test_httpd
-```
-
-### Running the tests
-```sh
-make test
-```
-
-All the tests will be run. More specific targets exist :
-```sh
-make test_libkc3
-make test_ikc3
-make test_libkc3_asan
-make test_ikc3_asan
-make test_asan
-```
-
-### Running ikc3
-```sh
-ikc3/.libs/ikc3
-```
-
-### Running gdb
-```sh
-make gdb_ikc3
-make gdb_test
-```
-
-### Adding or removing files from the source tree
-```sh
-make gen
-./update_sources
-```
-
-Don't forget to commit your files and the modified sources.mk and
-sources.sh files.
-
-
-## Structure
-
-### libkc3
-
-KC3 is implemented using libkc3 a small C99 library implementing the core
-of the language.
-
-The library includes a parser and an interpreter for KC3 code in C
-structures.
-
-Support for large integers provided by
-[libtommath](https://github.com/libtom/libtommath).
-
-Support for C function calls provided by
-[libffi](https://github.com/libffi/libffi).
-
-Modules are saved as facts databases.
-
-
-#### Parser
-
-The parser is recursive descent.
-
-#### AST
-
-The AST is represented as KC3 data structures and can be meta-programmed
-in C.
-
-#### Interpreter
-
-Under development.
-
-
-### ikc3
-
-Interactive shell. Terminal I/O provided by
-[linenoise](https://github.com/antirez/linenoise/tree/1.0).
-
-Example :
-```
-$ make test
-$ ikc3/ikc3
-ikc3> ikc3> 1 + 1
-2
-ikc3> 2 + 2
-4
-ikc3> 3 + 3
-6
-ikc3> 1 +
-ikc3> 1
-2
-ikc3> double = fn (x) { x * 2 }
-fn (x) { x * 2 }
-ikc3> double
-fn (x) { x * 2 }
-ikc3> double(1)
-2
-ikc3> double(2)
-4
-ikc3> double(3)
-6
-ikc3> double(4)
-8
-ikc3> List.map([1, 2, 3, 4], double)
-[2, 4, 6, 8]
-ikc3> List.reverse(List.map([1, 2, 3, 4], double))
-[8, 6, 4, 2]
-```
-
-The `List.map` and `List.reverse` functions are defined in
-`lib/kc3/0.1/list.kc3` and can be modified in real time.
-
-For example, without closing ikc3 let's redefine `List.reverse`,
-open an editor and change the line in `lib/kc3/0.1/list.kc3` from
-
-```
-  def reverse = fn {
-    (x) { reverse(x, ()) }
-    ([], acc) { acc }
-    ([a | b], acc) { reverse(b, [a | acc]) }
-  }
-```
-
-to
-
-```
-  def reverse = fn {
-    (x) { reverse(x, ()) }
-    ([], acc) { [:reversed | acc] }
-    ([a | b], acc) { reverse(b, [a | acc]) }
-  }
-}}
-```
-
-and check the results of the last command (up key) in ikc3/ikc3 :
-
-```
-ikc3> List.reverse(List.map([1, 2, 3, 4], double))
-[:reversed, 8, 6, 4, 2]
-```
-
-Don't forget to revert the changes to `list.kc3`.
-
-
-#### Maps
-
-KC3 maps are key-value stores, you can use any tag as a key and
-associate a value to it.
-
-You can use destructuring to access KC3 maps :
-```
-ikc3> a = %{id: 1, title: "My title", message: "Hello, world !"}
-%{id: 1, title: "My title", message: "Hello, world !"}
-ikc3> a = %{}
-%{id: 1, title: "My title", message: "Hello, world !"}
-ikc3> %{id: id, title: "My title", message: message} = a
-%{id: 1, title: "My title", message: "Hello, world !"}
-ikc3> id
-1
-ikc3> message
-"Hello, world !"
-```
-
-You can use the dot syntax to access map values from a `Sym` key :
-```
-ikc3> a = %{id: 1, title: "My title", message: "Hello, world !"}
-%{id: 1, title: "My title", message: "Hello, world !"}
-ikc3> a.id
-1
-ikc3> a.message
-"Hello, world !"
-```
-
-You can also use the `KC3.access` function for the same result :
-```
-ikc3> a = %{id: 1, title: "My title", message: "Hello, world !"}
-%{id: 1, title: "My title", message: "Hello, world !"}
-ikc3> access(a, :id)
-1
-ikc3> access(a, :message)
-"Hello, world !"
-```
-
-
-#### Unicode characters
-
-`ikc3` fully supports Unicode :
-
-Some unicode characters :
-```
-ikc3> '\U+1B2FB'
-'𛋻'
-ikc3> '𐅀'
-'𐅀'
-ikc3> '🤩'
-'🤩'
-ikc3>
-```
-
-#### Large integers
-
-```
-ikc3> a = 1 + 100000000000000000000000000000000
-100000000000000000000000000000001
-ikc3> a * a
-10000000000000000000000000000000200000000000000000000000000000001
-ikc3>
-```
-
-#### Ratios
-
-Ratios are made with a couple of large integers : the numerator
-which can be any number, and the denominator which has to be positive.
-They represent fractions of integral numbers.
-They are written with a slash and no space.
-
-```
-ikc3> 1/2 + 2/3
-7/6
-ikc3> 1/2 * 2/3
-1/3
-ikc3> 1/2 / 2/3
-3/4
-ikc3> 1/2 - 2/3
--1/6
-```
-
-
-#### Complex numbers
-
-Complex numbers are constructed using the operator `+i` on any kind of
-numbers (unsigned, signed, float, ratios, and even other complex
-numbers). For instance, you can write `a +i b` where `a` and `b` are
-real numbers.
-
-```
-ikc3> 1 +i 2
-1 +i 2
-ikc3> 1 +i 2 + 2 +i 3
-3 +i 5
-ikc3> (1 +i 2) * (2 +i 3)
--4 +i 7
-ikc3> (1 +i 2) / (2 +i 3)
-0 +i 0
-ikc3> (1/1 +i 2/1) / (2 +i 3)
-8/13 +i 1/13
-```
-
-As you can see integer division is not producing ratios.
-That might change in future releases.
-
-
-#### Lists
-
-Lists are marked with brackets `[]`.
-
-Regular lists can be :
- - an element and a list : `[1 | []]` → `[1]`
- - multiple elements : `[1, 2, 3]`
- - multiple elements and a list : `[1, 2 | [3, 4]]` → `[1, 2, 3, 4]`
- - the empty list : `[]`
-
-Regular lists end with the empty list : `[1] == [1 | []]`.
-
-You can also contruct dotted lists like in Common Lisp where
-the next list pointer is an arbitrary form. E.g. :
- - an element and an element : `[1 | 2]`
- - multiple elements and an element : `[1, 2, 3 | 4]`
- - the empty list and an element : `[[] | 1]`
-
-All these list formats are supported in pattern matching.
-
-
-#### Pattern matching and destructuring
-
-The KC3 pattern matching principles come from Erlang and Elixir.
-
-All tag data structures in KC3 can be pattern matched using the equal
-sign (`=`) against litteral values containing identifiers. All
-identifiers are supposed to be new bindings when using pattern matching
-in KC3. If you want to use an identifier's value in pattern matching you
-must use the _pin operator_ (`^`). Variables can be assigned a new value
-from either side of the equal sign and from inside a tag data structure,
-which is called _destructuring_.
-
-
-Examples :
-```
-ikc3> a = 1
-1
-ikc3> a = 2
-2
-ikc3> a
-2
-ikc3> ^ a = 1
-void
-ikc3> ^ a = 2
-2
-ikc3> ^ a = b
-2
-ikc3> b
-2
-```
-
-To use destructuring just type the litteral value you want to match and
-put identifiers (variable names) where you want a variable matching the
-value on the other side of the equal sign. This is the most visual
-approach possible to text-based value matching : the data is constantly
-matched to litterals that show their type to the programmer. This is
-really helpful when writing large programs that need to scale in the way
-of abstractions. Let the data flow in the code through visual types.
-
-Examples :
-```
-ikc3> [x, y | z] = List.reverse([1, 2, 3, 4])
-[4, 3, 2, 1]
-ikc3> x
-4
-ikc3> y
-3
-ikc3> z
-[2, 1]
-```
-
-
-#### Macros
-
-KC3 macros are like Common Lisp macros with Elixir pattern-matching.
-
-Macros are like functions but start with `macro` instead of `fn` and
-their arguments do not get evaluated. However they get pattern matched
-and the full power of the pattern matcher is available for arguments
-destructuring. Use a map if you want named arguments. Use a list if you
-want &rest arguments, use a block if you want a &body argument.
-
-When evaluated, a macro call returns a tag which is in turn evaluated
-in the calling site lexical environment. This allows for DSLs and custom
-control structures to be defined in KC3.
-
-Many basic operations in KC3 are defined as macros : error handling,
-free operations with `unwind-protect`, graph database operations like
-`Facts.with`.
-
-
-#### If, then, else.
-
-Conditionals in KC3 are like in Ruby, for example :
-```
-ikc3> if true && true
-ikc3>   1 + 1
-ikc3>   2 + 2
-ikc3> end
-4
-
-ikc3> if true && false
-ikc3>   1 + 1
-ikc3>   2 + 2
-ikc3> else
-ikc3>   3 + 3
-ikc3>   4 + 4
-ikc3> end
-8
-```
-
-A KC3 `if` statement always return a value. If the condition is true, the
-first (then) block gets evaluated. If the condition is false the second
-block gets evaluated. If the condition is false and an `else` block is
-not provided, then `void` gets returned.
-
-One liner examples with `then` :
-```
-ikc3> if 42 then 100 else 101 end
-100
-ikc3> if 0 then 100 else 101 end
-101
-```
-
-## defmodule and def
-
-Example :
-```
-ikc3> defmodule Example do
-ikc3>   def three = 3
-ikc3>   def double = fn (x) do x * 2 end
-ikc3>   def double_tuple = macro (x) do {x, x} end
-ikc3>   def operator_double = %KC3.Operator{sym: :double, symbol_value: fn (x) { x * 2 }
-ikc3> end
-Example
-ikc3> Example.three
-3
-ikc3> Example.double
-fn (x) do x * 2 end
-ikc3> Example.double(21)
-42
-ikc3> Example.double_tuple(:ok)
-{:ok, :ok}
-ikc3> double 21
-42
-```
-
-
-#### Facts
-
-The Facts module allows read and write access to a graph database
-containing facts : triples of subject, predicate, object.
-
-Examples for querying the KC3 database containing all definitions of
-the interpreter :
-
-```
-ikc3> Facts.with_tags(Facts.env_facts(), KC3, :operator, ?,
-        fn (fact) { puts(fact.object); :ok })
-operator_eq
-operator_gt
-operator_lt
-[...]
-:ok
-```
-
-
-### kc3s
-
-Script interpreter. Works the same as ikc3 but is not interactive
-and does not output results.
-
-
-### HTTPd
-
-HTTP daemon, use `make test_httpd`.
-
-The http daemon is defined in `httpd/httpd.c` and
-`lib/kc3/0.1/httpd.kc3`.
-
-The http daemon is a static file server listing directories and
-serving files for display or download (Web 1.0).
 
 
 ## TODO
diff --git a/STRUCTURE.md b/STRUCTURE.md
new file mode 100644
index 0000000..99b6df5
--- /dev/null
+++ b/STRUCTURE.md
@@ -0,0 +1,136 @@
+
+## Structure
+
+### libkc3
+
+KC3 is implemented using libkc3 a small C99 library implementing the core
+of the language.
+
+The library includes a parser and an interpreter for KC3 code in C
+structures.
+
+Support for large integers provided by
+[libtommath](https://github.com/libtom/libtommath).
+
+Support for C function calls provided by
+[libffi](https://github.com/libffi/libffi).
+
+Modules are saved as facts databases.
+
+
+#### Parser
+
+The parser is recursive descent.
+
+#### AST
+
+The AST is represented as KC3 data structures and can be meta-programmed
+in C.
+
+#### Interpreter
+
+Please see the following functions in `libkc3/env.c`:
+ - `env_eval_tag` : evaluates a tag (any KC3 type)
+ - `env_eval_block` : evaluates a block (`do ... end`)
+ - `env_eval_call` : evaluates a function call (`Cfn`, `Fn`)
+ - `env_eval_call_fn_args` : evaluates a KC3 function call (Fn)
+
+
+### ikc3
+
+Interactive shell. Terminal I/O provided by
+[linenoise](https://github.com/antirez/linenoise/tree/1.0).
+
+Example :
+```
+$ make test
+$ ikc3/ikc3
+ikc3> ikc3> 1 + 1
+2
+ikc3> 2 + 2
+4
+ikc3> 3 + 3
+6
+ikc3> 1 +
+ikc3> 1
+2
+ikc3> double = fn (x) { x * 2 }
+fn (x) { x * 2 }
+ikc3> double
+fn (x) { x * 2 }
+ikc3> double(1)
+2
+ikc3> double(2)
+4
+ikc3> double(3)
+6
+ikc3> double(4)
+8
+ikc3> List.map([1, 2, 3, 4], double)
+[2, 4, 6, 8]
+ikc3> List.reverse(List.map([1, 2, 3, 4], double))
+[8, 6, 4, 2]
+```
+
+### Library path
+
+The `List.map` and `List.reverse` functions are defined in
+`lib/kc3/0.1/list.kc3` and can be modified in real time.
+
+For example, without closing ikc3 let's redefine `List.reverse`,
+open an editor and change the line in `lib/kc3/0.1/list.kc3` from
+
+```
+  def reverse = fn {
+    (x) { reverse(x, ()) }
+    ([], acc) { acc }
+    ([a | b], acc) { reverse(b, [a | acc]) }
+  }
+```
+
+to
+
+```
+  def reverse = fn {
+    (x) { reverse(x, ()) }
+    ([], acc) { [:reversed | acc] }
+    ([a | b], acc) { reverse(b, [a | acc]) }
+  }
+}}
+```
+
+and check the results of the last command (up key) in ikc3/ikc3 :
+
+```
+ikc3> List.reverse(List.map([1, 2, 3, 4], double))
+[:reversed, 8, 6, 4, 2]
+```
+
+Don't forget to revert the changes to `list.kc3`.
+
+
+### kc3s
+
+Script interpreter. Works the same as ikc3 but is not interactive
+and does not output results.
+
+
+### HTTPd
+
+HTTP daemon, use `make test_httpd`.
+
+The http daemon is defined in `httpd/httpd.c` and
+`lib/kc3/0.1/httpd.kc3`.
+
+The http daemon is both a static file server listing directories and
+serving files for display or download (Web 1.0), and a MVC framework
+loading KC3 files in `./app`. The router is defined in
+`./conf/router.kc3` .
+
+---
+
+Top : [KC3 README.md](README.md)
+
+Previous : [KC3 usage guide](USAGE.md)
+
+Next : [KC3 tutorial and examples guide](TUTORIAL.md)
diff --git a/TESTING.md b/TESTING.md
new file mode 100644
index 0000000..915e7fd
--- /dev/null
+++ b/TESTING.md
@@ -0,0 +1,64 @@
+# Testing KC3
+
+Before running the tests, ensure KC3 is correctly installed.
+You can consult the [KC3 installation guide](INSTALL.md) for this.
+
+
+## Running the OpenGL demo
+```sh
+make demo_gl
+```
+
+Press Q to quit, F for fullscreen, Left and Right arrows to move
+through sequences.
+
+Other targets exist :
+```sh
+make demo_gl_asan
+make gdb_demo_gl
+make lldb_demo_gl
+```
+
+## Running the Cairo demo
+```sh
+make demo
+```
+
+Press Q to quit, Left and Right arrows to move through sequences.
+
+Other targets exist :
+```sh
+make demo_asan
+make gdb_demo
+make lldb_demo
+```
+
+## Running the HTTPd demo
+```sh
+make test_httpd
+```
+
+And direct your browser to http://127.0.0.1:58000/ .
+
+
+## Running the tests
+```sh
+make test
+```
+
+All the tests will be run. More specific targets exist :
+```sh
+make test_libkc3
+make test_ikc3
+make test_libkc3_asan
+make test_ikc3_asan
+make test_asan
+```
+
+---
+
+Top : [KC3 README.md](README.md)
+
+Previous : [KC3 installation guide](INSTALL.md)
+
+Next : [KC3 usage guide](USAGE.md)
diff --git a/TUTORIAL.md b/TUTORIAL.md
new file mode 100644
index 0000000..b4d6154
--- /dev/null
+++ b/TUTORIAL.md
@@ -0,0 +1,285 @@
+# KC3 tutorial and examples
+
+Here are a few `ikc3` examples to play with.
+
+
+## Maps
+
+KC3 maps are key-value stores, you can use any tag as a key and
+associate a value to it.
+
+You can use destructuring to access KC3 maps :
+```
+ikc3> a = %{id: 1, title: "My title", message: "Hello, world !"}
+%{id: 1, title: "My title", message: "Hello, world !"}
+ikc3> a = %{}
+%{id: 1, title: "My title", message: "Hello, world !"}
+ikc3> %{id: id, title: "My title", message: message} = a
+%{id: 1, title: "My title", message: "Hello, world !"}
+ikc3> id
+1
+ikc3> message
+"Hello, world !"
+```
+
+You can use the dot syntax to access map values from a `Sym` key :
+```
+ikc3> a = %{id: 1, title: "My title", message: "Hello, world !"}
+%{id: 1, title: "My title", message: "Hello, world !"}
+ikc3> a.id
+1
+ikc3> a.message
+"Hello, world !"
+```
+
+You can also use the `KC3.access` function for the same result :
+```
+ikc3> a = %{id: 1, title: "My title", message: "Hello, world !"}
+%{id: 1, title: "My title", message: "Hello, world !"}
+ikc3> access(a, :id)
+1
+ikc3> access(a, :message)
+"Hello, world !"
+```
+
+
+## Unicode characters
+
+`ikc3` fully supports Unicode :
+
+Some unicode characters :
+```
+ikc3> '\U+1B2FB'
+'𛋻'
+ikc3> '𐅀'
+'𐅀'
+ikc3> '🤩'
+'🤩'
+ikc3>
+```
+
+## Large integers
+
+```
+ikc3> a = 1 + 100000000000000000000000000000000
+100000000000000000000000000000001
+ikc3> a * a
+10000000000000000000000000000000200000000000000000000000000000001
+ikc3>
+```
+
+## Ratios
+
+Ratios are made with a couple of large integers : the numerator
+which can be any number, and the denominator which has to be positive.
+They represent fractions of integral numbers.
+They are written with a slash and no space.
+
+```
+ikc3> 1/2 + 2/3
+7/6
+ikc3> 1/2 * 2/3
+1/3
+ikc3> 1/2 / 2/3
+3/4
+ikc3> 1/2 - 2/3
+-1/6
+```
+
+
+## Complex numbers
+
+Complex numbers are constructed using the operator `+i` on any kind of
+numbers (unsigned, signed, float, ratios, and even other complex
+numbers). For instance, you can write `a +i b` where `a` and `b` are
+real numbers.
+
+```
+ikc3> 1 +i 2
+1 +i 2
+ikc3> 1 +i 2 + 2 +i 3
+3 +i 5
+ikc3> (1 +i 2) * (2 +i 3)
+-4 +i 7
+ikc3> (1 +i 2) / (2 +i 3)
+0 +i 0
+ikc3> (1/1 +i 2/1) / (2 +i 3)
+8/13 +i 1/13
+```
+
+As you can see integer division is not producing ratios.
+That might change in future releases.
+
+
+## Lists
+
+Lists are marked with brackets `[]`.
+
+Regular lists can be :
+ - an element and a list : `[1 | []]` → `[1]`
+ - multiple elements : `[1, 2, 3]`
+ - multiple elements and a list : `[1, 2 | [3, 4]]` → `[1, 2, 3, 4]`
+ - the empty list : `[]`
+
+Regular lists end with the empty list : `[1] == [1 | []]`.
+
+You can also contruct dotted lists like in Common Lisp where
+the next list pointer is an arbitrary form. E.g. :
+ - an element and an element : `[1 | 2]`
+ - multiple elements and an element : `[1, 2, 3 | 4]`
+ - the empty list and an element : `[[] | 1]`
+
+All these list formats are supported in pattern matching.
+
+
+## Pattern matching and destructuring
+
+The KC3 pattern matching principles come from Erlang and Elixir.
+
+All tag data structures in KC3 can be pattern matched using the equal
+sign (`=`) against litteral values containing identifiers. All
+identifiers are supposed to be new bindings when using pattern matching
+in KC3. If you want to use an identifier's value in pattern matching you
+must use the _pin operator_ (`^`). Variables can be assigned a new value
+from either side of the equal sign and from inside a tag data structure,
+which is called _destructuring_.
+
+
+Examples :
+```
+ikc3> a = 1
+1
+ikc3> a = 2
+2
+ikc3> a
+2
+ikc3> ^ a = 1
+void
+ikc3> ^ a = 2
+2
+ikc3> ^ a = b
+2
+ikc3> b
+2
+```
+
+To use destructuring just type the litteral value you want to match and
+put identifiers (variable names) where you want a variable matching the
+value on the other side of the equal sign. This is the most visual
+approach possible to text-based value matching : the data is constantly
+matched to litterals that show their type to the programmer. This is
+really helpful when writing large programs that need to scale in the way
+of abstractions. Let the data flow in the code through visual types.
+
+Examples :
+```
+ikc3> [x, y | z] = List.reverse([1, 2, 3, 4])
+[4, 3, 2, 1]
+ikc3> x
+4
+ikc3> y
+3
+ikc3> z
+[2, 1]
+```
+
+
+## Macros
+
+KC3 macros are like Common Lisp macros with Elixir pattern-matching.
+
+Macros are like functions but start with `macro` instead of `fn` and
+their arguments do not get evaluated. However they get pattern matched
+and the full power of the pattern matcher is available for arguments
+destructuring. Use a map if you want named arguments. Use a list if you
+want &rest arguments, use a block if you want a &body argument.
+
+When evaluated, a macro call returns a tag which is in turn evaluated
+in the calling site lexical environment. This allows for DSLs and custom
+control structures to be defined in KC3.
+
+Many basic operations in KC3 are defined as macros : error handling,
+free operations with `unwind-protect`, graph database operations like
+`Facts.with`.
+
+
+## If, then, else.
+
+Conditionals in KC3 are like in Ruby, for example :
+```
+ikc3> if true && true
+ikc3>   1 + 1
+ikc3>   2 + 2
+ikc3> end
+4
+
+ikc3> if true && false
+ikc3>   1 + 1
+ikc3>   2 + 2
+ikc3> else
+ikc3>   3 + 3
+ikc3>   4 + 4
+ikc3> end
+8
+```
+
+A KC3 `if` statement always return a value. If the condition is true, the
+first (then) block gets evaluated. If the condition is false the second
+block gets evaluated. If the condition is false and an `else` block is
+not provided, then `void` gets returned.
+
+One liner examples with `then` :
+```
+ikc3> if 42 then 100 else 101 end
+100
+ikc3> if 0 then 100 else 101 end
+101
+```
+
+## defmodule and def
+
+Example :
+```
+ikc3> defmodule Example do
+ikc3>   def three = 3
+ikc3>   def double = fn (x) do x * 2 end
+ikc3>   def double_tuple = macro (x) do {x, x} end
+ikc3>   def operator_double = %KC3.Operator{sym: :double, symbol_value: fn (x) { x * 2 }
+ikc3> end
+Example
+ikc3> Example.three
+3
+ikc3> Example.double
+fn (x) do x * 2 end
+ikc3> Example.double(21)
+42
+ikc3> Example.double_tuple(:ok)
+{:ok, :ok}
+ikc3> double 21
+42
+```
+
+
+## Facts
+
+The Facts module allows read and write access to a graph database
+containing facts : triples of subject, predicate, object.
+
+Examples for querying the KC3 database containing all definitions of
+the interpreter :
+
+```
+ikc3> Facts.with_tags(Facts.env_facts(), KC3, :operator, ?,
+        fn (fact) { puts(fact.object); :ok })
+operator_eq
+operator_gt
+operator_lt
+[...]
+:ok
+```
+
+---
+
+Top : [KC3 README.md](README.md)
+
+Previous : [KC3 structure guide](STRUCTURE.md)
diff --git a/USAGE.md b/USAGE.md
new file mode 100644
index 0000000..168c83c
--- /dev/null
+++ b/USAGE.md
@@ -0,0 +1,28 @@
+# KC3 usage guide
+
+## Running ikc3
+```sh
+ikc3/.libs/ikc3
+```
+
+## Running gdb
+```sh
+make gdb_ikc3
+make gdb_test
+make gdb_test_ikc3
+```
+
+## Running lldb
+```sh
+make lldb_ikc3
+make lldb_test
+make lldb_test_ikc3
+```
+
+---
+
+Top : [KC3 README.md](README.md)
+
+Previous : [KC3 testing guide](TESTING.md)
+
+Next : [KC3 structure guide](STRUCTURE.md)