Builtin Functions

These are the functions that are defined in the global namespace, they have no module prefix and are the core functions of the language, its flow, and error handling.

import

import(path: str) -> any|err

Loads a solus file and then executes it. If the file is not found at first and the .solu file extension is not provided, it will attempt to find path + ".solu", and path + ".solus".

Parameters

Parameter	Type	Description
path	str	File path to import

Example

var module = unwrap(import("module"));
if type(module) == "err"
    io.println("Failed to load module.solu");
else
    io.println(module.version);

require

require(path: str) -> any|panic

Loads a solus file and then executes it, behaving identically to import besides the fact that it panics instead of returning an error.

Parameters

Parameter	Type	Description
path	str	File path to import

Example

var module = require("notfound"); # This will stop execution!
var mod2 = catch([](){ require("notfound") }); # Same as import("notfound")

include

include(path: str) -> any

Technically not a function but rather a keyword, this includes a file in the compilation path of the file it is called in, therefore resulting in a single chunk of bytecode.

Parameters

Parameter	Type	Description
path	str	File path to include

Example

var module = include("notfound"); # This will fail at compile time

eval

eval(src: str) -> any|err

Compiles source code from a string into a fun, note that this is NOT sandboxed and is NOT safe to accept use input with. Treat eval very carefully.

Parameters

Parameter	Type	Description
src	str	solus source code

Example

var cat = "{ meows = 2 paws = 4 }";
var instance = eval(cat);
io.println(instance.meows); # 2

panic

panic(err: str)

Creates a runtime panic, solus’ equivalent to an exception pretty much. This will exit the program if it is not DIRECTLY caught.

Parameters

Parameter	Type	Description
err	str	The reason for failure

Example

if fatal_err_condition:
    panic("ohhhh shit!");

catch

catch(try: fun) -> any|err

Catches any panics thrown within the provided try block’s scope of execution. Think of this as a try/catch that returns a result instead of passing it.

Parameters

Parameter	Type	Description
try	fun	A function to attempt

Example

var mod = catch([](){ require("notfound") }); # Same as import("notfound")

attempt

attempt(try: fun, handler: fun) -> any

Similar to catch except it uses a proper handler fun, mimicking try/catch behavior in other languages. If try fails or panics, handler will be passed the err.

Parameters

Parameter	Type	Description
try	fun	A function to attempt first
handler	fun	A function to call on failure

Example

var mod = attempt(
    []() { return import("doesnt-exist.solu"); },
    [](err) { io.println(err); return {}; }
);

unwrap

unwrap(val: any) -> any|panic

Unwraps a variable that is ambiguously value or error, returning either the value or panicking on err

Parameters

Parameter	Type	Description
val	any err	Either an error or a value

Example

var mod = unwrap(import("")); # Panics on failure like require("")

unwrap_or

unwrap_or(valid: any, invalid: any) -> any

Returns valid if it is a valid value, or returns invalid if valid is err

Parameters

Parameter	Type	Description
valid	any err	Either an error or a value
invalid	any	The default or fallback value

Example

var cfg = unwrap_or(do {
    var f = io.fread("test.cfg");
    type(f) == "err" and f or eval(f)
}, do {
    unwrap(io.fwrite("test.cfg", obj.stringify(default, false)));
    default
});

assert

assert(con: bool) -> nil|panic

Throws a panic if the provided condition is false

Parameters

Parameter	Type	Description
con	bool	A boolean condition to assert

Example

assert(1 == 1);
assert(1 == 2); # Panic

type

type(val: any) -> str

Returns the type of a value represented as a string

Parameters

Parameter	Type	Description
val	any	Any value possible in solus

Example

var module = unwrap(import("module"));
if type(module) == "err"
    io.println("Failed to load module.solu");
else
    io.println(module.version);

str

str(val: any)

Converts a value of any type into a string representation. Note that this function does not stringify objects, but rather gives a string representation of the pointer.

Parameters

Parameter	Type	Description
val	any	Any value possible in solus

Example

var x = 4; # i64
var y = {}; # obj
io.println("x: " + str(x) + ", y: " + str(y)); # "x: 4, y: 0x71d00c0d8"

err

err(str: str) -> err

Constructs an err type from a str. You can return this to represent failure conditions.

Parameters

Parameter	Type	Description
str	str	The reason for failure

Example

var fun = [](bool) {
    bool and "success"
    or err("failure!")
};

i64

i64(conv: f64|str)

Converts an f64 value into the i64 equivalent value. This will result in loss of floating point (decimal) precision.

Parameters

Parameter	Type	Description
conv	f64 str	The value to convert to i64

f64

f64(conv: i64|str) -> f64

Converts an i64 value into the f64 equivalent value. Not all values i64 represents can be represented by f64 accurately.

Parameters

Parameter	Type	Description
conv	i64 str	The value to convert to f64