Extend documentation

diff --git a/README.md b/README.md
index c9f28859bdc3b1e4a1a8c0c25da5bc335487d1dc..211c407f9a604d8e5b89a8f67adddcaf5dcc8608 100644 (file)
--- a/README.md
+++ b/README.md
@@ -11,6 +11,8 @@ fibo
        )))
 ```
 
+You can run the example using `./uwu example/test.uwu`
+
 ## What this language is
 
 - Demonstration of dlopen - 35%
@@ -58,22 +60,7 @@ The syntax is very minimal. Almost everything is solved via functions (no contro
 
 Currently there are no floating point values, but they might be added in the future (One could also add them using native modules).
 
-## Syntax
-
-A module is made out of functions. Each function is made out of a name and exactly one expression, seperated by arbitrary whitespace.
-
-```
-function_name expression
-
-other_function_name
-       other_expression
-
-
-               weird_indent_function_name
-
-       weird_indent_expression
-
-```
+Typing is weak and handled at runtime, native modules can easily add their own types. Handling of type errors is up to the functions, usually they will throw an error and exit the program if incorrect types were passed to them.
 
 ## Platform
 
@@ -84,3 +71,8 @@ Uses shared object files for native modules, opens them with `dlopen`, which is
 Requires a libc that implements asprintf (asprintf is not standard, glibc and musl implement it and there are drop-in replacements)
 
 The current implementation of the VM does not take advantage of lambda (no caching of results), but such a feature might be added in the future. I might also add a compiler for LLVM or x86_64 NASM or a JIT in the future.
+
+## Further Documentation
+
+See `doc/syntax.md` for a syntax documentation.
+See `doc/std.md` for standard library documentation.

diff --git a/doc/std.md b/doc/std.md
new file mode 100644 (file)
index 0000000..1ebd6db
--- /dev/null
+++ b/doc/std.md
@@ -0,0 +1,51 @@
+# Standard library
+
+## The `:bool` module
+
+- `:bool:if`: Requires exactly 3 arguments of arbitrary type. If $0 is a truthy value, evaluate and return $1. If $0 is a falsy value, evaluate and return $2. Values considered as falsy are: `:bool:false` and `:nil:nil`. Everything else is considered truey.
+
+- `:bool:and`: Accepts an arbitrary number of arguments of arbitrary type, but at least one. Returns `:bool:true` if all of the arguments are considered truthy.
+
+- `:bool:or`: Accepts an arbitrary number of arguments of arbitrary type, but at least one. Returns `:bool:true` if at least one of the arguments is considered truthy.
+
+- `:bool:equal`: Accepts an arbitrary number of arguments of arbitrary type, but at least 2. Returns `bool:true` if either all of the arguments are considered truthy or all of the arguments are considered falsy.
+
+- `:bool:not`: Accepts exactly one argument of arbitrary type. Returns `:bool:true` if the $0 is considered falsy, returns `:bool:false` if $0 is considered truthy.
+
+- `:bool:true`: The true constant
+
+- `:bool:false`: The false constant
+
+- `:bool:is`: Accepts an arbitrary number of arguments of arbitrary type, but at least one. Returns `:bool:true` if all arguments are booleans (`:nil:nil` is NOT considered a boolean).
+
+## The `:int` module
+
+- `:int:add`: Accepts an arbitrary number of integer arguments (or none at all) and returns the sum of all arguments, or `0` if none were given.
+
+- `:int:sub`: Accepts exactly 2 integer arguments and returns their difference.
+
+- `:int:mul`: Accepts an arbitrary number of integer arguments (or none at all) and returns the product of all arguments, or `1` if none were given.
+
+- `:int:div`: Accepts exactly 2 integer arguments and returns their quotient (rounded towards 0).
+
+- `:int:mod`: Accepts exactly 2 integer arguments and returns the reminder of their division.
+
+- `:int:smaller`: Accepts exactly 2 integer arguments and returns `:bool:true` if $0 is smaller than $1, `:boool:false` else.
+
+- `:int:greater`: Accepts exactly 2 integer arguments and returns `:bool:true` if $0 is greater than $1, `:bool:false` else.
+
+- `:int:equal`: Accepts an arbitrary number of integer arguments, but at least 2. Returns `bool:true` if all the arguments are equal.
+
+- `:int:is`: Accepts an arbitrary number of arguments of arbitrary type, but at least one. Returns `:bool:true` if all arguments are integers.
+
+## The `:str` module
+
+- `:str:cat`: Accepts an arbitrary number of arguments of arbitrary type and returns the concatenation of their string representations.
+
+### String representations
+
+- Integers: decimal notation
+- Strings: themself
+- Function references: `[Function referece: %p]`, where %p is the memory address of the UwUVMFunction in memory.
+- Nil: an empty string
+- Booleans: `true` or `false`

diff --git a/doc/syntax.md b/doc/syntax.md
new file mode 100644 (file)
index 0000000..6ec3cfc
--- /dev/null
+++ b/doc/syntax.md
@@ -0,0 +1,35 @@
+## Syntax
+
+A module is made out of functions. Each function is made out of a name and exactly one expression, seperated by arbitrary whitespace.
+
+```
+function_name expression
+
+other_function_name
+       other_expression
+
+
+               weird_indent_function_name
+
+       weird_indent_expression
+
+```
+
+An expression is either of these:
+
+- Integer literal: `0`, `1`, `3245`
+- String literal: `"hello, world"`, `""`, `"this is
+a multiline
+string literal
+"`
+- Argument number: `$0`, `$1`, `$5` 
+- Function reference: `&function_name`
+- Function call: `function_name(args)` or just `function_name`, where args is a comma-separated list of expressions.
+
+**Important:** When passing arguments to a function, these arguments are not passed directly as values, but rather as expressions. Each argument is evaulated as the called function accesses it. This means that you can have constructs that would cause infinite recursion in other languages - a good example for a usecase of that are conditions: `:bool:if(condition, if_true, else)` is just a regular function from the standard library. `if_true` is only evaluated if condition is truey, meaning that if condition is falsey and `if_true` is a function call, that function will not be called.
+
+Function name syntax:
+
+- `function`: Call `function` in the current module.
+- `path:to:module:function`: Call `function` in the module located at `path/to/module`. That path is relative to the path of the module calling the function. See module paths section under Invocation.
+- `:std_module:function`: Call `function` in the module `std_module` from the standard library.