From f4e7cc49c8eed6e224a11d303e11b15887c7dc17 Mon Sep 17 00:00:00 2001 From: mlokr Date: Sat, 15 Jun 2024 09:37:19 +0200 Subject: [PATCH 1/7] adding more elaborate directive example --- hblang/examples/directives.hb | 10 +++++++++- hblang/tests/codegen_tests_different_types.txt | 2 +- hblang/tests/codegen_tests_directives.txt | 2 +- hblang/tests/codegen_tests_example.txt | 2 +- hblang/tests/codegen_tests_fb_driver.txt | 2 +- hblang/tests/codegen_tests_if_statements.txt | 2 +- hblang/tests/codegen_tests_structs.txt | 2 +- 7 files changed, 15 insertions(+), 7 deletions(-) diff --git a/hblang/examples/directives.hb b/hblang/examples/directives.hb index b371db42..c4caf9cd 100644 --- a/hblang/examples/directives.hb +++ b/hblang/examples/directives.hb @@ -4,5 +4,13 @@ Type := struct { } main := fn(): int { - return @eca(int, 1, Type.(10, 20), @sizeof(Type), @alignof(Type), 5, 6); + byte := @as(u8, 10); + same_type_as_byte := @as(@TypeOf(byte), 30); + wide_uint := @as(u32, 40); + truncated_uint := @as(u8, @intcast(wide_uint)); + size_of_Type_in_bytes := @sizeof(Type); + align_of_Type_in_bytes := @alignof(Type); + hardcoded_pointer := @as(^u8, @bitcast(10)); + ecall_that_returns_int := @eca(int, 1, Type.(10, 20), 5, 6); + return 0; } diff --git a/hblang/tests/codegen_tests_different_types.txt b/hblang/tests/codegen_tests_different_types.txt index d6f5ec3d..13fe3f06 100644 --- a/hblang/tests/codegen_tests_different_types.txt +++ b/hblang/tests/codegen_tests_different_types.txt @@ -1,3 +1,3 @@ -code size: 477 +code size: 471 ret: 512 status: Ok(()) diff --git a/hblang/tests/codegen_tests_directives.txt b/hblang/tests/codegen_tests_directives.txt index 0c040308..831d0486 100644 --- a/hblang/tests/codegen_tests_directives.txt +++ b/hblang/tests/codegen_tests_directives.txt @@ -1,4 +1,4 @@ ev: Ecall -code size: 182 +code size: 235 ret: 0 status: Ok(()) diff --git a/hblang/tests/codegen_tests_example.txt b/hblang/tests/codegen_tests_example.txt index 93fa5415..b1b92cc2 100644 --- a/hblang/tests/codegen_tests_example.txt +++ b/hblang/tests/codegen_tests_example.txt @@ -1,3 +1,3 @@ -code size: 85 +code size: 82 ret: 1 status: Ok(()) diff --git a/hblang/tests/codegen_tests_fb_driver.txt b/hblang/tests/codegen_tests_fb_driver.txt index 07dad9fa..32750759 100644 --- a/hblang/tests/codegen_tests_fb_driver.txt +++ b/hblang/tests/codegen_tests_fb_driver.txt @@ -1,3 +1,3 @@ -code size: 525 +code size: 513 ret: 0 status: Ok(()) diff --git a/hblang/tests/codegen_tests_if_statements.txt b/hblang/tests/codegen_tests_if_statements.txt index f95d4bda..2ae138d5 100644 --- a/hblang/tests/codegen_tests_if_statements.txt +++ b/hblang/tests/codegen_tests_if_statements.txt @@ -1,3 +1,3 @@ -code size: 265 +code size: 262 ret: 55 status: Ok(()) diff --git a/hblang/tests/codegen_tests_structs.txt b/hblang/tests/codegen_tests_structs.txt index 5c3dce3f..473452e1 100644 --- a/hblang/tests/codegen_tests_structs.txt +++ b/hblang/tests/codegen_tests_structs.txt @@ -1,3 +1,3 @@ -code size: 420 +code size: 417 ret: 3 status: Ok(()) From 36930ebd9be1818447223c35aa168f5897313a28 Mon Sep 17 00:00:00 2001 From: mlokr Date: Sat, 15 Jun 2024 10:37:50 +0200 Subject: [PATCH 2/7] putting tests as examples in readme --- hblang/README.md | 308 ++++++++++++++++++ hblang/src/codegen.rs | 56 +++- hblang/src/lexer.rs | 42 --- hblang/src/lib.rs | 3 +- hblang/src/parser.rs | 18 - hblang/src/tests.rs | 9 +- hblang/tests/codegen_tests_example.txt | 3 - ...es.txt => codegen_tests_generic_types.txt} | 0 hblang/tests/lexer_tests_arithmetic.txt | 31 -- hblang/tests/lexer_tests_empty.txt | 1 - hblang/tests/lexer_tests_example.txt | 13 - hblang/tests/lexer_tests_whitespace.txt | 1 - hblang/tests/parser_tests_arithmetic.txt | 3 - hblang/tests/parser_tests_example.txt | 3 - 14 files changed, 358 insertions(+), 133 deletions(-) create mode 100644 hblang/README.md delete mode 100644 hblang/tests/codegen_tests_example.txt rename hblang/tests/{codegen_tests_geneic_types.txt => codegen_tests_generic_types.txt} (100%) delete mode 100644 hblang/tests/lexer_tests_arithmetic.txt delete mode 100644 hblang/tests/lexer_tests_empty.txt delete mode 100644 hblang/tests/lexer_tests_example.txt delete mode 100644 hblang/tests/lexer_tests_whitespace.txt delete mode 100644 hblang/tests/parser_tests_arithmetic.txt delete mode 100644 hblang/tests/parser_tests_example.txt diff --git a/hblang/README.md b/hblang/README.md new file mode 100644 index 00000000..8500faf4 --- /dev/null +++ b/hblang/README.md @@ -0,0 +1,308 @@ +# HERE SHALL THE DOCUMENTATION RESIDE + +#### directives +```hb +Type := struct { + brah: int, + blah: int, +} + +main := fn(): int { + byte := @as(u8, 10); + same_type_as_byte := @as(@TypeOf(byte), 30); + wide_uint := @as(u32, 40); + truncated_uint := @as(u8, @intcast(wide_uint)); + size_of_Type_in_bytes := @sizeof(Type); + align_of_Type_in_bytes := @alignof(Type); + hardcoded_pointer := @as(^u8, @bitcast(10)); + ecall_that_returns_int := @eca(int, 1, Type.(10, 20), 5, 6); + return 0; +} +``` + +#### if_statements +```hb +main := fn(): int { + return fib(10); +} + +fib := fn(x: int): int { + if x <= 2 { + return 1; + } else { + return fib(x - 1) + fib(x - 2); + } +} +``` + +#### global_variables +```hb +global_var := 10; + +complex_global_var := fib(global_var) - 5; + +fib := fn(n: int): int { + if 2 > n { + return n; + } + return fib(n - 1) + fib(n - 2); +} + +main := fn(): int { + return complex_global_var; +} + +``` + +#### generic_types +```hb +Vec := fn($Elem: type): type { + return struct { + data: ^Elem, + len: uint, + cap: uint, + }; +} + +main := fn(): int { + i := 69; + vec := Vec(int).{ + data: &i, + len: 1, + cap: 1, + }; + return *vec.data; +} +``` + +#### fb_driver +```hb +arm_fb_ptr := fn(): int return 100; +x86_fb_ptr := fn(): int return 100; + + +check_platform := fn(): int { + return x86_fb_ptr(); +} + +set_pixel := fn(x: int, y: int, width: int): int { + pix_offset := y * width + x; + + return 0; +} + +main := fn(): int { + fb_ptr := check_platform(); + width := 100; + height := 30; + x:= 0; + y:= 0; + + loop { + if x <= height + 1 { + set_pixel(x,y,width); + x = x + 1; + } else { + set_pixel(x,y,width); + x = 0; + y = y + 1; + } + if y == width { + break; + } + } + return 0; +} +``` + +#### struct_operators +```hb +Point := struct { + x: int, + y: int, +} + +Rect := struct { + a: Point, + b: Point, +} + +main := fn(): int { + a := Point.(1, 2); + b := Point.(3, 4); + + d := Rect.(a + b, b - a); + d2 := Rect.(Point.(0, 0) - b, a); + d2 = d2 + d; + + c := d2.a + d2.b; + return c.x + c.y; +} +``` + +#### main_fn +```hb +main := fn(): int { + return 1; +} +``` + +#### structs +```hb +Ty := struct { + a: int, + b: int, +} + +Ty2 := struct { + ty: Ty, + c: int, +} + +main := fn(): int { + finst := Ty2.{ ty: Ty.{ a: 4, b: 1 }, c: 3 }; + inst := odher_pass(finst); + if inst.c == 3 { + return pass(&inst.ty); + } + return 0; +} + +pass := fn(t: ^Ty): int { + return t.a - t.b; +} + +odher_pass := fn(t: Ty2): Ty2 { + return t; +} +``` + +#### pointers +```hb +main := fn(): int { + a := 1; + b := &a; + modify(b); + drop(a); + stack_reclamation_edge_case := 0; + return *b - 2; +} + +modify := fn(a: ^int): void { + *a = 2; + return; +} + +drop := fn(a: int): void { + return; +} +``` + +#### functions +```hb + +main := fn(): int { + return add_one(10) + add_two(20); +} + +add_two := fn(x: int): int { + return x + 2; +} + +add_one := fn(x: int): int { + return x + 1; +} + + +``` + +#### variables +```hb +main := fn(): int { + a := 1; + b := 2; + a = a + 1; + return a - b; +} +``` + +#### loops +```hb +main := fn(): int { + return fib(10); +} + +fib := fn(n: int): int { + a := 0; + b := 1; + loop { + if n == 0 { + break; + } + c := a + b; + a = b; + b = c; + n -= 1; + + stack_reclamation_edge_case := 0; + + continue; + } + return a; +} +``` + +#### different_types +```hb + +Color := struct { + r: u8, + g: u8, + b: u8, + a: u8, +} + +Point := struct { + x: u32, + y: u32, +} + +Pixel := struct { + color: Color, + point: Point, +} + +main := fn(): int { + pixel := Pixel.{ + color: Color.{ + r: 255, + g: 0, + b: 0, + a: 255, + }, + point: Point.{ + x: 0, + y: 2, + }, + }; + + if *(&pixel.point.x + 1) != 2 { + return 0; + } + + if *(&pixel.point.y - 1) != 0 { + return 64; + } + + return pixel.point.x + pixel.point.y + pixel.color.r + + pixel.color.g + pixel.color.b + pixel.color.a; +} +``` + +#### arithmetic +```hb +main := fn(): int { + return 10 - 20 / 2 + 4 * (2 + 2) - 4 * 4 + 1; +} +``` + diff --git a/hblang/src/codegen.rs b/hblang/src/codegen.rs index b6103997..b9724412 100644 --- a/hblang/src/codegen.rs +++ b/hblang/src/codegen.rs @@ -2366,7 +2366,34 @@ mod tests { use super::parser; - fn generate(input: &'static str, output: &mut String) { + const README: &str = include_str!("../README.md"); + + fn generate(ident: &'static str, input: &'static str, output: &mut String) { + fn find_block(mut input: &'static str, test_name: &'static str) -> &'static str { + const CASE_PREFIX: &str = "#### "; + const CASE_SUFFIX: &str = "\n```hb"; + loop { + let Some(pos) = input.find(CASE_PREFIX) else { + unreachable!("test {test_name} not found"); + }; + + input = unsafe { input.get_unchecked(pos + CASE_PREFIX.len()..) }; + if !input.starts_with(test_name) { + continue; + } + input = unsafe { input.get_unchecked(test_name.len()..) }; + if !input.starts_with(CASE_SUFFIX) { + continue; + } + input = unsafe { input.get_unchecked(CASE_SUFFIX.len()..) }; + + let end = input.find("```").unwrap_or(input.len()); + break unsafe { input.get_unchecked(..end) }; + } + } + + let input = find_block(input, ident); + let path = "test"; let mut codegen = super::Codegen::default(); codegen.files = vec![parser::Ast::new(path, input, &parser::no_loader)]; @@ -2405,19 +2432,18 @@ mod tests { } crate::run_tests! { generate: - example => include_str!("../examples/main_fn.hb"); - arithmetic => include_str!("../examples/arithmetic.hb"); - variables => include_str!("../examples/variables.hb"); - functions => include_str!("../examples/functions.hb"); - if_statements => include_str!("../examples/if_statement.hb"); - loops => include_str!("../examples/loops.hb"); - fb_driver => include_str!("../examples/fb_driver.hb"); - pointers => include_str!("../examples/pointers.hb"); - structs => include_str!("../examples/structs.hb"); - different_types => include_str!("../examples/different_types.hb"); - struct_operators => include_str!("../examples/struct_operators.hb"); - directives => include_str!("../examples/directives.hb"); - global_variables => include_str!("../examples/global_variables.hb"); - geneic_types => include_str!("../examples/generic_types.hb"); + arithmetic => README; + variables => README; + functions => README; + if_statements => README; + loops => README; + fb_driver => README; + pointers => README; + structs => README; + different_types => README; + struct_operators => README; + directives => README; + global_variables => README; + generic_types => README; } } diff --git a/hblang/src/lexer.rs b/hblang/src/lexer.rs index 75c89360..9e531c75 100644 --- a/hblang/src/lexer.rs +++ b/hblang/src/lexer.rs @@ -388,45 +388,3 @@ impl LineMap { } } } - -#[cfg(test)] -mod tests { - fn map_lines(input: &'static str, _: &mut String) { - let line_map = super::LineMap::new(input); - for i in 0..input.len() { - assert_eq!( - line_map.line_col(i as u32), - //line_map.line_col(i as u32), - super::line_col(input.as_bytes(), i as u32) - ); - } - } - - crate::run_tests! { map_lines: - empty_file => ""; - log_line => " ".repeat(1000).leak(); - this_file => &include_str!("parser.rs")[..1000]; - } - - fn lex(input: &'static str, output: &mut String) { - use { - super::{Lexer, TokenKind as T}, - std::fmt::Write, - }; - let mut lexer = Lexer::new(input); - loop { - let token = lexer.next(); - writeln!(output, "{:?} {:?}", token.kind, &input[token.range()],).unwrap(); - if token.kind == T::Eof { - break; - } - } - } - - crate::run_tests! { lex: - empty => ""; - whitespace => " \t\n\r"; - example => include_str!("../examples/main_fn.hb"); - arithmetic => include_str!("../examples/arithmetic.hb"); - } -} diff --git a/hblang/src/lib.rs b/hblang/src/lib.rs index 0abc4db7..336915d9 100644 --- a/hblang/src/lib.rs +++ b/hblang/src/lib.rs @@ -1,4 +1,5 @@ #![feature(vec_pop_if)] +#![feature(pattern)] #![feature(if_let_guard)] #![feature(slice_partition_dedup)] #![feature(noop_waker)] @@ -26,7 +27,7 @@ macro_rules! run_tests { ($runner:path: $($name:ident => $input:expr;)*) => {$( #[test] fn $name() { - $crate::tests::run_test(std::any::type_name_of_val(&$name), $input, $runner); + $crate::tests::run_test(std::any::type_name_of_val(&$name), stringify!($name), $input, $runner); } )*}; } diff --git a/hblang/src/parser.rs b/hblang/src/parser.rs index 09cba22e..f5633fe7 100644 --- a/hblang/src/parser.rs +++ b/hblang/src/parser.rs @@ -1077,21 +1077,3 @@ impl Drop for ArenaChunk { } } } - -#[cfg(test)] -mod tests { - fn parse(input: &'static str, output: &mut String) { - use std::fmt::Write; - let arena = super::Arena::default(); - let mut symbols = Vec::new(); - let mut parser = super::Parser::new(&arena, &mut symbols, &super::no_loader); - for expr in parser.file(input, "test") { - writeln!(output, "{}", expr).unwrap(); - } - } - - crate::run_tests! { parse: - example => include_str!("../examples/main_fn.hb"); - arithmetic => include_str!("../examples/arithmetic.hb"); - } -} diff --git a/hblang/src/tests.rs b/hblang/src/tests.rs index 0efafbd8..b0b5633e 100644 --- a/hblang/src/tests.rs +++ b/hblang/src/tests.rs @@ -1,6 +1,11 @@ #![cfg(test)] -pub fn run_test(name: &'static str, input: &'static str, test: fn(&'static str, &mut String)) { +pub fn run_test( + name: &'static str, + ident: &'static str, + input: &'static str, + test: fn(&'static str, &'static str, &mut String), +) { use std::{io::Write, path::PathBuf}; let filter = std::env::var("PT_FILTER").unwrap_or_default(); @@ -9,7 +14,7 @@ pub fn run_test(name: &'static str, input: &'static str, test: fn(&'static str, } let mut output = String::new(); - test(input, &mut output); + test(ident, input, &mut output); let mut root = PathBuf::from( std::env::var("PT_TEST_ROOT") diff --git a/hblang/tests/codegen_tests_example.txt b/hblang/tests/codegen_tests_example.txt deleted file mode 100644 index b1b92cc2..00000000 --- a/hblang/tests/codegen_tests_example.txt +++ /dev/null @@ -1,3 +0,0 @@ -code size: 82 -ret: 1 -status: Ok(()) diff --git a/hblang/tests/codegen_tests_geneic_types.txt b/hblang/tests/codegen_tests_generic_types.txt similarity index 100% rename from hblang/tests/codegen_tests_geneic_types.txt rename to hblang/tests/codegen_tests_generic_types.txt diff --git a/hblang/tests/lexer_tests_arithmetic.txt b/hblang/tests/lexer_tests_arithmetic.txt deleted file mode 100644 index 26de539b..00000000 --- a/hblang/tests/lexer_tests_arithmetic.txt +++ /dev/null @@ -1,31 +0,0 @@ -Ident "main" -Decl ":=" -Fn "fn" -LParen "(" -RParen ")" -Colon ":" -Ident "int" -LBrace "{" -Return "return" -Number "10" -Sub "-" -Number "20" -Div "/" -Number "2" -Add "+" -Number "4" -Mul "*" -LParen "(" -Number "2" -Add "+" -Number "2" -RParen ")" -Sub "-" -Number "4" -Mul "*" -Number "4" -Add "+" -Number "1" -Semi ";" -RBrace "}" -Eof "" diff --git a/hblang/tests/lexer_tests_empty.txt b/hblang/tests/lexer_tests_empty.txt deleted file mode 100644 index 3f671079..00000000 --- a/hblang/tests/lexer_tests_empty.txt +++ /dev/null @@ -1 +0,0 @@ -Eof "" diff --git a/hblang/tests/lexer_tests_example.txt b/hblang/tests/lexer_tests_example.txt deleted file mode 100644 index 7df9f67d..00000000 --- a/hblang/tests/lexer_tests_example.txt +++ /dev/null @@ -1,13 +0,0 @@ -Ident "main" -Decl ":=" -Fn "fn" -LParen "(" -RParen ")" -Colon ":" -Ident "int" -LBrace "{" -Return "return" -Number "1" -Semi ";" -RBrace "}" -Eof "" diff --git a/hblang/tests/lexer_tests_whitespace.txt b/hblang/tests/lexer_tests_whitespace.txt deleted file mode 100644 index 3f671079..00000000 --- a/hblang/tests/lexer_tests_whitespace.txt +++ /dev/null @@ -1 +0,0 @@ -Eof "" diff --git a/hblang/tests/parser_tests_arithmetic.txt b/hblang/tests/parser_tests_arithmetic.txt deleted file mode 100644 index 5a9d1e67..00000000 --- a/hblang/tests/parser_tests_arithmetic.txt +++ /dev/null @@ -1,3 +0,0 @@ -main := fn(): int { - return 10 - 20 / 2 + 4 * (2 + 2) - 4 * 4 + 1; -} diff --git a/hblang/tests/parser_tests_example.txt b/hblang/tests/parser_tests_example.txt deleted file mode 100644 index fa54eb11..00000000 --- a/hblang/tests/parser_tests_example.txt +++ /dev/null @@ -1,3 +0,0 @@ -main := fn(): int { - return 1; -} From 738e2e95f4fec1e4e24aa75a9edc66548a499fb5 Mon Sep 17 00:00:00 2001 From: mlokr Date: Sat, 15 Jun 2024 10:38:16 +0200 Subject: [PATCH 3/7] pup --- hblang/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/hblang/README.md b/hblang/README.md index 8500faf4..570ed404 100644 --- a/hblang/README.md +++ b/hblang/README.md @@ -1,5 +1,7 @@ # HERE SHALL THE DOCUMENTATION RESIDE +### Examples + #### directives ```hb Type := struct { From b0b04228d430fcb749a8d6cdd9c6db6dd9f4541c Mon Sep 17 00:00:00 2001 From: mlokr Date: Sat, 15 Jun 2024 10:46:53 +0200 Subject: [PATCH 4/7] little guide to add examples --- hblang/README.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/hblang/README.md b/hblang/README.md index 570ed404..24679b33 100644 --- a/hblang/README.md +++ b/hblang/README.md @@ -2,6 +2,20 @@ ### Examples +Examples are also used in tests, to and an example that runs during testing add: +
+    #### 
+
+    ```hb
+    
+    ```
+
+and also: +```rs + => README; +``` +to the `run_tests` macro at the bottom of the `src/codegen.rs`. + #### directives ```hb Type := struct { From fe52edbd93197284b4ee4df03f13d11d918fdd8d Mon Sep 17 00:00:00 2001 From: mlokr Date: Sat, 15 Jun 2024 10:48:42 +0200 Subject: [PATCH 5/7] fixing pre --- hblang/README.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/hblang/README.md b/hblang/README.md index 24679b33..0a836232 100644 --- a/hblang/README.md +++ b/hblang/README.md @@ -4,11 +4,10 @@ Examples are also used in tests, to and an example that runs during testing add: 
-    #### 
-
-    ```hb
-    
-    ```
+#### &ls;name>
+```hb
+<example>
+```
and also: ```rs From 4a1ca72030273a89e21003bd77c6e37d5eef86ec Mon Sep 17 00:00:00 2001 From: mlokr Date: Sat, 15 Jun 2024 10:49:02 +0200 Subject: [PATCH 6/7] brah --- hblang/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hblang/README.md b/hblang/README.md index 0a836232..966e4585 100644 --- a/hblang/README.md +++ b/hblang/README.md @@ -4,7 +4,7 @@ Examples are also used in tests, to and an example that runs during testing add: 
-#### &ls;name>
+#### <name>
 ```hb
 <example>
 ```

From fa0e5239ac664827248e573fc7f14925a73dbd60 Mon Sep 17 00:00:00 2001
From: mlokr 
Date: Thu, 20 Jun 2024 11:18:36 +0200
Subject: [PATCH 7/7] cleaning up the docs

---
 hblang/README.md | 382 +++++++++++++++++++++++++----------------------
 1 file changed, 205 insertions(+), 177 deletions(-)

diff --git a/hblang/README.md b/hblang/README.md
index 966e4585..1a996091 100644
--- a/hblang/README.md
+++ b/hblang/README.md
@@ -1,8 +1,26 @@
 # HERE SHALL THE DOCUMENTATION RESIDE
 
-### Examples
+## Enforced Political Views
 
-Examples are also used in tests, to and an example that runs during testing add:
+- worse is better
+- less is more
+- embrace `unsafe {}`
+- adhere `macro_rules!`
+- pessimization == death (put in `std::pin::Pin` and left with hungry crabs)
+- importing external dependencies == death (`fn(dependencies) -> ExecutionStrategy`)
+- above sell not be disputed, discussed, or questioned
+
+## What hblang is
+
+Holey-Bytes-Language (hblang for short) (*.hb) is the only true language targeting hbvm byte code. hblang is low level, manually managed, and procedural. Its rumored to be better then writing hbasm and you should probably use it for complex applications.
+
+## What hblang isnt't
+
+hblang knows what it isn't, because it knows what it is, hblang computes this by sub...
+
+## Examples
+
+Examples are also used in tests. To add an example that runs during testing add:
 
 #### <name>
 ```hb
