Cyber Docs

v0.4-dev 73-8d31034
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)!"
^topic

Syntax. #

^top

Cyber's syntax is concise and easy to read.

Statements. #

A statement ends with the new line:

var a = 123

To wrap a statement to the next line, the last token before the new line must be an operator or a separator:

var gameover = health <= 0 or
    player.collidesWith(spikes)

if year > 2020 and year <= 2030 and
    month > 0 and month <= 11:
    print 'Valid'

Any token inside a delimited syntax (such as parentheses or brackets) can be wrapped to the next line:

var sum = add(1, 2, 3, 4,
    100, 200, 300, 400)

var colors = ['red', 'blue', 'green',
    'purple', 'orange', 'yellow']
^topic

Blocks. #

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.

Compact blocks allow only one statement after the starting block:

-- A single line block.
if true: print 123

if true: print 123
    -- This is an indentation error since the compact block is already consumed.
    print 234

Since blocks require at least one statement, use pass as a placeholder statement:

func foo():
    pass
^topic

Variables. #

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.

^topic

Local variables. #

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
^topic

Dynamic variables. #

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.

^topic

Variable scopes. #

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"
^topic

Static Variables. #

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 .a = 123

func foo():
    print a     -- '123'

The . prefix 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 .b = a   -- Compile error, initializer can not reference a local variable.

-- Main execution.
var a = 123

However, they can be reassigned after initialization:

var .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 .a = print(123)
var .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 .a = b + 321
var .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 .a = b
var .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 .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.

^topic

Reserved identifiers. #

^topic

Keywords. #

There are 26 general keywords. This list categorizes them:

^topic

Contextual keywords. #

These keywords only have meaning in a certain context.

^topic

Literals. #

^topic

Operators. #

Cyber supports the following operators. They are ordered from highest to lowest precedence.

OperatorDescription
<< >>Bitwise left shift, right shift.
&Bitwise and.
| ||Bitwise or, exclusive or.
^Power.
/ % *Division, modulus, multiplication.
+ -Addition, subtraction.
asType casting.
> >= < <= != ==Greater, greater or equal, less, less or equal, not equals, equals.
andLogical and.
orLogical or.
^topic

Arithmetic Operators. #

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.
^topic

Comparison Operators. #

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
^topic

Logic Operators. #

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
^topic

Bitwise Operators. #

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
^topic

Operator overloading. #

See Operator overloading in Metaprogramming.

^topic

Comments. #

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.

^topic

CYON. #

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',
    ],
]
^topic

Basic Types. #

^top

In Cyber, there are primitive types and object types. By default, primitives are copied around by value and don't need additional heap memory or reference counts.

Primitives include Booleans, Floats, Integers, Enums, Symbols, and Error Values.

Object types include Lists, Tuples, Maps, Strings, Arrays, Objects, Lambdas, Fibers, Choices, Optionals, Pointers, and several internal object types.

Booleans. #

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.

^topic

Numbers. #

^topic

Integers. #

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.

^topic

Floats. #

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) 
^topic

Big Numbers. #

Planned Feature

^topic

Strings. #

The String type represents a sequence of validated 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.

Strings are immutable, so operations that do string manipulation return a new string. By default, short strings are interned to reduce memory footprint.

Under the hood, there are multiple string implementations to make operations faster by default using SIMD.

^topic

Raw string literal. #

A raw string doesn't allow any escape sequences or string interpolation.

Single quotes are used to delimit a single line literal:

var fruit = 'apple'
var str = 'abc🦊xyz🐶'

Since raw strings interprets the sequence of characters as is, a single quote character can not be escaped:

var fruit = 'Miso's apple'    -- ParseError.

Triple single quotes are used to delimit a multi-line literal. It also allows single quotes and double single quotes in the string:

var fruit = '''Miso's apple'''
var greet = '''Hello
World'''
^topic

String literal. #

A string literal allows escape sequences and string interpolation.

Double quotes are used to delimit a single line literal:

var fruit = "apple"
var sentence = "The $(fruit) is tasty."
var doc = "A double quote can be escaped: \""

Triple double quotes are used to delimit a multi-line literal:

var title = "last"
var doc = """A double quote " doesn't need to be escaped."""
var str = """line a
line "b"
line $(title)
"""
^topic

Escape sequences. #

The following escape sequences are supported in string literals:

Escape SequenceCodeDescription
\a0x07Terminal bell.
\b0x08Backspace.
\e0x1bEscape character.
\n0x0aLine feed character.
\r0x0dCarriage return character.
\t0x09Horizontal tab character.
^topic

String operations. #

See type String for all available methods.

Concatenate two strings together with the + operator or the method concat.

var res = 'abc' + 'xyz'
res = res.concat('end')

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"
^topic

String interpolation. #

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.

^topic

String formatting. #

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))"
^topic

Line-join literal. #

The line-join literal joins string literals with the new line character \n. Planned Feature

