Syntax Reference

A complete reference for every syntax construct in the Chuks language.

Variables and Constants

// Mutable variable
var name: string = "Chuks";
name = "New Name";

// Immutable constant
const pi: float = 3.14159;
// pi = 3.14; // Error: Cannot assign to const

// Type inference
var age = 25; // Inferred as int

Basic Data Types

Category	Types
Integers	int, int8, int16, int32, int64, uint, uint8, uint16, uint32, uint64, byte, rune
Floats	float, float32, float64
Complex	complex64, complex128
Boolean	bool (true, false)
String	string
Dynamic	any
Void	void (return type)
Nullable	T? — any type suffixed with ? (e.g., string?, int?, User?)

Nullable Types

Append ? to any type to allow null values:

var name: string? = null;    // nullable string
var count: int? = 42;        // nullable int
var user: User? = null;      // nullable dataType/class

function find(id: int): string? {
    if (id == 0) { return null; }
    return "found";
}

Type Conversions

Chuks provides Go-style builtin functions for converting between primitive types:

Function	Returns	Description	Example
int(value)	int	Convert to integer (truncates)	int(3.99) → 3
float(value)	float	Convert to float	float(42) → 42.0
string(value)	string	Convert any value to string	string(42) → "42"

// Float to int (truncates decimal)
var x: int = int(3.99)       // 3

// Int to float
var y: float = float(42)     // 42.0

// String to number
var z: int = int("123")      // 123
var w: float = float("3.14") // 3.14

// Any value to string representation
var s: string = string(42)     // "42"
var s2: string = string(true)  // "true"

// Boolean conversions
var b1: int = int(true)        // 1
var b2: int = int(false)       // 0
var b3: float = float(true)    // 1.0

Note

toString(value) also exists as a legacy alias for string(value). Prefer string() in new code.

Numeric Literals

Chuks supports decimal, hexadecimal, octal, and binary integer literals:

var dec = 255;           // Decimal
var hex = 0xFF;          // Hexadecimal (0x prefix)
var oct = 0o77;          // Octal (0o prefix)
var bin = 0b11111111;    // Binary (0b prefix)

Prefix	Base	Digits	Example
(none)	10	0-9	255
0x	16	0-9, a-f	0xFF
0o	8	0-7	0o77
0b	2	0-1	0b1010

Operators

Arithmetic

var a = 10 + 5;   // Addition
var b = 10 - 5;   // Subtraction
var c = 10 * 5;   // Multiplication
var d = 10 / 5;   // Division
var e = 10 % 3;   // Modulo

Comparison

var eq = (a == b);   // Equal
var ne = (a != b);   // Not equal
var gt = (a > b);    // Greater than
var lt = (a < b);    // Less than
var ge = (a >= b);   // Greater than or equal
var le = (a <= b);   // Less than or equal

Logical

var and = (a > 0 && b > 0);   // Logical AND
var or  = (a > 0 || b > 0);   // Logical OR

Increment / Decrement

var i = 0;
i++;   // i is now 1
i--;   // i is now 0

Compound Assignment

+= (add), -= (subtract), *= (multiply), /= (divide), %= (modulo). x op= y is shorthand for x = x op y.

var x = 10;
x += 5;   // x is now 15
x -= 3;   // x is now 12
x *= 2;   // x is now 24
x /= 4;   // x is now 6
x %= 4;   // x is now 2

+= also works for string concatenation:

var msg = "Hello";
msg += ", world!";   // "Hello, world!"

Bitwise

var a = 0xFF & 0x0F;   // Bitwise AND  → 15
var b = 0xF0 | 0x0F;   // Bitwise OR   → 255
var c = 0xFF ^ 0x0F;   // Bitwise XOR  → 240
var d = ~0;             // Bitwise NOT  → -1
var e = 1 << 8;         // Left shift   → 256
var f = 256 >> 4;       // Right shift  → 16

Operator	Name	Description
&	AND	Sets bit to 1 if both bits are 1
|	OR	Sets bit to 1 if either bit is 1
^	XOR	Sets bit to 1 if only one bit is 1
~	NOT	Inverts all bits
<<	Left shift	Shifts bits left (multiply by 2ⁿ)
>>	Right shift	Shifts bits right (divide by 2ⁿ)

