6. Modules

Modules are the lifeblood of the language, that provide the core functionalities that actually make the language useful. They expose a wrapper of custom function calls directly embedded to the interpreter that can be called from any point of the program, with some special propierties unique to those types of function calls.

That way, we wrap a bunch of libraries with different useful functionalities around a simple turing complete procedural dynamic scripting language, thus being the very essence of LiteScript.

6.0.1 Module Functions

Module functions are the public interface of the callable functionalities of each module, they can either manipulate variables that you provide, or change the internal state of the module.

They are invoked just like regular user functions, except that they end with a semicolon (';') to signal that it is a module function call and it cannot used as an expression in an assigner statement, therefore they are strictly considered procedures and never return anything.

    [module function]; ... ✅
    [variable] [assigner] [module function]; ... ❌

Module functions have a predefined fixed behavior and are directly embedded in the interpreter's source code, so they always expect a certain amount of arguments of a certain type so they cannot be of any type, unlike user functions (providing a wrong type as a argument will result in a type mismatch error).

Since these functions never return anything, All parameters are passed by reference meaning that if we pass variables they are mutable and can be altered after calling the module function. Don't worry as in each module function description it specifies when variables are modified and when they are not.

However, arguments passed in a module function cannot dynamically change types, so only the expected types can be provided.

Unlike, user functions, module functions are higher order functions, meaning that apart from accepting primitive data types and containers, they also accept functions as parameters (note though that it is always the last parameter of the module function and all parameters after the call are parameters associated to the passed function).

func
    ...
start
    ...
    x = 3.14
    [module function]; x 3 "Hello there" func: a b
    The value of x may be altered, but the values of a and b not.

6.0.2 Notation

In this subsection, we want to make clear the notation used to describe the modules in the following sections, since many modules carry an internal state that is mutable throughout the program and some topics need to be addressed, such as when functionalities are thread local, which types of arguments are expected and when arguments can be expressions.

Module notation:

Import statement:

import MODULE

Its import statement to activate/import the module, so that its module function are available for use, with the module NAME required to be put.

Internal state attributes:

TYPE NAME

Thread local: Yes/No
Cardinality: NUMBER

For each internal data structure that it may have, information about its type, its name, if it is thread local and the number of elements that it can have if it is a data structure, ergo its cardinality, where:

TYPE: Some simplifications may be made, but what is important is to show what it conceptually represents.
- Integer: May also represent a boolean value.
- Real
- String
- Tuple(TYPE, TYPE, ..., TYPE)
- Array(TYPE)
- Map(TYPE, TYPE): Equivalent to a key-value pair dictionary.
- CUSTOM: Check the source code for more information, may be either domain-specific custom types or C++ standard library types.
NAME: The name of the attribute.
NUMBER: Number of the cardinality of the attribute, following the UML multiplicity notation.

If an attribute is not thread local that means that any modification, including insertion and deletion of certain entries in a data structure, is prone to race conditions and therefore mutual exclusion must be guaranteed between modifications.

Will not be present if there are no attributes.

Description: DESCRIPTION

A description that explains in more detail what the module's purpose is.

Module function notation:

Function call:

    NAME; TYPE1 ... TYPEn

Describes how a certain module function has to be called an its types, where:

NAME: Name of the module function.
TYPE:
- integer
- real
- string
- numeric: integer or real.
- primitive: integer, real or string.
- container
- function (invoked with ':', any arguments passed after the function call will be part of the function that is being passed as an argument).

There are special symbols with meanings, if a type is between:

[]: It is mandatory.
(): It is optional.

More special symbols:

*: The argument is mutated therefore a variable is to be provided and an expression cannot be used.
/: If used when listing arguments, then the arguments on the right are an additional optional extension of mandatory arguments.
...: Variadic number of arguments, any number accepted.

Arguments:

1st argument: DESCRIPTION
2nd argument: DESCRIPTION
...

More information about the arguments, with a brief DESCRIPTION.

Modifies:

STATEATTRIBUTE1
STATEATTRIBUTE2
...

Lists the names of the internal state attribute that will be modified.

Will not be present if there are no modifications.

Description: DESCRIPTION

A description that explains in more detail what the module function call does.

Examples: ...

Optional examples can be provided to more clearly illustrate concepts, with a possible additional description.

6.1 IO Module

Import statement:

import io

Description: Provides functions to recieve user input and output values.

display;

Function call:

    display; (primitive) ...

Arguments:

Any argument: Primitive expression.

Description: Writes values to the standard output file descriptor, to the terminal in the running directory by default.

input;

Function call:

    input; (primitive)* ...

Arguments:

Any argument: Variable to be overwritten.

Description: For each variable of a primitive type provided, expects an input from the standard input file descriptor and assigns that value to that variable, from the terminal in the running directory by default.

6.2 ASCII Module

Import statement:

import ascii

Description: Provides functions for string utilities and string casts.

len;

Function call:

    len; [string] [integer]*

Arguments:

1st argument: String expression.
2nd argument: Return variable to be overwritten.

Description: Returns the number of characters in the provided string.

substr;

Function call:

    substr; [string] [integer] [integer] [string]*

Arguments:

1st argument: String expression.
2nd argument: Starting string index.
3nd argument: Ending string index.
4th argument: Return variable to be overwritten.

Description: Given a closed interval of two indexes (starting at 0), return the substring of characters of that specified range.

contains;

Function call:

    contains; [string] [string] [integer]*

Arguments:

1st argument: String expression.
2nd argument: Substring expression.
3nd argument: Return variable to be overwritten.

Description: Returns a boolean value that indicates if the string contains the given substring.

starts_with;

Function call:

    starts_with; [string] [string] [integer]*

Arguments:

1st argument: String expression.
2nd argument: Substring expression.
3nd argument: Return variable to be overwritten.

Description: Returns a boolean value that indicates if the string starts with the given substring.

ends_with;

Function call:

    ends_with; [string] [string] [integer]*

Arguments:

1st argument: String expression.
2nd argument: Substring expression.
3nd argument: Return variable to be overwritten.

Description: Returns a boolean value that indicates if the string ends with the given substring.

to_upper;

Function call:

    to_upper; [string]*

Arguments:

1st argument: Variable to be overwritten.

Description: All lowercase ASCII characters will be turned to their uppercase versions.

to_lower;

Function call:

    to_lower; [string]*

Arguments:

1st argument: Variable to be overwritten.

Description: All uppercase ASCII characters will be turned to their lowercase versions.

trim;

Function call:

    trim; [string]*

Arguments:

1st argument: Variable to be overwritten.

Description: Erases all space characters (' ', '\t', '\n', '\r') preceeding the first proper character and following the last proper character.

trim_left;

Function call:

    trim_left; [string]*

Arguments:

1st argument: Variable to be overwritten.

Description: Erases all space characters (' ', '\t', '\n', '\r') preceeding the first proper character.

trim_right;

Function call:

    trim_right; [string]*