This has several properties:

var paragraph = [
    \'the line-join literal
    \'hello\nworld
    \"hello $(name)
    \'last line
    \'
]
^topic

Mutable strings. #

To mutate an existing string, use type MutString. Planned Feature

^topic

Arrays. #

An Array is an immutable sequence of bytes. It can be a more performant way 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"
^topic

Lists. #

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)
^topic

Tuples. #

Incomplete: Tuples can only be created from #host funcs at the moment.

^topic

Maps. #

Maps are a builtin type that store key value pairs in dictionaries. See type Map.

^topic

Create 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,
]
^topic

Empty map. #

The empty map is initialized using [:]:

var empty = [:]
^topic

Map indexing. #

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
^topic

Map operations. #

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)"
^topic

Map block. #

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
^topic

Symbols. #

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.
^topic

Custom Types. #

^top

Objects. #

An object type contains field and function members. New instances can be created from them similar to a struct or class in other languages. Unlike classes, there is no builtin concept of inheritance but a similar effect can be achieved using composition and embedding.

Object types are declared with type object. The object keyword is optional when using a type declaration. These two declarations are equivalent:

type A object:
    var b int

type A:
    var b int
^topic

Fields. #

Fields must be declared at the top of the type block using var or my:

type Node:
    var value int
    var next  ?Node

Field types are optional for var declarations and defaults to the any type. When fields are declared with my instead, they become dynamically typed and do not accept a type specifier.

^topic

Instantiate. #

New object instances are created using a record literal with a leading type name:

var node = [Node value: 123, next: none]
print node.value       -- Prints "123"

A record literal can also initialize to the inferred object type:

var node Node = [value: 234, next: none]
print node.value       -- Prints "234"
^topic

Default field values. #

When a field is omitted in the record literal, it gets initialized to its zero value:

var node Node = [value: 234]
print node.next       -- Prints "Option.none"

type Student:
    var name String
    var age  int
    var gpa  float

var s = [Student:]
print s.name       -- Prints ""
print s.age        -- Prints "0"
print s.gpa        -- Prints "0.0"
^topic

Circular references. #

Circular type references are allowed if the object can be initialized:

Planned Feature: Optional types are not currently supported.

type Node:
    var val  any
    var next ?Node

var n = [Node:]    -- Initializes.

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:
    var val  any
    var next Node

var n = [Node:]    -- CompileError. Can not zero initialize `next`
                   -- because of circular dependency.
^topic

Unnamed object. #

Unnamed object types can be declared and used without an explicit type declaration:

type Node:
    var value object:
        var a  int
        var b  float
    var next ?Node

var node = [Node
    value: [a: 123, b: 100.0],
    next: none,
]
^topic

Methods. #

Methods allow invoking a function on an object instance using the . operator:

type Node:
    var value int
    var next  ?Node

    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 be declared outside of the type declaration. When using the flat declaration style, self must be the first parameter to distinguish it from a type function:

func Node.getNext(self):
    return self.next
^topic

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:
    var value int
    var next  ?Node

    func double():
        return self.value * 2
^topic

Type functions. #

Type functions are declared outside of the type block with an explicit namespace path:

type Node:
    var value int
    var next  ?Node

-- Declare namespace function inside `Node`.
func Node.new():
    return [Node value: 123, next: none]

var n = Node.new()
^topic

Type variables. #

Similarily, type variables are declared outside of the type block:

-- Declare inside the `Node` namespace.
var Node.DefaultValue = 100

print Node.DefaultValue    -- Prints "100"
^topic

Structs. #

Struct types can contain field and method members just like object types, but their instances are copied by value rather than by reference. In that sense, they behave like primitive data types.

Unlike objects, structs do not have a reference count. They can be safely referenced using borrow semantics. Unsafe pointers can also reference structs.

^topic

Declare struct. #

Struct types are created using the type struct declaration:

type Vec2 struct:
    var x float
    var y float

var v = [Vec2 x: 30, y: 40]
^topic

Copy structs. #

Since structs are copied by value, assigning a struct to another variable creates a new struct:

var v = [Vec2 x: 30, y: 40]
var w = v
v.x = 100
print w.x    -- Prints '30'
print v.x    -- Prints '100'
^topic

Enums. #

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'
^topic

Choices. #

Choices are enums with payloads (also known as sum types or tagged unions). An enum declaration becomes a choice type if one of the cases has a payload type specifier:

type Shape enum:
    case rectangle Rectangle
    case circle    object:
        var radius float
    case triangle  object:
        var base   float
        var height float
    case line      float
    case point 

type Rectangle:
    var width  float
    var height float
^topic

Initialize choice. #

If the payload is an object type, the choice can be initialized with a simplified record literal:

var s = [Shape.rectangle width: 10, height: 20]

The general way to initialize a choice is to pass the payload as an argument:

var rect = [Rectangle width: 10, height: 20]
var s = [Shape rectangle: rect]

