Cyber’s just-in-time compiler is incomplete and unstable. To run your script with JIT enabled:
cyber -jit <script>
-The JIT compiler is just as fast as the bytecode generation so when it’s enabled, the entire script is compiled from the start.
Work on the ahead-of-time compiler has not begun.
Cyber supports fibers as a concurrency mechanism. There are plans to support preemptive concurrency with async/await as well as multithreading.
A fiber represents a separate execution context as a first-class value. It contains it’s own call stack and program counter. Fibers by themselves do not enable parallelism.
The coinit keyword creates and returns a new fiber using a function as the entry point:
var count = 0
-
-var foo = func ():
- count += 1
- coyield
- count += 1
-
-var fiber = coinit(foo)
-
-print count -- '0'
-coresume fiber
-print count -- '1'
-coresume fiber
-print count -- '2'
-A fiber does not start execution until coresume is invoked on it.
-coyield pauses the current fiber and execution is returned to the previous fiber that invoked coresume.
Arguments after the callee are passed into the entry function:
var count = 0
-
-var increment = func (inc):
- count += inc
-
-var fiber = coinit(increment, 5)
-coresume fiber
-print count -- '5'
-When the fiber is created, the arguments are saved inside the fiber’s stack. Once the first coresume is invoked, the entry function is invoked with the saved arguments.
To reset a fiber to its initial state, invoke reset(). *Planned Feature
-When reset, the existing stack is unwinded, the program counter returns to the starting point, and the state is set to .init:
func fib(n int) int:
- coyield n
- if n < 2:
- return n
- return fib(n - 1) + fib(n - 2)
-
-var task = coinit(fib, 10)
-
--- Progress the fiber...
-print(coresume task) -- Prints "10"
-print(coresume task) -- Prints "9"
-print(coresume task) -- Prints "8"
-
--- Reset back to the start with the `.init` state.
-fiber.reset()
-print(coresume task) -- Prints "10"
-Arguments attached to the fiber can be rebinded with a different set of values. *Planned Feature -This allows fiber reuse, instead of creating a new fiber:
var task = coinit(fib, 10)
-
--- Run task to completion.
-var res = 0
-while fiber.status() != .done:
- res = coresume fiber
-print res
-
-fiber.reset()
-fiber.bindArgs(20)
-
--- Run task again with the new argument...
-A fiber block is used to construct a fiber without an entry function. *Planned Feature The counting example can be rewritten to:
var count = 0
-
-var fiber = coinit:
- count += 1 -- `count is captured`
- coyield
- count += 1
-
-print count -- '0'
-coresume fiber
-print count -- '1'
-coresume fiber
-print count -- '2'
-Referencing parent variables from the fiber block automatically captures them just like a function closure.
coyield can be used anywhere in a fiber’s call stack to pause execution and return to the previous fiber.
func foo():
- print 'foo'
- bar()
-
-func bar():
- -- Nested coyield in call stack.
- coyield
- print 'bar'
-
-var fiber = coinit(foo)
-coresume fiber
-coresume also returns the resulting value.
func foo():
- return 123
-
-var fiber = coinit(foo)
-print(coresume fiber) -- '123'
-coyield can return a value back to coresume. *Planned Feature
Use Fiber.status() to get the current state of the fiber.
func foo():
- coyield
- print 'done'
-
-var fiber = coinit(foo)
-print fiber.status() -- '.paused'
-coresume fiber
-print fiber.status() -- '.paused'
-coresume fiber
-print fiber.status() -- '.done'
-The main execution context is a fiber as well. Once the main fiber has finished, the VM is done and control is returned to the host.
Planned Feature
Planned Feature
Planned Feature
Cyber provides the common constructs to branch and enter loops.
if statement.
-#Use if and else statements to branch the execution of your code depending on conditions. The else clause can contain a condition which is only evaluated if the previous if or conditional else clause was false.
var a = 10
-if a == 10:
- print 'a is 10'
-else a == 20:
- print 'a is 20'
-else:
- print 'neither 10 nor 20'
-A conditional branch expression evaluates a condition and returns either the true value or false value:
var a = 10
-var str = a == 10 ? 'red' else 'blue'
-and/or
-#Use and and or logical operators to combine conditions:
var a = 10
-if a > 5 and a < 15:
- print 'a is between 5 and 15'
-if a == 20 or a == 10:
- print 'a is 10 or 20'
-The while keyword starts an infinite loop which continues to run the code in the block until a break or return is reached.
var count = 0
-while:
- if count > 100:
- break
- count += 1
-When the while clause contains a condition, the loop continues to run until the condition is evaluated to false:
var running = true
-var count = 0
-while running:
- if count > 100:
- running = false
- count += 1
-Using the capture operator -> unwraps the left optional value to the right variable declaration. The loop exits when the left value is none:
var iter = dir.walk()
-while iter.next() -> entry:
- print entry.name
-for loops can iterate over a range that starts at an int (inclusive) to a target int (exclusive).
-The capture operator -> is used to capture the loop’s counter variable:
for 0..4:
- performAction()
-
-for 0..100 -> i:
- print i -- 0, 1, 2, ... , 99
-To decrement the counter instead, use -..:
for 100-..0 -> i:
- print i -- 100, 99, 98, ... , 1
-When the range operator .. is replaced with ..=, the target int is inclusive: *Planned Feature
for 0..=100 -> i:
- print i -- 0, 1, 2, ... , 100
-The for clause can iterate over any type that implements the Iterable trait. An Iterable contains an iterator() method which returns an Iterator object. The for loop continually invokes the Iterator’s next() method until none is returned.
Lists can be iterated since they implement the Iterable trait. The capture operator -> is used to capture the value returned from an iterator’s next():
var list = [1, 2, 3, 4, 5]
-
-for list -> n:
- print n
-Maps can be iterated. next() returns a key and value tuple:
var map = [ a: 123, b: 234 ]
-
-for map -> entry:
- print entry[0]
- print entry[1]
-Use the destructure syntax to extract the key and value into two separate variables:
for map -> [ key, val ]:
- print 'key $(key) -> value $(val)'
-A counting index can be declared after the each variable. The count starts at 0 for the first value:
var list = [1, 2, 3, 4, 5]
-
-for list -> val, i:
- print 'index $(i), value $(val)'
-Use break to exit a loop. This loop stops printing once i reaches 4:
for 0..10 -> i:
- if i == 4:
- break
- print i
-Use continue to skip the rest of the loop and go to the next iteration.
-This loop prints 0 through 9 but skips 4:
for 0..10 -> i:
- if i == 4:
- continue
- print i
-The switch statement branches to a case block from a matching case condition. The expression that is matched against comes after switch statement. Multiple cases can be grouped together using a comma separator. An optional else fallback case is executed when no other cases were matched.
-*Incomplete: Not all types can be used in the case conditions such as ranges.
var val = 1000
-switch val:
-case 0..100: print 'at or between 0 and 99'
-case 100 : print 'val is 100'
-case 200:
- print 'val is 200'
-case 300, 400:
- print 'combined case'
-else:
- print 'val is $(val)'
-Note that the switch block must be empty and requires at least one case block or an else block to come after it.
Although switch can not be used freely as an expression, it can be assigned to a left variable or destination:
var shu = switch pepper:
-case 'bell' => 0
-case 'anaheim' => 500
-case 'jalapeño' => 2000
-case 'serrano' => 10000
-When declaring an assignable switch, the cases must have a return value using the syntax case {cond} => {expr} or else => {expr}.
A break statement exits the current case block and resumes execution after the end of the switch statement: *Planned Feature
switch value:
-case 0..5:
- print value
- if value == 3:
- break case
- print value -- Skips second print if `value` is 3.
-The try catch statement, try else and try expressions provide a way to catch a throwing error and resume execution in a different branch. Learn more about Error Handling.
Planned Feature
In Cyber, there are primitive types and object types. Primitives are copied around by value and don’t need additional heap memory or reference counts.
Primitives include Booleans, Floats, Integers, Enums, Symbols, Error Symbols, and the none value.
Object types include Lists, Tuples, Maps, Strings, Arrays, User Objects, Lambdas, Fibers, Enums with payloads, Pointers, and several internal object types.
The none value represents an empty value. This is similar to null in other languages.
Booleans can be true or false. See type bool.
var a = true
-if a:
- print 'a is true'
-When other value types are coerced to the bool type, the truthy value is determined as follows.
none value is false.true.int is the default integer type. It has 48-bits and can represent integers in the range -(247) to 247-1. See type int.
When a numeric literal is used and the type can not be inferred, it will default to the int type:
var a = 123
-Integer notations always produce a int value:
var a = 0xFF -- hex.
-a = 0o17 -- octal.
-a = 0b1010 -- binary.
-a = `🐶` -- UTF-8 rune.
-Arbitrary values can be converted to a int using the type as a function.
var a = '123'
-var b = int(a)
-In addition to arithmetic operations, integers can also perform bitwise operations.
float is the default floating point type. It has a (IEEE 754) 64-bit floating point format. See type float.
Although a float represents a decimal number, it can also represent integers between -(253-1) and (253-1). Any integers beyond the safe integer range is not guaranteed to have a unique representation.
A numeric literal can be used to create a float if the inferred type is a float:
var a float = 123
-Decimal and scientific notations always produce a float value:
var a = 2.34567
-var b = 123.0e4
-Arbitrary values can be converted to a float using the type as a function.
var a = '12.3'
-var b = float(a)
-Planned Feature
The string type represents a sequence of UTF-8 codepoints, also known as runes. Each rune is stored internally as 1-4 bytes and can be represented as an int. See type string.
Under the hood, there are multiple string implementations to make operations faster by default.
Strings are immutable, so operations that do string manipulation return a new string. By default, small strings are interned to reduce memory footprint.
To mutate an existing string, use MutString. *Planned Feature
A string is always UTF-8 validated. Using an Array to represent raw bytes of a string is faster but you’ll have to validate them and take care of indexing.
A single line string literal is surrounded in single quotes.
var apple = 'a fruit'
-You can escape the single quote inside the literal or use double quotes.
var apple = 'Bob\'s fruit'
-apple = "Bob's fruit"
-Concatenate two strings together with the + operator or the method concat.
var res = 'abc' + 'xyz'
-res = res.concat('end')
-Strings are UTF-8 encoded.
var str = 'abc🦊xyz🐶'
-Use double quotes to surround a multi-line string.
var str = "line a
-line b
-line c"
-You can escape double quotes inside the literal or use triple quotes.
var str = "line a
-line \"b\"
-line c"
-
--- Using triple quotes.
-str = '''line a
-line "b"
-line c
-'''
-The following escape sequences are supported:
| Escape Sequence | Code | Description |
|---|---|---|
| \a | 0x07 | Terminal bell. |
| \b | 0x08 | Backspace. |
| \e | 0x1b | Escape character. |
| \n | 0x0a | Line feed character. |
| \r | 0x0d | Carriage return character. |
| \t | 0x09 | Horizontal tab character. |
The boundary of each line can be set with a vertical line character. This makes it easier to see the whitespace. -*Planned Feature
var poem = "line a
- | two spaces from the left
- | indented further"
-Using the index operator will return the UTF-8 rune at the given index as a slice. This is equivalent to calling the method sliceAt().
var str = 'abcd'
-print str[1] -- "b"
-Using the slice operator will return a view of the string at the given start and end (exclusive) indexes. The start index defaults to 0 and the end index defaults to the string’s length.
var str = 'abcxyz'
-var sub = str[0..3]
-print sub -- "abc"
-print str[..5] -- "abcxy"
-print str[1..] -- "bcxyz"
-
--- One way to use slices is to continue a string operation.
-str = 'abcabcabc'
-var i = str.findRune(`c`)
-print(i) -- "2"
-i += 1
-print(i + str[i..].findRune(`c`)) -- "5"
-Expressions can be embedded into string templates with $():
var name = 'Bob'
-var points = 123
-var str = 'Scoreboard: $(name) $(points)'
-String templates can not contain nested string templates.
Values that can be formatted into a string will have a fmt method:
var file = os.openFile('data.bin', .read)
-var bytes = file.readToEnd()
-
--- Dump contents in hex.
-print '$(bytes.fmt(.x))'
-An array is an immutable sequence of bytes. It can be used to represent strings but it won’t automatically validate their encoding and indexing returns the n’th byte rather than a UTF-8 rune. See type array.
var a = array('abcd')
-a = a.insertByte(1, 255)
-print a[0] -- "97"
-print a[1] -- "255"
-Bracket literals are delimited with brackets []. They are used to initialize Lists, Maps, and Objects:
var list = [1, 2, 3]
-var map = [ a: 123, b: 234 ]
-var obj = [MyObject a: 123, b: 234]
-Lists are a builtin type that holds an ordered collection of elements. Lists grow or shrink as you insert or remove elements. See type List.
-- Construct a new list.
-var list = [1, 2, 3]
-
--- The first element of the list starts at index 0.
-print list[0] -- Prints '1'
-Lists can be sliced with the range .. clause. The sliced list becomes a new list that you can modify without affecting the original list. The end index is non-inclusive.
var list = [ 1, 2, 3, 4, 5 ]
-list[0..0] -- []
-list[0..3] -- [ 1, 2, 3 ]
-list[3..] -- [ 4, 5 ]
-list[..3] -- [ 1, 2, 3 ]
-The +.. invokes the slice operator with an end position that is an increment from the start: *Planned Feature
var list = [ 1, 2, 3, 4, 5 ]
-list[2+..2] -- [ 3, 4 ]
-List operations.
var list = [234]
-
--- Append a value.
-list.append 123
-
--- Inserting a value at an index.
-list.insert(1, 345)
-
--- Get the length.
-print list.len() -- Prints '2'
-
--- Sort the list in place.
-list.sort((a, b) => a < b)
-
--- Iterating a list.
-for list -> it:
- print it
-
--- Remove an element at a specific index.
-list.remove(1)
-Incomplete: Tuples can only be created from @host funcs at the moment.
Maps are a builtin type that store key value pairs in dictionaries. See type Map.
Create a map using key value pairs inside a collection literal:
var map = [ a: 123, b: () => 5 ]
-Maps entries can be listed in multiple lines:
var map = [
- foo: 1,
- bar: 2,
-]
-The empty map is initialized using [:]:
var empty = [:]
-Get a value from the map using the index operator:
print map['a']
-Maps can be accessed with the . dot operator as well:
print map.a
-var map = [:]
-
--- Set a key value pair.
-map[123] = 234
-
--- Get the size of the map.
-print map.size()
-
--- Remove an entry by key.
-map.remove 123
-
--- Iterating a map.
-for map -> [val, key]:
- print '$(key) -> $(val)'
-Entries can also follow a collection literal block. -This gives structure to the entries and has -the added benefit of allowing multi-line lambdas. -*Planned Feature
var colors = []:
- red: 0xFF0000
- green: 0x00FF00
- blue: 0x0000FF
- dump func (c):
- print c.red
- print c.green
- print c.blue
-
- -- Nested map.
- darker []:
- red: 0xAA0000
- green: 0x00AA00
- blue: 0x0000AA
-Any value that isn’t a primitive is an object. You can declare your own object types using the type object declaration.
-Object types are similar to structs and classes in other languages.
-Unlike classes, there is no concept of inheritance at the language level.
Fields must be declared at the top of the type object block using var or my:
type Node object:
- var value int
- var next any
-When fields are declared with my instead, they become dynamically typed.
New object instances are created using a leading type name and the field values in a collection literal:
var node = [Node value: 123, next: none]
-print node.value -- Prints "123"
-Methods allow invoking a function on an object instance using the . operator:
type Node object:
- var value int
- var next any
-
- func inc(n):
- value += n
-
- func incAndPrint():
- self.inc(321)
- print value
-
-var n = [Node value: 123, next: none]
-n.incAndPrint() -- Prints "444"
-Methods can also be declared outside of the type declaration. To distinguish a method from a type function, self must be provided as a parameter:
func Node.getNext(self):
- return self.next
-self variable.
-#Type members can be implicitly referenced inside the method. *Incomplete: Only the type's fields can be referenced this way.
To reference members explicitly inside a method, use the builtin self:
type Node object:
- var value int
- var next any
-
- func double():
- return self.value * 2
-Type functions are declared outside of the type block with an explicit namespace path:
type Node object:
- var value int
- var next any
-
--- Declare namespace function inside `Node`.
-func Node.new():
- return [Node value: 123, next: none]
-
-var n = Node.new()
-Similarily, type variables are declared outside of the type block:
-- Declare inside the `Node` namespace.
-var Node.DefaultValue = 100
-
-print Node.DefaultValue -- Prints "100"
-A new enum type can be declared with the type enum declaration.
-An enum value can only be one of the unique symbols declared in the enum type.
-By default, the symbols generate unique ids starting from 0.
type Fruit enum:
- case apple
- case orange
- case banana
- case kiwi
-
-var fruit = Fruit.kiwi
-print fruit -- 'Fruit.kiwi'
-print int(fruit) -- '3'
-When the type of the value is known to be an enum, it can be assigned using a symbol literal.
var fruit = Fruit.kiwi
-fruit = .orange
-print(fruit == Fruit.orange) -- 'true'
-Symbol literals begin with ., followed by an identifier. They have their own global unique id.
var currency = .usd
-print(currency == .usd) -- 'true'
-print int(currency) -- '123' or some arbitrary id.
-The Embed API allows embedding the Cyber compiler and VM as a library into applications. Cyber’s core types and the CLI app were built using the Embed API.
The API is defined in the C header file. -The examples shown below can be found in the repository under c-embedded. C is used as the host language, but it can be easily translated to C++ or any C-ABI compatible language.
Types from the Embed API begin with Cs, constants begin with CS, and functions begin with cs.
Most operations are tied to a VM handle. To create a new VM instance, call csCreate:
#include "cyber.h"
-
-int main() {
- CsVM* vm = csCreate();
- // ...
- csDestroy(vm);
- return 0;
-}
-print.
-#The builtin print function does nothing by default, so it needs to be overrided to print to stdout for example:
void print(CsVM* vm, CsStr str) {
- printf("My print: %.*s\n", (int)str.len, str.buf);
-}
-
-int main() {
- // ...
- csSetPrint(vm, print);
- // ...
-}
-csEval compiles and evaluates a script:
CsStr src = STR(
- "var a = 1\n"
- "print(a + 2)\n"
-);
-
-CsValue val;
-int res = csEval(vm, src, &val);
-if (res == CS_SUCCESS) {
- printf("Success!\n");
- csRelease(vm, val);
-} else {
- const char* report = csNewLastErrorReport(vm);
- printf("%s\n", report);
- csFreeStrZ(report);
-}
-If a value is returned from the main block of the script, it’s saved to the result value argument.
-Memory is managed by ARC so a value that points to a heap object requires a csRelease when it’s no longer needed.
csEval returns a result code that indicates whether it was successful.
A module loader describes how a module is loaded when an import statement is encountered during script execution.
-Only one module loader can be active and is set using csSetModuleLoader:
bool modLoader(CsVM* vm, CsStr spec, CsModuleLoaderResult* out) {
- if (strncmp("my_mod", spec.buf, spec.len) == 0) {
- out->src =
- "@host func add(a float, b float) float\n"
- "@host var Root.MyConstant float\n"
- "@host var Root.MyList List\n"
- "\n"
- "@host\n"
- "type MyCollection object:\n"
- " @host func asList() any"
- "\n"
- "@host func MyCollection.new(a, b) MyCollection\n";
- out->funcLoader = funcLoader;
- out->varLoader = varLoader;
- out->typeLoader = typeLoader;
- return true;
- } else {
- // Fallback to the default module loader to load `builtins`.
- return csDefaultModuleLoader(vm, spec, out);
- }
-}
-
-int main() {
- //...
- csSetModuleLoader(vm, modLoader);
- //...
-}
-The above example checks whether “my_mod” was imported and returns it’s source code. Additional loaders are returned to load the functions, variables, and types from the source code.
Since only one module loader can be set to the VM instance, a custom loader is required to handle the “builtins” import which contains all of the core types and functions in Cyber. This can simply be delegated to csDefaultModuleLoader.
A function loader describes how to load a @host function when it’s encountered by the compiler.
-The loader can bind functions and type methods:
struct { char* n; CsFuncFn fn; } funcs[] = {
- {"add", add},
- {"asList", myCollectionAsList},
- {"MyCollection.new", myCollectionNew},
-};
-
-bool funcLoader(CsVM* vm, CsFuncInfo info, CsFuncResult* out) {
- // Check that the name matches before setting the function pointer.
- if (strncmp(funcs[info.idx].n, info.name.buf, info.name.len) == 0) {
- out->ptr = funcs[info.idx].fn;
- return true;
- } else {
- return false;
- }
-}
-This example uses the CsFuncInfo.idx of a @host function to index into an array and return a Host function pointer. The name is also compared to ensure it’s binding to the correct pointer.
This is an efficient way to map Cyber functions to host functions. A different implementation might use a hash table to map the name of the function to it’s pointer.
A variable loader describes how to load a @host variable when it’s encountered by the compiler:
// C has limited static initializers (and objects require a vm instance) so initialize them in `main`.
-typedef struct { char* n; CsValue v; } NameValue;
-NameValue vars[2];
-
-bool varLoader(CsVM* vm, CsVarInfo info, CsValue* out) {
- // Check that the name matches before setting the value.
- if (strncmp(vars[info.idx].n, info.name.buf, info.name.len) == 0) {
- // Objects are consumed by the module.
- *out = vars[info.idx].v;
- return true;
- } else {
- return false;
- }
-}
-
-int main() {
- // ...
-
- // Initialize var array for loader.
- vars[0] = (NameValue){"Root.MyConstant", csFloat(1.23)};
- CsValue myInt = csInteger(123);
- vars[1] = (NameValue){"Root.MyList", csNewList(vm, &myInt, 1)};
-
- // ...
-}
-This example uses the same technique as the function loader, but it can be much simpler. It doesn’t matter how the mapping is done as long as the variable loader returns a CsValue.
A type loader describes how to load a @host type when it’s encountered by the compiler:
CsTypeId myCollectionId;
-
-bool typeLoader(CsVM* vm, CsTypeInfo info, CsTypeResult* out) {
- if (strncmp("MyCollection", info.name.buf, info.name.len) == 0) {
- out->type = CS_TYPE_OBJECT;
- out->data.object.outTypeId = &myCollectionId;
- out->data.object.getChildren = myCollectionGetChildren;
- out->data.object.finalizer = myCollectionFinalizer;
- return true;
- } else {
- return false;
- }
-}
-When binding to the “MyCollection” type, it’s typeId is saved to outTypeId. This id is then used to create new instances of this type. See Host types.
A host function requires a specific function signature:
CsValue add(CsVM* vm, const CsValue* args, uint8_t nargs) {
- double res = csAsFloat(args[0]) + csAsFloat(args[1]);
- return csFloat(res);
-}
-A host function should always return a CsValue. csNone() can be returned if the function does not intend to return any value.
A host type are types that are opaque to Cyber scripts but still behave like an object. They can have type functions and methods.
Only the host application can directly create new instances of them, so usually a function is binded to expose a constructor to the user script:
// Binding a C struct with it's own children and finalizer.
-// This struct retains 2 VM values and has 2 arbitrary data values unrelated to the VM.
-typedef struct MyCollection {
- CsValue val1;
- CsValue val2;
- int a;
- double b;
-} MyCollection;
-
-// Implement the `new` function in MyCollection.
-CsValue myCollectionNew(CsVM* vm, const CsValue* args, uint8_t nargs) {
- // Instantiate our object.
- CsValue new = csNewHostObject(vm, myCollectionId, sizeof(MyCollection));
- MyCollection* my = (MyCollection*)csAsHostObject(new);
-
- // Assign the constructor args passed in and retain them since the new object now references them.
- csRetain(vm, args[0]);
- my->val1 = args[0];
- csRetain(vm, args[1]);
- my->val2 = args[1];
-
- // Assign non VM values.
- my->a = 123;
- my->b = 9999.999;
- return new;
-}
-csNewHostObject takes the type id (returned from the Type loader) and size (in bytes) and returns a new heap object. Note that the size is allowed to vary. Different instances of the same type can occupy different amounts of memory.
getChildren
-#Since MyCollection contains CsValue children, the Type loader requires a getChildren callback so that memory management can reach them:
CsValueSlice myCollectionGetChildren(CsVM* vm, void* obj) {
- MyCollection* my = (MyCollection*)obj;
- return (CsValueSlice){ .ptr = &my->val1, .len = 2 };
-}
-finalizer
-#A type finalizer is optional since the memory and children of an instance will be freed automatically by ARC. -However, it can be useful to perform additional cleanup tasks for instances that contain external resources.
void myCollectionFinalizer(CsVM* vm, void* obj) {
- printf("MyCollection finalizer was called.\n");
-}
-Cyber provides a throw/catch mechanism to handle expected errors. For unexpected errors, panics can be used as a fail-fast mechanism to abort the currently running fiber.
Only types that implement the Error trait can be thrown or attached to a panic.
-Since the Error trait is empty, it’s simple to turn any type into a throwable type.
error value.
-#An error value contains a symbol and implements the Error trait. They can be created without a declaration using the error literal:
var err = error.Oops
-Use sym() to obtain the underlying symbol:
print err.sym() -- Prints ".Oops"
-Since error is a primitive value, it can be compared using the == operator.
if err == error.Oops:
- handleOops()
-
--- Alternatively.
-if err.sym() == .Oops:
- handleOops()
-By implementing the Error trait, an enum type can be throwable: *Planned Feature
type MyError enum:
- with Error
- boom
- badArgument
- nameTooLong
-
-var err = MyError.nameTooLong
-Use the throw keyword to throw errors.
-A thrown error continues to bubble up the call stack until it is caught by a try block or expression.
func fail():
- throw error.Oops -- Throws an error with the symbol `#Oops`
-
-func fail2():
- throw 123 -- Panic. Can only throw an error
- -- that implement the `Error` trait.
-throw can also be used as an expression.
func fail():
- var a = false or throw error.False
-try block.
-#The try block catches thrown errors and resumes execution in a followup catch block:
try:
- funcThatCanFail()
-catch err:
- print err -- 'error.Failed'
-caught variable.
-#The contextual caught variable is used to reference the caught error: *Planned Feature
try:
- funcThatCanFail()
-catch:
- print caught -- 'error.Failed'
-catch matching.
-#An inner catch block contains a matching clause: *Planned Feature
try:
- funcThatCanFail()
-catch error.BadDay:
- eatSnack()
-catch:
- print caught
-Enum errors can be matched: *Planned Feature
try:
- funcThatCanFail()
-catch MyError.Boom:
- print 'Kaboom!'
-catch:
- print caught
-try expression.
-#The try expression either returns a non-error result or the default value from the catch clause:
var res = try funcThatCanFail() catch 123
-print res -- '123'
-Since errors bubble up automatically, any errors thrown from sub-expressions are also caught:
var res = try happyFunc(funcThatCanFail()) catch 123
-print res -- '123'
-When the catch clause is omitted, the try expression will return either the value or the error:
var res = try funcThatCanFail()
-if res == error.Failed:
- print 'Result is an error.'
-throws specifier.
-#The throws specifier indicates that a function contains a throwing expression that was not caught with try catch.
When a function does not have a return specifier, it’s implicitly given the throws specifier:
func foo():
- throw error.Failure
-
-func bar() throws:
- throw error.Failure
-
--- `foo` and `bar` both have the same return specifier.
-Return types for typed functions are declared after throws using a comma separator:
func result(cond bool) throws, int:
- if cond:
- return 123
- else:
- throw error.Failure
-throws.
-#A compile-time error is issued when a typed function without a throws specifier contains an uncaught throwing expression: *Planned Feature
func foo(a int) int:
- if a == 10:
- throw error.Failure -- CompileError. `foo` requires the `throws`
- else: -- specifier or any throwing expression must
- return a * 2 -- be caught with `try catch`.
-When an uncaught error bubbles up to the top, its stack trace from the throw callsite is dumped to the console. The builtin errorTrace() and errorReport() are used to obtain the stack trace info.
try:
- funcThatCanFail()
-catch:
- -- Prints the stack trace summary of the caught error.
- print errorReport()
-
- -- Provides structured info about the stack trace.
- var info = errorTrace()
- print info.frames.len()
-An unexpected error is an error that is not meant to be handled at runtime.
The builtin panic is used as a fail-fast mechanism to quickly exit the current fiber with an error payload:
func kaboom():
- panic(error.danger)
-
-kaboom() -- Script ends and prints the stack trace.
-Panics can not be caught using try catch. Once panic is invoked, the current fiber stops execution and begins to unwind its call stack. Once the error is propagated to the root, the fiber ends and transitions to a panic state. If the main fiber ends this way, the VM begins to shutdown. Otherwise, execution resumes on the next fiber which allows recovery from a panic.
Cyber supports binding to an existing C ABI compatible library at runtime.
-This allows you to call into dynamic libraries created in C or other languages.
-Cyber uses libtcc to JIT compile the bindings so function calls are fast.
-The example shown below can be found in Examples.
An FFI context contains declarations that map C to Cyber. Afterwards, it allows you to bind to a dynamic library or create interoperable objects. To create a new FFI context:
import os
-
-var ffi = os.newFFI()
-Functions from a library are first declared using cfunc which accepts C types in the form of symbols. In a future update they will accept C syntax instead.
ffi.cfunc('add', [.int, .int], .int)
-The first argument refers to the symbol’s name in the dynamic library. -The second argument contains the function’s parameter types and finally the last argument is the function’s return type.
The example above maps to this C function:
int add(int a, int b) {
- return a + b;
-}
-bindLib accepts the path to the library and returns a object which can be used to invoke the functions declared from cfunc:
my lib = ffi.bindLib('./mylib.so')
-lib.add(123, 321)
-Note that my is used to allow lib to be used dynamically since the type is unknown at compile-time.
If the path argument to bindLib is just a filename, the search steps for the library is specific to the operating system. Provide an absolute (eg. ‘/foo/mylib.so’) or relative (eg. ‘./mylib.so’) path to load from a direct location instead. When the path argument is none, it loads the currently running executable as a library allowing you to bind exported functions from the Cyber CLI or your own application/runtime.
By default bindLib returns an anonymous object with the binded C-functions as methods. This is convenient for invoking functions using the method call syntax. If a config is passed into bindLib as the second argument, genMap: true makes bindLib return a map instead with the binded C-functions as Cyber functions.
The resulting object of bindLib holds a reference to an internal TCCState which owns the loaded JIT code.
-Once the object is released by ARC, the TCCState is also released which removes the JIT code from memory.
When using cfunc or cbind declarations, symbols are used to represent default type mappings from Cyber to C and back:
Incomplete: This is not the final API for dynamically loading and interfacing with C libraries. The plan is to parse a subset of C headers to bind to Cyber types and functions.
| Binding | Cyber | C | Details |
|---|---|---|---|
| .bool | bool | bool | |
| .char | int | int8_t, signed char | |
| .uchar | int | uint8_t, unsigned char | |
| .short | int | int16_t, short | |
| .ushort | int | uint16_t, unsigned short | |
| .int | int | int32_t, int | |
| .uint | int | uint32_t, unsigned int | |
| .long | int | int64_t, long long | |
| .ulong | int | uint64_t, unsigned long long | |
| .usize | int | size_t, uintptr_t | |
| .float | float | float | |
| .double | float | double | |
| .charPtr | pointer | char* | Use os.cstr() and pointer.fromCstr() to convert between a Cyber string and a null terminated C string. |
| .voidPtr | pointer | void* | |
| type {S} object | type {S} object | struct | The mapping from a Cyber object type S and the C-struct can be declared with cbind. |
cbind is used to bind a C struct to a Cyber object type. Once declared, the Cyber type can be used as a binding type in function declarations:
import os
-
-type MyObject object:
- var a float
- var b pointer
- var c bool
-
-ffi.cbind(MyObject, [.float, .voidPtr, .bool])
-ffi.cfunc('foo', [MyObject], MyObject)
-my lib = ffi.bindLib('./mylib.so')
-
-var res = lib.foo([MyObject a: 123.0, b: os.cstr('foo'), c: true])
-The example above maps to these C declarations in mylib.so:
typedef struct MyObject {
- double a;
- char* b;
- bool c;
-} MyObject;
-
-MyObject foo(MyObject o) {
- // Do something.
-}
-cbind also generates ptrTo[Type] as a helper function to dereference an opaque ptr to a new Cyber object:
ffi.cfunc('foo', [MyObject], .voidPtr)
-my lib = ffi.bindLib('./mylib.so')
-
-var ptr = lib.foo([MyObject a: 123, b: os.cstr('foo'), c: true])
-var res = lib.ptrToMyObject(ptr)
-A pointer is used to read or write to an exact memory address. This is typically used for FFI to manually map Cyber types to C, and back. See type pointer.
A new pointer can be created with the builtin pointer.
var ptr = pointer(0xDEADBEEF)
-print ptr.value() --'3735928559'
-cbindgen.cy is a Cyber script that automatically generates bindings given a C header file. Some example bindings that were generated include: Raylib and LLVM.
In Cyber, there are first-class functions (or function values) and static functions.
Static functions are not initially values themselves. They allow function calls to be optimal since they don’t need to resolve a dynamic value.
Static functions are declared with the func keyword and must have a name.
import math
-
-func dist(x0 float, y0 float, x1 float, y1 float) float:
- var dx = x0-x1
- var dy = y0-y1
- return math.sqrt(dx^2 + dy^2)
-Calling static functions is straightforward. You can also reassign or pass them around as function values.
print dist(0, 0, 10, 20)
-
--- Assigning to a local variable.
-var bar = dist
-
--- Passing `dist` as an argument.
-func squareDist(dist, size):
- return dist(0.0, 0.0, size, size)
-
-print squareDist(dist, 30.0)
-Functions can only return one value. However, the value can be destructured: *Planned Feature
import {cos, sin} 'math'
-
-func compute(rad):
- return [ cos(rad), sin(rad) ]
-
-var [ x, y ] = compute(pi)
-Functions can be overloaded by the number of parameters in its signature. Typed functions are further overloaded by their type signatures.
func foo():
- return 2 + 2
-
-func foo(n):
- return 10 + n
-
-func foo(n, m):
- return n * m
-
-print foo() -- "4"
-print foo(2) -- "12"
-print foo(20, 5) -- "100"
-Lambdas or function values can be assigned to variables or passed as arguments into other constructs.
When a lambda only returns an expression, it can be declared with a simplified syntax.
-- Passing simple lambda as an argument.
-foo(word => toUpper(word))
-
--- A simple lambda with multiple arguments.
-foo((word, prefix) => prefix + toUpper(word))
-
--- Assigning a simple lambda.
-canvas.onUpdate = delta_ms => print delta_ms
-Lambdas that need a block of statements can be declared with the func keyword without a name.
-- Assigning lambda block to a variable.
-var add = func (a, b):
- return a + b
-
--- Passing a lambda block as an argument.
-canvas.onUpdate():
- ..func (delta_ms):
- print delta_ms
-Passing a lambda block as a call argument is only possible in a call block. *Planned Feature See Function Calls.
Lambdas can capture local variables from parent blocks. This example shows the lambda f capturing a from the main scope: *Incomplete, only variables one parent block away can be captured.
var a = 1
-var f = func():
- return a + 2
-print f() -- "3"
-The following lambda expression captures a from the function add:
func add():
- var a = 123
- return b => a + b
-var addTo = add()
-print addTo(10) -- "133"
-Like static variables, static functions can not reference local variables outside of their scope:
var a = 1
-func foo():
- print a -- CompileError: Undeclared variable `a`.
-Planned Feature
Planned Feature
Planned Feature
The straightforward way to call a function is to use parentheses.
var d = dist(100, 100, 200, 200)
-You can call functions with named parameters.
Planned Feature
var d = dist(x0: 10, x1: 20, y0: 30, y1: 40)
-The shorthand method for calling functions omits parentheses and commas. This only works for functions that accept parameters:
Incomplete: Only the most trivial cases work with the shorthand method. The case with operators being separated by spaces might not end up being implemented.
var d = dist 100 100 200 200 -- Calls the function `dist`.
-
-func random(): -- Function with no parameters.
- return 4
-
-var r = random -- Returns the function itself as a value.
- -- Does not call the function `random`.
-r = random() -- Calls the function `random`.
-The top level arguments for the shorthand convention must be separated by whitespace. A string can contain whitespace since it’s surrounded by delimiters.
var a = myFunc 'cyber script'
-The following has a binary expression with spaces inbetween which is not allowed. Removing that whitespace fixes the call expression.
var a = myFunc 1 + 2 -- Not allowed.
-a = myFunc 1+2 -- Correct.
-Wrapping arguments in parentheses allows you to keep the whitespace in the sub-expression.
-- This calls the function `myFunc` with 2 arguments.
-var a = myFunc 'hello' (1 + 2 * 3)
-
--- Nested function call using the shorthand convention.
-a = myFunc 'hello' (otherFunc 1+2 'world')
-The call expression block continues to add arguments from the block’s body. If arguments are omitted from the initial call expression they can be added inside using the .. syntax. Arguments mapped to named parameters have a key value syntax separated by a :. All other arguments are added into a list and passed as the last argument.
Planned Feature
foo(123):
- ..func ():
- return 123
- param3: 123
- 234
- bar()
- 'hello'
-In the example above, the function foo is called with 4 arguments. The first argument 123 is included in the starting call expression. The second argument is a function value inside the call expression block. The third argument is mapped to the param param3. Finally, the fourth argument is a list that contains 234, bar(), and 'hello'.
Cyber provides memory safety by default.
Cyber uses ARC or automatic reference counting to manage memory. -ARC is deterministic and has less overhead compared to a tracing garbage collector. Reference counting distributes memory management, which reduces GC pauses and makes ARC suitable for realtime applications. One common issue in ARC implementations is reference cycles which Cyber addresses with Weak References and it’s very own Cycle Detection.
In Cyber, there are primitive and object values. Primitives don’t need any memory management, since they are copied by value and no heap allocation is required (with the exception of primitives being captured by a closure).
Objects are managed by ARC. Each object has its own reference counter. Upon creating a new object, it receives a reference count of 1. When the object is copied, it’s retained and the reference count increments by 1. When an object value is removed from it’s parent or is no longer reachable in the current stack frame, it is released and the reference count decrements by 1.
Once the reference count reaches 0 the object begins its destruction procedure. First, child references are released thereby decrementing their reference counts by 1. If the object is a host object, it will invoke its finalizer function. Afterwards, the object is freed from memory.
The compiler can reduce the number of retain/release ops since it can infer value types even though they are dynamically typed to the user. Arguments passed to functions are only retained depending on the analysis from the callsite.
When primitive variables are captured by a closure, they are boxed and allocated on the heap. This means they are managed by ARC and cleaned up when there are no more references to them.
Fibers are freed by ARC just like any other object. Once there are no references to the fiber, it begins to release it’s child references by unwinding it’s call stack.
Many object types in Cyber are small enough to be at or under 40 bytes. To take advantage of this, Cyber can reserve object pools to quickly allocate and free these small objects with very little bookkeeping. Bigger objects are allocated and managed by mimalloc which has proven to be a fast and reliable general-purpose heap allocator.
Planned Feature
The cycle detector is also considered a GC and frees abandoned objects managed by ARC. Although weak references can remove cycles altogether, Cyber does not force you to use them and provides a manual GC as a one-time catch all solution.
Incomplete Feature: Only the main fiber stack is cleaned up at the moment.
To invoke the GC, call the builtin function: performGC.
func foo():
- -- Create a reference cycle.
- var a = []
- var b = []
- a.append(b)
- b.append(a)
-
- -- Cycle still alive in the current stack so no cleanup is done.
- var res = performGC()
- print res['numCycFreed'] -- Output: 0
- print res['numObjFreed'] -- Output: 0
-
-foo()
--- `a` and `b` are no longer reachable, so the GC does work.
-var res = performGC()
-print res['numCycFreed'] -- Output: 2
-print res['numObjFreed'] -- Output: 2
-All operators are implemented as object methods.
Incomplete: Not all operators have transitioned to the method paradigm.
Normally this would impact performance, but Cyber generates specialized bytecode for builtin types like int and float. The VM performs inline caching at runtime to eliminate the overhead of evaluating on dynamic operands.
To overload an operator for an object type, declare $prefix, $infix, $postfix methods. See the available builtin operators. Since operator names aren’t allowed as standard identifiers, they are contained in a string literal.
type Vec2 object:
- var x float
- var y float
-
- func '$infix+'(o Vec2) Vec2:
- return [Vec2
- x: x + o.x,
- y: y + o.y,
- ]
-
- func '$prefix-'() Vec2:
- return [Vec2 x: -x, y: -y]
-
-var a = [Vec2 x: 1, y: 2]
-var b = a + [Vec2 x: 3, y: 4]
-var c = -a
-Some special operators have their own name. This example overloads the index operator and the set index operator:
type MyCollection object:
- var arr List
-
- func '$index'(idx):
- return arr[idx * 2]
-
- func '$setIndex'(idx, val):
- arr[idx * 2] = val
-
-var a = [MyCollection arr: [1, 2, 3, 4]]
-print a[1] -- Prints `3`
-A list of all supported operators:
| Operator | Name |
|---|---|
| Bitwise not | $prefix~ |
| Minus | $prefix- |
| Greater | $infix> |
| Greater equal | $infix>= |
| Less | $infix< |
| Less equal | $infix<= |
| Add | $infix+ |
| Subtract | $infix- |
| Multiply | $infix* |
| Divide | $infix/ |
| Modulus | $infix% |
| Power | $infix^ |
| Bitwise and | $infix& |
| Bitwise or | $infix| |
| Bitwise xor | $infix|| |
| Bitwise left shift | $infix<< |
| Bitwise right shift | $infix>> |
| Index | $index |
| Set index | $setIndex |
| Slice | $slice |
Planned Feature
Declare a $call function to allow invoking a module as a function.
Incomplete: Although $call function is supported in the VM and builtin modules use it, it is not currently enabled for user modules.
-- Object types are also modules.
-type Vec2 object:
- var x float
- var y float
-
-func Vec2.'$call'(x float, y float) Vec2:
- return [Vec2 x: x, y: y]
-
-var v = Vec2(1, 2)
-Planned Feature
Declare a $missing method as a fallback when a method was not found in an instance.
Planned Feature
type A object:
-
- func '$missing'(args...):
- return args.len
-
-var a = [A:]
-print a.foo() -- Output: '0'
-print a.bar(1, 2) -- Output: '2'
-A metatype object references an internal type. Use the typeof builtin to get the metatype of a value.
var val = 123
-print typeof(val) -- 'type: float'
-
--- Referencing a type as a value also returns its `metatype`.
-print bool -- 'type: bool'
-Annotations are used to attach modifiers to declarative statements. The @host annotation is used for embedding to bind a host function to a Cyber function:
@host func compute() float
-Custom annotations.
Planned Feature
Planned Feature
Planned Feature
Planned Feature
Modules have their own namespace and contain accessible static symbols. By default, importing another Cyber script returns a module with its declared symbols.
Import declarations create a local alias to the module referenced by the import specifier. The Cyber CLI comes with some builtin modules like math and test. If the specifier does not refer to a builtin module, it looks for a Cyber script file relative to the current script’s directory. An embedder can integrate their own module loader and resolver.
import test
-test.eq(123, 123)
-
--- Imports are static declarations so they can be anywhere in the script.
-import math
-print math.cos(0)
-When the imported alias needs to be renamed, the import specifier comes after the alias name and must be a string literal.
import m 'math'
-print m.random()
-
--- Loading a Cyber module from the local directory.
-import foo 'bar.cy'
-print foo.myFunc()
-print foo.myVar
-A Cyber script that is imported doesn’t evaluate its main block. Only static declarations are effectively loaded. If there is code in the main block, it will skip evaluation. In the following, only the print statement in the main.cy is evaluated.
-- main.cy
-import a 'foo.cy'
-print a.foo
-
--- foo.cy
-import 'bar.cy'
-var Root.foo = 123
-print foo -- Statement is ignored.
-
--- bar.cy
-var Root.bar = 321
-print bar -- Statement is ignored.
-You can have circular imports in Cyber. In the following example, main.cy and foo.cy import each other without any problems.
-- main.cy
-import foo 'foo.cy'
-
-func printB():
- foo.printC()
-
-foo.printA()
-
--- foo.cy
-import main 'main.cy'
-
-func printA():
- main.printB()
-
-func printC():
- print 'done'
-Static variable declarations from imports can have circular references. Read more about this in Static Variables.
Modules can also be destructured using the following syntax:
Planned Feature
import { cos, pi } 'math'
-print cos(pi)
-All static declarations are exported when the script’s module is loaded.
func foo(): -- Exported static function.
- print 123
-
-var Root.bar = 234 -- Exported static variable.
-
-type Thing object: -- Exported type.
- var a float
-To get the absolute path of the current module, reference the compile-time variable ModUri.
-This can be used with os.dirName to get the current module directory.
print #ModUri -- Prints '/some/path/foo.cy'
-
-import os
-print os.dirName(#ModUri) -- Prints '/some/path'
-The annotation @hide provides a hint to editors that a static symbol should not appear in the auto-complete. Despite this, the symbol is still reachable.
Builtin modules are the bare minimum that comes with Cyber. The embeddable library contains these modules and nothing more. They include:
The builtins module contains functions related to Cyber and common utilities. It is automatically imported into each script’s namespace.
Sample usage:
-- `print` and `typeof` are available without imports.
-print 'hello'
-print typeof('my str').id()
-func copy(val any) anyfunc dump(val any) nonetoCyon on a value.func errorReport() stringfunc getObjectRc(val any) intfunc is(a any, b any) boolfunc isAlpha(val int) boolfunc isDigit(val int) boolfunc must(val any) anyval is an error, panic(val) is invoked. Otherwise, val is returned.func panic(err any) nonefunc parseCyber(src string) Mapfunc parseCyon(src string) anyfunc performGC() Mapfunc print(str any) nonefunc runestr(val int) stringfunc toCyon(val any) stringfunc typeof(val any) metatypemetatype object.func typesym(val any) symboltype bool
-#func bool.'$call'(val any) booltrue or false.type error
-#func sym() symbolsymbol.func error.'$call'(val any) errortype int
-#func $prefix~() intfunc $prefix-() intfunc $infix<(o any) boolfunc $infix<=(o any) boolfunc $infix>(o any) boolfunc $infix>=(o any) boolfunc $infix+(o any) intfunc $infix-(o any) intfunc $infix*(o any) intfunc $infix/(o any) intfunc $infix%(o any) intfunc $infix^(o any) intfunc $infix&(o any) intfunc $infix|(o any) intfunc $infix||(o any) intfunc $infix<<(o any) intfunc $infix>>(o any) intfunc fmt(kind symbol) string.b, octal .o, decimal .d, hexadecimal .x, ASCII .c.func fmt(kind symbol, opts Map) stringopts.pad provides the ASCII rune that is used for padding with a string length of opts.width.func int.'$call'(val any) inttype float
-#func $prefix-() floatfunc $infix<(o any) boolfunc $infix<=(o any) boolfunc $infix>(o any) boolfunc $infix>=(o any) boolfunc $infix+(o any) floatfunc $infix-(o any) floatfunc $infix*(o any) floatfunc $infix/(o any) floatfunc $infix%(o any) floatfunc $infix^(o any) floatfunc float.'$call'(val any) floatfloat. Panics if type conversion fails.type List
-#func $index(idx any) anyfunc $setIndex(idx any, val any) nonefunc $slice(start any, end any) Listfunc append(val any) nonefunc concat(list List) nonefunc insert(idx int, val any) noneidx.func iterator() ListIteratorfunc join(sep string) stringseparator.func len() intfunc remove(idx int) noneidx.func resize(size int) nonelen elements. If the new size is bigger, none values are appended to the list. If the new size is smaller, elements at the end of the list are removed.func slice(start any, end any) Listfunc List.fill(val any, n int) Listn and values set to val. If the value is an object, it is shallow copied n times.type ListIterator
-#func next() anytype tuple
-#func $index(idx int) anytype Map
-#func $index(key any) anyfunc $setIndex(key any, val any) nonefunc remove(key any) nonekey.func size() intfunc iterator() MapIteratortype MapIterator
-#func next() anytype string
-#func $infix+(o any) stringfunc concat(o string) stringstr.func endsWith(suffix string) boolsuffix.func find(needle string) anyneedle in the string or none if not found.func findAnyRune(runes string) anyrunes or none if not found.func findRune(rune int) intneedle in the string or none if not found.func insert(idx int, str string) stringstr inserted at index idx.func isAscii() boolfunc len() intfunc less(other string) boolother.func lower() stringfunc replace(needle string, replacement string) stringneedle replaced with replacement.func repeat(n int) stringn times.func runeAt(n int) intidx.func slice(start any, end any) stringstart to end (exclusive) indexes. This is equivalent to using the slice index operator [start..end].func $slice(start any, end any) stringfunc sliceAt(idx int) stringidx as a single rune string.func $index(idx int) stringfunc split(sep string) Listsep.func startsWith(prefix string) boolprefix.func trim(mode symbol, delims string) stringdelims. mode can be .left, .right, or .ends.func upper() stringfunc string.'$call'(val any) stringtype array
-#func $infix+(o any) arrayfunc concat(other array) arrayother.func decode() stringfunc decode(encoding symbol) stringencoding. Supported encodings: .utf8. Returns the decoded string or throws error.Decode.func endsWith(suffix array) boolsuffix.func find(needle array) anyneedle in the array or none if not found.func findAnyByte(bytes array) anybytes in arrays or none if not found.func findByte(byte int) anybyte in the array or none if not found.func fmt(kind symbol) string.b, octal .o, decimal .d, hexadecimal .x, ASCII .c. Each byte is zero padded.func getByte(idx int) intidx.func getInt(idx int, endian symbol) intidx with the given endianness (.little or .big).func getInt32(idx int, endian symbol) intidx with the given endianness (.little or .big).func insert(idx int, arr array) arrayarr inserted at index idx.func insertByte(idx int, byte int) arraybyte inserted at index idx.func len() intfunc repeat(n int) arrayn times.func replace(needle array, replacement array) arrayneedle replaced with replacement.func slice(start any, end any) arraystart to end (exclusive) indexes. This is equivalent to using the slice index operator [start..end].func $slice(start any, end any) arrayfunc $index(idx int) intfunc split(sep array) Listsep.func startsWith(prefix array) boolprefix.func trim(mode symbol, delims array) arraydelims. mode can be .left, .right, or .ends.func array.'$call'(val any) arrayarray.type arrayIterator
-#type pointer
-#func addr() intint. The value may be negative since it’s bitcasted from an unsigned 48-bit integer but it retains the original pointer bits.func asObject() anyfunc fromCstr(offset int) arrayarray from a null terminated C string.func get(offset int, ctype symbol) anyfunc set(offset int, val any) nonefunc toArray(offset int, len int) arrayarray with a copy of the byte data starting from an offset to the specified length.func pointer.'$call'(val any) pointerint to a pointer value, or casts to a pointer. This is usually used with FFI.type Fiber
-#func status() symboltype metatype
-#func id() intThe math module contains commonly used math constants and functions.
Sample usage:
import math
-
-var r = 10.0
-print(math.pi * r^2)
-var e floatvar inf floatvar log10e floatvar log2e floatvar ln10 floatvar ln2 floatvar maxSafeInt floatvar minSafeInt floatvar nan floatisNaN instead.var neginf floatvar pi floatvar sqrt1_2 floatvar sqrt2 floatfunc abs(a float) floatfunc acos(a float) floatfunc acosh(a float) floatfunc asin(a float) floatfunc asinh(a float) floatfunc atan(a float) floatfunc atan2(a float, b float) floatfunc atanh(a float) floatfunc cbrt(a float) floatfunc ceil(a float) floatfunc clz32(a float) floatfunc cos(a float) floatfunc cosh(a float) floatfunc exp(a float) floatfunc expm1(a float) floatfunc floor(a float) floatfunc frac(a float) floatfunc hypot(a float, b float) floatfunc isInt(a float) boolfunc isNaN(a float) boolfunc ln(a float) floatfunc log(a float, b float) floatfunc log10(a float) floatfunc log1p(a float) floatfunc log2(a float) floatfunc max(a float, b float) floatfunc min(a float, b float) floatfunc mul32(a float, b float) floatfunc pow(a float, b float) floatfunc random() floatfunc round(a float) floatfunc sign(a float) floatfunc sin(a float) floatfunc sinh(a float) floatfunc sqrt(a float) floatfunc tan(a float) floatfunc tanh(a float) floatfunc trunc(a float) floatStd modules come with Cyber’s CLI. They include:
Cyber’s os module contains system level functions. It’s still undecided as to how much should be included here so it’s incomplete. You can still access os and libc functions yourself using Cyber’s FFI or embedding API.
Sample usage:
import os
-
-var map = os.getEnvAll()
-for map -> [k, v]:
- print '$(k) -> $(v)'
-var cpu stringvar endian symbolvar stderr Filevar stdin Filevar stdout Filevar system stringvar vecBitSize intfunc access(path string, mode symbol) nonepath with the .read, .write, or .readWrite mode. Throws an error if unsuccessful.func args() ListList. Each argument is converted to a string.func cacheUrl(url string) stringurl. If no such file exists locally, it’s fetched from url.func copyFile(srcPath string, dstPath string) nonefunc createDir(path string) nonepath. Returns true if successful.func createFile(path string, truncate bool) Filepath. If truncate is true, an existing file will be truncated.func cstr(s any) pointerfunc cwd() stringfunc dirName(path string) stringfunc execCmd(args List) Mapfunc exePath() stringfunc exit(status int) nonefunc fetchUrl(url string) arrayurl using the HTTP GET request method.func free(ptr pointer) noneptr.func getEnv(key string) stringfunc getEnvAll() MapMap.func malloc(size int) pointersize bytes of memory and returns a pointer.func milliTime() floatnow().func newFFI() FFIfunc now() floatfunc openDir(path string) DiropenDir(path, false).func openDir(path string, iterable bool) Dirpath. iterable indicates that the directory’s entries can be iterated.func openFile(path string, mode symbol) Filepath with the .read, .write, or .readWrite mode.func parseArgs(options List) MapArgOptions, returns a map of the options and a rest entry which contains the non-option arguments.func readAll() stringstdin.readAll().func readFile(path string) stringpath as a UTF-8 string. To return the bytes instead, use File.readAll().func readLine() stringstring. This is intended to read user input from the command line. For bulk reads from stdin, use stdin.func realPath(path string) stringfunc removeDir(path string) nonepath. Returns true if successful.func removeFile(path string) nonepath. Returns true if successful.func setEnv(key string, val string) nonefunc sleep(ms float) nonefunc unsetEnv(key string) nonefunc writeFile(path string, contents any) nonecontents as a string or bytes to a file.type File
-#func close() noneerror.Closed.func iterator() anyfunc next() anyfunc read(n int) arrayn bytes as an array. n must be at least 1. A result with length 0 indicates the end of file was reached.func readAll() arrayarray.func seek(n int) nonepos bytes from the start. Negative pos is invalid.func seekFromCur(n int) nonepos bytes from the current position.func seekFromEnd(n int) nonepos bytes from the end. Positive pos is invalid.func stat() MapMap.func streamLines() FilestreamLines(4096).func streamLines(bufSize int) File\n, \r, \r\n, or the EOF. The lines returned include the new line character(s). A buffer size of bufSize bytes is allocated for reading. If \r is found at the end of the read buffer, the line is returned instead of waiting to see if the next read has a connecting \n.func write(val any) intstring or array at the current file position. The number of bytes written is returned.type Dir
-#func iterator() DirIteratorerror.NotAllowed is returned instead.func stat() MapMap.func walk() DirIteratorerror.NotAllowed is returned instead.type DirIterator
-#func next() anytype FFI
-#func bindCallback(fn any, params List, ret symbol) ExternFuncExternFunc that contains a C function pointer with the given signature. The extern function is a wrapper that calls the provided user function. Once created, the extern function is retained and managed by the FFI context.func bindLib(path any) anybindLib(path, [:]).func bindLib(path any, config Map) anycfunc. By default, an anonymous object is returned with the C-functions binded as the object’s methods. If config contains genMap: true, a Map is returned instead with C-functions binded as function values.func bindObjPtr(obj any) pointerfunc cbind(mt metatype, fields List) nonefunc cfunc(name string, params List, ret any) nonebindLib.func new(ctype symbol) pointerpointer to the allocated memory is returned. Eventually this will return a cpointer instead which will be more idiomatic to use.func unbindObjPtr(obj any) nonetype CArray
-#type CDimArray
-#map DirEntry
-#| Entry | Summary |
|---|---|
'name' -> array | The name of the file or directory. |
'type' -> #file | #dir | #unknown | The type of the entry. |
map DirWalkEntry
-#| Entry | Summary |
|---|---|
'name' -> array | The name of the file or directory. |
'path' -> array | The path of the file or directory relative to the walker’s root directory. |
'type' -> #file | #dir | #unknown | The type of the entry. |
map ArgOption
-#| Entry | Summary |
|---|---|
'name' -> string | The name of the option to match excluding the hyphen prefix. eg. -path |
'type' -> metatype(string | float | boolean) | Parse as given value type. |
'default' -> any | Optional: Default value if option is missing. none is used if this is not provided. |
The test module contains utilities for testing.
Sample usage:
import t 'test'
-
-var a = 123 + 321
-t.eq(a, 444)
-func eq(a any, b any) anyerror.AssertError if types or values do not match up.func eqList(a any, b any) anyeq was called on those corresponding elements.func eqNear(a any, b any) anyfunc fail() anyCyber’s syntax is concise and easy to read.
A statement ends with the new line.
-- An assignment statement.
-var a = 123
-Some statements can start a new block with a colon. -The first statement in a new block must be indented further. -Spaces or tabs can be used for indentation but not both.
-- This `if` statement begins a new block.
-if true:
- var a = 234
-Subsequent statements in the block must follow the same indentation. -The block ends when a statement recedes from this indentation.
var items = [10, 20, 30]
-for items -> it:
- if it == 20:
- print it
- print it -- This is the first statement outside of the `if` block.
-Single-line blocks allow only one statement after a starting block.
-- A single line block.
-if true: print 123
-
-if true: print 123
- -- This is an indentation error since the single-line block is already consumed.
- print 234
-Since blocks require at least one statement, use pass as a placeholder statement.
func foo():
- pass
-Cyber supports dynamic and static typing. If you’re used to a dynamic language such as Python, JavaScript, or Lua, use my to declare your variables and object fields. If you’re used to a static language then use var instead. The documentation will use static typing by default.
Local variables exist until the end of their scope.
-They are declared and initialized using the var keyword:
var a = 123
-When declared without a type specifier next to the variable, it infers the type from the right initializer. -To declare variables for a specific type, see Typed variables.
Variables can be set afterwards using the = operator:
a = 234
-Dynamically typed variables are easier to work with and there is no friction when using them. They are declared using the my keyword:
my a = 123
-To understand more about dynamically and statically typed code, see Type System.
Blocks create a new variable scope. Variables declared in the current scope will take precedence over any parent variables with the same name:
func foo():
- var a = 234
-
- if true:
- var a = 345 -- New `a` declared.
- print a -- Prints "345"
-
- print a -- Prints "234"
-Static variables live until the end of the script. -They act as global variables and are visible from anywhere in the script.
They are declared with var but a namespace must be provided before the variable name:
var Root.a = 123
-
-func foo():
- print a -- '123'
-The Root symbol is used to reference the current module’s namespace.
Since static variables are initialized outside of a fiber’s execution flow, they can not reference any local variables:
-- Static declaration.
-var Root.b = a -- Compile error, initializer can not reference a local variable.
-
--- Main execution.
-var a = 123
-However, they can be reassigned after initialization:
var Root.b = 0
-
-var a = 123
-b = a -- Reassigning after initializing.
-Static variable initializers have a natural order based on when it was encountered by the compiler. -In the case of imported variables, the order of the import would affect this order. -The following would print ‘123’ before ‘234’:
var Root.a = print(123)
-var Root.b = print(234)
-When the initializers reference other static variables, those child references are initialized first in DFS order and supersede the natural ordering. The following initializes b before a.
var Root.a = b + 321
-var Root.b = 123
-
-print a -- '444'
-Circular references in initializers are not allowed. -When initialization encounters a reference that creates a circular dependency an error is reported.
var Root.a = b
-var Root.b = a -- CompileError. Referencing `a` creates a circular dependency.
-Sometimes, you may want to initialize a static variable by executing multiple statements in order. -For this use case, you can use a declaration block. *Planned Feature
var Root.myImage =:
- var img = loadImage('me.png')
- img.resize(100, 100)
- img.filter(.blur, 5)
- break img
-The final resulting value that is assigned to the static variable is provided by a break statement. If a break statement is not provided, none is assigned instead.
There are 25 general keywords. This list categorizes them:
if else switch case while for break continue passor and notvar myfunc returncoinit coyield, coresumetype astry catch throwimportThese keywords only have meaning in a certain context.
self, SelfcaughtobjectenumthrowsRoottrue falseerrornoneCyber supports the following operators. They are ordered from highest to lowest precedence.
| Operator | Description |
|---|---|
<< >> | Bitwise left shift, right shift. |
& | Bitwise and. |
| || | Bitwise or, exclusive or. |
^ | Power. |
/ % * | Division, modulus, multiplication. |
+ - | Addition, subtraction. |
as | Type casting. |
> >= < <= != == | Greater, greater or equal, less, less or equal, not equals, equals. |
and | Logical and. |
or | Logical or. |
The following arithmetic operators are supported for the numeric data types.
1 + 2 -- Addition, evaluates to 3.
-100 - 10 -- Subtraction, evaluates to 90.
-3 * 4 -- Multiplication, evaluates to 12.
-20 / 5 -- Division, evaluates to 4.
-2 ^ 4 -- Raise to the power, evaluates to 16.
-12 % 5 -- Modulus remainder, evaluates to 2.
--(10) -- Apply negative, evaluates to -10.
-Cyber supports the following comparison operators. -By default, a comparison operator evaluates to a Boolean value.
The equals operator returns true if the two values are equal. For primitive types, the comparison checks the types and the underlying value. For strings, the underlying bytes are compared for equality. For objects, the comparison checks that the two values reference the same object.
1 == 1 -- Evaluates to `true`
-1 == 2 -- Evaluates to `false`
-1 == true -- Evaluates to `false`
-
-my a = 'abc'
-a == 'abc' -- Evaluates to `true`
-
-a = []
-my b = a
-a == b -- Evaluates to `true`
-a == [] -- Evaluates to `false`
-The not equals operator returns true if the two values are not equal.
1 != 1 -- Evaluates to `false`
-1 != 2 -- Evaluates to `true`
-Number types have additional comparison operators.
a > b -- `true` if a is greater than b
-a >= b -- `true` if a is greater than or equal to b
-a < b -- `true` if a is less than b
-a <= b -- `true` if a is less than or equal to b
-The logical operators and, or, and not are supported.
and evaluates to a if a is not truthy. Otherwise, it evaluates to b. If a is not truthy, the evaluation of b is not executed. A numeric value that isn’t 0 is truthy. An object reference is always truthy. The none value is not truthy.
true and true -- Evaluates to true
-123 and 234 -- Evaluates to 234
-123 and 0 -- Evaluates to false
-or evaluates to a if a is truthy. Otherwise, it evaluates to b. If a is found to be truthy, the evaluation of b is not executed.
true or false -- Evaluates to true
-false or true -- Evaluates to true
-false or false -- Evaluates to false
-123 or false -- Evaluates to 123
-The unary operator not performs negation on the boolean value. The unary operator ! can also be used instead of not.
not false -- Evaluates to true
-not true -- Evaluates to false
-not 0 -- Evaluates to true
-not 123 -- Evaluates to false
-!false -- Evaluates to true
-!true -- Evaluates to false
-The following bitwise operators are supported for int number values.
-- Bitwise and: any underlying bits that are set in both integers are set in the new integer.
-a & b
-
--- Bitwise or: any underlying bits that are set in either integer a or integer b are set in the new integer.
-a | b
-
--- Bitwise exclusive or: any underlying bits that are set in either integer a or integer b but not both are set in the new integer.
-a || b
-
--- Bitwise right shift: a's bits are shifted b bits to the least significant end. This performs sign-extension on the 32-bit integer.
-a >> b
-
--- Bitwise left shift: a's bits are shifted b bits to the most significant end. This does not perform sign-extension on the 32-bit integer.
-a << b
-
--- Bitwise not: a's integer bits are flipped.
-~a
-See Operator Overloading in Metaprogramming.
A single line comment starts with two hyphens and ends at the end of the line.
-- This is a comment.
-
-var a = 123 -- This is a comment on the same line as a statement.
-There will be multi-line comments in Cyber but the syntax has not been determined.
CYON or the Cyber object notation is similar to JSON. The format uses the same literal value semantics as Cyber.
[
- name: 'John Doe',
- 'age': 25,
- -- This is a comment
- cities: [
- 'New York',
- 'San Francisco',
- 'Tokyo',
- ],
-]
-Cyber supports the use of both dynamically and statically typed code.
Dynamic typing can reduce the amount of friction when writing code, but it can also result in more runtime errors.
my declaration.
-#Variables declared with my are assigned the dynamic type:
my a = 123
-dynamic vs any
-#dynamic values can be freely used and copied without any compile errors (if there is a chance it can succeed at runtime, see Recent type inference):
my a = 123
-
-func getFirstRune(s string):
- return s[0]
-
-getFirstRune(a) -- RuntimeError. Expected `string`.
-Since a is dynamic, passing it to a typed function parameter is allowed at compile-time, but will fail when the function is invoked at runtime.
The any type on the otherhand is a static type and must be explicitly declared using var:
var a any = 123
-
-func getFirstRune(s string):
- return s[0]
-
-getFirstRune(a) -- CompileError. Expected `string`.
-This same setup will now fail at compile-time because any does not satisfy the destination’s string type constraint.
The use of the dynamic type effectively defers type checking to runtime while any is a static type and must adhere to type constraints at compile-time.
A dynamic value can be used in any operation. It can be invoked as the callee, invoked as the receiver of a method call, or used with operators.
dynamic values.
-#When a dynamic value is invoked, checks on whether the callee is a function is deferred to runtime.
my op = 123
-print op(1, 2, 3) -- RuntimeError. Expected a function.
-When the return type of a function is not specified, it defaults to the dynamic type.
-This allows copying the return value to a typed destination without casting:
func getValue():
- return 123
-
-func add(a int, b int):
- return a + b
-
-print add(getValue(), 2) -- Prints "125"
-The add function defers type checking of getValue() to runtime because it has the dynamic type.
Although a dynamic variable has the most flexibility, in some situations it is advantageous to know what type it could be.
The compiler keeps a running record of a dynamic variable’s most recent type to gain additional compile-time features without sacrificing flexibility. It can prevent inevitable runtime errors and avoid unnecessary type casts.
When a dynamic variable is first initialized, it has a recent type inferred from its initializer. In the following, a has the recent type of int at compile-time because numeric literals default to the int type:
my a = 123
-The recent type can change at compile-time from another assignment.
-If a is then assigned to a string literal, a from that point on has the recent type of string at compile-time:
my a = 123
-foo(a) -- Valid call expression.
-a = 'hello'
-foo(a) -- CompileError. Expected `int` argument, got `string`.
-
-func foo(n int):
- pass
-Even though a is dynamic and is usually allowed to defer type checking to runtime, the compiler knows that doing so in this context would always result in a runtime error, so it provides a compile error instead. This provides a quicker feedback to fix the problem.
The recent type of a can also change in branches. However, after the branch block, a will have a recent type after merging the types assigned to a from the two branched code paths. Currently, the any type is used if the types from the two branches differ. At the end of the following if block, a has the recent type of any type after merging the int and string types: *Planned Feature
my a = 123
-if a > 20:
- a = 'hello'
- foo(a) -- Valid call expression. `foo` can be called without type casting.
-
-foo(a) -- CompileError. Expected `string` argument, got `any`.
-
-func foo(s string):
- pass
-Static typing can be incrementally applied which provides compile-time guarantees and prevents runtime errors. -Static typing also makes it easier to maintain and refactor your code.
The following builtin types are available in every module: bool, float, int, string, List, Map, error, fiber, any.
var declaration.
-#A var declaration automatically infers the type from the initializer:
-- Initialized as an `int` variable.
-var a = 123
-var declarations are strictly for static typing. If the assigned value’s type is dynamic, the variable’s type becomes any.
func getValue():
- return ['a', 'list']
-
--- Initialized as an `any` variable.
-var a = getValue()
-A typed local variable can be declared by attaching a type specifier after its name. The value assigned to the variable must satisfy the type constraint or a compile error is issued.
var a float = 123
-
-var b int = 123.0 -- CompileError. Expected `int`, got `float`.
-Any operation afterwards that violates the type constraint of the variable will result in a compile error.
a = 'hello' -- CompileError. Expected `float`, got `string`.
-Static variables are declared in a similar way:
var Root.global Map = [:]
-Unlike local variables, static variable declarations do not infer the type from the right hand side. A specific type must be specified or it will default to the any type.
A type object declaration creates a new object type. Field types are optional and declared with a type specifier after their name.
type Student object: -- Creates a new type named `Student`
- var name string
- var age int
- var gpa float
-Instantiating a new object does not require typed fields to be initialized. Missing field values will default to their zero value:
var s = [Student:]
-print s.name -- Prints ""
-print s.age -- Prints "0"
-print s.gpa -- Prints "0.0"
-Circular type dependencies are allowed if the object can be initialized:
Planned Feature: Optional types are not currently supported.
type Node object:
- var val any
- var next Node? -- Valid type specifier.
-In this example, next has an optional Node? type so it can be initialized to none when creating a new Node object.
The following example will fail because this version of Node can not be initialized:
type Node object:
- var val any
- var next Node
-
-var n = [Node:] -- CompileError. Can not zero initialize `next`
- -- because of circular dependency.
-The following shows the zero values of builtin or created types.
| Type | Zero value |
|---|---|
boolean | false |
int | 0 |
float | 0.0 |
string | '' |
array | array('') |
List | [] |
Map | [:] |
type S object | [S:] |
@host type S object | S.$zero() |
dynamic | none |
any | none |
S? | none |
A type alias is declared from a single line type statement. This creates a new type symbol for an existing data type.
import util './util.cy'
-
-type Vec3 util.Vec3
-
-var v = [Vec3 x: 3, y: 4, z: 5]
-Function parameter and return type specifiers follows a similiar syntax.
func mul(a float, b float) float:
- return a * b
-
-print mul(3, 4)
-print mul(3, '4') -- CompileError. Function signature mismatch.
-Planned Feature
Planned Feature
any type.
-#A variable with the any type can hold any value, but copying it to narrowed type destination will result in a compile error:
func square(i int):
- return i * i
-
-var a any = 123
-a = ['a', 'list'] -- Valid assignment to a value with a different type.
-a = 10
-
-print square(a) -- CompileError. Expected `int`, got `any`.
-a must be explicitly casted to satisfy the type constraint:
print square(a as int) -- Prints "100".
-any values.
-#Since any is a static type, invoking an any value must be explicitly casted to the appropriate function type.
Planned Feature: Casting to a function type is not currently supported.
func add(a int, b int) int:
- return a + b
-
-var op any = add
-print op(1, 2) -- CompileError. Expected `func (int, int) any`
-
-var opFunc = op as (func (int, int) int)
-print opFunc(1, 2) -- Prints "3".
-The as keyword can be used to cast a value to a specific type. Casting lets the compiler know what the expected type is and does not perform any conversions.
If the compiler knows the cast will always fail at runtime, a compile error is returned instead.
print('123' as int) -- CompileError. Can not cast `string` to `int`.
-If the cast fails at runtime, a panic is returned.
var erased any = 123
-add(1, erased as int) -- Success.
-print(erased as string) -- Panic. Can not cast `int` to `string`.
-
-func add(a int, b int):
- return a + b
-Cyber is a fast, efficient, and concurrent scripting language. To learn more about Cyber itself visit the website at cyberscript.dev.
Cyber is easy to learn. These docs provide a reference manual for the language. You can read it in order or jump around using the navigation.
You may come across features that are marked Incomplete or Planned. This is because the docs are written as if all features have been completed already.
import math
-
-var worlds = ['World', '世界', 'दुनिया', 'mundo']
+
+
+
+
+ Cyber Docs
+
+
+
+
+
+
+ Cyber Docs
+ dev
+
+ - Homepage
+ - Playground
+ - Edit Docs
+
+ Table of Contents
+
+
+
+
+Introduction. #
+Cyber is a fast, efficient, and concurrent scripting language. The landing page is at cyberscript.dev and contains performance metrics and release notes.
+Cyber is easy to learn. These docs provide a reference manual for the language. You can read it in order or jump around using the navigation.
+You may come across features that are marked Incomplete or Planned. This is because the docs are written as if all features have been completed already.
+Hello World. #
+import math
+
+var worlds = ['World', '世界', 'दुनिया', 'mundo']
worlds.append(math.random())
-for worlds -> w:
- print 'Hello, $(w)!'
-
| + + | + + | +
Cyber's syntax is concise and easy to read.
+A statement ends with the new line.
+-- An assignment statement.
+var a = 123
+Some statements can start a new block with a colon. +The first statement in a new block must be indented further. +Spaces or tabs can be used for indentation but not both.
+-- This `if` statement begins a new block.
+if true:
+ var a = 234
+Subsequent statements in the block must follow the same indentation. +The block ends when a statement recedes from this indentation.
+var items = [10, 20, 30]
+for items -> it:
+ if it == 20:
+ print it
+ print it -- This is the first statement outside of the `if` block.
+Single-line blocks allow only one statement after a starting block.
+-- A single line block.
+if true: print 123
+
+if true: print 123
+ -- This is an indentation error since the single-line block is already consumed.
+ print 234
+Since blocks require at least one statement, use pass as a placeholder statement.
func foo():
+ pass
+Cyber supports dynamic and static typing. If you're used to a dynamic language such as Python, JavaScript, or Lua, use my to declare your variables and object fields. If you're used to a static language then use var instead. The documentation will use static typing by default.
Local variables exist until the end of their scope.
+They are declared and initialized using the var keyword:
var a = 123
+When declared without a type specifier next to the variable, it infers the type from the right initializer. +To declare variables for a specific type, see Typed variables.
+Variables can be set afterwards using the = operator:
a = 234
+Dynamically typed variables are easier to work with and there is no friction when using them. They are declared using the my keyword:
my a = 123
+To understand more about dynamically and statically typed code, see Type System.
+ +Blocks create a new variable scope. Variables declared in the current scope will take precedence over any parent variables with the same name:
+func foo():
+ var a = 234
+
+ if true:
+ var a = 345 -- New `a` declared.
+ print a -- Prints "345"
+
+ print a -- Prints "234"
+Static variables live until the end of the script. +They act as global variables and are visible from anywhere in the script.
+They are declared with var but a namespace must be provided before the variable name:
var Root.a = 123
+
+func foo():
+ print a -- '123'
+The Root symbol is used to reference the current module's namespace.
Since static variables are initialized outside of a fiber's execution flow, they can not reference any local variables:
+-- Static declaration.
+var Root.b = a -- Compile error, initializer can not reference a local variable.
+
+-- Main execution.
+var a = 123
+However, they can be reassigned after initialization:
+var Root.b = 0
+
+var a = 123
+b = a -- Reassigning after initializing.
+Static variable initializers have a natural order based on when it was encountered by the compiler. +In the case of imported variables, the order of the import would affect this order. +The following would print '123' before '234':
+var Root.a = print(123)
+var Root.b = print(234)
+When the initializers reference other static variables, those child references are initialized first in DFS order and supersede the natural ordering. The following initializes b before a.
var Root.a = b + 321
+var Root.b = 123
+
+print a -- '444'
+Circular references in initializers are not allowed. +When initialization encounters a reference that creates a circular dependency an error is reported.
+var Root.a = b
+var Root.b = a -- CompileError. Referencing `a` creates a circular dependency.
+Sometimes, you may want to initialize a static variable by executing multiple statements in order. +For this use case, you can use a declaration block. Planned Feature
+var Root.myImage =:
+ var img = loadImage('me.png')
+ img.resize(100, 100)
+ img.filter(.blur, 5)
+ break img
+The final resulting value that is assigned to the static variable is provided by a break statement. If a break statement is not provided, none is assigned instead.
There are 25 general keywords. This list categorizes them:
if else switch case while for break continue passor and notvar myfunc returncoinit coyield, coresumetype astry catch throwimportThese keywords only have meaning in a certain context.
+self, SelfcaughtobjectenumthrowsRoottrue falseerrornoneCyber supports the following operators. They are ordered from highest to lowest precedence.
+| Operator | Description |
|---|---|
<< >> | Bitwise left shift, right shift. |
& | Bitwise and. |
\| \|\| | Bitwise or, exclusive or. |
^ | Power. |
/ % * | Division, modulus, multiplication. |
+ - | Addition, subtraction. |
as | Type casting. |
> >= < <= != == | Greater, greater or equal, less, less or equal, not equals, equals. |
and | Logical and. |
or | Logical or. |
The following arithmetic operators are supported for the numeric data types.
+1 + 2 -- Addition, evaluates to 3.
+100 - 10 -- Subtraction, evaluates to 90.
+3 * 4 -- Multiplication, evaluates to 12.
+20 / 5 -- Division, evaluates to 4.
+2 ^ 4 -- Raise to the power, evaluates to 16.
+12 % 5 -- Modulus remainder, evaluates to 2.
+-(10) -- Apply negative, evaluates to -10.
+Cyber supports the following comparison operators. +By default, a comparison operator evaluates to a Boolean value.
+The equals operator returns true if the two values are equal. For primitive types, the comparison checks the types and the underlying value. For strings, the underlying bytes are compared for equality. For objects, the comparison checks that the two values reference the same object.
+1 == 1 -- Evaluates to `true`
+1 == 2 -- Evaluates to `false`
+1 == true -- Evaluates to `false`
+
+my a = 'abc'
+a == 'abc' -- Evaluates to `true`
+
+a = []
+my b = a
+a == b -- Evaluates to `true`
+a == [] -- Evaluates to `false`
+The not equals operator returns true if the two values are not equal.
+1 != 1 -- Evaluates to `false`
+1 != 2 -- Evaluates to `true`
+Number types have additional comparison operators.
+a > b -- `true` if a is greater than b
+a >= b -- `true` if a is greater than or equal to b
+a < b -- `true` if a is less than b
+a <= b -- `true` if a is less than or equal to b
+The logical operators and, or, and not are supported.
and evaluates to a if a is not truthy. Otherwise, it evaluates to b. If a is not truthy, the evaluation of b is not executed. A numeric value that isn't 0 is truthy. An object reference is always truthy. The none value is not truthy.
true and true -- Evaluates to true
+123 and 234 -- Evaluates to 234
+123 and 0 -- Evaluates to false
+or evaluates to a if a is truthy. Otherwise, it evaluates to b. If a is found to be truthy, the evaluation of b is not executed.
true or false -- Evaluates to true
+false or true -- Evaluates to true
+false or false -- Evaluates to false
+123 or false -- Evaluates to 123
+The unary operator not performs negation on the boolean value. The unary operator ! can also be used instead of not.
not false -- Evaluates to true
+not true -- Evaluates to false
+not 0 -- Evaluates to true
+not 123 -- Evaluates to false
+!false -- Evaluates to true
+!true -- Evaluates to false
+The following bitwise operators are supported for int number values.
-- Bitwise and: any underlying bits that are set in both integers are set in the new integer.
+a & b
+
+-- Bitwise or: any underlying bits that are set in either integer a or integer b are set in the new integer.
+a | b
+
+-- Bitwise exclusive or: any underlying bits that are set in either integer a or integer b but not both are set in the new integer.
+a || b
+
+-- Bitwise right shift: a's bits are shifted b bits to the least significant end. This performs sign-extension on the 32-bit integer.
+a >> b
+
+-- Bitwise left shift: a's bits are shifted b bits to the most significant end. This does not perform sign-extension on the 32-bit integer.
+a << b
+
+-- Bitwise not: a's integer bits are flipped.
+~a
+See Operator overloading in Metaprogramming.
+ +A single line comment starts with two hyphens and ends at the end of the line.
+-- This is a comment.
+
+var a = 123 -- This is a comment on the same line as a statement.
+There will be multi-line comments in Cyber but the syntax has not been determined.
+ +CYON or the Cyber object notation is similar to JSON. The format uses the same literal value semantics as Cyber.
+[
+ name: 'John Doe',
+ 'age': 25,
+ -- This is a comment
+ cities: [
+ 'New York',
+ 'San Francisco',
+ 'Tokyo',
+ ],
+]
+| + + | ++ + | +
In Cyber, there are primitive types and object types. Primitives are copied around by value and don't need additional heap memory or reference counts.
+Primitives include Booleans, Floats, Integers, Enums, Symbols, Error Values, and the none value.
Object types include Lists, Tuples, Maps, Strings, Arrays, User Objects, Lambdas, Fibers, Enums with payloads, Pointers, and several internal object types.
+The none value represents an empty value. This is similar to null in other languages.
Booleans can be true or false. See type bool.
var a = true
+if a:
+ print 'a is true'
+When other value types are coerced to the bool type, the truthy value is determined as follows.
+none value is false.true.int is the default integer type. It has 48-bits and can represent integers in the range -(247) to 247-1. See type int.
When a numeric literal is used and the type can not be inferred, it will default to the int type:
var a = 123
+Integer notations always produce a int value:
var a = 0xFF -- hex.
+a = 0o17 -- octal.
+a = 0b1010 -- binary.
+a = `🐶` -- UTF-8 rune.
+Arbitrary values can be converted to a int using the type as a function.
var a = '123'
+var b = int(a)
+In addition to arithmetic operations, integers can also perform bitwise operations.
+ +float is the default floating point type. It has a (IEEE 754) 64-bit floating point format. See type float.
Although a float represents a decimal number, it can also represent integers between -(253-1) and (253-1). Any integers beyond the safe integer range is not guaranteed to have a unique representation.
A numeric literal can be used to create a float if the inferred type is a float:
var a float = 123
+Decimal and scientific notations always produce a float value:
var a = 2.34567
+var b = 123.0e4
+Arbitrary values can be converted to a float using the type as a function.
var a = '12.3'
+var b = float(a)
++Planned Feature
+
The string type represents a sequence of UTF-8 codepoints, also known as runes. Each rune is stored internally as 1-4 bytes and can be represented as an int. See type string.
Under the hood, there are multiple string implementations to make operations faster by default.
+Strings are immutable, so operations that do string manipulation return a new string. By default, small strings are interned to reduce memory footprint.
+To mutate an existing string, use MutString. Planned Feature
+A string is always UTF-8 validated. Using an Array to represent raw bytes of a string is faster but you'll have to validate them and take care of indexing.
+A single line string literal is surrounded in single quotes.
+var apple = 'a fruit'
+You can escape the single quote inside the literal or use double quotes.
+var apple = 'Bob\'s fruit'
+apple = "Bob's fruit"
+Concatenate two strings together with the + operator or the method concat.
var res = 'abc' + 'xyz'
+res = res.concat('end')
+Strings are UTF-8 encoded.
+var str = 'abc🦊xyz🐶'
+Use double quotes to surround a multi-line string.
+var str = "line a
+line b
+line c"
+You can escape double quotes inside the literal or use triple quotes.
+var str = "line a
+line \"b\"
+line c"
+
+-- Using triple quotes.
+str = '''line a
+line "b"
+line c
+'''
+The following escape sequences are supported:
+| Escape Sequence | Code | Description |
|---|---|---|
| \a | 0x07 | Terminal bell. |
| \b | 0x08 | Backspace. |
| \e | 0x1b | Escape character. |
| \n | 0x0a | Line feed character. |
| \r | 0x0d | Carriage return character. |
| \t | 0x09 | Horizontal tab character. |
The boundary of each line can be set with a vertical line character. This makes it easier to see the whitespace. +Planned Feature
+var poem = "line a
+ | two spaces from the left
+ | indented further"
+Using the index operator will return the UTF-8 rune at the given index as a slice. This is equivalent to calling the method sliceAt().
var str = 'abcd'
+print str[1] -- "b"
+Using the slice operator will return a view of the string at the given start and end (exclusive) indexes. The start index defaults to 0 and the end index defaults to the string's length.
+var str = 'abcxyz'
+var sub = str[0..3]
+print sub -- "abc"
+print str[..5] -- "abcxy"
+print str[1..] -- "bcxyz"
+
+-- One way to use slices is to continue a string operation.
+str = 'abcabcabc'
+var i = str.findRune(`c`)
+print(i) -- "2"
+i += 1
+print(i + str[i..].findRune(`c`)) -- "5"
+Expressions can be embedded into string templates with $():
var name = 'Bob'
+var points = 123
+var str = 'Scoreboard: $(name) $(points)'
+String templates can not contain nested string templates.
+ +Values that can be formatted into a string will have a fmt method:
var file = os.openFile('data.bin', .read)
+var bytes = file.readToEnd()
+
+-- Dump contents in hex.
+print '$(bytes.fmt(.x))'
+An array is an immutable sequence of bytes. It can be used to represent strings but it won't automatically validate their encoding and indexing returns the n'th byte rather than a UTF-8 rune. See type array.
var a = array('abcd')
+a = a.insertByte(1, 255)
+print a[0] -- "97"
+print a[1] -- "255"
+Bracket literals are delimited with brackets []. They are used to initialize Lists, Maps, and Objects:
var list = [1, 2, 3]
+var map = [ a: 123, b: 234 ]
+var obj = [MyObject a: 123, b: 234]
+Lists are a builtin type that holds an ordered collection of elements. Lists grow or shrink as you insert or remove elements. See type List.
-- Construct a new list.
+var list = [1, 2, 3]
+
+-- The first element of the list starts at index 0.
+print list[0] -- Prints '1'
+Lists can be sliced with the range .. clause. The sliced list becomes a new list that you can modify without affecting the original list. The end index is non-inclusive.
var list = [ 1, 2, 3, 4, 5 ]
+list[0..0] -- []
+list[0..3] -- [ 1, 2, 3 ]
+list[3..] -- [ 4, 5 ]
+list[..3] -- [ 1, 2, 3 ]
+The +.. invokes the slice operator with an end position that is an increment from the start: Planned Feature
var list = [ 1, 2, 3, 4, 5 ]
+list[2+..2] -- [ 3, 4 ]
+List operations.
+var list = [234]
+
+-- Append a value.
+list.append 123
+
+-- Inserting a value at an index.
+list.insert(1, 345)
+
+-- Get the length.
+print list.len() -- Prints '2'
+
+-- Sort the list in place.
+list.sort((a, b) => a < b)
+
+-- Iterating a list.
+for list -> it:
+ print it
+
+-- Remove an element at a specific index.
+list.remove(1)
++Incomplete: Tuples can only be created from @host funcs at the moment.
+
Maps are a builtin type that store key value pairs in dictionaries. See type Map.
Create a map using key value pairs inside a collection literal:
+var map = [ a: 123, b: () => 5 ]
+Maps entries can be listed in multiple lines:
+var map = [
+ foo: 1,
+ bar: 2,
+]
+The empty map is initialized using [:]:
var empty = [:]
+Get a value from the map using the index operator:
+print map['a']
+Maps can be accessed with the . dot operator as well:
print map.a
+var map = [:]
+
+-- Set a key value pair.
+map[123] = 234
+
+-- Get the size of the map.
+print map.size()
+
+-- Remove an entry by key.
+map.remove 123
+
+-- Iterating a map.
+for map -> [val, key]:
+ print '$(key) -> $(val)'
+Entries can also follow a collection literal block. +This gives structure to the entries and has +the added benefit of allowing multi-line lambdas. +Planned Feature
+var colors = []:
+ red: 0xFF0000
+ green: 0x00FF00
+ blue: 0x0000FF
+ dump func (c):
+ print c.red
+ print c.green
+ print c.blue
+
+ -- Nested map.
+ darker []:
+ red: 0xAA0000
+ green: 0x00AA00
+ blue: 0x0000AA
+Any value that isn't a primitive is an object. You can declare your own object types using the type object declaration.
+Object types are similar to structs and classes in other languages.
+Unlike classes, there is no concept of inheritance at the language level.
Fields must be declared at the top of the type object block using var or my:
type Node object:
+ var value int
+ var next any
+When fields are declared with my instead, they become dynamically typed.
New object instances are created using a leading type name and the field values in a collection literal:
+var node = [Node value: 123, next: none]
+print node.value -- Prints "123"
+Methods allow invoking a function on an object instance using the . operator:
type Node object:
+ var value int
+ var next any
+
+ func inc(n):
+ value += n
+
+ func incAndPrint():
+ self.inc(321)
+ print value
+
+var n = [Node value: 123, next: none]
+n.incAndPrint() -- Prints "444"
+Methods can also be declared outside of the type declaration. To distinguish a method from a type function, self must be provided as a parameter:
func Node.getNext(self):
+ return self.next
+self variable. #Type members can be implicitly referenced inside the method. Incomplete: Only the type's fields can be referenced this way.
+To reference members explicitly inside a method, use the builtin self:
type Node object:
+ var value int
+ var next any
+
+ func double():
+ return self.value * 2
+Type functions are declared outside of the type block with an explicit namespace path:
type Node object:
+ var value int
+ var next any
+
+-- Declare namespace function inside `Node`.
+func Node.new():
+ return [Node value: 123, next: none]
+
+var n = Node.new()
+Similarily, type variables are declared outside of the type block:
-- Declare inside the `Node` namespace.
+var Node.DefaultValue = 100
+
+print Node.DefaultValue -- Prints "100"
+A new enum type can be declared with the type enum declaration.
+An enum value can only be one of the unique symbols declared in the enum type.
+By default, the symbols generate unique ids starting from 0.
type Fruit enum:
+ case apple
+ case orange
+ case banana
+ case kiwi
+
+var fruit = Fruit.kiwi
+print fruit -- 'Fruit.kiwi'
+print int(fruit) -- '3'
+When the type of the value is known to be an enum, it can be assigned using a symbol literal.
+var fruit = Fruit.kiwi
+fruit = .orange
+print(fruit == Fruit.orange) -- 'true'
+Symbol literals begin with ., followed by an identifier. They have their own global unique id.
var currency = .usd
+print(currency == .usd) -- 'true'
+print int(currency) -- '123' or some arbitrary id.
+| + + | + + | +
Cyber provides the common constructs to branch and enter loops.
+if statement. #Use if and else statements to branch the execution of your code depending on conditions. The else clause can contain a condition which is only evaluated if the previous if or conditional else clause was false.
var a = 10
+if a == 10:
+ print 'a is 10'
+else a == 20:
+ print 'a is 20'
+else:
+ print 'neither 10 nor 20'
+A conditional branch expression evaluates a condition and returns either the true value or false value:
+var a = 10
+var str = a == 10 ? 'red' else 'blue'
+and/or #Use and and or logical operators to combine conditions:
var a = 10
+if a > 5 and a < 15:
+ print 'a is between 5 and 15'
+if a == 20 or a == 10:
+ print 'a is 10 or 20'
+The while keyword starts an infinite loop which continues to run the code in the block until a break or return is reached.
var count = 0
+while:
+ if count > 100:
+ break
+ count += 1
+When the while clause contains a condition, the loop continues to run until the condition is evaluated to false:
var running = true
+var count = 0
+while running:
+ if count > 100:
+ running = false
+ count += 1
+Using the capture operator -> unwraps the left optional value to the right variable declaration. The loop exits when the left value is none:
var iter = dir.walk()
+while iter.next() -> entry:
+ print entry.name
+for range. #for loops can iterate over a range that starts at an int (inclusive) to a target int (exclusive).
+The capture operator -> is used to capture the loop's counter variable:
for 0..4:
+ performAction()
+
+for 0..100 -> i:
+ print i -- 0, 1, 2, ... , 99
+To decrement the counter instead, use -..:
for 100-..0 -> i:
+ print i -- 100, 99, 98, ... , 1
+When the range operator .. is replaced with ..=, the target int is inclusive: Planned Feature
for 0..=100 -> i:
+ print i -- 0, 1, 2, ... , 100
+for each. #The for clause can iterate over any type that implements the Iterable trait. An Iterable contains an iterator() method which returns an Iterator object. The for loop continually invokes the Iterator's next() method until none is returned.
Lists can be iterated since they implement the Iterable trait. The capture operator -> is used to capture the value returned from an iterator's next():
var list = [1, 2, 3, 4, 5]
+
+for list -> n:
+ print n
+Maps can be iterated. next() returns a key and value tuple:
var map = [ a: 123, b: 234 ]
+
+for map -> entry:
+ print entry[0]
+ print entry[1]
+Use the destructure syntax to extract the key and value into two separate variables:
+for map -> [ key, val ]:
+ print 'key $(key) -> value $(val)'
+for each with index. #A counting index can be declared after the each variable. The count starts at 0 for the first value:
+var list = [1, 2, 3, 4, 5]
+
+for list -> val, i:
+ print 'index $(i), value $(val)'
+Use break to exit a loop. This loop stops printing once i reaches 4:
for 0..10 -> i:
+ if i == 4:
+ break
+ print i
+Use continue to skip the rest of the loop and go to the next iteration.
+This loop prints 0 through 9 but skips 4:
for 0..10 -> i:
+ if i == 4:
+ continue
+ print i
+switch matching. #The switch statement branches to a case block from a matching case condition. The expression that is matched against comes after switch statement. Multiple cases can be grouped together using a comma separator. An optional else fallback case is executed when no other cases were matched.
+Incomplete: Not all types can be used in the case conditions such as ranges.
var val = 1000
+switch val:
+case 0..100: print 'at or between 0 and 99'
+case 100 : print 'val is 100'
+case 200:
+ print 'val is 200'
+case 300, 400:
+ print 'combined case'
+else:
+ print 'val is $(val)'
+Note that the switch block must be empty and requires at least one case block or an else block to come after it.
switch assignment. #Although switch can not be used freely as an expression, it can be assigned to a left variable or destination:
var shu = switch pepper:
+case 'bell' => 0
+case 'anaheim' => 500
+case 'jalapeño' => 2000
+case 'serrano' => 10000
+When declaring an assignable switch, the cases must have a return value using the syntax case {cond} => {expr} or else => {expr}.
switch break. #A break statement exits the current case block and resumes execution after the end of the switch statement: Planned Feature
switch value:
+case 0..5:
+ print value
+ if value == 3:
+ break case
+ print value -- Skips second print if `value` is 3.
+The try catch statement, try else and try expressions provide a way to catch a throwing error and resume execution in a different branch. Learn more about Error Handling.
+Planned Feature
+
In Cyber, there are first-class functions (or function values) and static functions.
+Static functions are not initially values themselves. They allow function calls to be optimal since they don't need to resolve a dynamic value.
+Static functions are declared with the func keyword and must have a name.
import math
+
+func dist(x0 float, y0 float, x1 float, y1 float) float:
+ var dx = x0-x1
+ var dy = y0-y1
+ return math.sqrt(dx^2 + dy^2)
+Calling static functions is straightforward. You can also reassign or pass them around as function values.
+print dist(0, 0, 10, 20)
+
+-- Assigning to a local variable.
+var bar = dist
+
+-- Passing `dist` as an argument.
+func squareDist(dist, size):
+ return dist(0.0, 0.0, size, size)
+
+print squareDist(dist, 30.0)
+Functions can only return one value. However, the value can be destructured: Planned Feature
+import {cos, sin} 'math'
+
+func compute(rad):
+ return [ cos(rad), sin(rad) ]
+
+var [ x, y ] = compute(pi)
+Functions can be overloaded by the number of parameters in its signature. Typed functions are further overloaded by their type signatures.
+func foo():
+ return 2 + 2
+
+func foo(n):
+ return 10 + n
+
+func foo(n, m):
+ return n * m
+
+print foo() -- "4"
+print foo(2) -- "12"
+print foo(20, 5) -- "100"
+Lambdas or function values can be assigned to variables or passed as arguments into other constructs.
+When a lambda only returns an expression, it can be declared with a simplified syntax.
+-- Passing simple lambda as an argument.
+foo(word => toUpper(word))
+
+-- A simple lambda with multiple arguments.
+foo((word, prefix) => prefix + toUpper(word))
+
+-- Assigning a simple lambda.
+canvas.onUpdate = delta_ms => print delta_ms
+Lambdas that need a block of statements can be declared with the func keyword without a name.
-- Assigning lambda block to a variable.
+var add = func (a, b):
+ return a + b
+
+-- Passing a lambda block as an argument.
+canvas.onUpdate():
+ ..func (delta_ms):
+ print delta_ms
+Passing a lambda block as a call argument is only possible in a call block. Planned Feature See Function calls.
+ +Lambdas can capture local variables from parent blocks. This example shows the lambda f capturing a from the main scope: Incomplete, only variables one parent block away can be captured.
var a = 1
+var f = func():
+ return a + 2
+print f() -- "3"
+The following lambda expression captures a from the function add:
func add():
+ var a = 123
+ return b => a + b
+var addTo = add()
+print addTo(10) -- "133"
+Like static variables, static functions can not reference local variables outside of their scope:
+var a = 1
+func foo():
+ print a -- CompileError: Undeclared variable `a`.
++Planned Feature
+
+Planned Feature
+
+Planned Feature
+
The straightforward way to call a function is to use parentheses.
+var d = dist(100, 100, 200, 200)
+You can call functions with named parameters.
+Planned Feature
+
var d = dist(x0: 10, x1: 20, y0: 30, y1: 40)
+The shorthand method for calling functions omits parentheses and commas. This only works for functions that accept parameters:
+Incomplete: Only the most trivial cases work with the shorthand method. The case with operators being separated by spaces might not end up being implemented.
+
var d = dist 100 100 200 200 -- Calls the function `dist`.
+
+func random(): -- Function with no parameters.
+ return 4
+
+var r = random -- Returns the function itself as a value.
+ -- Does not call the function `random`.
+r = random() -- Calls the function `random`.
+The top level arguments for the shorthand convention must be separated by whitespace. A string can contain whitespace since it's surrounded by delimiters.
+var a = myFunc 'cyber script'
+The following has a binary expression with spaces inbetween which is not allowed. Removing that whitespace fixes the call expression.
+var a = myFunc 1 + 2 -- Not allowed.
+a = myFunc 1+2 -- Correct.
+Wrapping arguments in parentheses allows you to keep the whitespace in the sub-expression.
+-- This calls the function `myFunc` with 2 arguments.
+var a = myFunc 'hello' (1 + 2 * 3)
+
+-- Nested function call using the shorthand convention.
+a = myFunc 'hello' (otherFunc 1+2 'world')
+The call expression block continues to add arguments from the block's body. If arguments are omitted from the initial call expression they can be added inside using the .. syntax. Arguments mapped to named parameters have a key value syntax separated by a :. All other arguments are added into a list and passed as the last argument.
Planned Feature
+
foo(123):
+ ..func ():
+ return 123
+ param3: 123
+ 234
+ bar()
+ 'hello'
+In the example above, the function foo is called with 4 arguments. The first argument 123 is included in the starting call expression. The second argument is a function value inside the call expression block. The third argument is mapped to the param param3. Finally, the fourth argument is a list that contains 234, bar(), and 'hello'.
| + + | + + | +
Modules have their own namespace and contain accessible static symbols. By default, importing another Cyber script returns a module with its declared symbols.
+Import declarations create a local alias to the module referenced by the import specifier. The Cyber CLI comes with some builtin modules like math and test. If the specifier does not refer to a builtin module, it looks for a Cyber script file relative to the current script's directory. An embedder can integrate their own module loader and resolver.
import test
+test.eq(123, 123)
+
+-- Imports are static declarations so they can be anywhere in the script.
+import math
+print math.cos(0)
+When the imported alias needs to be renamed, the import specifier comes after the alias name and must be a string literal.
+import m 'math'
+print m.random()
+
+-- Loading a Cyber module from the local directory.
+import foo 'bar.cy'
+print foo.myFunc()
+print foo.myVar
+A Cyber script that is imported doesn't evaluate its main block. Only static declarations are effectively loaded. If there is code in the main block, it will skip evaluation. In the following, only the print statement in the main.cy is evaluated.
-- main.cy
+import a 'foo.cy'
+print a.foo
+
+-- foo.cy
+import 'bar.cy'
+var Root.foo = 123
+print foo -- Statement is ignored.
+
+-- bar.cy
+var Root.bar = 321
+print bar -- Statement is ignored.
+You can have circular imports in Cyber. In the following example, main.cy and foo.cy import each other without any problems.
-- main.cy
+import foo 'foo.cy'
+
+func printB():
+ foo.printC()
+
+foo.printA()
+
+-- foo.cy
+import main 'main.cy'
+
+func printA():
+ main.printB()
+
+func printC():
+ print 'done'
+Static variable declarations from imports can have circular references. Read more about this in Static Variables.
+Modules can also be destructured using the following syntax:
+Planned Feature
+
import { cos, pi } 'math'
+print cos(pi)
+All static declarations are exported when the script's module is loaded.
+func foo(): -- Exported static function.
+ print 123
+
+var Root.bar = 234 -- Exported static variable.
+
+type Thing object: -- Exported type.
+ var a float
+To get the absolute path of the current module, reference the compile-time variable ModUri.
+This can be used with os.dirName to get the current module directory.
print #ModUri -- Prints '/some/path/foo.cy'
+
+import os
+print os.dirName(#ModUri) -- Prints '/some/path'
+The annotation @hide provides a hint to editors that a static symbol should not appear in the auto-complete. Despite this, the symbol is still reachable.
Builtin modules are the bare minimum that comes with Cyber. The embeddable library contains these modules and nothing more. They include:
+The builtins module contains functions related to Cyber and common utilities. It is automatically imported into each script's namespace.
Sample usage:
+-- `print` and `typeof` are available without imports.
+print 'hello'
+print typeof('my str').id()
++
func copy(val any) anyCopies a primitive value or creates a shallow copy of an object value.
+
+
func dump(val any) nonePrints the result of
+toCyonon a value.
+
func errorReport() string
+
func getObjectRc(val any) intReturns the current reference count of an object.
+
+
func is(a any, b any) boolReturns whether two values refer to the same instance.
+
+
func isAlpha(val int) boolReturns whether a rune is an alphabetic letter.
+
+
func isDigit(val int) boolReturns whether a rune is a digit.
+
+
func must(val any) anyIf
+valis an error,panic(val)is invoked. Otherwise,valis returned.
+
func panic(err any) noneStop execution in the current fiber and starts unwinding the call stack. See Unexpected Errors.
+
+
func parseCyber(src string) MapParses Cyber source string into structured map object. Currently, only metadata about static declarations is made available but this will be extended to include an AST.
+
+
func parseCyon(src string) anyParses a CYON string into a value.
+
+
func performGC() MapRuns the garbage collector once to detect reference cycles and abandoned objects. Returns the statistics of the run in a map value.
+
+
func print(str any) nonePrints a value. The host determines how it is printed.
+
+
func runestr(val int) stringConverts a rune to a string.
+
+
func toCyon(val any) stringEncodes a value to CYON string.
+
+
func typeof(val any) metatypeReturns the value's type as a
+metatypeobject.
+
func typesym(val any) symbolReturns the value's type as one of the predefined symbols: .float, .int, .bool, .object, .list, .map, .string, .array, .function, .fiber, .pointer, .symbol, .metatype, .none, .error
+
type bool #+
func bool.'$call'(val any) boolConverts a value to either
+trueorfalse.
type error #+
func sym() symbolReturn the underlying
+symbol.
+
func error.'$call'(val any) errorCreate an error from an enum or symbol.
+
type int #+
func $prefix~() int
+
func $prefix-() int
+
func $infix<(o any) bool
+
func $infix<=(o any) bool
+
func $infix>(o any) bool
+
func $infix>=(o any) bool
+
func $infix+(o any) int
+
func $infix-(o any) int
+
func $infix*(o any) int
+
func $infix/(o any) int
+
func $infix%(o any) int
+
func $infix^(o any) int
+
func $infix&(o any) int
+
func $infix|(o any) int
+
func $infix||(o any) int
+
func $infix<<(o any) int
+
func $infix>>(o any) int
+
func fmt(kind symbol) stringFormats the integer using a kind specifier which can be binary
+.b, octal.o, decimal.d, hexadecimal.x, ASCII.c.
+
func fmt(kind symbol, opts Map) string+
opts.padprovides the ASCII rune that is used for padding with a string length ofopts.width.
+
func int.'$call'(val any) intConverts a value to an 48-bit integer.
+
type float #+
func $prefix-() float
+
func $infix<(o any) bool
+
func $infix<=(o any) bool
+
func $infix>(o any) bool
+
func $infix>=(o any) bool
+
func $infix+(o any) float
+
func $infix-(o any) float
+
func $infix*(o any) float
+
func $infix/(o any) float
+
func $infix%(o any) float
+
func $infix^(o any) float
+
func float.'$call'(val any) floatConverts the value to a
+float. Panics if type conversion fails.
type List #+
func $index(idx any) any
+
func $setIndex(idx any, val any) none
+
func $slice(start any, end any) List
+
func append(val any) noneAppends a value to the end of the list.
+
+
func concat(list List) noneConcats the elements of another list to the end of this list.
+
+
func insert(idx int, val any) noneInserts a value at index
+idx.
+
func iterator() ListIteratorReturns a new iterator over the list elements.
+
+
func join(sep string) stringReturns a new string that joins the elements with
+separator.
+
func len() intReturns the number of elements in the list.
+
+
func remove(idx int) noneRemoves an element at index
+idx.
+
func resize(size int) noneResizes the list to
+lenelements. If the new size is bigger,nonevalues are appended to the list. If the new size is smaller, elements at the end of the list are removed.
+
func slice(start any, end any) List
+
func List.fill(val any, n int) ListCreates a list with initial capacity of
+nand values set toval. If the value is an object, it is shallow copiedntimes.
type ListIterator #+
func next() any
type tuple #+
func $index(idx int) any
type Map #+
func $index(key any) any
+
func $setIndex(key any, val any) none
+
func remove(key any) noneRemoves the element with the given key
+key.
+
func size() intReturns the number of key-value pairs in the map.
+
+
func iterator() MapIteratorReturns a new iterator over the map elements.
+
type MapIterator #+
func next() any
type string #+
func $infix+(o any) string
+
func concat(o string) stringReturns a new string that concats this string and
+str.
+
func endsWith(suffix string) boolReturns whether the string ends with
+suffix.
+
func find(needle string) anyReturns the first index of substring
+needlein the string ornoneif not found. SIMD enabled.
+
func findAnyRune(runes string) anyReturns the first index of any UTF-8 rune in
+runesornoneif not found. SIMD enabled.
+
func findRune(rune int) intReturns the first index of UTF-8 rune
+needlein the string ornoneif not found. SIMD enabled.
+
func insert(idx int, str string) stringReturns a new string with
+strinserted at indexidx.
+
func isAscii() boolReturns whether the string contains all ASCII runes.
+
+
func len() intReturns the number of UTF-8 runes in the string.
+
+
func less(other string) boolReturns whether this string is lexicographically before
+other.
+
func lower() stringReturns this string in lowercase.
+
+
func replace(needle string, replacement string) stringReturns a new string with all occurrences of
+needlereplaced withreplacement.
+
func repeat(n int) stringReturns a new string with this string repeated
+ntimes.
+
func runeAt(n int) intReturns the UTF-8 rune at index
+idx.
+
func slice(start any, end any) stringReturns a slice into this string from
+starttoend(exclusive) indexes. This is equivalent to using the slice index operator[start..end].
+
func $slice(start any, end any) string
+
func sliceAt(idx int) stringReturns the UTF-8 rune at index
+idxas a single rune string.
+
func $index(idx int) string
+
func split(sep string) ListReturns a list of UTF-8 strings split at occurrences of
+sep.
+
func startsWith(prefix string) boolReturns whether the string starts with
+prefix.
+
func trim(mode symbol, delims string) stringReturns the string with ends trimmed from runes in
+delims.modecan be .left, .right, or .ends.
+
func upper() stringReturns this string in uppercase.
+
+
func string.'$call'(val any) stringConverts a value to a string.
+
type array #+
func $infix+(o any) array
+
func concat(other array) arrayReturns a new array that concats this array and
+other.
+
func decode() stringCalls decode(.utf8)
+
+
func decode(encoding symbol) stringDecodes the array based on an
+encoding. Supported encodings:.utf8. Returns the decoded string or throwserror.Decode.
+
func endsWith(suffix array) boolReturns whether the array ends with
+suffix.
+
func find(needle array) anyReturns the first index of
+needlein the array ornoneif not found.
+
func findAnyByte(bytes array) anyReturns the first index of any
+bytesinarraysornoneif not found.
+
func findByte(byte int) anyReturns the first index of
+bytein the array ornoneif not found.
+
func fmt(kind symbol) stringFormats each byte in the array using a kind specifier which can be binary
+.b, octal.o, decimal.d, hexadecimal.x, ASCII.c. Each byte is zero padded.
+
func getByte(idx int) intReturns the byte value (0-255) at the given index
+idx.
+
func getInt(idx int, endian symbol) intReturns the int value of the 6 bytes starting from
+idxwith the given endianness (.little or .big).
+
func getInt32(idx int, endian symbol) intReturns the int value of the 4 bytes starting from
+idxwith the given endianness (.little or .big).
+
func insert(idx int, arr array) arrayReturns a new array with
+arrinserted at indexidx.
+
func insertByte(idx int, byte int) arrayReturns a new array with
+byteinserted at indexidx.
+
func len() intReturns the number of bytes in the array.
+
+
func repeat(n int) arrayReturns a new array with this array repeated
+ntimes.
+
func replace(needle array, replacement array) arrayReturns a new array with all occurrences of
+needlereplaced withreplacement.
+
func slice(start any, end any) arrayReturns a slice into this array from
+starttoend(exclusive) indexes. This is equivalent to using the slice index operator[start..end].
+
func $slice(start any, end any) array
+
func $index(idx int) int
+
func split(sep array) ListReturns a list of arrays split at occurrences of
+sep.
+
func startsWith(prefix array) boolReturns whether the array starts with
+prefix.
+
func trim(mode symbol, delims array) arrayReturns the array with ends trimmed from runes in
+delims.modecan be .left, .right, or .ends.
+
func array.'$call'(val any) arrayConverts a string to an byte
+array.
type arrayIterator #type pointer #+
func addr() intReturns the memory address as an
+int. The value may be negative since it's bitcasted from an unsigned 48-bit integer but it retains the original pointer bits.
+
func asObject() anyUnsafe. Casts the pointer to a Cyber object. The object is retained before it's returned.
+
+
func fromCstr(offset int) arrayUnsafe. Returns an
+arrayfrom a null terminated C string.
+
func get(offset int, ctype symbol) anyUnsafe. Dereferences the pointer at a byte offset and returns the C value converted to Cyber.
+
+
func set(offset int, ctype symbol, val any) noneUnsafe. Converts the value to a compatible C value and writes it to a byte offset from this pointer.
+
+
func toArray(offset int, len int) arrayUnsafe. Returns an
+arraywith a copy of the byte data starting from an offset to the specified length.
+
func pointer.'$call'(val any) pointerConverts a
+intto apointervalue, or casts to apointer. This is usually used with FFI.
type ExternFunc #+
func addr() intReturns the memory address as an
+int. The value may be negative since it's bitcasted from an unsigned 48-bit integer but it retains the original pointer bits.
type Fiber #+
func status() symbol
type metatype #++
func id() int
The math module contains commonly used math constants and functions.
+Sample usage:
+import math
+
+var r = 10.0
+print(math.pi * r^2)
++
var e floatEuler's number and the base of natural logarithms; approximately 2.718.
+
+
var inf floatInfinity.
+
+
var log10e floatBase-10 logarithm of E; approximately 0.434.
+
+
var log2e floatBase-2 logarithm of E; approximately 1.443.
+
+
var ln10 floatNatural logarithm of 10; approximately 2.303.
+
+
var ln2 floatNatural logarithm of 2; approximately 0.693.
+
+
var maxSafeInt floatThe maximum integer value that can be safely represented as a float. 2^53-1 or 9007199254740991.
+
+
var minSafeInt floatThe minumum integer value that can be safely represented as a float. -(2^53-1) or -9007199254740991.
+
+
var nan floatNot a number. Note that nan == nan. However, if a nan came from an arithmetic operation, the comparison is undefined. Use
+isNaNinstead.
+
var neginf floatNegative infinity.
+
+
var pi floatRatio of a circle's circumference to its diameter; approximately 3.14159.
+
+
var sqrt1_2 floatSquare root of ½; approximately 0.707.
+
+
var sqrt2 floatSquare root of 2; approximately 1.414.
+
+
func abs(a float) floatReturns the absolute value of x.
+
+
func acos(a float) floatReturns the arccosine of x.
+
+
func acosh(a float) floatReturns the hyperbolic arccosine of x.
+
+
func asin(a float) floatReturns the arcsine of x.
+
+
func asinh(a float) floatReturns the hyperbolic arcsine of a number.
+
+
func atan(a float) floatReturns the arctangent of x.
+
+
func atan2(a float, b float) floatReturns the arctangent of the quotient of its arguments.
+
+
func atanh(a float) floatReturns the hyperbolic arctangent of x.
+
+
func cbrt(a float) floatReturns the cube root of x.
+
+
func ceil(a float) floatReturns the smallest integer greater than or equal to x.
+
+
func clz32(a float) floatReturns the number of leading zero bits of the 32-bit integer x.
+
+
func cos(a float) floatReturns the cosine of x.
+
+
func cosh(a float) floatReturns the hyperbolic cosine of x.
+
+
func exp(a float) floatReturns e^x, where x is the argument, and e is Euler's number (2.718…, the base of the natural logarithm).
+
+
func expm1(a float) floatReturns subtracting 1 from exp(x).
+
+
func floor(a float) floatReturns the largest integer less than or equal to x.
+
+
func frac(a float) floatReturns the fractional or decimal part of a float value.
+
+
func hypot(a float, b float) floatReturns the square root of the sum of squares of its arguments.
+
+
func isInt(a float) boolReturns true if the float has no fractional part, otherwise false.
+
+
func isNaN(a float) boolReturns whether x is not a number.
+
+
func ln(a float) floatReturns the natural logarithm (㏒e; also, ㏑) of x.
+
+
func log(a float, b float) floatReturns the logarithm of y with base x.
+
+
func log10(a float) floatReturns the base-10 logarithm of x.
+
+
func log1p(a float) floatReturns the natural logarithm (㏒e; also ㏑) of 1 + x for the number x.
+
+
func log2(a float) floatReturns the base-2 logarithm of x.
+
+
func max(a float, b float) floatReturns the largest of two numbers.
+
+
func min(a float, b float) floatReturns the smallest of two numbers.
+
+
func mul32(a float, b float) floatReturns the result of the 32-bit integer multiplication of x and y. Integer overflow is allowed.
+
+
func pow(a float, b float) floatReturns base x to the exponent power y (that is, x^y).
+
+
func random() floatReturns a pseudo-random number between 0 and 1.
+
+
func round(a float) floatReturns the value of the number x rounded to the nearest integer.
+
+
func sign(a float) floatReturns the sign of the x, indicating whether x is positive, negative, or zero.
+
+
func sin(a float) floatReturns the sine of x.
+
+
func sinh(a float) floatReturns the hyperbolic sine of x.
+
+
func sqrt(a float) floatReturns the positive square root of x.
+
+
func tan(a float) floatReturns the tangent of x.
+
+
func tanh(a float) floatReturns the hyperbolic tangent of x.
+
++
func trunc(a float) floatReturns the integer portion of x, removing any fractional digits.
+
Std modules come with Cyber's CLI. They include:
+ + +Cyber's os module contains system level functions. It's still undecided as to how much should be included here so it's incomplete. You can still access os and libc functions yourself using Cyber's FFI or embedding API.
+Sample usage:
+import os
+
+var map = os.getEnvAll()
+for map -> [k, v]:
+ print '$(k) -> $(v)'
++
var cpu stringThe current cpu arch's tag name.
+
+
var endian symbolThe current arch's endianness: .little, .big
+
+
var stderr FileStandard error file descriptor.
+
+
var stdin FileStandard input file descriptor.
+
+
var stdout FileStandard output file descriptor.
+
+
var system stringThe current operating system's tag name.
+
+
var vecBitSize intDefault SIMD vector bit size.
+
+
func access(path string, mode symbol) noneAttempts to access a file at the given
+pathwith the.read,.write, or.readWritemode. Throws an error if unsuccessful.
+
func args() ListReturns the command line arguments in a
+List. Each argument is converted to astring.
+
func cacheUrl(url string) stringReturns the path of a locally cached file of
+url. If no such file exists locally, it's fetched fromurl.
+
func copyFile(srcPath string, dstPath string) noneCopies a file to a destination path.
+
+
func createDir(path string) noneCreates the directory at
+path. Returnstrueif successful.
+
func createFile(path string, truncate bool) FileCreates and opens the file at
+path. Iftruncateis true, an existing file will be truncated.
+
func cstr(s any) pointerReturns a null terminated C string.
+
+
func cwd() stringReturns the current working directory.
+
+
func dirName(path string) stringReturns the given path with its last component removed.
+
+
func execCmd(args List) MapRuns a shell command and returns the stdout/stderr.
+
+
func exePath() stringReturns the current executable's path.
+
+
func exit(status int) noneExits the program with a status code.
+
+
func fetchUrl(url string) arrayFetches the contents at
+urlusing the HTTP GET request method.
+
func free(ptr pointer) noneFrees the memory located at
+ptr.
+
func getEnv(key string) stringReturns an environment variable by key.
+
+
func getEnvAll() MapReturns all environment variables as a
+Map.
+
func malloc(size int) pointerAllocates
+sizebytes of memory and returns a pointer.
+
func milliTime() floatReturn the calendar timestamp, in milliseconds, relative to UTC 1970-01-01. For an high resolution timestamp, use
+now().
+
func newFFI() FFIReturns a new FFI context for declaring C mappings and binding a dynamic library.
+
+
func now() floatReturns the current time (in high resolution seconds) since an arbitrary point in time.
+
+
func openDir(path string) DirInvokes
+openDir(path, false).
+
func openDir(path string, iterable bool) DirOpens a directory at the given
+path.iterableindicates that the directory's entries can be iterated.
+
func openFile(path string, mode symbol) FileOpens a file at the given
+pathwith the.read,.write, or.readWritemode.
+
func parseArgs(options List) MapGiven expected
+ArgOptions, returns a map of the options and arestentry which contains the non-option arguments.
+
func readAll() stringReads stdin to the EOF as a UTF-8 string. To return the bytes instead, use
+stdin.readAll().
+
func readFile(path string) stringReads the file contents from
+pathas a UTF-8 string. To return the bytes instead, useFile.readAll().
+
func readLine() stringReads stdin until a new line as a
+string. This is intended to read user input from the command line. For bulk reads from stdin, usestdin.
+
func realPath(path string) stringReturns the absolute path of the given path.
+
+
func removeDir(path string) noneRemoves an empty directory at
+path. Returnstrueif successful.
+
func removeFile(path string) noneRemoves the file at
+path. Returnstrueif successful.
+
func setEnv(key string, val string) noneSets an environment variable by key.
+
+
func sleep(ms float) nonePauses the current thread for given milliseconds.
+
+
func unsetEnv(key string) noneRemoves an environment variable by key.
+
+
func writeFile(path string, contents any) noneWrites
+contentsas a string or bytes to a file.
type File #+
func close() noneCloses the file handle. File ops invoked afterwards will return
+error.Closed.
+
func iterator() any
+
func next() any
+
func read(n int) arrayReads at most
+nbytes as anarray.nmust be at least 1. A result with length 0 indicates the end of file was reached.
+
func readAll() arrayReads to the end of the file and returns the content as an
+array.
+
func seek(n int) noneSeeks the read/write position to
+posbytes from the start. Negativeposis invalid.
+
func seekFromCur(n int) noneSeeks the read/write position by
+posbytes from the current position.
+
func seekFromEnd(n int) noneSeeks the read/write position by
+posbytes from the end. Positiveposis invalid.
+
func stat() MapReturns info about the file as a
+Map.
+
func streamLines() FileEquivalent to
+streamLines(4096).
+
func streamLines(bufSize int) FileReturns an iterable that streams lines ending in
+\n,\r,\r\n, or theEOF. The lines returned include the new line character(s). A buffer size ofbufSizebytes is allocated for reading. If\ris found at the end of the read buffer, the line is returned instead of waiting to see if the next read has a connecting\n.
+
func write(val any) intWrites a
+stringorarrayat the current file position. The number of bytes written is returned.
type Dir #+
func iterator() DirIteratorReturns a new iterator over the directory entries. If this directory was not opened with the iterable flag,
+error.NotAllowedis returned instead.
+
func stat() MapReturns info about the file as a
+Map.
+
func walk() DirIteratorReturns a new iterator over the directory recursive entries. If this directory was not opened with the iterable flag,
+error.NotAllowedis returned instead.
type DirIterator #+
func next() any
type FFI #+
func bindCallback(fn any, params List, ret symbol) ExternFuncCreates an
+ExternFuncthat contains a C function pointer with the given signature. The extern function is a wrapper that calls the provided user function. Once created, the extern function is retained and managed by the FFI context.
+
func bindLib(path any) anyCalls
+bindLib(path, [:]).
+
func bindLib(path any, config Map) anyCreates a handle to a dynamic library and functions declared from
+cfunc. By default, an anonymous object is returned with the C-functions binded as the object's methods. IfconfigcontainsgenMap: true, aMapis returned instead with C-functions binded as function values.
+
func bindObjPtr(obj any) pointerReturns a Cyber object's pointer. Operations on the pointer is unsafe, but it can be useful when passing it to C as an opaque pointer. The object is also retained and managed by the FFI context.
+
+
func cbind(mt metatype, fields List) noneBinds a Cyber type to a C struct.
+
+
func cfunc(name string, params List, ret any) noneDeclares a C function which will get binded to the library handle created from
+bindLib.
+
func new(ctype symbol) pointerAllocates memory for a C struct or primitive with the given C type specifier. A
+pointerto the allocated memory is returned. Eventually this will return acpointerinstead which will be more idiomatic to use.
+
func unbindObjPtr(obj any) noneReleases the object from the FFI context. External code should no longer use the object's pointer since it's not guaranteed to exist or point to the correct object.
+
type CArray #type CDimArray #map DirEntry #| key | summary |
|---|---|
'name' -> array | The name of the file or directory. |
'type' -> #file | #dir | #unknown | The type of the entry. |
map DirWalkEntry #| key | summary |
|---|---|
'name' -> array | The name of the file or directory. |
'path' -> array | The path of the file or directory relative to the walker's root directory. |
'type' -> #file | #dir | #unknown | The type of the entry. |
map ArgOption #| key | summary |
|---|---|
'name' -> string | The name of the option to match excluding the hyphen prefix. eg. -path |
'type' -> metatype(string | float | boolean) | Parse as given value type. |
'default' -> any | Optional: Default value if option is missing. none is used if this is not provided. |
The test module contains utilities for testing.
Sample usage:
+import t 'test'
+
+var a = 123 + 321
+t.eq(a, 444)
++
func eq(a any, b any) anyReturns whether two values are equal. Panics with
+error.AssertErrorif types or values do not match up.
+
func eqList(a any, b any) anyReturns true if two lists have the same size and the elements are equal as if
+eqwas called on those corresponding elements.
+
func eqNear(a any, b any) anyReturns two numbers are near each other within epsilon 1e-5.
+
++
func fail() any
Cyber supports binding to an existing C ABI compatible library at runtime.
+This allows you to call into dynamic libraries created in C or other languages.
+Cyber uses libtcc to JIT compile the bindings so function calls are fast.
+The example shown below can be found in Examples.
An FFI context contains declarations that map C to Cyber. Afterwards, it allows you to bind to a dynamic library or create interoperable objects. To create a new FFI context:
import os
+
+var ffi = os.newFFI()
+Functions from a library are first declared using cfunc which accepts C types in the form of symbols. In a future update they will accept C syntax instead.
ffi.cfunc('add', [.int, .int], .int)
+The first argument refers to the symbol's name in the dynamic library. +The second argument contains the function's parameter types and finally the last argument is the function's return type.
+The example above maps to this C function:
+int add(int a, int b) {
+ return a + b;
+}
+bindLib accepts the path to the library and returns a object which can be used to invoke the functions declared from cfunc:
my lib = ffi.bindLib('./mylib.so')
+lib.add(123, 321)
+Note that my is used to allow lib to be used dynamically since the type is unknown at compile-time.
If the path argument to bindLib is just a filename, the search steps for the library is specific to the operating system. Provide an absolute (eg. '/foo/mylib.so') or relative (eg. './mylib.so') path to load from a direct location instead. When the path argument is none, it loads the currently running executable as a library allowing you to bind exported functions from the Cyber CLI or your own application/runtime.
By default bindLib returns an anonymous object with the binded C-functions as methods. This is convenient for invoking functions using the method call syntax. If a config is passed into bindLib as the second argument, genMap: true makes bindLib return a map instead with the binded C-functions as Cyber functions.
The resulting object of bindLib holds a reference to an internal TCCState which owns the loaded JIT code.
+Once the object is released by ARC, the TCCState is also released which removes the JIT code from memory.
When using cfunc or cbind declarations, symbols are used to represent default type mappings from Cyber to C and back:
Incomplete: This is not the final API for dynamically loading and interfacing with C libraries. The plan is to parse a subset of C headers to bind to Cyber types and functions.
+
| Binding | Cyber | C | Details |
|---|---|---|---|
| .bool | bool | bool | |
| .char | int | int8_t, signed char | |
| .uchar | int | uint8_t, unsigned char | |
| .short | int | int16_t, short | |
| .ushort | int | uint16_t, unsigned short | |
| .int | int | int32_t, int | |
| .uint | int | uint32_t, unsigned int | |
| .long | int | int64_t, long long | |
| .ulong | int | uint64_t, unsigned long long | |
| .usize | int | size_t, uintptr_t | |
| .float | float | float | |
| .double | float | double | |
| .charPtr | pointer | char* | Use os.cstr() and pointer.fromCstr() to convert between a Cyber string and a null terminated C string. |
| .voidPtr | pointer | void* | |
| type {S} object | type {S} object | struct | The mapping from a Cyber object type S and the C-struct can be declared with cbind. |
cbind is used to bind a C struct to a Cyber object type. Once declared, the Cyber type can be used as a binding type in function declarations:
import os
+
+type MyObject object:
+ var a float
+ var b pointer
+ var c bool
+
+ffi.cbind(MyObject, [.float, .voidPtr, .bool])
+ffi.cfunc('foo', [MyObject], MyObject)
+my lib = ffi.bindLib('./mylib.so')
+
+var res = lib.foo([MyObject a: 123.0, b: os.cstr('foo'), c: true])
+The example above maps to these C declarations in mylib.so:
typedef struct MyObject {
+ double a;
+ char* b;
+ bool c;
+} MyObject;
+
+MyObject foo(MyObject o) {
+ // Do something.
+}
+cbind also generates ptrTo[Type] as a helper function to dereference an opaque ptr to a new Cyber object:
ffi.cfunc('foo', [MyObject], .voidPtr)
+my lib = ffi.bindLib('./mylib.so')
+
+var ptr = lib.foo([MyObject a: 123, b: os.cstr('foo'), c: true])
+var res = lib.ptrToMyObject(ptr)
+A pointer is used to read or write to an exact memory address. This is typically used for FFI to manually map Cyber types to C, and back. See type pointer.
A new pointer can be created with the builtin pointer.
var ptr = pointer(0xDEADBEEF)
+print ptr.value() --'3735928559'
+cbindgen.cy is a Cyber script that automatically generates bindings given a C header file. Some example bindings that were generated include: Raylib and LLVM.
+ +| + + | + + | +
Cyber provides a throw/catch mechanism to handle expected errors. For unexpected errors, panics can be used as a fail-fast mechanism to abort the currently running fiber.
+Only types that implement the Error trait can be thrown or attached to a panic.
+Since the Error trait is empty, it's simple to turn any type into a throwable type.
error value. #An error value contains a symbol and implements the Error trait. They can be created without a declaration using the error literal:
var err = error.Oops
+Use sym() to obtain the underlying symbol:
print err.sym() -- Prints ".Oops"
+Since error is a primitive value, it can be compared using the == operator.
if err == error.Oops:
+ handleOops()
+
+-- Alternatively.
+if err.sym() == .Oops:
+ handleOops()
+By implementing the Error trait, an enum type can be throwable: Planned Feature
type MyError enum:
+ with Error
+ boom
+ badArgument
+ nameTooLong
+
+var err = MyError.nameTooLong
+Use the throw keyword to throw errors.
+A thrown error continues to bubble up the call stack until it is caught by a try block or expression.
func fail():
+ throw error.Oops -- Throws an error with the symbol `#Oops`
+
+func fail2():
+ throw 123 -- Panic. Can only throw an error
+ -- that implement the `Error` trait.
+throw can also be used as an expression.
func fail():
+ var a = false or throw error.False
+try block. #The try block catches thrown errors and resumes execution in a followup catch block:
try:
+ funcThatCanFail()
+catch err:
+ print err -- 'error.Failed'
+caught variable. #The contextual caught variable is used to reference the caught error: Planned Feature
try:
+ funcThatCanFail()
+catch:
+ print caught -- 'error.Failed'
+catch matching. #An inner catch block contains a matching clause: Planned Feature
try:
+ funcThatCanFail()
+catch error.BadDay:
+ eatSnack()
+catch:
+ print caught
+Enum errors can be matched: Planned Feature
+try:
+ funcThatCanFail()
+catch MyError.Boom:
+ print 'Kaboom!'
+catch:
+ print caught
+try expression. #The try expression either returns a non-error result or the default value from the catch clause:
var res = try funcThatCanFail() catch 123
+print res -- '123'
+Since errors bubble up automatically, any errors thrown from sub-expressions are also caught:
+var res = try happyFunc(funcThatCanFail()) catch 123
+print res -- '123'
+When the catch clause is omitted, the try expression will return either the value or the error:
var res = try funcThatCanFail()
+if res == error.Failed:
+ print 'Result is an error.'
+throws specifier. #The throws specifier indicates that a function contains a throwing expression that was not caught with try catch.
When a function does not have a return specifier, it's implicitly given the throws specifier:
func foo():
+ throw error.Failure
+
+func bar() throws:
+ throw error.Failure
+
+-- `foo` and `bar` both have the same return specifier.
+Return types for typed functions are declared after throws using a comma separator:
func result(cond bool) throws, int:
+ if cond:
+ return 123
+ else:
+ throw error.Failure
+throws. #A compile-time error is issued when a typed function without a throws specifier contains an uncaught throwing expression: Planned Feature
func foo(a int) int:
+ if a == 10:
+ throw error.Failure -- CompileError. `foo` requires the `throws`
+ else: -- specifier or any throwing expression must
+ return a * 2 -- be caught with `try catch`.
+When an uncaught error bubbles up to the top, its stack trace from the throw callsite is dumped to the console. The builtin errorTrace() and errorReport() are used to obtain the stack trace info.
try:
+ funcThatCanFail()
+catch:
+ -- Prints the stack trace summary of the caught error.
+ print errorReport()
+
+ -- Provides structured info about the stack trace.
+ var info = errorTrace()
+ print info.frames.len()
+An unexpected error is an error that is not meant to be handled at runtime.
+ +The builtin panic is used as a fail-fast mechanism to quickly exit the current fiber with an error payload:
func kaboom():
+ panic(error.danger)
+
+kaboom() -- Script ends and prints the stack trace.
+Panics can not be caught using try catch. Once panic is invoked, the current fiber stops execution and begins to unwind its call stack. Once the error is propagated to the root, the fiber ends and transitions to a panic state. If the main fiber ends this way, the VM begins to shutdown. Otherwise, execution resumes on the next fiber which allows recovery from a panic.
Cyber supports fibers as a concurrency mechanism. There are plans to support preemptive concurrency with async/await as well as multithreading.
+A fiber represents a separate execution context as a first-class value. It contains it's own call stack and program counter. Fibers by themselves do not enable parallelism.
+ +The coinit keyword creates and returns a new fiber using a function as the entry point:
var count = 0
+
+var foo = func ():
+ count += 1
+ coyield
+ count += 1
+
+var fiber = coinit(foo)
+
+print count -- '0'
+coresume fiber
+print count -- '1'
+coresume fiber
+print count -- '2'
+A fiber does not start execution until coresume is invoked on it.
+coyield pauses the current fiber and execution is returned to the previous fiber that invoked coresume.
Arguments after the callee are passed into the entry function:
+var count = 0
+
+var increment = func (inc):
+ count += inc
+
+var fiber = coinit(increment, 5)
+coresume fiber
+print count -- '5'
+When the fiber is created, the arguments are saved inside the fiber's stack. Once the first coresume is invoked, the entry function is invoked with the saved arguments.
To reset a fiber to its initial state, invoke reset(). Planned Feature
+When reset, the existing stack is unwinded, the program counter returns to the starting point, and the state is set to .init:
func fib(n int) int:
+ coyield n
+ if n < 2:
+ return n
+ return fib(n - 1) + fib(n - 2)
+
+var task = coinit(fib, 10)
+
+-- Progress the fiber...
+print(coresume task) -- Prints "10"
+print(coresume task) -- Prints "9"
+print(coresume task) -- Prints "8"
+
+-- Reset back to the start with the `.init` state.
+fiber.reset()
+print(coresume task) -- Prints "10"
+Arguments attached to the fiber can be rebinded with a different set of values. Planned Feature +This allows fiber reuse, instead of creating a new fiber:
+var task = coinit(fib, 10)
+
+-- Run task to completion.
+var res = 0
+while fiber.status() != .done:
+ res = coresume fiber
+print res
+
+fiber.reset()
+fiber.bindArgs(20)
+
+-- Run task again with the new argument...
+A fiber block is used to construct a fiber without an entry function. Planned Feature The counting example can be rewritten to:
+var count = 0
+
+var fiber = coinit:
+ count += 1 -- `count is captured`
+ coyield
+ count += 1
+
+print count -- '0'
+coresume fiber
+print count -- '1'
+coresume fiber
+print count -- '2'
+Referencing parent variables from the fiber block automatically captures them just like a function closure.
+ +coyield can be used anywhere in a fiber's call stack to pause execution and return to the previous fiber.
func foo():
+ print 'foo'
+ bar()
+
+func bar():
+ -- Nested coyield in call stack.
+ coyield
+ print 'bar'
+
+var fiber = coinit(foo)
+coresume fiber
+coresume also returns the resulting value.
func foo():
+ return 123
+
+var fiber = coinit(foo)
+print(coresume fiber) -- '123'
+coyield can return a value back to coresume. Planned Feature
Use Fiber.status() to get the current state of the fiber.
func foo():
+ coyield
+ print 'done'
+
+var fiber = coinit(foo)
+print fiber.status() -- '.paused'
+coresume fiber
+print fiber.status() -- '.paused'
+coresume fiber
+print fiber.status() -- '.done'
+The main execution context is a fiber as well. Once the main fiber has finished, the VM is done and control is returned to the host.
+ ++Planned Feature
+
+Planned Feature
+
+Planned Feature
+
| + + | + + | +
Cyber supports the use of both dynamically and statically typed code.
+Dynamic typing can reduce the amount of friction when writing code, but it can also result in more runtime errors.
+ +my declaration. #Variables declared with my are assigned the dynamic type:
my a = 123
+dynamic vs any #dynamic values can be freely used and copied without any compile errors (if there is a chance it can succeed at runtime, see Recent type inference):
my a = 123
+
+func getFirstRune(s string):
+ return s[0]
+
+getFirstRune(a) -- RuntimeError. Expected `string`.
+Since a is dynamic, passing it to a typed function parameter is allowed at compile-time, but will fail when the function is invoked at runtime.
The any type on the otherhand is a static type and must be explicitly declared using var:
var a any = 123
+
+func getFirstRune(s string):
+ return s[0]
+
+getFirstRune(a) -- CompileError. Expected `string`.
+This same setup will now fail at compile-time because any does not satisfy the destination's string type constraint.
The use of the dynamic type effectively defers type checking to runtime while any is a static type and must adhere to type constraints at compile-time.
A dynamic value can be used in any operation. It can be invoked as the callee, invoked as the receiver of a method call, or used with operators.
dynamic values. #When a dynamic value is invoked, checks on whether the callee is a function is deferred to runtime.
my op = 123
+print op(1, 2, 3) -- RuntimeError. Expected a function.
+When the return type of a function is not specified, it defaults to the dynamic type.
+This allows copying the return value to a typed destination without casting:
func getValue():
+ return 123
+
+func add(a int, b int):
+ return a + b
+
+print add(getValue(), 2) -- Prints "125"
+The add function defers type checking of getValue() to runtime because it has the dynamic type.
Although a dynamic variable has the most flexibility, in some situations it is advantageous to know what type it could be.
The compiler keeps a running record of a dynamic variable's most recent type to gain additional compile-time features without sacrificing flexibility. It can prevent inevitable runtime errors and avoid unnecessary type casts.
When a dynamic variable is first initialized, it has a recent type inferred from its initializer. In the following, a has the recent type of int at compile-time because numeric literals default to the int type:
my a = 123
+The recent type can change at compile-time from another assignment.
+If a is then assigned to a string literal, a from that point on has the recent type of string at compile-time:
my a = 123
+foo(a) -- Valid call expression.
+a = 'hello'
+foo(a) -- CompileError. Expected `int` argument, got `string`.
+
+func foo(n int):
+ pass
+Even though a is dynamic and is usually allowed to defer type checking to runtime, the compiler knows that doing so in this context would always result in a runtime error, so it provides a compile error instead. This provides a quicker feedback to fix the problem.
The recent type of a can also change in branches. However, after the branch block, a will have a recent type after merging the types assigned to a from the two branched code paths. Currently, the any type is used if the types from the two branches differ. At the end of the following if block, a has the recent type of any type after merging the int and string types: Planned Feature
my a = 123
+if a > 20:
+ a = 'hello'
+ foo(a) -- Valid call expression. `foo` can be called without type casting.
+
+foo(a) -- CompileError. Expected `string` argument, got `any`.
+
+func foo(s string):
+ pass
+Static typing can be incrementally applied which provides compile-time guarantees and prevents runtime errors. +Static typing also makes it easier to maintain and refactor your code.
+ +The following builtin types are available in every module: bool, float, int, string, List, Map, error, fiber, any.
var declaration. #A var declaration automatically infers the type from the initializer:
-- Initialized as an `int` variable.
+var a = 123
+var declarations are strictly for static typing. If the assigned value's type is dynamic, the variable's type becomes any.
func getValue():
+ return ['a', 'list']
+
+-- Initialized as an `any` variable.
+var a = getValue()
+A typed local variable can be declared by attaching a type specifier after its name. The value assigned to the variable must satisfy the type constraint or a compile error is issued.
+var a float = 123
+
+var b int = 123.0 -- CompileError. Expected `int`, got `float`.
+Any operation afterwards that violates the type constraint of the variable will result in a compile error.
+a = 'hello' -- CompileError. Expected `float`, got `string`.
+Static variables are declared in a similar way:
+var Root.global Map = [:]
+Unlike local variables, static variable declarations do not infer the type from the right hand side. A specific type must be specified or it will default to the any type.
A type object declaration creates a new object type. Field types are optional and declared with a type specifier after their name.
type Student object: -- Creates a new type named `Student`
+ var name string
+ var age int
+ var gpa float
+Instantiating a new object does not require typed fields to be initialized. Missing field values will default to their zero value:
+var s = [Student:]
+print s.name -- Prints ""
+print s.age -- Prints "0"
+print s.gpa -- Prints "0.0"
+Circular type dependencies are allowed if the object can be initialized:
+Planned Feature: Optional types are not currently supported.
+
type Node object:
+ var val any
+ var next Node? -- Valid type specifier.
+In this example, next has an optional Node? type so it can be initialized to none when creating a new Node object.
The following example will fail because this version of Node can not be initialized:
type Node object:
+ var val any
+ var next Node
+
+var n = [Node:] -- CompileError. Can not zero initialize `next`
+ -- because of circular dependency.
+The following shows the zero values of builtin or created types.
+| Type | Zero value |
|---|---|
boolean | false |
int | 0 |
float | 0.0 |
string | '' |
array | array('') |
List | [] |
Map | [:] |
type S object | [S:] |
@host type S object | S.$zero() |
dynamic | none |
any | none |
S? | none |
A type alias is declared from a single line type statement. This creates a new type symbol for an existing data type.
import util './util.cy'
+
+type Vec3 util.Vec3
+
+var v = [Vec3 x: 3, y: 4, z: 5]
+Function parameter and return type specifiers follows a similiar syntax.
+func mul(a float, b float) float:
+ return a * b
+
+print mul(3, 4)
+print mul(3, '4') -- CompileError. Function signature mismatch.
++Planned Feature
+
+Planned Feature
+
any type. #A variable with the any type can hold any value, but copying it to narrowed type destination will result in a compile error:
func square(i int):
+ return i * i
+
+var a any = 123
+a = ['a', 'list'] -- Valid assignment to a value with a different type.
+a = 10
+
+print square(a) -- CompileError. Expected `int`, got `any`.
+a must be explicitly casted to satisfy the type constraint:
print square(a as int) -- Prints "100".
+any values. #Since any is a static type, invoking an any value must be explicitly casted to the appropriate function type.
Planned Feature: Casting to a function type is not currently supported.
+
func add(a int, b int) int:
+ return a + b
+
+var op any = add
+print op(1, 2) -- CompileError. Expected `func (int, int) any`
+
+var opFunc = op as (func (int, int) int)
+print opFunc(1, 2) -- Prints "3".
+The as keyword can be used to cast a value to a specific type. Casting lets the compiler know what the expected type is and does not perform any conversions.
If the compiler knows the cast will always fail at runtime, a compile error is returned instead.
+print('123' as int) -- CompileError. Can not cast `string` to `int`.
+If the cast fails at runtime, a panic is returned.
+var erased any = 123
+add(1, erased as int) -- Success.
+print(erased as string) -- Panic. Can not cast `int` to `string`.
+
+func add(a int, b int):
+ return a + b
+| + + | + + | +
All operators are implemented as object methods.
+Incomplete: Not all operators have transitioned to the method paradigm.
+
Normally this would impact performance, but Cyber generates specialized bytecode for builtin types like int and float. The VM performs inline caching at runtime to eliminate the overhead of evaluating on dynamic operands.
To overload an operator for an object type, declare $prefix, $infix, $postfix methods. See the available builtin operators. Since operator names aren't allowed as standard identifiers, they are contained in a string literal.
type Vec2 object:
+ var x float
+ var y float
+
+ func '$infix+'(o Vec2) Vec2:
+ return [Vec2
+ x: x + o.x,
+ y: y + o.y,
+ ]
+
+ func '$prefix-'() Vec2:
+ return [Vec2 x: -x, y: -y]
+
+var a = [Vec2 x: 1, y: 2]
+var b = a + [Vec2 x: 3, y: 4]
+var c = -a
+Some special operators have their own name. This example overloads the index operator and the set index operator:
type MyCollection object:
+ var arr List
+
+ func '$index'(idx):
+ return arr[idx * 2]
+
+ func '$setIndex'(idx, val):
+ arr[idx * 2] = val
+
+var a = [MyCollection arr: [1, 2, 3, 4]]
+print a[1] -- Prints `3`
+A list of all supported operators:
+| Operator | Name |
|---|---|
| Bitwise not | $prefix~ |
| Minus | $prefix- |
| Greater | $infix> |
| Greater equal | $infix>= |
| Less | $infix< |
| Less equal | $infix<= |
| Add | $infix+ |
| Subtract | $infix- |
| Multiply | $infix* |
| Divide | $infix/ |
| Modulus | $infix% |
| Power | $infix^ |
| Bitwise and | $infix& |
| Bitwise or | $infix\| |
| Bitwise xor | $infix\|\| |
| Bitwise left shift | $infix<< |
| Bitwise right shift | $infix>> |
| Index | $index |
| Set index | $setIndex |
| Slice | $slice |
+Planned Feature
+
Declare a $call function to allow invoking a module as a function.
-- Object types are also modules.
+type Vec2 object:
+ var x float
+ var y float
+
+func Vec2.'$call'(x float, y float) Vec2:
+ return [Vec2 x: x, y: y]
+
+var v = Vec2(1, 2)
++Planned Feature
+
Declare a $missing method as a fallback when a method was not found in an instance.
Planned Feature
+
type A object:
+
+ func '$missing'(args...):
+ return args.len
+
+var a = [A:]
+print a.foo() -- Output: '0'
+print a.bar(1, 2) -- Output: '2'
+A type metatype object references an internal type. Use the typeof builtin to get the metatype of a value.
var val = 123
+print typeof(val) -- 'type: float'
+
+-- Referencing a type as a value also returns its `metatype`.
+print bool -- 'type: bool'
+Annotations are used to attach modifiers to declarative statements. The @host annotation is used for embedding to bind a host function to a Cyber function:
@host func compute() float
+Custom annotations.
++Planned Feature
+
+Planned Feature
+
+Planned Feature
+
+Planned Feature
+
| + + |
+
|
+
The Embed API allows embedding the Cyber compiler and VM as a library into applications. Cyber's core types and the CLI app were built using the Embed API.
+The API is defined in the C header file. +The examples shown below can be found in the repository under c-embedded. C is used as the host language, but it can be easily translated to C++ or any C-ABI compatible language.
+Types from the Embed API begin with Cs, constants begin with CS, and functions begin with cs.
Most operations are tied to a VM handle. To create a new VM instance, call csCreate:
#include "cyber.h"
+
+int main() {
+ CsVM* vm = csCreate();
+ // ...
+ csDestroy(vm);
+ return 0;
+}
+print. #The builtin print function does nothing by default, so it needs to be overrided to print to stdout for example:
void print(CsVM* vm, CsStr str) {
+ printf("My print: %.*s\n", (int)str.len, str.buf);
+}
+
+int main() {
+ // ...
+ csSetPrint(vm, print);
+ // ...
+}
+csEval compiles and evaluates a script:
CsStr src = STR(
+ "var a = 1\n"
+ "print(a + 2)\n"
+);
+
+CsValue val;
+int res = csEval(vm, src, &val);
+if (res == CS_SUCCESS) {
+ printf("Success!\n");
+ csRelease(vm, val);
+} else {
+ const char* report = csNewLastErrorReport(vm);
+ printf("%s\n", report);
+ csFreeStrZ(report);
+}
+If a value is returned from the main block of the script, it's saved to the result value argument.
+Memory is managed by ARC so a value that points to a heap object requires a csRelease when it's no longer needed.
csEval returns a result code that indicates whether it was successful.
A module loader describes how a module is loaded when an import statement is encountered during script execution.
+Only one module loader can be active and is set using csSetModuleLoader:
bool modLoader(CsVM* vm, CsStr spec, CsModuleLoaderResult* out) {
+ if (strncmp("my_mod", spec.buf, spec.len) == 0) {
+ out->src =
+ "@host func add(a float, b float) float\n"
+ "@host var Root.MyConstant float\n"
+ "@host var Root.MyList List\n"
+ "\n"
+ "@host\n"
+ "type MyCollection object:\n"
+ " @host func asList() any"
+ "\n"
+ "@host func MyCollection.new(a, b) MyCollection\n";
+ out->funcLoader = funcLoader;
+ out->varLoader = varLoader;
+ out->typeLoader = typeLoader;
+ return true;
+ } else {
+ // Fallback to the default module loader to load `builtins`.
+ return csDefaultModuleLoader(vm, spec, out);
+ }
+}
+
+int main() {
+ //...
+ csSetModuleLoader(vm, modLoader);
+ //...
+}
+The above example checks whether "my_mod" was imported and returns it's source code. Additional loaders are returned to load the functions, variables, and types from the source code.
+ +Since only one module loader can be set to the VM instance, a custom loader is required to handle the "builtins" import which contains all of the core types and functions in Cyber. This can simply be delegated to csDefaultModuleLoader.
A function loader describes how to load a @host function when it's encountered by the compiler.
+The loader can bind functions and type methods:
struct { char* n; CsFuncFn fn; } funcs[] = {
+ {"add", add},
+ {"asList", myCollectionAsList},
+ {"MyCollection.new", myCollectionNew},
+};
+
+bool funcLoader(CsVM* vm, CsFuncInfo info, CsFuncResult* out) {
+ // Check that the name matches before setting the function pointer.
+ if (strncmp(funcs[info.idx].n, info.name.buf, info.name.len) == 0) {
+ out->ptr = funcs[info.idx].fn;
+ return true;
+ } else {
+ return false;
+ }
+}
+This example uses the CsFuncInfo.idx of a @host function to index into an array and return a Host function pointer. The name is also compared to ensure it's binding to the correct pointer.
This is an efficient way to map Cyber functions to host functions. A different implementation might use a hash table to map the name of the function to it's pointer.
+ +A variable loader describes how to load a @host variable when it's encountered by the compiler:
// C has limited static initializers (and objects require a vm instance) so initialize them in `main`.
+typedef struct { char* n; CsValue v; } NameValue;
+NameValue vars[2];
+
+bool varLoader(CsVM* vm, CsVarInfo info, CsValue* out) {
+ // Check that the name matches before setting the value.
+ if (strncmp(vars[info.idx].n, info.name.buf, info.name.len) == 0) {
+ // Objects are consumed by the module.
+ *out = vars[info.idx].v;
+ return true;
+ } else {
+ return false;
+ }
+}
+
+int main() {
+ // ...
+
+ // Initialize var array for loader.
+ vars[0] = (NameValue){"Root.MyConstant", csFloat(1.23)};
+ CsValue myInt = csInteger(123);
+ vars[1] = (NameValue){"Root.MyList", csNewList(vm, &myInt, 1)};
+
+ // ...
+}
+This example uses the same technique as the function loader, but it can be much simpler. It doesn't matter how the mapping is done as long as the variable loader returns a CsValue.
A type loader describes how to load a @host type when it's encountered by the compiler:
CsTypeId myCollectionId;
+
+bool typeLoader(CsVM* vm, CsTypeInfo info, CsTypeResult* out) {
+ if (strncmp("MyCollection", info.name.buf, info.name.len) == 0) {
+ out->type = CS_TYPE_OBJECT;
+ out->data.object.outTypeId = &myCollectionId;
+ out->data.object.getChildren = myCollectionGetChildren;
+ out->data.object.finalizer = myCollectionFinalizer;
+ return true;
+ } else {
+ return false;
+ }
+}
+When binding to the "MyCollection" type, it's typeId is saved to outTypeId. This id is then used to create new instances of this type. See Host types.
A host function requires a specific function signature:
+CsValue add(CsVM* vm, const CsValue* args, uint8_t nargs) {
+ double res = csAsFloat(args[0]) + csAsFloat(args[1]);
+ return csFloat(res);
+}
+A host function should always return a CsValue. csNone() can be returned if the function does not intend to return any value.
A host type are types that are opaque to Cyber scripts but still behave like an object. They can have type functions and methods.
+Only the host application can directly create new instances of them, so usually a function is binded to expose a constructor to the user script:
+// Binding a C struct with it's own children and finalizer.
+// This struct retains 2 VM values and has 2 arbitrary data values unrelated to the VM.
+typedef struct MyCollection {
+ CsValue val1;
+ CsValue val2;
+ int a;
+ double b;
+} MyCollection;
+
+// Implement the `new` function in MyCollection.
+CsValue myCollectionNew(CsVM* vm, const CsValue* args, uint8_t nargs) {
+ // Instantiate our object.
+ CsValue new = csNewHostObject(vm, myCollectionId, sizeof(MyCollection));
+ MyCollection* my = (MyCollection*)csAsHostObject(new);
+
+ // Assign the constructor args passed in and retain them since the new object now references them.
+ csRetain(vm, args[0]);
+ my->val1 = args[0];
+ csRetain(vm, args[1]);
+ my->val2 = args[1];
+
+ // Assign non VM values.
+ my->a = 123;
+ my->b = 9999.999;
+ return new;
+}
+csNewHostObject takes the type id (returned from the Type loader) and size (in bytes) and returns a new heap object. Note that the size is allowed to vary. Different instances of the same type can occupy different amounts of memory.
getChildren #Since MyCollection contains CsValue children, the Type loader requires a getChildren callback so that memory management can reach them:
CsValueSlice myCollectionGetChildren(CsVM* vm, void* obj) {
+ MyCollection* my = (MyCollection*)obj;
+ return (CsValueSlice){ .ptr = &my->val1, .len = 2 };
+}
+finalizer #A type finalizer is optional since the memory and children of an instance will be freed automatically by ARC. +However, it can be useful to perform additional cleanup tasks for instances that contain external resources.
+void myCollectionFinalizer(CsVM* vm, void* obj) {
+ printf("MyCollection finalizer was called.\n");
+}
+Cyber provides memory safety by default.
+Cyber uses ARC or automatic reference counting to manage memory. +ARC is deterministic and has less overhead compared to a tracing garbage collector. Reference counting distributes memory management, which reduces GC pauses and makes ARC suitable for realtime applications. One common issue in ARC implementations is reference cycles which Cyber addresses with Weak References and it's very own Cycle Detection.
+ +In Cyber, there are primitive and object values. Primitives don't need any memory management, since they are copied by value and no heap allocation is required (with the exception of primitives being captured by a closure.
+Objects are managed by ARC. Each object has its own reference counter. Upon creating a new object, it receives a reference count of 1. When the object is copied, it's retained and the reference count increments by 1. When an object value is removed from it's parent or is no longer reachable in the current stack frame, it is released and the reference count decrements by 1.
+Once the reference count reaches 0 the object begins its destruction procedure. First, child references are released thereby decrementing their reference counts by 1. If the object is a host object, it will invoke its finalizer function. Afterwards, the object is freed from memory.
The compiler can reduce the number of retain/release ops since it can infer value types even though they are dynamically typed to the user. Arguments passed to functions are only retained depending on the analysis from the callsite.
+ +When primitive variables are captured by a closure, they are boxed and allocated on the heap. This means they are managed by ARC and cleaned up when there are no more references to them.
+ +Fibers are freed by ARC just like any other object. Once there are no references to the fiber, it begins to release it's child references by unwinding it's call stack.
+ +Many object types in Cyber are small enough to be at or under 40 bytes. To take advantage of this, Cyber can reserve object pools to quickly allocate and free these small objects with very little bookkeeping. Bigger objects are allocated and managed by mimalloc which has proven to be a fast and reliable general-purpose heap allocator.
+Planned Feature
+
The cycle detector is also considered a GC and frees abandoned objects managed by ARC. Although weak references can remove cycles altogether, Cyber does not force you to use them and provides a manual GC as a one-time catch all solution.
+Incomplete Feature: Only the main fiber stack is cleaned up at the moment.
+
To invoke the GC, call the builtin function: performGC.
func foo():
+ -- Create a reference cycle.
+ var a = []
+ var b = []
+ a.append(b)
+ b.append(a)
+
+ -- Cycle still alive in the current stack so no cleanup is done.
+ var res = performGC()
+ print res['numCycFreed'] -- Output: 0
+ print res['numObjFreed'] -- Output: 0
+
+foo()
+-- `a` and `b` are no longer reachable, so the GC does work.
+var res = performGC()
+print res['numCycFreed'] -- Output: 2
+print res['numObjFreed'] -- Output: 2
+Cyber's just-in-time compiler is incomplete and unstable. To run your script with JIT enabled:
+cyber -jit <script>
+The JIT compiler is just as fast as the bytecode generation so when it's enabled, the entire script is compiled from the start.
+ +Work on the ahead-of-time compiler has not begun.
+ + + + + + + \ No newline at end of file diff --git a/index.xml b/index.xml deleted file mode 100644 index e1cd044b5..000000000 --- a/index.xml +++ /dev/null @@ -1,28 +0,0 @@ -