Arguments:

1st argument: Variable to be overwritten.

Description: Erases all space characters (' ', '\t', '\n', '\r') following the last proper character.

cut;

Function call:

    cut; [integer] [integer] [string]*

Arguments:

1st argument: Starting string index.
2nd argument: Ending string index.
3rd argument: Variable to be overwritten.

Description: Erases all characters given a closed interval of two indexes (starting at 0).

paste;

Function call:

    paste; [string] [integer] [string]*

Arguments:

1st argument: Substring expression.
2nd argument: String index.
3rd argument: Variable to be overwritten.

Description: Inserts a substring into the string at a specific index, all the old characters past the index get moved in the following positions after the inserted substring.

replace;

Function call:

    replace; [string] [string] [string]*

Arguments:

1st argument: Old substring expression.
2nd argument: New substring expression.
3rd argument: Variable to be overwritten.

Description: Given a string, replaces all ocurrences of a specified old substring with the new substring.

reverse;

Function call:

    reverse; [string]*

Arguments:

1st argument: Variable to be overwritten.

Description: Reverses the order of all the characters in a string.

split;

Function call:

    split; [string] [container]*

Arguments:

1st argument: String expression.
2nd argument: Container to be overwritten.

Description: Splits a given string into different strings by space characters (' ', '\t', '\n', '\r') and puts them all in the container. Each splitted string will have its own entry in the container with an integer key (starting at 0).

to_integer;

Function call:

    to_integer; [string] [integer]*

Arguments:

1st argument: String expression.
2nd argument: Variable to be overwritten.

Description: Casts the string into an integer type. Only compatible with base 10 integers.

to_real;

Function call:

    to_real; [string] [real]*

Arguments:

1st argument: String expression.
2nd argument: Variable to be overwritten.

Description: Casts the string into a real type. Also works with infinite and NaN values.

to_string;

Function call:

    to_string; [numeric] [string]*

Arguments:

1st argument: Numeric expression.
2nd argument: Variable to be overwritten.

Description: Casts a numeric value into a string.

6.3 Thread Module

Import statement:

import thread

Internal state attributes:

std::atomic(Integer) activeThreads

Thread local: No
Cardinality: 1

Array(std::mutex) implicitMutexes

Thread local: No
Cardinality: 0..128

Integer currentThreadIndex

Thread local: Yes
Cardinality: 1

Description: Allows execution of concurrent and parallel code with a fork-join thread model or with asynchronous threads, with up to 128 implicit mutex objects available for mutual exclusion.

parallel;

Function call:

    parallel; [integer] [function]

Arguments:

1st argument: Integer expression indicating how many threads the master thread creates.
2nd argument: Worker function that the threads will execute, with providable parameters.

Modifies:

activeThreads: Set to the number of threads indicated by the expression.
currentThreadIndex: Each worker thread will have a unique identifier.

Description: Executes a function with a provided number of worker threads, forking each thread which all will execute the function in parallel and then all be joined after the worker function has been executed. All worker threads are guaranteed to after this statement. Note that the number of threads in execution is N+1 (being N the number of threads specified in the statement), since the master thread will wait for all worker threads to finish. Nested parallel regions are not supported.

thread_id;

Function call:

    thread_id; [integer]*

Arguments:

1st argument: Return variable to be overwritten.

Description: Returns a unique integer identifier ranging from 0 to N-1 (being N the total of worker threads), for each thread in parallel execution (previous parallel; statement). Returns -1 if there is no parallel context. Allows distinction between worker threads for implicit tasks.

num_threads;

Function call:

    num_threads; [integer]*

Arguments:

1st argument: Return variable to be overwritten.

Description: Returns the total of worker threads in parallel execution (previous parallel; statement). Returns 0 if there is no parallel context.

cache_line_bytes;

Function call:

    cache_line_bytes; [integer]*

Arguments:

1st argument: Return variable to be overwritten.

Description: Returns the number of bytes in a cache line of the current CPU. Returns 64 as a default value if the sysconf call fails.

num_cores;

Function call:

    num_cores; [integer]*

Arguments:

1st argument: Return variable to be overwritten.

Description: Returns the number of cores of the current CPU. Returns 1 as a default value if the sysconf call fails.

lock_mutex;

Function call:

    lock_mutex; [integer]

Arguments:

1st argument: Integer expression indicating a implicitMutexes index.

Modifies:

implicitMutexes: Thread safe lock of a mutex.

Description: Given a value from 0 to 127, locks one of the 128 implicit mutexes thus entering a region of mutual exclusion where only one thread can run. Any thread wanting to lock a locked mutex waits until it is unlocked, if multiple are waiting the entry order is arbitrary.

unlock_mutex;

Function call:

    unlock_mutex; [integer]

Arguments:

1st argument: Integer expression indicating a implicitMutexes index.

Modifies:

implicitMutexes: Thread safe unlock of a mutex.

Description: Given a value from 0 to 127, unlocks one of the 128 implicit mutexes thus leaving a region of mutual exclusion previously defined by lock_mutex;. Umlocking an unlocked mutex is undefined behavior.

async_thread;

Function call:

    async_thread; [function]

Arguments:

1st argument: Worker function to be executed asynchronously, with providable parameters.

Description: Spawns and forks a thread that detaches and executes a worker function asynchronously from the master thread, meaning that the master thread does not wait to finish its execution. The asynchronous thread will exist throughout the entire main process's lifetime or until it finishes executing the function.

6.4 Math Module

Import statement:

import math

Internal state attributes:

std::mt19937 mt

Thread local: No
Cardinality: 1

Description: Provides trigonometric functions, degree and radiant conversions and pseudo-random number generation with a Mersenne twister (with its seed initialized to the unix epoch time when the module is first imported).

sin;

Function call:

    sin; [numeric] [real]*

Arguments:

1st argument: Numeric expression in radiants.
2nd argument: Return variable to be overwritten.

Description: Returns the sine of the expression.

cos;

Function call:

    cos; [numeric] [real]*

Arguments:

1st argument: Numeric expression in radiants.
2nd argument: Return variable to be overwritten.

Description: Returns the cosine of the expression.

tan;

Function call:

    tan; [numeric] [real]*

Arguments:

1st argument: Numeric expression in radiants.
2nd argument: Return variable to be overwritten.

Description: Returns the tangent of the expression.

asin;

Function call:

    asin; [numeric] [real]*

Arguments:

1st argument: Numeric expression in radiants.
2nd argument: Return variable to be overwritten.

Description: Returns the arcsine of the expression.

acos;

Function call:

    acos; [numeric] [real]*

Arguments:

1st argument: Numeric expression in radiants.
2nd argument: Return variable to be overwritten.

Description: Returns the arcosine of the expression.

atan;

Function call:

    atan; [numeric] [real]*

Arguments:

1st argument: Numeric expression in radiants.
2nd argument: Return variable to be overwritten.

Description: Returns the arctangent of the expression.