s = [Shape line: 20]

A choice without a payload is initialized with an empty record literal:

var s = [Shape.point:]
^topic

Choice switch. #

case clauses can match choices and capture the payload:

switch s
case .rectangle -> r:
    print "$(r.width) $(r.height)"
case .circle -> c:
    print "$(c.radius)"
case .triangle -> t:
    print "$(t.base) $(t.height)"
case .line -> len:
    print "$(len)"
case .point:
    print "a point"
else:
    print "Unsupported."
^topic

Access choice. #

A choice can be accessed by specifying the access operator .! before the tagged member name. This will either return the payload or panic at runtime: Planned Feature

var s = [Shape line: 20]
print s.!line     -- Prints '20'
^topic

Optionals. #

The generic Option type is a choice type that either holds a none value or contains some value. The option template is defined as:

template(T type)
type Option enum:
    case none
    case some #T

A type prefixed with ? is a more idiomatic way to create an option type. The following String optional types are equivalent:

Option#String
?String
^topic

Wrap value. #

Use ? as a type prefix to turn it into an Option type. A value is automatically wrapped into the inferred optional's some case:

var a ?String = 'abc'
print a     -- Prints 'Option(abc)'
^topic

Wrap none. #

none is automatically initialized to the inferred optional's none case:

var a ?String = none
print a     -- Prints 'Option.none'
^topic

Unwrap or panic. #

The .? access operator is used to unwrap an optional. If the expression evaluates to the none case, the runtime panics:

var opt ?String = 'abc'
var v = opt.?
print v     -- Prints 'abc'
^topic

Unwrap or default. #

The ?else control flow operator either returns the unwrapped value or a default value when the optional is none: Planned Feature

var opt ?String = none
var v = opt ?else 'empty'
print v     -- Prints 'empty'

else can also start a new statement block: Planned Feature

var v = opt else:
    break 'empty'

var v = opt else:
    throw error.Missing
^topic

Optional chaining. #

Given the last member's type T in a chain of ?. access operators, the chain's execution will either return Option(T).none on the first encounter of none or returns the last member as an Option(T).some: Planned Feature

print root?.a?.b?.c?.last
^topic

if unwrap. #

The if statement can be amended to unwrap an optional value using the capture -> operator: Planned Feature

var opt ?String = 'abc'
if opt -> v:
    print v     -- Prints 'abc'
^topic

while unwrap. #

The while statement can be amended to unwrap an optional value using the capture -> operator. The loop exits when none is encountered: Planned Feature

var iter = dir.walk()
while iter.next() -> entry:
    print entry.name
^topic

Type aliases. #

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]
^topic

Traits. #

Planned Feature

^topic

Union types. #

Planned Feature

^topic

Generic types. #

Templates are used to specialize type declarations. Since template parameters only exist at compile-time, the # prefix is used to reference them in the template body:

template(T type)
type MyContainer:
    var id int
    var value #T

    func get() #T:
        return self.value
^topic

Expand type template. #

When the template is invoked with compile-time argument(s), a specialized version of the type is generated.

Invoking a template requires a # before the call arguments. This indicates that they are compile-time arguments. In this example, String can be used as an argument since it satisfies the type parameter constraint:

var a MyContainer#(String) = [id: 123, value: 'abc']
print a.get()      -- Prints 'abc'

When there is only one template argument, the syntax can be simplified:

var a MyContainer#String = [id: 123, value: 'abc']
print a.get()      -- Prints 'abc'

Note that invoking the template again with the same argument(s) returns the same generated type. In other words, the generated type is always memoized from the input parameters.

^topic

Control Flow. #

^top

Cyber provides the common constructs to branch and enter loops.

Branching. #

^topic

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'
^topic

Conditional expression. #

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'
^topic

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'
^topic

Iterations. #

^topic

Infinite while. #

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
^topic

Conditional while. #

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
^topic

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
^topic

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)"
^topic

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)"
^topic

Exit loop. #

Use break to exit a loop. This loop stops printing once i reaches 4:

for 0..10 -> i:
    if i == 4:
        break
    print i
^topic

Next iteration. #

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
^topic

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)"

The switch statement requires at least one case block or an else block. When the switch statement begins a new block, the case statements must be indented:

switch val:
    case 0: print 'a'
    case 1: print 'b'
    else: print 'c'
^topic

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}.

^topic

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.
^topic

Try/Catch. #

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.

^topic

Deferred Execution. #

Planned Feature

^topic

Functions. #

^top

In Cyber, there are first-class functions (or function values) and static functions.

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)
^topic

Function overloading. #

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"
^topic

Lambdas. #

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.

^topic

