Updated some info and added reference file

README.md

@@ -1,42 +1,39 @@
 # Bits Runner Builder
+Welcome to Bits Runner Builder!
+
+## Quick links
+- [Language Reference](Reference.md)
+- [Detailed Syntax](Syntax.md)
 
 ## Overview
-Bits Runner Builder (brb) is a compiler for Bits Runner Code (brc) language, which has been designed for the Bits Runner Builder operating system. It aims to be a low-level language, which can be a replacement for C while providing a revised syntax and a couple of quality of life improvement. It's a simple system programming language, so no class hierarchies, templates, or other unnecessary fluff.
+Bits Runner Builder (brb) is a compiler for Bits Runner Code (brc) language, which has been designed for the Bits Runner Builder operating system. It aims to be an opinionated, low-level language, a sort of improved C while providing a revised syntax and a couple of quality of life improvement. It's a simple system programming language, so no class hierarchies, templates, or other unnecessary fluff.
 
-It has been been built on top of LLVM.
+It has been been built with LLVM so it should be fairly performant.
 
-## Show me the code!
+## Main features
+It should allow for low-level system programming, so one of the main features is a seamless support for embeded assembly, pointers mainipulation and explicit data handling. For this reason data types have explicit byte-sizes, there is no runtime and the memory is manually managed.
 
-### Comments
-Like in C, comments can specified using either `\\` which will run until the end of the line or through `/* */` block. However, unlike C, the `/* bla bla /* bla */ */` comments can be also embeded inside each other.
-
-### Literals
-**Number literals** can be specified as decimal, hexadecimal, and binary numbers. Digits can be separated by an '_' but it cannot be the first or the last character (otherwise it will get interpreted as and identifier).
+The language aims to be simple, easy to reason about and predictable. For this reason there a class-like features, but no inheritance. Composition is much better anyway and doesn't lead to incomprehensible codebases (did I mention that it's opinionated?).
 
+## Examples
 ```
-// Valid examples:
-1024
-1_024
-1.245
+// Basic hello world
+//
+@extern putchar fun: character u32 -> u32
 
-1_000.
+main fun -> u32
+    text data<u8> <- "Hello, world!\n"
+    
+    rep i u32 <- 0, text[i] != 0:
+        putchar(text[i])
+        i <- i + 1
+    ;
 
-0xffa
-0xffaa_42bb
-
-0b1101
-0b1010_0101
-
-// Invalid examples:
-_100
-1000_.100
-
-0x_fa
-
-0b10_
-_0b1101
+    ret 0
+;
 ```
 
-### Control flow
+## But why?
+The idea was to build the whole computing environment from scratch which can be its own thing. Many project of this kind try to be sort of recoding of C/Unix, but this is not the point in the case. This project doesn't aim at compatibility so it may hapilly break things in order to make things simpler, more modern, or just different.
 
-### Functions
+It's mostly a learning opportunity and a bit of fun, but maybe you can find some bits of interesting knowledge for your own project.

Reference.md

@@ -0,0 +1,71 @@
+# Fatures Description
+
+## List language elements
+- Literals
+- Variables
+  - Integers (signed & unsigned)
+  - Floating points
+  - Data (array type)
+  - Type (structure type)
+  - Pointers
+- Functions
+- Conditions
+- Repeat (loop)
+- Modules
+- Comments
+
+## Literals
+**Number literals** can be specified as decimal, hexadecimal, and binary numbers. Digits can be separated by an '_' but it cannot be the first or the last character (otherwise it will get interpreted as and identifier).
+
+```
+// Valid examples:
+1024
+1_024
+1.245
+
+1_000.
+
+0xffa
+0xffaa_42bb
+
+0b1101
+0b1010_0101
+
+// Invalid examples:
+_100
+1000_.100
+
+0x_fa
+
+0b10_
+_0b1101
+```
+
+## Functions
+
+## Conditions
+If-Else statements can be written on a single or multiple lines and are an expression, which allows for something like this:
+```
+isValid bool <- if count = 0: doForEmpty() else doForCount(count)
+```
+
+## Repeats
+C-style for, while, and do-while are all combined into a single `rep` loop. The format is `rep init, pre-condition, post-condition`. `init` allows to setup a counter, pre-condition is evaluated before and post after each loop. Each part is optional, but if you include post-condition, pre-condition must also be include. Some examples:
+```
+// infinite loop
+rep: doStuff()
+
+// do things ten times
+rep i s32 <- 0, i < 10:
+  doStuff(i)
+  i <- i + 1
+;
+
+// do things at least once
+rep i s32 <- 0, true, i < someValue:
+  doStuff(i)
+;
+```
+
+## Comments
+Like in C, comments can specified using either `\\` which will run until the end of the line or through `/* */` block. However, unlike C, the `/* bla bla /* bla */ */` comments can be also embeded inside each other.