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:
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:
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