+
+Variable declarations have the following syntax:
+
+<name> :[:] [type] [= expression];
+
+
+
The square brackets ([]) indicate something optional.
+
+
+All of the following statements
+declare an new variable x which is an integer, and has a value of 0:
+
+x : int;
+x : int = 0;
+x := 0;
+
+Note that in the first of those statements, although no expression
+is specified, it defaults to 0.
+
+
+
If you wanted x to be a floating-point number, you could use:
+
+
+x : float;
+x : float = 0;
+x := 0.0;
+
+
+
Note that 0 can be used as both a float and an integer, but
+when no type is specified, it defaults to an int, whereas 0.0
+defaults to a float.
+
+
Here are all of toc's basic builtin types and their ranges of values:
+
+
+
int - A 64-bit signed integer (always), -9223372036854775808 to 9223372036854775807
+
i8 - An 8-bit signed integer, -128 to 128
+
i16 - 16-bit signed integer, -32768 to 32767
+
i32 - 32-bit signed integer, -2147483648 to 2147483647
+
i64 - 64-bit signed integer (same as int, but more explicit about the size), -9223372036854775808 to 9223372036854775807
+
u8 - An 8-bit unsigned integer, 0 to 255
+
u16 - 16-bit unsigned integer, 0 to 65535
+
u32 - 32-bit unsigned integer, 0 to 4294967295
+
u64 - 64-bit unsigned integer, 0 to 18446744073709551615
+
float - A 32-bit floating-point number, -3.40282347e+38 to 3.40282347e+38
+
f32 - A 32-bit floating-point number (same as float, but more explicit about the size)
+
f64 - A 64-bit floating-point number, -1.7976931348623157e+308 to 1.7976931348623157e+308
+
bool - A boolean value, either false or true.
+
char - A character (usually either -128 to 127 or 0 to 255).
+
+
+
To make declarations constant, use :: instead of :. e.g.
+
+
+x ::= 5+3;
+y :: float = 5.123;
+
+
+
Here, "constant" means constant at compile time, not read-only as it does in C. One interesting thing about toc is that normal functions can run at compile time, so pretty much any expression is a valid initializer for a constant, e.g. doing x ::= some_function(); runs some_function at compile time, not at run time.
+
+
diff --git a/docs/01.html b/docs/01.html
new file mode 100644
index 0000000..f520805
--- /dev/null
+++ b/docs/01.html
@@ -0,0 +1,31 @@
+
+
+
+
+A first program
+
+
+
The main function in toc corresponds to the main function in C. This function is called when your program is run. So, this is a valid toc program which does nothing:
+
+
+main ::= fn() {
+}
+
+
+
It declares a constant, main, which is a function with an empty body. Note that the syntax for declaring functions is the same as the syntax for declaring constants (it isn't something like fn main() { ... }).
+
+
Note that you do not need a semicolon at the end of this declaration (for convenience, if a declaration ends with a closing brace (}), you do not need a semicolon).
+
+
Assuming you have compiled the compiler (see README.md for instructions about that), you can compile it with
+
+
+toc <your filename>
+
+
+
You will get a file called out.c, which you can then put through your C compiler to get an executable file which does nothing. Congratulations! You've written your first toc program.