Created Standard Library (markdown)

Standard-Library.md

@@ -0,0 +1,349 @@
+# Standard Library
+
+## API for interfacing with C
+
+### Functions
+
+Function have no return values. They must be declared as procedures.
+Parameter qualified as `in` are passed as value. Parameter `out` are passed as pointer. References are equivalent to pointers in C.
+An `out` reference is passed as a pointer to a pointer.
+
+The gemstone function
+```
+type box: book {
+    ref half half int: title
+}
+
+fun foo(in int: a, in book: b)(out int: c, out ref book: d)
+```
+Can be resolved to the following C code:
+```c
+struct book {
+    char* title;
+}
+
+void foo(int a, struct book b, int* c, struct book** d);
+```
+
+## Modules of standard library
+
+- core
+- bool
+- mem
+- math
+- vec
+- str
+- os
+- io
+- fs
+- net
+
+## Module `core`
+
+Provides core data types and functionality for other standard library modules
+
+### Extended type defintions for interoperability
+
+```
+# single byte (8-Bit)
+type unsigned half half int: byte
+
+# single word (16-Bit)
+type unsgined double byte: word
+
+# double word (32-Bit)
+type unsgined double word: dword
+
+# quad word (64-Bit)
+type unsgined double dword: qword
+
+# IEEE-754 single precision
+type signed float: f32
+
+# IEEE-754 double precision
+type signed double f32: f64
+```
+
+## Module `bool`
+
+```
+type byte: bool
+
+bool: True = 1
+bool: False = 0
+```
+
+## Module `mem`
+
+Interface for heap memory management.
+
+### Global Variables
+
+```
+ref byte: NULL = 0 as ref byte
+```
+
+### Allocate memory
+
+Return a pointer to a location of heap memory which is at least `n` bytes in size.
+
+```
+fun alloc(in dword: n)(out ref byte: ptr)
+```
+
+### Reallocate memory
+
+Return a pointer to a location of heap memory which is at least `n` bytes in size.
+If possible extend the area of the given pointer to `n` bytes.
+If not possible, `ptr` will be a new pointer to a slice with at least `n` bytes of capacity.
+
+```
+fun realloc(in dword: n)(in out ref byte: ptr)
+```
+
+C declaration:
+
+```c
+void mem_realloc(int32_t n, (unsigned char*)* ptr);
+```
+
+### Free memory
+
+Free the given block of memory
+
+```
+fun free(in ref byte: ptr)
+```
+
+### Copy memory
+
+Copy `n` bytes from `src` into `dst`.
+
+```
+fun copy(in ref byte: src, in ref byte dst, in dword n)
+```
+
+### Fill memory
+
+Copy `pattern` `n` times into `dst`.
+
+```
+fun copy(in ref byte dst, in byte: pattern, in dword n)
+```
+
+### Copy slice
+
+```
+fun copy_slice(in ref bytes: src, in ref byte: dst)(in dword: src_s)(in dword: dst_s)(in dword: n)
+```
+
+## Module `math`
+
+### Globals
+
+```
+f32: PI = 3.141592653589793
+f32: E = 2.718281828459045
+```
+
+### Functions
+
+```
+fun sin(in f32)(out f32)
+fun cos(in f32)(out f32)
+fun tan(in f32)(out f32)
+fun floor(in f32)(out f32)
+fun fract(in f32)(out f32)
+```
+
+## Module `vec`
+
+Provides a growable vector data type
+
+```
+import "mem"
+
+silent dword: PRE_ALLOC_BYTES = 16
+
+type box: Vec {
+    silent ref byte: array
+    silent dword: len
+    silent dword: cap
+
+    silent fun resize(in dword: n) {
+        self.cap = self.cap + n + PRE_ALLOC_BYTES
+        realloc(self.cap)(self.array)
+    }
+
+    silent fun shrink(in dword: n) {
+        self.cap = self.cap - n
+        realloc(self.cap)(self.array)
+    }
+
+    fun push(in ref byte: bytes, in dword n) {
+        if self.len + n > cap {
+            self.resize(self.len + n - cap)
+        }
+
+        copy_slice(self.array, bytes)(self.len, 0)(n)
+
+        self.len = len + bytes
+    }
+
+    fun pop(in dword: n, out ref byte: bytes) {
+        
+        copy_slice(bytes, self.array)(0, self.len - n)(n)
+
+        self.shrink(n)
+    }
+
+    fn get(in dword: idx)(out ref byte: ptr) {
+        ptr = self.array + idx
+    }
+}
+```
+
+## Module `str`
+
+Provides a string box and manioulation functions
+
+```
+type byte: utf8
+type byte: ascii
+
+# UTF-8 encoded growable string
+type box: String {
+    silent Vec: bytes
+
+    fun from_raw(in ref byte: raw_utf8, in dword: len)
+    fun clone(in ref String: other)
+    fun concat(in ref String other)
+    fun contains(in ref String other)(out bool: res)
+    fun starts_with(in ref String other)(out bool: res)
+    fun ends_with(in ref String other)(out bool: res)
+}
+```
+
+## Module `os`
+
+Provides cross platform os related functionality.
+
+### Get name/identifier of OS
+
+```
+fun platform_name(out ref utf8: name)
+```
+
+### Environment variables
+
+#### Get environment variable
+
+```
+fun get_env(in ref utf8: name)(out ref utf8: value)
+```
+
+#### Set environment variable
+
+```
+fun set_env(in ref utf8: name)(in ref utf8: value)
+```
+
+### Program arguments
+
+#### Get number of arguments
+
+```
+fun get_arg_count(out dword: idx)
+```
+
+#### Get argument
+
+```
+fun get_arg(in dword: idx)(out ref utf8: value)
+```
+
+## Module `io`
+
+Low level entry point for platform specific I/O resources which may permit read/write and auxilery operations.
+
+```
+# platform specific handle for an I/O resource
+type dword: handle
+```
+
+### Read
+
+```
+fun read(in handle: device, in dword: n)(out ref byte: ptr)
+```
+
+### Write
+
+```
+fun write(in handle: device, in dword: n, in ref byte: ptr)
+```
+
+### Flush
+
+```
+fun flush(in handle: device)
+```
+
+### Standard I/O
+
+```
+fun get_stdout_handle(out handle: device)
+```
+
+```
+fun get_stderr_handle(out handle: device)
+```
+
+```
+fun get_stdin_handle(out handle: device)
+```
+
+## Module `fs`
+
+Provides a cross platform abstraction layer for basic file interactions.
+
+```
+# File path
+type box: Path {
+    silent String: buf
+    silent utf8: path_separator
+
+    fun from_string(in ref String: path)
+    fun append(in String: elem)
+    fun remove(in dword: idx)
+    fun exists(out bool: exists)
+    fun open(out File: file)
+    fun separator(out utf8: sep)
+    fun set_separator(in utf8: sep)
+}
+
+# Abstraction of a file
+type box: File {
+    silent handle: os_device_handle
+    silent Path: path
+
+    fun write(in ref byte: bytes, in dword: n)
+    fun write_string(in ref String: string)
+
+    fun read(in ref byte: bytes, in dword: n)
+    fun read_string(out String: content)
+    fun read_line(out String: line)
+
+    fun name()
+    fun rename(in String: new_name)
+
+    fun delete()
+    fun move()
+
+    fun close()
+}
+```
+
+## Module `net`
+
+Simple functionality for TCP/IP UDP/IP networking