sinh;

Function call:

    sinh; [numeric] [real]*

Arguments:

1st argument: Numeric expression in radiants.
2nd argument: Return variable to be overwritten.

Description: Returns the hyperbolic sine of the expression.

cosh;

Function call:

    cosh; [numeric] [real]*

Arguments:

1st argument: Numeric expression in radiants.
2nd argument: Return variable to be overwritten.

Description: Returns the hyperbolic cosine of the expression.

tanh;

Function call:

    tanh; [numeric] [real]*

Arguments:

1st argument: Numeric expression in radiants.
2nd argument: Return variable to be overwritten.

Description: Returns the hyperbolic tangent of the expression.

asinh;

Function call:

    asinh; [numeric] [real]*

Arguments:

1st argument: Numeric expression in radiants.
2nd argument: Return variable to be overwritten.

Description: Returns the hyperbolic arcsine of the expression.

acosh;

Function call:

    acosh; [numeric] [real]*

Arguments:

1st argument: Numeric expression in radiants.
2nd argument: Return variable to be overwritten.

Description: Returns the hyperbolic arcosine of the expression.

atanh;

Function call:

    atanh; [numeric] [real]*

Arguments:

1st argument: Numeric expression in radiants.
2nd argument: Return variable to be overwritten.

Description: Returns the hyperbolic arctangent of the expression.

deg2rad;

Function call:

    deg2rad; [numeric] [real]*

Arguments:

1st argument: Numeric expression in degrees.
2nd argument: Return variable to be overwritten.

Description: Returns the conversion to radiants of the expression.

rad2deg;

Function call:

    rad2deg; [numeric] [real]*

Arguments:

1st argument: Numeric expression in radiants.
2nd argument: Return variable to be overwritten.

Description: Returns the conversion to degrees of the expression.

rand_integer;

Function call:

    rand_integer; [integer] [integer] [integer]*

Arguments:

1st argument: Integer expression indicating a lower bound.
2nd argument: Integer expression indicating an upper bound.
3rd argument: Return variable to be overwritten.

Description: Returns a random integer in the closed interval defined by the lower and upper bounds following a uniform distribution.

rand_real;

Function call:

    rand_real; [real] [real] [real]*

Arguments:

1st argument: Real expression indicating a lower bound.
2nd argument: Real expression indicating an upper bound.
3rd argument: Return variable to be overwritten.

Description: Returns a random real in the closed interval defined by the lower and upper bounds following a uniform distribution.

get_pi;

Function call:

    get_pi; [real]*

Arguments:

1st argument: Return variable to be overwritten.

Description: Returns the value of pi used implicitly by the interpreter (rounded to 7 decimals of precision).

6.5 Unix Module

Import statement:

import unix

Internal state attributes:

Map(String, void*) memoryChunks

Thread local: No
Cardinality: *

Array(Tuple(Integer, Integer)) implicitPipes

Thread local: No
Cardinality: 0..128

Description: Implements wrappers to unix based system calls on the Linux kernel for systems programming; allowing process creation/management, signal sending, low level garbage collected heap chunk manipulation for fast contiguous memory, pipe creation with up to 128 implicit pipes, along with miscellaneous functionalities.

fork;

Function call:

    fork; (integer)*

Arguments:

1st argument: Return variable to be overwritten.

Description: Performs a unix fork of the current process, creating a new cloned child process. Optionally returns the return value of the fork, 0 for the child process and the child's pid for the parent process (might return a negative value if fork failed).

exec;

Function call:

    exec; [string] [string] (string) ...

Arguments:

1st argument: Path to the executable to be mutated to.
2nd argument: Mandatory first argument of exec (usually the executable name).
3rd-Nth argument: Optional additional arguments for the exec call.

Description: Performs a unix exec of the current process, mutating it to the new executable specified by the path, with the provided arguments. First searches in the running directory and then in the $PATH environment variable, for relative paths. If exec fails, the program continues executing the next statement.

get_pid;

Function call:

    get_pid; [integer]*

Arguments:

1st argument: Return variable to be overwritten.

Description: Returns the pid of the current process.

get_ppid;

Function call:

    get_ppid; [integer]*

Arguments:

1st argument: Return variable to be overwritten.

Description: Returns the pid of the parent process of the current process.

waitpid;

Function call:

    waitpid; [integer] (integer)*

Arguments:

1st argument: Integer expression indicating a child process pid.
2nd argument: Optional return variable to be overwritten.

Description: Performs a unix pid of the current process, waits for the child process of the indicated pid (-1 for any) to finish executing. Optionally returns the exit code of the finished child process. Follows the same rules as glibc's waitpid implementation.

kill;

Function call:

    kill; [integer] [integer]

Arguments:

1st argument: Integer expression indicating a target process pid.
2nd argument: Integer expression indicating the number of a signal to be sent.

Description: Performs a unix kill, sending a signal to the targeted process with the provided pid. The number of each signal is indicated in the signal man page.

sleep;

Function call:

    sleep; [integer]

Arguments:

1st argument: Integer expression indicating number of milliseconds.

Description: The current process sleeps/idles for at least the indicated number of milliseconds, in accordance to the CPU scheduler.

time;

Function call:

    time; [integer]* (integer)*

Arguments:

1st argument: Return variable to be overwritten.
2nd argument: Optional return variable to be overwritten.

Description: Returns the current unix epoch time truncated to 32 bits. Optional second variable for returning the upper 32 bits of the current unix epoch time.

heap_allocate;

Function call:

    heap_allocate; [string] [integer]

Arguments:

1st argument: String identifier to memoryChunks.
2nd argument: Integer expression indicating number of bytes.

Modifies:

memoryChunks: Creates a new entry with a pointer to the newly allocated heap chunk.

Description: Creates a new memory chunk on the heap allocating the specified number of bytes, which can be later referenced with the provided identifier. If a memory chunk with the same identifier already exists, it automatically gets freed and reallocated with a new chunk.

heap_read;

Function call:

    heap_read; [string] [integer] [primitive]* / [integer]

Arguments:

1st argument: String identifier to memoryChunks.
2nd argument: Integer expression indicating offset to base memory chunk pointer.
3rd argument: Return variable to be overwritten.
4th argument: Integer expression indicating number of bytes to be read, mandatory when returning strings.

Description: Reads the contents of a memory address in the heap, provided by the base pointer of the memory chunk identifier plus the indicated offset, and writes them into the return variable. It reads the raw bytes of whatever is left there so it automatically gets casted into the return variable type. If the return variable type is numeric, it reads 4 bytes and if it is a string then it reads the specified number of bytes. Bounds checking is not taken into account.

heap_write;

Function call:

    heap_write; [string] [integer] [primitive]

Arguments:

1st argument: String identifier to memoryChunks.
2nd argument: Integer expression indicating offset to base memory chunk pointer.
3rd argument: Primitive expression to be written in the heap.