Ternary Operator

var label = count == 1 ? "item" : "items";

// Nested (right-associative)
var grade = score >= 90 ? "A" : score >= 80 ? "B" : "C";

Built-in Functions

Function	Description
print(value)	Print a value to stdout
println(value)	Print a value followed by a newline
len(collection)	Return the length of an array, string, or map
copy(collection)	Return a shallow clone of an array or map
clear(collection)	Remove all elements from an array or map
delete(map, key)	Delete a key-value pair from a map
append(arr, ...items)	Append elements to an array and return it
int(value)	Convert a value to integer
float(value)	Convert a value to float
string(value)	Convert any value to its string representation
strings.fromCharCode(code)	Convert an integer char code to a single-character string (via import { strings } from "std/strings")

Collections

Arrays

var numbers: []int = [1, 2, 3];
var empty: []string = [];

// Access and modify
print(numbers[0]);
numbers.push(4);
numbers.pop();
print(numbers.length);

// Slice expressions (Go-style)
var sub = numbers[1:3];    // elements at index 1, 2
var head = numbers[:2];    // first two elements
var tail = numbers[2:];    // from index 2 to end

Maps

var scores: map[string]int = {
    "Alice": 95,
    "Bob": 88
};

scores["Charlie"] = 90;
var aliceScore = scores["Alice"];
scores.delete("Alice");
scores.keys();

DataType (Structs)

Lightweight data containers. Supports quoted keys for JSON compatibility.

dataType Point {
    x: int;
    y: int;
    "z-coord": int;
}

var p: Point = { "x": 10, "y": 20, "z-coord": 30 };

Classes

Basic Class

class Animal {
    var name: string

    constructor(name: string) {
        this.name = name
    }

    speak(): string {
        return "..."
    }
}

var a = new Animal("Rex")
println(a.speak())
println(a.name)

Inheritance

class Dog extends Animal {
    override speak(): string {
        return "Woof!"
    }
}

var dog = new Dog("Rex")
println(dog.speak()) // Woof!

Constructor Chaining

class Shape {
    var kind: string

    constructor(kind: string) {
        this.kind = kind
    }
}

class Circle extends Shape {
    var radius: int

    constructor(radius: int) {
        super("circle")
        this.radius = radius
    }
}

Multi-Level Inheritance

Chuks supports deep inheritance chains with proper super() chaining:

class Base {
    var value: int
    constructor(v: int) { this.value = v }
    function describe(): string { return "Base(" + string(this.value) + ")" }
}

class Middle extends Base {
    var label: string
    constructor(v: int, label: string) {
        super(v)
        this.label = label
    }
    override describe(): string {
        return "Middle:" + super.describe()
    }
}

class Top extends Middle {
    constructor(v: int) { super(v, "top") }
    override describe(): string {
        return "Top->" + super.describe()
    }
}

var t = new Top(42)
println(t.describe()) // Top->Middle:Base(42)

Access Modifiers

class BankAccount {
    private var balance: int = 0
    var owner: string

    constructor(owner: string, initial: int) {
        this.owner = owner
        this.balance = initial
    }

    public getBalance(): int {
        return this.balance
    }

    public deposit(amount: int) {
        this.balance = this.balance + amount
    }
}

Modifier	Access
public	Anywhere (default)
private	Declaring class only
protected	Declaring class and subclasses

Readonly Properties

class Config {
    readonly var appName: string
    var version: int = 1

    constructor(name: string) {
        this.appName = name
    }
}

Static Methods

class MathUtils {
    static add(a: int, b: int): int {
        return a + b
    }
}

println(MathUtils.add(3, 4)) // 7

Abstract Classes

abstract class Shape {
    abstract area(): float;

    describe(): string {
        return "I am a shape"
    }
}

class Rectangle extends Shape {
    var w: float
    var h: float

    constructor(w: float, h: float) {
        this.w = w
        this.h = h
    }

    override area(): float {
        return this.w * this.h
    }
}

Final Classes and Methods

final class Singleton {
    static getInstance(): string {
        return "instance"
    }
}
// class Child extends Singleton { }  // Error: cannot extend final class

