TITLE: Undâr Programming Language
#+AUTHOR: Zongor
#+EMAIL: archive@undar-lang.org
#+DATE: [2025-04-05]
#+LANGUAGE: en
#+OPTIONS: H:4 num:t toc:t \n:nil @:t ::t |:t ^:t -:t f:t *:t <:t
#+STARTUP: align fold nodlcheck hidestars oddeven lognotestate
#+TAGS: { TODO(t) NEXT(n) DONE(d) | HOLD(h) WAITING(w) CANCELLED(c) }
#+PROPERTY: header-args :tangle-mode (identity #o0644)

A permacomputing & 3D video game oriented language transpiler.


* Getting Started

** Requirements
*** Main
- C compiler that supports C89

** Build

#+BEGIN_SRC sh
git clone https://git.alfrescocavern.com/zongor/undar-lang.git
cd undar-lang && ./build
#+END_SRC

* Memory Management

All memory used by the program exists in one big bump allocator.
When a function gets called, it creates a new arena in memory starting at the end of the previous frame. (or at the beginning of memory if no function has been called)
Variables allocated in the frame's arena are owned by default by the frame they are allocated in.
When variables get modified within the current frame they will get updated in that frame in their current location in the arena.
All complex types (Plex, arrays, strings) use fat pointers where they have a header of the length of that block and a "next" ptr that refers to the next allocated block for that value
If the size of the variable changes (like adding a value to the end of a array), a link is added to the internal list that points to a new block is allocated at the end of the arena of the size of that value, so they are variable sized blocks
When a variable is passed to a child function primitive types are pass by value, complex types (Arrays, Plexes, Strings) are pass by reference.
Variables passed as arguments to the child follow the same rules except when the size of a complex type changes, then a new value is added as a link from the parent to the child and the new value is allocated at the end of the childs arena (but the owner is still the parent).
When a function "returns" the frame is deallocated and all values allocated by it is freed; thus freeing memory deterministically.
Only a single variable may be returned from a function. When a variable is returned if it is primitive it is just passed back to the parent. If it is complex the value is coalesced into a single contiguous values and the link in the parent is updated to point at the "new" end of the arena. If the parents block is at the end the entire block is coalesced into a single contiguous block.
this allows for the low resource usage of a C but the convenience of a garbage collected language like C# or Go but without the GC pauses.

**Built in Types**

| Type | Description                        |
|------+------------------------------------|
| =byte= | Character (architecture specific)  |
| =u8=   | exactly 8-bit unsigned int         |
| =i8=   | exactly 8-bit signed int           |
| =u16=  | exactly 16-bit unsigned int        |
| =i16=  | exactly 16-bit signed int          |
| =u32=  | exactly 32-bit unsigned integer    |
| =i32=  | exactly 32-bit signed integer      |
| =int=  | 1 word signed number               |
| =nat=  | 1 word unsigned number             |
| =real= | Q16.16 fixed-point real number     |
| =str=  | fat pointer [length + data] string |
| =bool= | true/false                         |

* Roadmap

[[./ROADMAP.org][Compiler, Plex, Immidate mode GUI, Constructive solid geometry, Tunnels, Actor model]]

* License

[[./LICENSE][MIT]]

* Inspirations 

- [[https://plan9.io/][Plan 9]] / 9P - Unified I/O, Tunnels.
- [[https://fortran-lang.org/][Fortran]] - Array semantics.
- [[https://en.wikipedia.org/wiki/C_(programming_language)][C]] / [[https://ziglang.org/][Zig]] - Type system, portability, control.
- [[https://lua.org][Lua]] - Friendly syntax, portable, and minimal VM.
- [[https://www.craftinginterpreters.com/the-lox-language.html][Lox]] - Lexer & Parser logic.
- [[https://wiki.xxiivv.com/site/uxn.html][Uxn]] - Major inspiration.
- Retro Systems - N64, PS1, Mac Classic, Windows 95 - UI esthetics