buzz-language/buzz

👨‍🚀 buzz, A small/lightweight statically typed scripting language

👨‍🚀 buzz

A small/lightweight statically typed scripting language written in Zig

Homepage — Discord

Features

• Small in size and complexity (just a bit more than Lua though)
• Statically typed
• Unambiguous
• No nonsense coercion
• Fibers
• JIT compilation with MIR
• Tooling
  • Generate doc from docblocks (in progress)
  • VS Code extension
    • Syntax highlighting
    • LSP (in progress)
    • Debugger and DAP (planned)

How to build and install

Latest zig version supported: 0.12.0-dev.3245+4f782d1e8

Requirements

• Since this is built with Zig, you should be able to build buzz on a wide variety of architectures even though this has only been tested on x86/M1.
• Linux or macOS (Windows support is coming)
• libc
• zig master

Build

1. Clone the project: git clone https://github.com/buzz-language/buzz <buzz_dir>
2. Checkout submodules: git submodule update --init
3. Build MIR:

cd vendors/mir
make

4. Have fun: zig build run -- <myscript.buzz>

Install

# install locally at ~/.local
zig build -Doptimize=ReleaseSafe install -p ~/.local

# install globally at /usr/local
sudo zig build -Doptimize=ReleaseSafe install -p /usr/local

If you're usage if performance critical (game dev for example), you can build using -Doptimize=ReleaseFast.

Remember to modify PATH to include the bin directory where it is installed. For example, export PATH=PATH:/home/xxx/.local/bin. You can then run buzz with buzz <myscript.buzz>. Or you can simply run buzz to start the REPL.

Additionally, install the VS Code extension to get syntax highlighting. If you don't use VS Code but your editor supports TextMate grammar files, you can use that.

buzz's Issues

Object methods and native functions can't have default arguments

At codegen, we don't have access to the ParseNode which holds the default arguments nodes.

Argument default value for native calls

Default arguments for native call

Ranges

list[1..10] == list.sub(1,10);

[int] myRange = 1..10;

foreach (int i in 1..10) {
    | ...
}

list lib

• append(X value): append new element to end of list
• len: returns length of list
• next(num index) > ?num: returns next index in list after index or null if end of list is reached (used by foreach)
• remove(num index): remove element at index and shifts items
• sub(num start, num? len) > [X]
• indexOf(X element) > num?
• concat
• join(str? separator) > str

Globals as upvalues

When exported, a function should capture global it uses.
Right now we juste take the whole script globals for the ride.

This would not be needed if we do https://github.com/buzz-language/buzz/issues/215

gc lib

• gc.allocated
• gc.collect

Generational GC

Generational GC

Do not crash after compile error

Right now we continue parsing/codegen after reporting errors and almost always end up crashing buzz.
Go over each error reporting and see how it must be handled: either stopping everything or providing enough details so buzz does not crash going forward.

Wrong error location when error occured in imported script

We show code from the entry point script rather than the revelant script

Don't duplicate chunk constant with the same value

num hello = 42;
num bonjour = 42; | -> should be the same constant

String are not concerned since they are interned.

(Co)routines

Implement coroutines

import "lib/std";

fun main() > void {
    | Async call, creates a new routine (new VM instance), count is not yet executed
    rti<str, num> counter = async count(10);

    | A routine is over when a OP_RETURN as been executed
    while (!counter.over()) {
        print("counter is {resume counter}");
    }
    
    assert(counter.over(), message: "Routine should be over now");
    
    | await either runs the routine until completion or get the return value of a terminated routine
    | if the function yields but is never resumed when we reach the await, yields value are dismissed (?)
    print(await counter);
}

| returns str, yields num
fun count(num n) > str > num {
    for (num i = 0; i < n; i = i + 1) {
        | error or yield is ignored if not called with a async call?
        yield i;
    }

    return "Counting is done!";
}

math lib

• math.abs
• math.acos
• math.asin
• math.atan
• math.ceil
• math.cos
• math.deg
• math.exp
• math.floor
• math.log
• math.max
• math.min
• math.pi
• math.rad
• math.random
• math.sin
• math.sqrt
• math.tan

os lib

• os.time(): epoch time in ms
• os.env(str key) > str: returns env variable named key
• os.execute([str] command) > num: execute command and return its exit code
• os.tmpDir() > str: returns path to system temp directory
• os.tmpFilename() > str: returns a temporary file name in system tmp dir
• os.exit(num exitCode) > void: exits program with exitCode

Tail calls

Tail calls

REPL

REPL

If no matching catch clause, raise the error

Right now if there's a catch that don't match the error is still considered caught

Userdata