class Base {
    final greet(): string {
        return "Hello"
    }
}
// Cannot override final methods in subclasses

Override Keyword

The override keyword is required when overriding a parent method. The compiler verifies the parent class has that method.

class Parent {
    greet(): string {
        return "Hello from Parent"
    }
}

class Child extends Parent {
    override greet(): string {
        return "Hello from Child"
    }
}

Interfaces

interface Runnable {
    run(): void;
}

class Runner implements Runnable {
    public function run(): void {
        print("Running...");
    }
}

Enums

enum Color {
    Red,
    Green,
    Blue
}

var c: Color = Color.Green;

Functions

function add(a: int, b: int): int {
    return a + b;
}

// Optional parameters with defaults
function greet(name: string, greeting: string = "Hello"): string {
    return greeting + ", " + name;
}
greet("Alice");           // "Hello, Alice"
greet("Alice", "Hi");    // "Hi, Alice"

Closures

function makeCounter(): any {
    var count = 0;
    return function(): int {
        count = count + 1;
        return count;
    };
}

var counter = makeCounter();
println(counter());  // 1
println(counter());  // 2

// Lambda
var multiply = function(a: int, b: int) { return a * b; };
println(multiply(3, 4));  // 12

Function Type with Named Parameters

Function type annotations can include parameter names for readability:

// Positional syntax (arrow)
var add: (int, int) => int = (a: int, b: int): int => a + b;

// Named parameter syntax (function keyword)
var greet: function(name: string): string = function(name: string): string {
    return "Hello, " + name;
}

// In callback position
function applyOp(a: int, b: int, op: function(x: int, y: int): int): int {
    return op(a, b);
}

Forward References

Functions and classes can be referenced before their declaration:

function main() {
    println(greet("World"));  // works — greet is defined below
}

function greet(name: string): string {
    return "Hello, " + name + "!";
}

Control Flow

Conditionals

if (x > 10) {
    print("Big");
} else if (x == 10) {
    print("Ten");
} else {
    print("Small");
}

While Loop

while (x > 0) {
    x = x - 1;
}

For Loop

for (var i = 0; i < 10; i++) {
    print(i);
}

// With compound assignment
for (var i = 0; i < 100; i += 10) {
    print(i);
}

For…of Loop (Arrays)

var fruits = ["apple", "banana", "cherry"];
for (var fruit of fruits) {
    println(fruit);
}

For…in Loop (Maps)

var scores: map[string]int = {"math": 90, "science": 85};
for (var key in scores) {
    println(key);
}

Switch

switch (x) {
    case 1:
        print("One");
        break;
    default:
        print("Other");
}

Error Handling

try {
    if (x < 0) {
        throw new Error("Negative value");
    }
} catch (e) {
    print("caught error: " + e.message);
} finally {
    print("clean up");
}

Concurrency

Async / Await

async function fetchData(): string {
    return "data";
}

var result = await fetchData();

Spawn

spawn(function() {
    print("Running in background");
});

Channels

import { channel } from "std/channel"

var ch: Channel = channel.new(1);

channel.send(ch, "hello");
var msg = channel.receive(ch);
println(msg); // "hello"

// Non-blocking operations
var result = channel.tryReceive(ch);
var sent = channel.trySend(ch, 42);

channel.close(ch);

Function	Description
channel.new(size?)	Create channel (default buffer 0)
channel.send(ch, value)	Blocking send
channel.receive(ch)	Blocking receive
channel.close(ch)	Close channel
channel.tryReceive(ch)	Non-blocking receive → {value, ok}
channel.trySend(ch, value)	Non-blocking send → true/false

Modules

// Exporting
export class MyClass { ... }
export function myFunction() { ... }

// Importing
import { MyClass, myFunction } from "./myModule";

Pointers

var x: int = 10;
var p: *int = &x;
print(*p); // 10

Comments

// Single-line comment

/*
   Multi-line
   comment
*/

Runtime Error Messages

Chuks provides source-mapped error messages with file name and line number:

test.chuks:14: property 'missing' not found on map
test.chuks:10: division by zero
test.chuks:5: unsupported operator for types