Created Standard Library (markdown)
parent
58ea514e93
commit
8b7e2811a4
|
@ -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
|
Loading…
Reference in New Issue