New type that can hold on pointer to something outside the VM (like Lua's userdata).

Import search strategy

• path to search and which order
• support dylib, .a and .dll

Debug metadata and api

Debug metadata and api

`throw` is not taken into account when determining if there's a missing `return`

This should be valid:

fun hello() > bool {
    if (condition) {
        return true;
    } else {
        throw "an error";
    }
}

json lib

Something similar to https://github.com/SwiftyJSON/SwiftyJSON

LSP

LSP

https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/

std lib

• assert(bool condition, str message)
• print(str message)
• parseNumber
• runFile(str path): runs file in a separate VM state

string lib: pattern matching (pcre regex)

• Pattern new type: pat pattern = _^hello$_;
• Allow pattern initialization with a string pat pattern = "^with a string$";

pat methods are:

• pattern.match(str subject) > [str]: Returns the first match and eventual captures
• pattern.matchAll(str subject) > [[str]]: Returns all matches and captures
• pattern.replace(str subject, str replacement) > str: Replaces first match with replacement
• pattern.replaceAll(str subject, str replacement) > str: Replaces all matches with replacement
• handle named capture

str methods:

• string.match(pat pattern) > [str]: same as pattern.match
• string.matchAll(pat pattern) > [str]: same as pattern.matchAll
• string.replace(pat pattern) > [str]: same as pattern.replace
• string.replaceAll(pat pattern) > [str]: same as pattern.replaceAll
• When #54 is done, string.match and pattern.match should return iterators.

Constant expressions

Would allow for instance, to have more complex function default parameters

fs lib

• fs.cwd() > str: returns current directory absolute path
• fs.mkDir(str path): creates directory path
• fs.rm(str path): deletes directory or file at path
• fs.move(str from, str to): moves/renames file at from to to
• fs.ls(str path) > [str]: list files under path

map lib

• next(X key) > X: returns next key after key (used by foreach)
• remove(X key) > X: removes entry under key and returns it
• size() > num: returns number of entries in the map
• merge
• keys(): returns list of the map keys
• values(): return list of the map values

UTF8 str

• string.utf8Len(str string) > num
• string.codepoint(num index) > str

Forbid use of command line arguments if not specified in `main` signature

Or: require main to always be fun main([str] args) > num.

Docblock

Keep docblocks in AST so we can reuse it to generate documentation:

|| This is a cool utility object
object MyObject {
    || Says hello
    || @param name To whom you say hello
    fun sayHello(str name) > void -> print("hello {name}"),
}

str lib

• subscript
• iterable
• len() > num
• sub(num start, num len) > str
• indexOf(str needle) > num?
• split(str separator) > [str]
• byte(num at) > num

Forbid use of `break` outside of a loop

Forbid use of break outside of a loop

First class types

First class types

type myType = <str>;

fun handleAnything(any value) -> typeOf(value) == myType;

• Types as value
• typeof operator

Edge cases:

• We would expect a reference to MyObject to be a type, but it's not. It's a reference to the value ObjObject. So user whishing to get the MyObject type would have to do: typeof MyObject.
• On the other hand, a foreign struct is an ObjTypeDef at runtime so we don't need the typeof operator to get its type.
• Same for Protocol whose runtime representation is also an ObjTypeDef

Function signature specify if/what errors are thrown

fun iCanFail() > !num {
    | ...
}

Two pass compilation

Placeholder system can't handle every case so we're forced to do 2 passes:

1. First pass for typing
2. Second pass for bytecode generation and type checking

Generate documentation from comments

| Do something complex
| @param str input - something to do complex things with
| @return something complex
fun complex(str input) > str {
    | ...
}

Anonymous objects

fun delta(num mul) > obj{ num x, num y } {
    return .{
        x = 10 * mul,
        y = 12 * mul,
    };
}

obj{ num x, num y } newPoint = delta(10);

Should not allow methods or static fields.

Constant object/class properties

object A {
    const num assignedOnce;
}

Default function arguments values

| optional default value is always null
fun myFunction(str name = "Joe", num? age) > str {
    if (age != null) {
        return "{name} is {age}";
    }

    return "{name} is ageless";
}

| valid calls
myFunction();
myFunction("John");
myFunction(age: 12);

`defer`

Zig-like defer keyword that will execute an expression just before exiting the current function.

fun main() > void {
    File file = File.open("hello", mode: FileMode.read);
    defer file.close();

    |...
}

Native function should be able to be stored in variables

Right now this does not work:

import "lib/std.buzz";

Function(str) > void p = print;

Inline `export`

Be able to export something when declaring it like so:

export num exportMe = 42;

`object`/`class` collectors

Special method that will be called when the object is collected:

object File {
    | ...

    fun collect() {
        this.close();
    }
}

io lib

• stdin, stderr, stdout
• File
• File.open
• File.close
• File.readAll
• File.readLine
• File.write
• File.read(num n) > ?str: reads n bytes, returns null if EOF

Proper cli

👨‍🚀 buzz A small/lightweight typed scripting language written in Zig

usage: buzz [options] [command] script.buzz [args]

Available options are:
    --dump                      Dump bytecode
    --dump-ast                  Dump AST tree
    --debug                     Show debug logs
    --debug-stack               Dump stack after each executed bytecode
    --debug-gc                  Show GC related logs
    --debug-current-instruction Show bytecode being executed
    --debug-perf                Show time to parse, codegen and run the script
    --debug-stop-on-report      Stop compiling on the first encountered error

Available commands are:
    version Print version number and exit
    test    Run test blocks in the provided script
    run     (default) Run script

Function argument default value

Be able to provide default value to function arguments:

fun myFunction(str hello = "world") { ... }

User data

Special type wrapping an opaque pointer

Bound functions definition omits this argument

MyObj{}.bound is Function() > bool -> MyObj{}.bound is Function(MyObj) > bool

Map subscript should return nullable

Map subscript should return null if key does not exists.

Catch clauses should be blocks

Right now they are functions so we can't do:

fun hello() > bool {
    willFail() catch {
        | here we return from this catch clause instead of returning from the enclosing function
        default -> return false;
    }

    return true;
}