Closures. #

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`.
^topic

Named parameters. #

Planned Feature

^topic

Optional parameters. #

Planned Feature

^topic

Variadic parameters. #

Planned Feature

^topic

Function calls. #

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)
^topic

Shorthand syntax. #

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')
^topic

Call block syntax. #

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'.

^topic

Generic functions. #

Planned Feature

^topic

Modules. #

^top

Modules have their own namespace and contain accessible static symbols. By default, importing another Cyber script returns a module with its declared symbols.

Importing. #

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 .foo = 123
print foo         -- Statement is ignored.

-- bar.cy
var .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)
^topic

Exporting. #

All static declarations are exported when the script's module is loaded.

func foo():         -- Exported static function.
    print 123

var .bar = 234      -- Exported static variable.

type Thing:  -- Exported type.
    var a float
^topic

Module URI. #

To get the absolute path of the current module, reference the compile-time constant #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'
^topic

Visibility. #

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.

^topic

Builtin modules. #

Builtin modules are the bare minimum that comes with Cyber. The embeddable library contains these modules and nothing more. They include:

^topic

builtins. #

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) any

Copies a primitive value or creates a shallow copy of an object value.

func dump(val any) none

Prints the result of toCyon on a value.

func errorReport() String

func getObjectRc(val any) int

Returns the current reference count of an object.

func is(a any, b any) bool

Returns whether two values refer to the same instance.

func isAlpha(val int) bool

Returns whether a rune is an alphabetic letter.

func isDigit(val int) bool

Returns whether a rune is a digit.

func must(val any) any

If val is an error, panic(val) is invoked. Otherwise, val is returned.

func panic(err any) none

Stop execution in the current fiber and starts unwinding the call stack. See Unexpected Errors.

func parseCyber(src String) Map

Parses 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) any

Parses a CYON string into a value.

func performGC() Map

Runs 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) none

Prints a value. The host determines how it is printed.

func runestr(val int) String

Converts a rune to a string.

func toCyon(val any) String

Encodes a value to CYON string.

func typeof(val any) metatype

Returns the value's type as a metatype object.

func typesym(val any) symbol

Returns 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

^topic

type bool #

func bool.'$call'(val any) bool

Converts a value to either true or false.

^topic

type error #

func sym() symbol

Return the underlying symbol.

func error.'$call'(val any)

Create an error from an enum or symbol.

^topic

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) String

Formats 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.pad provides the ASCII rune that is used for padding with a string length of opts.width.

func int.'$call'(val any) int

Converts a value to an 48-bit integer.

^topic

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) float

Converts the value to a float. Panics if type conversion fails.

^topic

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) none

Appends a value to the end of the list.

func concat(list List) none

Concats the elements of another list to the end of this list.

func insert(idx int, val any) none

Inserts a value at index idx.

func iterator() ListIterator

Returns a new iterator over the list elements.

func join(sep String) String

Returns a new string that joins the elements with separator.

func len() int

Returns the number of elements in the list.

func remove(idx int) none

Removes an element at index idx.

func resize(size int) none

Resizes the list to len 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) List

func List.fill(val any, n int) List

Creates a list with initial capacity of n and values set to val. If the value is an object, it is shallow copied n times.

^topic

type ListIterator #

func next() any

^topic

type tuple #

func $index(idx int) any

^topic

type Map #

func $index(key any) any

func $setIndex(key any, val any) none

func remove(key any) none

Removes the element with the given key key.

func size() int

Returns the number of key-value pairs in the map.

func iterator() MapIterator

Returns a new iterator over the map elements.

^topic

type MapIterator #

func next() any

^topic

type String #

func $infix+(o any) String

func concat(o String) String

Returns a new string that concats this string and str.

func endsWith(suffix String) bool

Returns whether the string ends with suffix.

func find(needle String) any

Returns the first index of substring needle in the string or none if not found. SIMD enabled.

func findAnyRune(runes String) any

Returns the first index of any UTF-8 rune in runes or none if not found. SIMD enabled.

func findRune(rune int) int

Returns the first index of UTF-8 rune needle in the string or none if not found. SIMD enabled.

func insert(idx int, str String) String

Returns a new string with str inserted at index idx.

func isAscii() bool

Returns whether the string contains all ASCII runes.

func len() int

Returns the number of UTF-8 runes in the string.

func less(other String) bool

Returns whether this string is lexicographically before other.

func lower() String

Returns this string in lowercase.

func replace(needle String, replacement String) String

Returns a new string with all occurrences of needle replaced with replacement.

func repeat(n int) String

Returns a new string with this string repeated n times.

func runeAt(n int) int

Returns the UTF-8 rune at index idx.

func slice(start any, end any) String

Returns a slice into this string from start to end (exclusive) indexes. This is equivalent to using the slice index operator [start..end].

func $slice(start any, end any) String

func sliceAt(idx int) String

Returns the UTF-8 rune at index idx as a single rune string.

func $index(idx int) String

func split(sep String) List

Returns a list of UTF-8 strings split at occurrences of sep.

func startsWith(prefix String) bool

Returns whether the string starts with prefix.

func trim(mode symbol, delims String) String

Returns the string with ends trimmed from runes in delims. mode can be .left, .right, or .ends.

func upper() String

Returns this string in uppercase.

func String.'$call'(val any) String

Converts a value to a string.

^topic

type Array #

func $infix+(o any) Array

func concat(other Array) Array

Returns a new array that concats this array and other.

func decode() String

Calls decode(.utf8)

func decode(encoding symbol) String

Decodes the array based on an encoding. Supported encodings: .utf8. Returns the decoded string or throws error.Decode.

func endsWith(suffix Array) bool

Returns whether the array ends with suffix.

func find(needle Array) any

Returns the first index of needle in the array or none if not found.

func findAnyByte(bytes Array) any

Returns the first index of any bytes in arrays or none if not found.

func findByte(byte int) any

Returns the first index of byte in the array or none if not found.

func fmt(kind symbol) String

Formats 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) int

Returns the byte value (0-255) at the given index idx.

func getInt(idx int, endian symbol) int

Returns the int value of the 6 bytes starting from idx with the given endianness (.little or .big).

func getInt32(idx int, endian symbol) int

Returns the int value of the 4 bytes starting from idx with the given endianness (.little or .big).

func insert(idx int, arr Array) Array

Returns a new array with arr inserted at index idx.

func insertByte(idx int, byte int) Array

Returns a new array with byte inserted at index idx.

func len() int

Returns the number of bytes in the array.

func repeat(n int) Array

Returns a new array with this array repeated n times.

func replace(needle Array, replacement Array) Array

Returns a new array with all occurrences of needle replaced with replacement.

func slice(start any, end any) Array

Returns a slice into this array from start to end (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) List

Returns a list of arrays split at occurrences of sep.

func startsWith(prefix Array) bool

Returns whether the array starts with prefix.

func trim(mode symbol, delims Array) Array

Returns the array with ends trimmed from runes in delims. mode can be .left, .right, or .ends.

func Array.'$call'(val any) Array

Converts a string to an byte Array.

^topic

type ArrayIterator #

^topic

type pointer #

func addr() int

Returns 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() any

Unsafe. Casts the pointer to a Cyber object. The object is retained before it's returned.

func fromCstr(offset int) Array

Unsafe. Returns an Array from a null terminated C string.

func get(offset int, ctype symbol) any

Unsafe. Dereferences the pointer at a byte offset and returns the C value converted to Cyber.

func set(offset int, ctype symbol, val any) none

Unsafe. Converts the value to a compatible C value and writes it to a byte offset from this pointer.

func toArray(offset int, len int) Array

Unsafe. Returns an Array with a copy of the byte data starting from an offset to the specified length.

func pointer.'$call'(val any) pointer

Converts a int to a pointer value, or casts to a pointer. This is usually used with FFI.

^topic

type ExternFunc #

func addr() int

Returns 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.

^topic

type Fiber #

func status() symbol

^topic

type metatype #

func id() int

^topic

math. #

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 float

Euler's number and the base of natural logarithms; approximately 2.718.

var inf float

Infinity.

var log10e float

Base-10 logarithm of E; approximately 0.434.

var log2e float

Base-2 logarithm of E; approximately 1.443.

var ln10 float

Natural logarithm of 10; approximately 2.303.

var ln2 float

Natural logarithm of 2; approximately 0.693.

var maxSafeInt float

The maximum integer value that can be safely represented as a float. 2^53-1 or 9007199254740991.

var minSafeInt float

The minumum integer value that can be safely represented as a float. -(2^53-1) or -9007199254740991.

var nan float

Not a number. Note that nan == nan. However, if a nan came from an arithmetic operation, the comparison is undefined. Use isNaN instead.

var neginf float

Negative infinity.

var pi float

Ratio of a circle's circumference to its diameter; approximately 3.14159.

var sqrt1_2 float

Square root of ½; approximately 0.707.

var sqrt2 float

Square root of 2; approximately 1.414.

func abs(a float) float

Returns the absolute value of x.

func acos(a float) float

Returns the arccosine of x.

func acosh(a float) float

Returns the hyperbolic arccosine of x.

func asin(a float) float

Returns the arcsine of x.

func asinh(a float) float

Returns the hyperbolic arcsine of a number.

func atan(a float) float

Returns the arctangent of x.

func atan2(a float, b float) float

Returns the arctangent of the quotient of its arguments.

func atanh(a float) float

Returns the hyperbolic arctangent of x.

func cbrt(a float) float

Returns the cube root of x.

func ceil(a float) float

Returns the smallest integer greater than or equal to x.

func clz32(a float) float

Returns the number of leading zero bits of the 32-bit integer x.

func cos(a float) float

Returns the cosine of x.

func cosh(a float) float

Returns the hyperbolic cosine of x.

func exp(a float) float

Returns 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) float

Returns subtracting 1 from exp(x).

func floor(a float) float

Returns the largest integer less than or equal to x.

func frac(a float) float

Returns the fractional or decimal part of a float value.

func hypot(a float, b float) float

Returns the square root of the sum of squares of its arguments.

func isInt(a float) bool

Returns true if the float has no fractional part, otherwise false.

func isNaN(a float) bool

Returns whether x is not a number.

func ln(a float) float

Returns the natural logarithm (㏒e; also, ㏑) of x.

func log(a float, b float) float

Returns the logarithm of y with base x.

func log10(a float) float

Returns the base-10 logarithm of x.

func log1p(a float) float

Returns the natural logarithm (㏒e; also ㏑) of 1 + x for the number x.

func log2(a float) float

Returns the base-2 logarithm of x.

func max(a float, b float) float

Returns the largest of two numbers.

func min(a float, b float) float

Returns the smallest of two numbers.

func mul32(a float, b float) float

Returns the result of the 32-bit integer multiplication of x and y. Integer overflow is allowed.

func pow(a float, b float) float

Returns base x to the exponent power y (that is, x^y).

func random() float

Returns a pseudo-random number between 0 and 1.

func round(a float) float

Returns the value of the number x rounded to the nearest integer.

func sign(a float) float

Returns the sign of the x, indicating whether x is positive, negative, or zero.

func sin(a float) float

Returns the sine of x.

func sinh(a float) float

Returns the hyperbolic sine of x.

func sqrt(a float) float

Returns the positive square root of x.

func tan(a float) float

Returns the tangent of x.

func tanh(a float) float

Returns the hyperbolic tangent of x.

func trunc(a float) float

Returns the integer portion of x, removing any fractional digits.

^topic

Std modules. #

Std modules come with Cyber's CLI. They include:

^topic

os. #

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 String

The current cpu arch's tag name.

var endian symbol

The current arch's endianness: .little, .big

var stderr File

Standard error file descriptor.

var stdin File

Standard input file descriptor.

var stdout File

Standard output file descriptor.

var system String

The current operating system's tag name.

var vecBitSize int

Default SIMD vector bit size.

func access(path String, mode symbol) none

Attempts to access a file at the given path with the .read, .write, or .readWrite mode. Throws an error if unsuccessful.

func args() List

Returns the command line arguments in a List. Each argument is converted to a String.

func cacheUrl(url String) String

Returns the path of a locally cached file of url. If no such file exists locally, it's fetched from url.

func copyFile(srcPath String, dstPath String) none

Copies a file to a destination path.

func createDir(path String) none

Creates the directory at path. Returns true if successful.

func createFile(path String, truncate bool) File

Creates and opens the file at path. If truncate is true, an existing file will be truncated.

func cstr(s any) pointer

Returns a null terminated C string.

func cwd() String

Returns the current working directory.

func dirName(path String) String

Returns the given path with its last component removed.

func execCmd(args List) Map

Runs a shell command and returns the stdout/stderr.

func exePath() String

Returns the current executable's path.

func exit(status int) none

Exits the program with a status code.

func fetchUrl(url String) Array

Fetches the contents at url using the HTTP GET request method.

func free(ptr pointer) none

Frees the memory located at ptr.

func getEnv(key String) String

Returns an environment variable by key.

func getEnvAll() Map

Returns all environment variables as a Map.

func malloc(size int) pointer

Allocates size bytes of memory and returns a pointer.

func milliTime() float

Return the calendar timestamp, in milliseconds, relative to UTC 1970-01-01. For an high resolution timestamp, use now().

func newFFI() FFI

Returns a new FFI context for declaring C mappings and binding a dynamic library.

func now() float

Returns the current time (in high resolution seconds) since an arbitrary point in time.

func openDir(path String) Dir

Invokes openDir(path, false).

func openDir(path String, iterable bool) Dir

Opens a directory at the given path. iterable indicates that the directory's entries can be iterated.

func openFile(path String, mode symbol) File

Opens a file at the given path with the .read, .write, or .readWrite mode.

func parseArgs(options List) Map

Given expected ArgOptions, returns a map of the options and a rest entry which contains the non-option arguments.

func readAll() String

Reads stdin to the EOF as a UTF-8 string. To return the bytes instead, use stdin.readAll().

func readFile(path String) String

Reads the file contents from path as a UTF-8 string. To return the bytes instead, use File.readAll().

func readLine() String

Reads stdin until a new line as a String. This is intended to read user input from the command line. For bulk reads from stdin, use stdin.

func realPath(path String) String

Returns the absolute path of the given path.

func removeDir(path String) none

Removes an empty directory at path. Returns true if successful.

func removeFile(path String) none

Removes the file at path. Returns true if successful.

func setEnv(key String, val String) none

Sets an environment variable by key.

func sleep(ms float) none

Pauses the current thread for given milliseconds.

func unsetEnv(key String) none

Removes an environment variable by key.

func writeFile(path String, contents any) none

Writes contents as a string or bytes to a file.

^topic

type File #

func close() none

Closes the file handle. File ops invoked afterwards will return error.Closed.

func iterator() any

func next() any

func read(n int) Array

Reads at most n bytes as an Array. n must be at least 1. A result with length 0 indicates the end of file was reached.

func readAll() Array

Reads to the end of the file and returns the content as an Array.

func seek(n int) none

Seeks the read/write position to pos bytes from the start. Negative pos is invalid.

func seekFromCur(n int) none

Seeks the read/write position by pos bytes from the current position.

func seekFromEnd(n int) none

Seeks the read/write position by pos bytes from the end. Positive pos is invalid.

func stat() Map

Returns info about the file as a Map.

func streamLines() File

Equivalent to streamLines(4096).

func streamLines(bufSize int) File

Returns an iterable that streams lines ending in \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) int

Writes a String or Array at the current file position. The number of bytes written is returned.

^topic

type Dir #

func iterator() DirIterator

Returns a new iterator over the directory entries. If this directory was not opened with the iterable flag, error.NotAllowed is returned instead.

func stat() Map

Returns info about the file as a Map.

func walk() DirIterator

Returns a new iterator over the directory recursive entries. If this directory was not opened with the iterable flag, error.NotAllowed is returned instead.

^topic

type DirIterator #

func next() any

^topic

type FFI #

func bindCallback(fn any, params List, ret symbol) ExternFunc

Creates an ExternFunc 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) any

Calls bindLib(path, [:]).

func bindLib(path any, config Map) any

Creates 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. If config contains genMap: true, a Map is returned instead with C-functions binded as function values.

func bindObjPtr(obj any) pointer

Returns 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) none

Binds a Cyber type to a C struct.

func cfunc(name String, params List, ret any) none

Declares a C function which will get binded to the library handle created from bindLib.

func new(ctype symbol) pointer

Allocates memory for a C struct or primitive with the given C type specifier. A pointer to the allocated memory is returned. Eventually this will return a cpointer instead which will be more idiomatic to use.

func unbindObjPtr(obj any) none

Releases 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.

^topic

type CArray #

^topic

type CDimArray #

^topic

map DirEntry #

keysummary
'name' -> ArrayThe name of the file or directory.
'type' -> #file | #dir | #unknownThe type of the entry.
^topic

map DirWalkEntry #

keysummary
'name' -> ArrayThe name of the file or directory.
'path' -> ArrayThe path of the file or directory relative to the walker's root directory.
'type' -> #file | #dir | #unknownThe type of the entry.
^topic

map ArgOption #

keysummary
'name' -> StringThe name of the option to match excluding the hyphen prefix. eg. -path
'type' -> metatype(String | float | boolean)Parse as given value type.
'default' -> anyOptional: Default value if option is missing. none is used if this is not provided.
^topic

test. #

The test module contains utilities for testing.

Sample usage:

import t 'test'

var a = 123 + 321
t.eq(a, 444)

func assert(pred any) none

Panics if pred is false.

func eq(a any, b any) bool

Returns whether two values are equal. Panics with error.AssertError if types or values do not match up.

func eqList(a any, b any) bool

Returns true if two lists have the same size and the elements are equal as if eq was called on those corresponding elements.

func eqNear(a any, b any) bool

Returns true if two numbers are near each other within epsilon 1e-5.

func fail() any

^topic

FFI. #

^top

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.

FFI context. #

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()
^topic

Declare functions. #

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;
}
^topic

Bind library. #

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.

^topic

Search path. #

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.

^topic

Configuration. #

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.

^topic

Finalizer. #

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.

^topic

Mappings. #

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.

BindingCyberC
.boolboolbool
.charintint8_t, signed char
.ucharintuint8_t, unsigned char
.shortintint16_t, short
.ushortintuint16_t, unsigned short
.intintint32_t, int
.uintintuint32_t, unsigned int
.longintint64_t, long long
.ulongintuint64_t, unsigned long long
.usizeintsize_t, uintptr_t
.floatfloatfloat
.doublefloatdouble
(1) .charPtrpointerchar*
.voidPtrpointervoid*
(2) type {S}type {S}struct
  1. Use os.cstr() and pointer.fromCstr() to convert between a Cyber string and a null terminated C string.
  2. The mapping from a Cyber object type S and the C-struct can be declared with cbind.
^topic

Bind to Cyber type. #

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:
    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)
^topic

Pointers. #

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'
^topic

cbindgen.cy #

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.

^topic

Error Handling. #

^top

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.

Error trait. #

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.

^topic

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()
^topic

Enum error. #

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
^topic

Throwing errors. #

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
^topic

Catching errors. #

^topic

try block. #

The try block catches thrown errors and resumes execution in a followup catch block:

try:
    funcThatCanFail()
catch err:
    print err      -- 'error.Failed'
^topic

caught variable. #

The contextual caught variable is used to reference the caught error: Planned Feature

try:
    funcThatCanFail()
catch:
    print caught   -- 'error.Failed'
^topic

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
^topic

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'
^topic

Value or error. #

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.'
^topic

Semantic checks. #

^topic

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
^topic

Requiring 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`.
^topic

