cleaning up the docs
This commit is contained in:
mlokr
parent
bd2a49d29a
commit
36d978d798
382
hblang/README.md
382
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:
|
||||
<pre>
|
||||
#### <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(<expr>)`: results into literal type of whatever the type of `<expr>` is, `<expr>` is not included in final binary
|
||||
- `@as(<ty>, <expr>)`: hint to the compiler that `@TypeOf(<expr>) == <ty>`
|
||||
- `@intcast(<expr>)`: needs to be used when conversion of `@TypeOf(<expr>)` would loose precision (widening of integers is implicit)
|
||||
- `@sizeof(<ty>), @alignof(<ty>)`: I think explaining this would insult your intelligence
|
||||
- `@bitcast(<expr>)`: tell compiler to assume `@TypeOf(<expr>)` is whatever is inferred, so long as size and alignment did not change
|
||||
- `@eca(<ty>, <expr>...)`: invoke `eca` instruction, where `<ty>` is the type this will return and `<expr>...` 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;
|
||||
}
|
||||
```
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue