Docs

docs/main.md

@@ -0,0 +1,174 @@
+
+## Quick warning
+
+This language is still in its pre alpha stages, while it tends to work it still has numerous bugs, breaks, and fails with a smell of unusual input, it is not suitable for anything beyond experimenting and having fun. That said this project has been my biggest one yet, and is one of my favorites, having went under multiple rewrites over the 4 or so years its changed a lot from simple forth style syntax, to now, a c/rust style, which has been a struggle, but now its at a point where it actually produces code and you can *kinda* make something with it.
+
+Hope you have fun figuring out how to use this damn thing, and maybe even build something with it.
+
+Also, the docs are also written with ChatGPT (gross, i know), but i needed some docs fast.
+
+ \- MCorange
+
+## Summary
+
+This language is a small, low level, C and Rust inspired systems language with a strong focus on explicit control, simple syntax, and predictable behavior. It mixes familiar C style statements and loops with Rust-like ideas such as structs, methods, references, and explicit types. The goal is clarity over magic: most things are spelled out, lifetimes are implied by references, and there is little hidden behavior.
+
+The language is suitable for experiments, embedded style programs, or as a foundation for a custom runtime or OS environment. It favors straightforward semantics, manual control flow, and a minimal standard library model.
+
+## High level description
+
+As a procedural language, barely higher level than C, programs are built from functions, structs, and constants. Types are explicit, references are written by prepending `&`, and arrays or slices are expressed directly in the type system. For now code is organized with `include`, for simpler development, this will change into modules eventually.
+
+Control flow is traditional and imperative. There are `if`, `else`, `for`, `while`, and `loop` constructs, along with `break` and `continue`. Functions return values explicitly using `return`, and side effects are visible and direct.
+
+Methods are just functions namespaced under a type, and there is no hidden constructor logic. Everything that allocates or returns a reference does so explicitly.
+
+## Small language reference
+
+## Types
+
+Type aliases:
+
+```no-test
+type cstr = [u8];
+```
+
+Creates an alias. Here, `str` is defined as a byte array type.
+
+Built-in simple types:
+
+* usize/isize
+* i8-i64
+* u8-u64
+* bool
+* array or slice types like [u8]
+
+References are written with `&T`.
+
+## Includes
+
+```no-test
+include "std.mcl";
+```
+
+Textual inclusion of another source file. This is resolved at compile time.
+
+## Structs
+
+```no-test
+struct Foo {
+    a: usize,
+    b: &str
+}
+```
+
+Structs group named fields. Fields have explicit types. There are no implicit constructors.
+
+## Functions
+
+Function definition syntax:
+
+```no-test
+fn name(arg: Type, ...) -> ReturnType {
+    ...
+}
+```
+
+Example:
+
+```no-test
+fn mul(n: usize, n2: usize) -> usize {
+    return n * n2;
+}
+```
+
+Functions may return values using `return`. Void functions omit the return type.
+
+## Methods
+
+Methods are functions scoped to a type:
+
+As of now methods are only able to be linked to [Structs](#Structs)
+
+```no-test
+fn Foo.new(a1: usize, b: &str) -> &Foo {
+    return &Foo {
+        a: a1,
+        b: b
+    };
+}
+```
+
+This defines a constructor-like function for `Foo`. It explicitly returns a reference to a `Foo` value.
+
+## Variables
+
+Variables are declared with `let`:
+
+```no-test
+let obj = Foo::new(1, "owo");
+```
+
+Type inference appears to exist, but types can likely be written explicitly if desired.
+
+## Field access
+
+Struct fields can be accessed through references:
+
+```no-test
+obj->b;
+```
+
+As well as without dereferencing:
+
+```no-test
+obj.c
+```
+
+## Control flow
+
+Infinite loop:
+
+```no-test
+loop {
+    ...
+}
+```
+
+While loop:
+
+```no-test
+while (true) {
+    ...
+}
+```
+
+For loop:
+
+```no-test
+for (let i = 0; i < 10; i += 1) {
+    ...
+}
+```
+
+Conditionals:
+
+```no-test
+if (i > 7) {
+    break;
+} else {
+    continue;
+}
+```
+
+## Constants
+
+```no-test
+const FOO: usize = main;
+```
+
+## Statics
+
+```no-test
+static FOO: usize = main;
+```