Created Standard Library (markdown)

servostar 2024-05-15 15:47:21 +00:00
parent 58ea514e93
commit 8b7e2811a4
1 changed files with 349 additions and 0 deletions

349
Standard-Library.md Normal file

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