Stack trace. #

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()
^topic

Unexpected errors. #

An unexpected error is an error that is not meant to be handled at runtime.

^topic

Panics. #

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.

^topic

Concurrency. #

^top

Cyber supports fibers as a concurrency mechanism. There are plans to support preemptive concurrency with async/await as well as multithreading.

Fibers. #

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.

^topic

Creating fibers. #

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.

^topic

Passing arguments. #

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.

^topic

Reset state. #

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"
^topic

Rebinding arguments. #

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...
^topic

Fiber block. #

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.

^topic

Pause and resume. #

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

^topic

Fiber state. #

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.

^topic

Gas mileage. #

Planned Feature

^topic

Async. #

Planned Feature

^topic

Multi-thread. #

Planned Feature

^topic

Type System. #

^top

Cyber supports the use of both dynamically and statically typed code.

Dynamic typing. #

Dynamic typing can reduce the amount of friction when writing code, but it can also result in more runtime errors.

^topic

my declaration. #

Variables declared with my are assigned the dynamic type:

my a = 123
^topic

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.

^topic

Invoking 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.
^topic

Dynamic return value. #

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.

^topic

Recent type inference. #

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
^topic

Static typing. #

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.

There are basic types that are built into Cyber and type declarations to create custom types.

^topic

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()
^topic