Description: Writes the contents of an expression in a memory address in the heap, provided by the base pointer of the memory chunk identifier plus the indicated offset, and writes them into the return variable. It writes the raw bytes of whatever type is the expression. If the return variable type is numeric, it writes 4 bytes and if it is a string then it writes the string encoding (in the case of ASCII strings, the number of characters are the bytes). Bounds checking is not taken into account.

heap_free;

Function call:

    heap_free; [string]

Arguments:

1st argument: String identifier to memoryChunks.

Modifies:

memoryChunks: Deletes the entry associated to the identifier.

Description: Frees, at will, an allocated memory chunk, freeing heap memory at runtime that can be reallocated later. All allocated memory chunks are also automatically freed at the end of execution.

pipe_open;

Function call:

    pipe_open; [integer]

Arguments:

1st argument: Integer expression indicating a implicitPipes index.

Modifies:

implicitPipes: New file descriptors for the read and write ends of a pipe.

Description: Given a value from 0 to 127, creates both ends of one of the 128 implicit pipes from where inter-process communication can be done between processes of the same hierarchy. The pipes are also inherited from the parent process during fork.

pipe_read;

Function call:

    pipe_read; [integer] [primitive]* / [integer]

Arguments:

1st argument: Integer expression indicating a implicitPipes index.
2nd argument: Return variable to be overwritten.
3rd argument: Integer expression indicating number of bytes to be read, mandatory when returning strings.

Description: The current process performs a blocking read of the reading end of a pipe until it recieves the requested bytes of information for the variable return, 4 bytes for numeric types and the specified bytes for strings. If the write end is closed, it doesn't block and keeps executing. The read end must be open for this operation.

pipe_write;

Function call:

    pipe_write; [integer] [primitive]

Arguments:

1st argument: Integer expression indicating a implicitPipes index.
2nd argument: Primitive expression to be written in the heap.

Description: The current process writes the contents of a primitive expression to the writing end of a pipe, 4 bytes for numeric types and the string content for strings. If the read end is closed, SIGPIPE gets sent to the current process. The write end must be open for this operation.

pipe_close_read;

Function call:

    pipe_close_read; [integer]

Arguments:

1st argument: Integer expression indicating a implicitPipes index.

Modifies:

implicitPipes: Invalidates the read end file descriptor of the pipe entry.

Description: Closes the read end of an implicit pipe. All pipe file descriptors are automatically closed at the end of execution.

pipe_close_write;

Function call:

    pipe_close_write; [integer]

Arguments:

1st argument: Integer expression indicating a implicitPipes index.

Modifies:

implicitPipes: Invalidates the write end file descriptor of the pipe entry.

Description: Closes the write end of an implicit pipe. All pipe file descriptors are automatically closed at the end of execution.

6.6 Filesystem Module

Import statement:

import filesystem

Internal state attributes:

Map(String, std::fstream) fileStreams

Thread local: Yes
Cardinality: *

Description: Provides many filesystem utilities: file interaction/manipulation, file/directory creation and deletion, directory traversal and other miscellaneous functionalities.

file_open;

Function call:

    file_open; [string] [string] (string)

Arguments:

1st argument: String identifier to fileStreams.
2nd argument: Path to file.
3rd argument: Read/write permissions following a specific string format.

Modifies:

fileStreams: Creates a new entry with an open file stream.