@@ -15,6 +33,183 @@ and also:
 ```
 to the `run_tests` macro at the bottom of the `src/codegen.rs`.
 
+### Tour Examples
+
+Following examples incrementally introduce language features and syntax.
+
+#### main_fn
+```hb
+main := fn(): int {
+	return 1;
+}
+```
+
+#### arithmetic
+```hb
+main := fn(): int {
+	return 10 - 20 / 2 + 4 * (2 + 2) - 4 * 4 + 1;
+}
+```
+
+#### functions
+```hb
+main := fn(): int {
+	return add_one(10) + add_two(20);
+}
+
+add_two := fn(x: int): int {
+	return x + 2;
+}
+
+add_one := fn(x: int): int {
+	return x + 1;
+}
+```
+
+#### if_statements
+```hb
+main := fn(): int {
+	return fib(10);
+}
+
+fib := fn(x: int): int {
+	if x <= 2 {
+		return 1;
+	} else {
+		return fib(x - 1) + fib(x - 2);
+	}
+}
+```
+
+#### variables
+```hb
+main := fn(): int {
+	a := 1;
+	b := 2;
+	a = a + 1;
+	return a - b;
+}
+```
+
+#### loops
+```hb
+main := fn(): int {
+	return fib(10);
+}
+
+fib := fn(n: int): int {
+	a := 0;
+	b := 1;
+	loop {
+		if n == 0 break;
+		c := a + b;
+		a = b;
+		b = c;
+		n -= 1;
+
+		stack_reclamation_edge_case := 0;
+
+		continue;
+	}
+	return a;
+}
+```
+
+#### pointers
+```hb
+main := fn(): int {
+	a := 1;
+	b := &a;
+	modify(b);
+	drop(a);
+	stack_reclamation_edge_case := 0;
+	return *b - 2;
+}
+
+modify := fn(a: ^int): void {
+	*a = 2;
+	return;
+}
+
+drop := fn(a: int): void {
+	return;
+}
+```
+
+#### structs
+```hb
+Ty := struct {
+	a: int,
+	b: int,
+}
+
+Ty2 := struct {
+	ty: Ty,
+	c: int,
+}
+
+main := fn(): int {
+	finst := Ty2.{ ty: Ty.{ a: 4, b: 1 }, c: 3 };
+	inst := odher_pass(finst);
+	if inst.c == 3 {
+		return pass(&inst.ty);
+	}
+	return 0;
+}
+
+pass := fn(t: ^Ty): int {
+	return t.a - t.b;
+}
+
+odher_pass := fn(t: Ty2): Ty2 {
+	return t;
+}
+```
+
+#### struct_operators
+```hb
+Point := struct {
+	x: int,
+	y: int,
+}
+
+Rect := struct {
+	a: Point,
+	b: Point,
+}
+
+main := fn(): int {
+	a := Point.(1, 2);
+	b := Point.(3, 4);
+
+	d := Rect.(a + b, b - a);
+	d2 := Rect.(Point.(0, 0) - b, a);
+	d2 = d2 + d;
+
+	c := d2.a + d2.b;
+	return c.x + c.y;
+}
+```
+
+#### global_variables
+```hb
+global_var := 10;
+
+complex_global_var := fib(global_var) - 5;
+
+fib := fn(n: int): int {
+	if 2 > n {
+		return n;
+	}
+	return fib(n - 1) + fib(n - 2);
+}
+
+main := fn(): int {
+	return complex_global_var;
+}
+```
+note: values of global variables are evaluated at compile time
+
 #### directives
 ```hb
 Type := struct {
@@ -35,39 +230,14 @@ main := fn(): int {
 }
 ```
 
-#### if_statements
-```hb
-main := fn(): int {
-	return fib(10);
-}
+- `@TypeOf()`: results into literal type of whatever the type of `` is, `` is not included in final binary
+- `@as(, )`: hint to the compiler that  `@TypeOf() == `
+- `@intcast()`: needs to be used when conversion of `@TypeOf()` would loose precision (widening of integers is implicit)
+- `@sizeof(), @alignof()`: I think explaining this would insult your intelligence
+- `@bitcast()`: tell compiler to assume `@TypeOf()` is whatever is inferred, so long as size and alignment did not change
+- `@eca(, ...)`: invoke `eca` instruction, where `` is the type this will return and `...` are arguments passed to the call
 
-fib := fn(x: int): int {
-	if x <= 2 {
-		return 1;
-	} else {
-		return fib(x - 1) + fib(x - 2);
-	}
-}
-```
-
-#### global_variables
-```hb
-global_var := 10;
-
-complex_global_var := fib(global_var) - 5;
-
-fib := fn(n: int): int {
-	if 2 > n {
-		return n;
-	}
-	return fib(n - 1) + fib(n - 2);
-}
-
-main := fn(): int {
-	return complex_global_var;
-}
-
-```
+### Incomplete Examples
 
 #### generic_types
 ```hb
@@ -130,142 +300,7 @@ main := fn(): int {
 }
 ```
 
-#### struct_operators
-```hb
-Point := struct {
-	x: int,
-	y: int,
-}
-
-Rect := struct {
-	a: Point,
-	b: Point,
-}
-
-main := fn(): int {
-	a := Point.(1, 2);
-	b := Point.(3, 4);
-
-	d := Rect.(a + b, b - a);
-	d2 := Rect.(Point.(0, 0) - b, a);
-	d2 = d2 + d;
-
-	c := d2.a + d2.b;
-	return c.x + c.y;
-}
-```
-
-#### main_fn
-```hb
-main := fn(): int {
-	return 1;
-}
-```
-
-#### structs
-```hb
-Ty := struct {
-	a: int,
-	b: int,
-}
-
-Ty2 := struct {
-	ty: Ty,
-	c: int,
-}
-
-main := fn(): int {
-	finst := Ty2.{ ty: Ty.{ a: 4, b: 1 }, c: 3 };
-	inst := odher_pass(finst);
-	if inst.c == 3 {
-		return pass(&inst.ty);
-	}
-	return 0;
-}
-
-pass := fn(t: ^Ty): int {
-	return t.a - t.b;
-}
-
-odher_pass := fn(t: Ty2): Ty2 {
-	return t;
-}
-```
-
-#### pointers
-```hb
-main := fn(): int {
-	a := 1;
-	b := &a;
-	modify(b);
-	drop(a);
-	stack_reclamation_edge_case := 0;
-	return *b - 2;
-}
-
-modify := fn(a: ^int): void {
-	*a = 2;
-	return;
-}
-
-drop := fn(a: int): void {
-	return;
-}
-```
-
-#### functions
-```hb
-
-main := fn(): int {
-	return add_one(10) + add_two(20);
-}
-
-add_two := fn(x: int): int {
-	return x + 2;
-}
-
-add_one := fn(x: int): int {
-	return x + 1;
-}
-
-
-```
-
-#### variables
-```hb
-main := fn(): int {
-	a := 1;
-	b := 2;
-	a = a + 1;
-	return a - b;
-}
-```
-
-#### loops
-```hb
-main := fn(): int {
-	return fib(10);
-}
-
-fib := fn(n: int): int {
-	a := 0;
-	b := 1;
-	loop {
-		if n == 0 {
-			break;
-		}
-		c := a + b;
-		a = b;
-		b = c;
-		n -= 1;
-
-		stack_reclamation_edge_case := 0;
-
-		continue;
-	}
-	return a;
-}
-```
+### Purely Testing Examples
 
 #### different_types
 ```hb
@@ -314,10 +349,3 @@ main := fn(): int {
 }
 ```
 
-#### arithmetic
-```hb
-main := fn(): int {
-	return 10 - 20 / 2 + 4 * (2 + 2) - 4 * 4 + 1;
-}
-```
-