Typed variables. #

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

^topic

Null safety. #

The type checker does not allow using none with an operation. Instead, Optionals must be unwrapped to access the payload value.

^topic

Zero values. #

The following shows the zero values of builtin or created types.

TypeZero value
booleanfalse
int0
float0.0
String''
ArrayArray('')
List[]
Map[:]
type S[S:]
#host type SS.$zero()
dynamicOption.none
anyOption.none
?SOption(S).none
^topic

Functions. #

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.
^topic

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".
^topic

Invoking 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".
^topic

Type casting. #

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
^topic

Metaprogramming. #

^top

Operator overloading. #

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:
    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:
    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`
^topic

Builtin operators. #

A list of all supported operators:

OperatorName
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
^topic

Custom operators. #

Planned Feature

^topic

Magic functions. #

^topic

Call module. #

Declare a $call function to allow invoking a module as a function.

-- Object types are also modules.
type Vec2:
    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)
^topic

Getter/Setter. #

Planned Feature

^topic

Missing method. #

Declare a $missing method as a fallback when a method was not found in an instance.

Planned Feature

type A:

    func '$missing'(args...):
        return args.len

var a = [A:]
print a.foo()      -- Output: '0'
print a.bar(1, 2)  -- Output: '2'
^topic

Reflection. #

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'
^topic

Directives. #

Directives start with # and are used as modifiers.

#host

Modifier to bind a function, variable, or type to the host. See Embedding.

^topic

Generics. #

Generics enables parametric polymorphism for types and functions. Compile-time arguments are passed to templates to generate specialized code. This facilitates developing container types and algorithms that operate on different types.

See Custom Types / Generic types and Functions / Generic functions.

^topic

Macros. #

Planned Feature

^topic

Compile-time execution. #

Planned Feature

^topic

Builtin functions. #

func genLabel(name String)

Emits a label during codegen for debugging.

^topic

Builtin constants. #

var modUri String

Evaluates to the module's URI as a string. See Module URI.

^topic

Runtime execution. #

Planned Feature

^topic

Embedding. #

^top

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.

Getting started. #

^topic

Create VM. #

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;
}
^topic

Override 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() {
    // ...
    csSetPrinter(vm, print);
    // ...
}
^topic

Eval script. #

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.

^topic

Module Loader. #

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 .MyConstant float\n"
            "#host var .MyList     List\n"
            "\n"
            "#host\n"
            "type MyCollection:\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.

^topic

Default module loader. #

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.

^topic

Function loader. #

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.

^topic

Variable loader. #

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){".MyConstant", csFloat(1.23)};
    CsValue myInt = csInteger(123);
    vars[1] = (NameValue){".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.

^topic

Type loader. #

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.

^topic

Host functions. #

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.

^topic

Host types. #

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.

^topic

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 };
}
^topic

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");
}
^topic

Memory. #

^top

Cyber provides memory safety by default.

ARC. #

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.

^topic

Reference counting. #

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.

^topic

Optimizations. #

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.

^topic

Closures. #

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.

^topic

Fibers. #

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.

^topic

Heap. #

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.

^topic

Weak references. #

Planned Feature

^topic

Cycle detection. #

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
^topic

Backends. #

^top

JIT. #

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.

^topic

AOT #

Work on the ahead-of-time compiler has not begun.