Description: Creates a new file stream opening a file given a specific path (creates it if it doesn't exist), which can later be referenced with the provided identifier. Optional string parameter for indicating read/write permissions:

"r" or "read": Only read permissions.
"w" or "write": Only write permissions.
"r/w" or "read/write": Both read and write permissions.

If the optional parameter is not provided, then open the file with read/write and truncate all content (other modes don't truncate). The read and write file cursors are both always synchronized.

file_close;

Function call:

    file_close; [string]

Arguments:

1st argument: String identifier to fileStreams.

Modifies:

fileStreams: Deletes the entry associated to the identifier.

Description: Closes an open file stream. All open file streams are automatically closed at the end of execution.

file_read;

Function call:

    file_read; [string] [integer] [string]*

Arguments:

1st argument: String identifier to fileStreams.
2nd argument: Integer expression indicating number of bytes to be read.
3rd argument: Return variable to be overwritten.

Description: Reads the amount of bytes specified from an open file stream provided by the identifier and writes them into the returned string.

file_readline;

Function call:

    file_readline; [string] [string]*

Arguments:

1st argument: String identifier to fileStreams.
2rd argument: Return variable to be overwritten.

Description: Reads all the bytes specified from an open file stream provided by the identifier and writes them into the returned string until it finds a line break (\n).

file_readall;

Function call:

    file_readall; [string] [string]*

Arguments:

1st argument: String identifier to fileStreams.
2rd argument: Return variable to be overwritten.

Description: Reads the entire file content bytes specified from an open file stream provided by the identifier and writes them into the returned string.

file_write;

Function call:

    file_write; [string] [string]

Arguments:

1st argument: String identifier to fileStreams.
2rd argument: String expression to be written.

Description: Writes the contents of a string to an open file stream provided by the identifier.

file_cursor;

Function call:

    file_cursor; [string] [integer]*

Arguments:

1st argument: String identifier to fileStreams.
2rd argument: Return variable to be overwritten.

Description: Returns the position of the cursor from an open file stream provided by the identifier.

file_move_cursor;

Function call:

    file_move_cursor; [string] [integer]

Arguments:

1st argument: String identifier to fileStreams.
2rd argument: Integer expression indicating number of bytes to move.

Description: Moves the cursor of an open file stream provided by the identifier a specific number of bytes relative to its old position. Negative values can be used to move the cursor backwards.

file_set_cursor;

Function call:

    file_set_cursor; [string] [integer]

Arguments:

1st argument: String identifier to fileStreams.
2rd argument: Integer expression indicating the cursor position.

Description: Sets the cursor's position of an open file stream provided by the identifier to an absolute position of bytes provided. All negative values map the cursor to the end of the file.

dir_create;

Function call:

    dir_create; [string] (string)

Arguments:

1st argument: The new directory name.
2nd argument: An optional path where the directory will be created.

Description: Creates an empty directory with the provided name, with an optional path indicating where it shall be created at (if none is provided then it will be created in the running directory).

remove;

Function call:

    remove; [string]

Arguments:

1st argument: Path to a directory or file.

Description: Removes an element from the filesystem given a specific path. If the element doesn't exist it does nothing, if it is just a filename it searches in the running directory, if the element is a file then it deletes it, and if the element is a directory, it deletes all its contents recursively and then it.

path_exists;

Function call:

    path_exists; [string] [integer]*

Arguments:

1st argument: String that represents a filesystem path.
2nd argument: Return variable to be overwritten.

Description: Returns a boolean value if the indicated path exists or not.

is_file;

Function call:

    is_file; [string] [integer]*

Arguments:

1st argument: String that represents a filesystem path.
2nd argument: Return variable to be overwritten.

Description: Returns a boolean value if the indicated path exists and points to a file or not.

is_dir;

Function call:

    is_dir; [string] [integer]*

Arguments:

1st argument: String that represents a filesystem path.
2nd argument: Return variable to be overwritten.

Description: Returns a boolean value if the indicated path exists and points to a directory or not.

walk;

Function call:

    walk; [string] [container]*

Arguments:

1st argument: String that represents a filesystem path.
2nd argument: Container to be overwritten.

Description: Given a filesystem path, if it is a directory: then it lists all the contents (files and directories) that it contains and puts them all in the container, if the path doesn't exist or it is a file, then it returns an empty container. Each listed element will have its own entry in the container with an integer key (starting at 0).

get_cwd;

Function call:

    get_cwd; [string]*

Arguments:

1st argument: Return variable to be overwritten.

Description: Returns the absolute filesystem path to the running directory.

set_cwd;

Function call:

    set_cwd; [string]

Arguments:

1st argument: String that represents a filesystem path.

Description: Sets the running directory to the provided filesystem path. If it doesn't exist, or it is a file, then it does nothing.

get_filename;

Function call:

    get_filename; [string] [string]*

Arguments:

1st argument: String that represents a filesystem path.
2nd argument: Return variable to be overwritten.

Description: Returns the last component of a provided filesystem path. Works with both files and directories.

get_extension;

Function call:

    get_extension; [string] [string]*

Arguments:

1st argument: String that represents a filesystem path.
2nd argument: Return variable to be overwritten.

Description: Returns the file extension of the last component of a provided filesystem path, with the leading dot. If it is a directory, it returns an empty string.

6.7 Network Module

Import statement:

import network

Internal state attributes:

Map(String, HttpServer) httpServers

Thread local: Yes
Cardinality: *

Map(String, TcpSocket) tcpSockets

Thread local: Yes
Cardinality: *

Description: Implements the different functionalities that interact with the internet over the network, such as: HTTP client requests and server responses, lower level TCP client and server connections, UDP packet sending and recovery, DNS resolutions, as well as other utilities for parsing data like base64 and JSON.

http_listen;

Function call:

    http_listen; [string] [integer]

Arguments:

1st argument: String identifier to httpServers.
2nd argument: Integer expression indicating a logical network port.

Modifies:

httpServers: Creates a new entry with the port a server side connection will listen to.

Description: Binds a port to a server side connection that will be specified later on (referenced by the provided identifier), doesn't actually listen for incoming requests to that port until http_start; is called. If there already was a port binded to the identifier, then it resets the port it will listen to and resets all defined routes.

http_route;

Function call:

    http_route; [string] [string] [string] [function]

Arguments:

1st argument: String identifier to httpServers.
2nd argument: HTTP method that will be handled.
3rd argument: Logical path that will be handled.
4th argument: Function that handles the request, parameters are ignored.

Modifies:

httpServers: Defines the route of an entry.

Description: Defines a HTTP route/endpoint of a binded port indicated by the identifier that indicates how to handle incoming requests with the provided HTTP method and path, and the provided user function will be in charge how handling the request and returning the response.

There are only 4 supported HTTP methods: "GET", "POST", "PATCH" and "DELETE". Dynamic paths are not supported (:attribute), only static fixed paths.

The parameters of the handler function will be replaced by one single argument containing all the necessary information of the HTTP request, stored in a container at the variable arg0. The request container will have the following key-value pairs:

"method": the HTTP method of the incoming request as a string.
"path": the path of the incoming request as a string.
"version": the HTTP version used as a string.
"body": the incoming request's content as a string.
"headers": any headers of the incoming requests as a container of string key and string value, such as "Content-Type".
"params": any query parameters provided by the request as a container of string key and string value.

After handling the logic for the request, the handler sends the response with the "return" keyword, which supports 2 different return types: If it returns a string, then it returns a simple text/plain with the string content in the body and a status code of 200, otherwise it only supports returning containers with specific key-value pairs:

"status": the status code of the response as an integer.
"body": the response content that will be sent as a string.
"headers": any headers that the response will contain as a container of string key and string value. Content-Type is a mandatory header.

Examples: Here is an example of how to handle the request containers and how to return the responses:

func
    method = ""
    path = ""
    version = ""
    body = ""
    container headers
    container params

    arg0 get "method" -> method
    arg0 get "path" -> path
    arg0 get "version" -> version
    arg0 get "body" -> body
    arg0 get "headers" -> headers
    arg0 get "params" -> params

    ...

    return "OK response with this string as response"

    ...

    container res
    res put "status" <- 200
    res put "body" <- htmlString
    container hdrs
    hdrs put "Content-Type" <- "text/html"
    res put "headers" <- hdrs
    return res

http_start;

Function call:

    http_start; [string]

Arguments:

1st argument: String identifier to httpServers.

Description: Starts the server by creating a new thread that runs asynchronously for each defined route/endpoint of the server side connection provided by the identifier, listening on the binded port for incoming requests.

http_get;

Function call:

    http_get; [string] [string] [string]* / [container] [container]

Arguments:

1st argument: Fully Qualified Domain Name (FQDN).
2nd argument: Path to a specific resource.
3rd argument: Return variable to be overwritten.
4th argument: Container with string key-value pairs representing headers.
5th argument: Container with string key-value pairs representing query parameters.

Description: Does a HTTP get to a resource given a path and domain and returns the body of the response, with an optional extension for headers and query parameters.

http_post;

Function call:

    http_post; [string] [string] [string] / [container] [container]

Arguments:

1st argument: Fully Qualified Domain Name (FQDN).
2nd argument: Path to a specific resource.
3rd argument: Content to be sent.
4th argument: Container with string key-value pairs representing headers.
5th argument: Container with string key-value pairs representing query parameters.

Description: Does a HTTP post to a resource given a path and domain sending a string as the body, with an optional extension for headers and query parameters.

http_patch;

Function call:

    http_patch; [string] [string] [string] / [container] [container]

Arguments:

1st argument: Fully Qualified Domain Name (FQDN).
2nd argument: Path to a specific resource.
3rd argument: Content to be sent.
4th argument: Container with string key-value pairs representing headers.
5th argument: Container with string key-value pairs representing query parameters.

Description: Does a HTTP patch to a resource given a path and domain sending a string as the body, with an optional extension for headers and query parameters.

http_delete;

Function call:

    http_delete; [string] [string] / [container] [container]

Arguments:

1st argument: Fully Qualified Domain Name (FQDN).
2nd argument: Path to a specific resource.
3rd argument: Content to be sent.
4th argument: Container with string key-value pairs representing headers.
5th argument: Container with string key-value pairs representing query parameters.

Description: Does a HTTP delete to a resource given a path and domain, with an optional extension for headers and query parameters.

tcp_listen;

Function call:

    tcp_listen; [string] [string] [integer]

Arguments:

1st argument: String socket identifier to tcpSockets.
2nd argument: IPv4 address of one of this machine's NIC's in string format.
3rd argument: Integer expression indicating a logical network port.

Modifies:

tcpSockets: Creates a new socket entry.

Description: Creates a TCP connection listening to specific port of one of the machine's IP addresses which can later be referenced with the provided socket identifier. Doesn't block.

tcp_accept;

Function call:

    tcp_accept; [string] [string]

Arguments:

1st argument: String socket identifier to tcpSockets.
2nd argument: String connection identifier to tcpSockets.

Modifies:

tcpSockets: Creates a new connection entry.

Description: Waits for a client connection on the listening port of the provided socket identifier, once a client connects, it creates a connection which can later be referenced with the provided connection identifier and starts executing the next statement to handle the TCP connection. Blocks until a client connects.

tcp_connect;

Function call:

    tcp_connect; [string] [integer] [string]

Arguments:

1st argument: String connection identifier to tcpSockets.
2nd argument: IPv4 address of the server in string format.
3rd argument: Integer expression indicating a logical network port.

Modifies:

tcpSockets: Creates a new connection entry.

Description: Waits to connect to a server on the provided port, once the server acknowledges, it creates a connection which can later be referenced with the provided connection identifier and starts executing the next statement to handle the TCP connection. Blocks until it connects.

tcp_send;

Function call:

    tcp_send; [string] [string]

Arguments:

1st argument: String connection identifier to tcpSockets.
2nd argument: String expression to be sent.

Description: Sends a string through a TCP connection of the provided identifier. Both client and server can send information.

tcp_recv;

Function call:

    tcp_recv; [string] [string]*

Arguments:

1st argument: String connection identifier to tcpSockets.
2nd argument: Return variable to be overwritten.

Description: Waits until it recieves a string through a TCP connection of the provided identifier. Both client and server can recieve information. Blocks until it recieves some data.

tcp_close;

Function call:

    tcp_close; [string]

Arguments:

1st argument: String socket or connection identifier.

Modifies:

tcpSockets: Deletes a socket/connection entry.

Description: Given a socket or connection identifier, either stops listening to a port or closes a TCP connection respectively. Sockets and connections are automatically closed during the end of execution.

udp_send;

Function call:

    udp_send; [string] [integer] [string]

Arguments:

1st argument: IPv4 address of the reciever in string format.
2nd argument: Integer expression indicating a logical network port.
3rd argument: String expression to be sent.

Description: Sends a string as a UDP packet to a specified IP address and port.

udp_recv;

Function call:

    udp_recv; [string] [integer] [string]*

Arguments:

1st argument: IPv4 address of the reciever in string format.
2nd argument: Integer expression indicating a logical network port.
3rd argument: Return variable to be overwritten.

Description: Checks the OS socket recieve buffer for a UDP packet of the specified IP address and port, returning the content if there is one.

dns_resolve;

Function call:

    dns_resolve; [string] [string]*

Arguments:

1st argument: Registered domain name (domain name + higher domains) as a string.
2nd argument: Return variable to be overwritten.

Description: Runs a dns resolution of the specified registered domain name and returns the IP address of the resolution as a string. Returns an empty string in case of failure.

local_ip;

Function call:

    local_ip; [string]*

Arguments:

1st argument: Return variable to be overwritten.

Description: Returns the machine's default outward facing IP address, which may be private. Returns "0.0.0.0" in case of failure.

encode_base64;

Function call:

    encode_base64; [string] [string]*

Arguments:

1st argument: String expression in ASCII.
2nd argument: Return variable to be overwritten.

Description: Returns the encoded base64 string. Unicode is not guaranteed to work.

decode_base64;

Function call:

    decode_base64; [string] [string]*

Arguments:

1st argument: String expression in base64.
2nd argument: Return variable to be overwritten.

Description: Returns the decoded base64 string in ASCII format.

json_to_container;

Function call:

    json_to_container; [string] [container]*

Arguments:

1st argument: String expression in JSON format.
2nd argument: Return variable to be overwritten.

Description: Returns a container that holds the parsed JSON string. The container format is pretty intuitive, with primitive data types almost being mapped as is, JSON arrays being represented as containers with integer keys (starting with 0) and JSON objects being nested containers with string keys, with the following exceptions:

Boolean values: Are converted to a string.
Null values: Are converted to a string.

container_to_json;

Function call:

    container_to_json; [container] [json]* (integer)

Arguments:

1st argument: Regular container (all containers can be converted to JSON).
2nd argument: Return variable to be overwritten.
3rd argument: Optional integer expression indicating spaces of intentation.

Description: Returns a JSON string that holds the parsed container, following the format specified in json_to_container;. String values "true", "false" and "null" are automatically converted to their respective JSON values, by eliminating their quotes.

6.8 GUI Module

Import statement:

import gui

Internal state attributes:

Map(String, Window) windows

Thread local: No
Cardinality: *

Description: Allows creating very simple windows and forms to display and input infomation in a user interface, with the coordination of GLFW, OpenGL, GLAD and the main framework of ImGui; with the limitation of fixed unresizeable windows and absolute coordinate position instead of using layouts to simplify programming.

make_window;

Function call:

    make_window; [string] [integer] [integer] [integer] [integer]

Arguments:

1st argument: String identifier to windows, which is also the window title.
2nd argument: Horizontal position of the window on the screen in pixels.
3rd argument: Vertical position of the window on the screen in pixels.
4th argument: Width of the window on the screen in pixels.
5th argument: Height of the window on the screen in pixels.

Modifies:

windows: Creates a new entry with a logical window.

Description: Creates a logical window (which won't be displayed yet) that can contain different widgets for displaying and accepting user input, given a position on the screen and its width and height; which can later be referenced with the provided identifier.

add_button;

Function call:

    add_button; [string] [string] [integer] [integer] [integer] [integer] [function]

Arguments:

1st argument: String identifier to windows.
2nd argument: String identifier to windows' widgets.
3rd argument: Horizontal position of the widget with respect to the window in pixels.
4th argument: Vertical position of the widget with respect to the window in pixels.
5th argument: Width of the widget in pixels.
6th argument: Height of the widget in pixels.
7th argument: Callback function to be executed on clicking.

Modifies:

windows: Adds a new widget to the specified window entry.

Description: Adds a button to a window given an id (which is also text), position, width, height and callback function that executes logic when clicking and that can read and write values of different widgets.

add_label;

Function call:

    add_label; [string] [string] [integer] [integer] [integer] (string)

Arguments:

1st argument: String identifier to windows.
2nd argument: String identifier to windows' widgets.
3rd argument: Horizontal position of the widget with respect to the window in pixels.
4th argument: Vertical position of the widget with respect to the window in pixels.
5th argument: Font size of the text.
6th argument: Optional placeholder text.

Modifies:

windows: Adds a new widget to the specified window entry.

Description: Adds a label to a window given an id, position, font size and placeholder text (if not provided it will be empty by default).

add_textfield;

Function call:

    add_textfield; [string] [string] [integer] [integer] [integer] [integer] (string)

Arguments:

1st argument: String identifier to windows.
2nd argument: String identifier to windows' widgets.
3rd argument: Horizontal position of the widget with respect to the window in pixels.
4th argument: Vertical position of the widget with respect to the window in pixels.
5th argument: Width of the widget in pixels.
6th argument: Height of the widget in pixels.
7th argument: Optional placeholder text.

Modifies:

windows: Adds a new widget to the specified window entry.

Description: Adds a multiline textfield to a window given an id, position, width, height and placeholder text (if not provided then it will be "Enter text..." by default).

add_checkbox;

Function call:

    add_checkbox; [string] [string] [integer] [integer] [integer] [integer]

Arguments:

1st argument: String identifier to windows.
2nd argument: String identifier to windows' widgets.
3rd argument: Horizontal position of the widget with respect to the window in pixels.
4th argument: Vertical position of the widget with respect to the window in pixels.
5th argument: Width of the widget in pixels.
6th argument: Height of the widget in pixels.

Modifies:

windows: Adds a new widget to the specified window entry.

Description: Adds a checkbox to a window given an id, position, width and height. It will be unchecked by default.

add_slider;

Function call:

    add_slider; [string] [string] [integer] [integer] [integer] [integer] [integer] (integer)

Arguments:

1st argument: String identifier to windows.
2nd argument: String identifier to windows' widgets.
3rd argument: Horizontal position of the widget with respect to the window in pixels.
4th argument: Vertical position of the widget with respect to the window in pixels.
5th argument: Width of the widget in pixels.
6th argument: Minimum value of the slider.
7th argument: Maximum value of the slider.
8th argument: Optional default value of the slider.

Modifies:

windows: Adds a new widget to the specified window entry.

Description: Adds a slider to a window given an id, position, width, minimum and maximum value, with an optional default value (if not provided then it will be set to the minimum by default).

add_progress_bar;

Function call:

    add_progress_bar; [string] [string] [integer] [integer] [integer] [integer] (real)

Arguments:

1st argument: String identifier to windows.
2nd argument: String identifier to windows' widgets.
3rd argument: Horizontal position of the widget with respect to the window in pixels.
4th argument: Vertical position of the widget with respect to the window in pixels.
5th argument: Width of the widget in pixels.
6th argument: Height of the widget in pixels.
7th argument: Optional default value of the slider in unit fraction [0,1].

Modifies:

windows: Adds a new widget to the specified window entry.

Description: Adds a progress bar to a window given an id, position, width and height, with an optional default value (if not provided then it will be 0.0 by default).

add_dropdown;

Function call:

    add_dropdown; [string] [string] [integer] [integer] [integer] [container]

Arguments:

1st argument: String identifier to windows.
2nd argument: String identifier to windows' widgets.
3rd argument: Horizontal position of the widget with respect to the window in pixels.
4th argument: Vertical position of the widget with respect to the window in pixels.
5th argument: Width of the widget in pixels.
6th argument: Container with all the options as strings.

Modifies:

windows: Adds a new widget to the specified window entry.

Description: Adds a dropdown to a window given an id, position, width and container where all the options are string values in each key-value pair (the key will be ignored).

add_window;

Function call:

    add_window; [string]

Arguments:

1st argument: String identifier to windows.

Modifies:

windows: Modifies the visibility of a specified window entry.

Description: Given a window identified by the provided string, puts the window in the gui loop to be rendered later.

close_window;

Function call:

    close_window; [string]

Arguments:

1st argument: String identifier to windows.

Modifies:

windows: Modifies the visibility of a specified window entry.

Description: Given a window identified by the provided string, closes the window during rendering of the gui loop.

visible_window;

Function call:

    visible_window; [string] [integer]*

Arguments:

1st argument: String identifier to windows.
2nd argument: Return variable to be overwritten.

Description: Returns a boolean value that indicates if a window identified by the string is running or not.

set_label;

Function call:

    set_label; [string] [string] [string]

Arguments:

1st argument: String identifier to windows.
2nd argument: String identifier to windows' widgets.
3rd argument: Value to be set to.

Modifies:

windows: Modifies the contents of a widget of the specified window entry.

Description: Sets the text of a label to a new value.

get_textfield;

Function call:

    get_textfield; [string] [string] [string]*

Arguments:

1st argument: String identifier to windows.
2nd argument: String identifier to windows' widgets.
3rd argument: Return variable to be overwritten.

Description: Returns the inputted text of the textfield.

set_textfield;

Function call:

    set_textfield; [string] [string] [string]

Arguments:

1st argument: String identifier to windows.
2nd argument: String identifier to windows' widgets.
3rd argument: Value to be set to.

Modifies:

windows: Modifies the contents of a widget of the specified window entry.

Description: Clears the old text and sets the text of a textfield with the new text.

get_checkbox;

Function call:

    get_checkbox; [string] [string] [integer]*

Arguments:

1st argument: String identifier to windows.
2nd argument: String identifier to windows' widgets.
3rd argument: Return variable to be overwritten.

Description: Returns the boolean value of the checkbox indicating if it is checked or not.

set_checkbox;

Function call:

    set_checkbox; [string] [string]

Arguments:

1st argument: String identifier to windows.
2nd argument: String identifier to windows' widgets.

Modifies:

windows: Modifies the contents of a widget of the specified window entry.

Description: Checks the checkbox if it was unchecked.

clear_checkbox;

Function call:

    clear_checkbox; [string] [string]

Arguments:

1st argument: String identifier to windows.
2nd argument: String identifier to windows' widgets.

Modifies:

windows: Modifies the contents of a widget of the specified window entry.

Description: Unchecks the checkbox if it was checked.

toggle_checkbox;

Function call:

    toggle_checkbox; [string] [string]

Arguments:

1st argument: String identifier to windows.
2nd argument: String identifier to windows' widgets.

Modifies:

windows: Modifies the contents of a widget of the specified window entry.

Description: Checks the checkbox if it was unchecked and unchecks the checkbox if it was checked.

get_slider;

Function call:

    get_slider; [string] [string] [integer]*

Arguments:

1st argument: String identifier to windows.
2nd argument: String identifier to windows' widgets.
3rd argument: Return variable to be overwritten.

Description: Returns the value of the slider.

set_slider;

Function call:

    set_slider; [string] [string] [integer]

Arguments:

1st argument: String identifier to windows.
2nd argument: String identifier to windows' widgets.
3rd argument: Value to be set to.

Modifies:

windows: Modifies the contents of a widget of the specified window entry.

Description: Sets the value of a slider, must be in between the minimum and maximum.

get_dropdown;

Function call:

    get_dropdown; [string] [string] [string]*

Arguments:

1st argument: String identifier to windows.
2nd argument: String identifier to windows' widgets.
3rd argument: Return variable to be overwritten.

Description: Returns the selected option of the dropdown.

set_dropdown;

Function call:

    set_dropdown; [string] [string] [string]

Arguments:

1st argument: String identifier to windows.
2nd argument: String identifier to windows' widgets.
3rd argument: Value to be set to.

Modifies:

windows: Modifies the contents of a widget of the specified window entry.

Description: Sets the selected option with the provided string, if it is not in any of the options, then it simply clears the selection.

render_gui;

Function call:

    render_gui;

Description: Renders the gui loop, all logical windows added to the gui loop now are visible to the screen. Windows may be closed but not added when the gui loop is rendered because it is very volatile. During rendering, the callbacks of the buttons now can read and modify the widgets' values with the previously mentioned functions. Blocks until all windows are closed, in that case it continues executing the next statement.

6.9 Database Module

Import statement:

import database

Internal state attributes:

DBWrapper backend

Thread local: Yes
Cardinality: 0..1

Integer inTxn

Thread local: Yes
Cardinality: 1

Description: Implements connections with relational SQL databases for storing and retrieving persistent data, using SQLite3 and PostgreSQL. This module is designed to be super rigid, allowing only one database connection per thread, explicit errors and transaction only interaction to guarantee safety. If any exception occurs during execution that is not caused by the database, will result in an immediate panic exit as the default behavior.

open_database;

Function call:

    open_database; [string] / [string] [string] [string]

Arguments:

1st argument: Filepath to .db file for SQLite, URL for PostgreSQL.
2nd argument: Username for PostgreSQL.
3rd argument: Password for PostgreSQL.
4th argument: Database name for PostgreSQL.

Modifies:

backend: Starts a database connection.

Description: Given the specified parameters, starts a connection either with a local SQLite database file, or a remote PostgreSQL database server.

in_database;

Function call:

    in_database; [integer]*

Arguments:

1st argument: Return variable to be overwritten.

Description: Returns a boolean value that indicates if there is an open database connection or not.

close_database;

Function call:

    close_database;

Modifies:

backend: Ends the database connection.
inTxn: Set to false.

Description: Closes the database connection, automatically aborts/rollsback any pending transaction.

begin_transaction;

Function call:

    begin_transaction;

Modifies:

inTxn: Set to true.

Description: Begins a database transaction so that SQL can be executed and any changes be confirmed with either commits or rollbacks. If there is a pending transaction, it automatically rollsback the pending transaction and throws an error.

in_transaction;

Function call:

    in_transaction; [integer]*

Arguments:

1st argument: Return variable to be overwritten.

Description: Returns a boolean value that indicates if there is a pending transaction connection or not.

commit_transaction;

Function call:

    commit_transaction;

Modifies:

inTxn: Set to false.

Description: Commits the transaction, ending it. Any changes made to the database are confirmed and executed.

rollback_transaction;

Function call:

    rollback_transaction;

Modifies:

inTxn: Set to false.

Description: Rollsback the transaction, ending it. Any changes made to the database are ignored and discarded.

prepare_statement;

Function call:

    prepare_statement; [string]

Arguments:

1st argument: SQL prepared statement (beware of binding syntax).

Modifies:

backend: Creates a new prepared statement, only one maximum.

Description: Creates a prepared statement with bindable arguments to prevent SQL injection. For SQLite there are an unlimited number of parameters but for PostgreSQL there is a maximum limit of 6. Remember that for SQLite to indicate a parameter it is with "?" and in PostgreSQL it is with "$n", where n is <= 6 and denotes a contiguous discrete set of natural numbers.

bind_statement;

Function call:

    bind_statement; [integer] [primitive]

Arguments:

1st argument: Binding parameter argument, starting at 1.
2nd argument: Data to be binded to, SQL types are automatically mapped.

Description: Binds a value to a parameter defined in an active prepared statement. The index must be in the interval of the number of bindable parameters.

execute_statement;

Function call:

    execute_statement; (container)*

Arguments:

1st argument: Return variable to be overwritten.

Description: Returns the previously prepared statement written in SQL, with an optional container to retrieve values from a query and/or for more information.

get_last_database_error;

Function call:

    get_last_database_error; [string]*

Arguments:

1st argument: Return variable to be overwritten.

Description: Returns the last error that occured in the database, which might result from an incorrect SQL statement, an internal database error, etc.

6.0.1 Module Functions​

6.0.2 Notation​

6.1 IO Module​

display;​

input;​

6.2 ASCII Module​

len;​

substr;​

contains;​

starts_with;​

ends_with;​

to_upper;​

to_lower;​

trim;​

trim_left;​

trim_right;​

cut;​

paste;​

replace;​

reverse;​

split;​

to_integer;​

to_real;​

to_string;​

6.3 Thread Module​

parallel;​

thread_id;​

num_threads;​

cache_line_bytes;​

num_cores;​

lock_mutex;​

unlock_mutex;​

async_thread;​

6.4 Math Module​

sin;​

cos;​

tan;​

asin;​

acos;​

atan;​

sinh;​

cosh;​

tanh;​

asinh;​

acosh;​

atanh;​

deg2rad;​

rad2deg;​

rand_integer;​

rand_real;​

get_pi;​

6.5 Unix Module​

fork;​

exec;​

get_pid;​

get_ppid;​

waitpid;​

kill;​

sleep;​

time;​

heap_allocate;​

heap_read;​

heap_write;​

heap_free;​

pipe_open;​

pipe_read;​

pipe_write;​

pipe_close_read;​

pipe_close_write;​

6.6 Filesystem Module​

file_open;​

file_close;​

file_read;​

file_readline;​

file_readall;​

file_write;​

file_cursor;​

file_move_cursor;​

file_set_cursor;​

dir_create;​

6.0.1 Module Functions

6.0.2 Notation

6.1 IO Module

display;

input;

6.2 ASCII Module

len;

substr;

contains;

starts_with;

ends_with;

to_upper;

to_lower;

trim;

trim_left;

trim_right;

cut;

paste;

replace;

reverse;

split;

to_integer;

to_real;

to_string;

6.3 Thread Module

parallel;

thread_id;

num_threads;

cache_line_bytes;

num_cores;

lock_mutex;

unlock_mutex;

async_thread;

6.4 Math Module

sin;

cos;

tan;

asin;

acos;

atan;

sinh;

cosh;

tanh;

asinh;

acosh;

atanh;

deg2rad;

rad2deg;

rand_integer;

rand_real;

get_pi;

6.5 Unix Module

fork;

exec;

get_pid;

get_ppid;

waitpid;

kill;

sleep;

time;

heap_allocate;

heap_read;

heap_write;

heap_free;

pipe_open;

pipe_read;

pipe_write;

pipe_close_read;

pipe_close_write;

6.6 Filesystem Module

file_open;

file_close;

file_read;

file_readline;

file_readall;

file_write;

file_cursor;

file_move_cursor;

file_set_cursor;

dir_create;