Interpreter
Tue May 21 2024

The Brainterpreter includes the bauble interpreter binary, so you can run your source files directly.

Building interpreter binary

The source of interpreter cli is the src/bin/bauble.rs.
The normal cargo build does not build the cli by default. It only builds the brainterpreter library. The interpreter cli is a part of cli build feature.
Use this command to build the interpreter cli.
cargo build --features="cli"

Installing interpreter binary locally

You may want to install the binary locally for convenience. Cargo can help you to do so using the command.
cargo install --features="cli" --path .

Running bauble files

Create your source and save it with the bbl extension. E.g., you have a hello.bbl file with the source:
print "Hello, World!";
Run it with the command.
bauble hello.bbl run

Viewing virtual machine trace

The virtual machine provides a verbose diagnostic output while running the program. It produces the output in the trace logging level.
Enable the trace output by using the --trace flag of the interpreter cli.
bauble --trace hello.bbl run
Alternatively, you can enable the trace output by setting the RUST_LOG environment variable to trace level.
The example for nix systems:
RUST_LOG="trace" bauble hello.bbl
The diagnostic output of the VM looks includes instructions window and the stack.
[DEBUG brainterpreter::log] ================
1
[DEBUG brainterpreter::log] = instructions [DEBUG brainterpreter::log] 3: ST_L 0
2
[DEBUG brainterpreter::log] 4: CONST_F, 1 [DEBUG brainterpreter::log] 5:> LD_L 0
3
[DEBUG brainterpreter::log] ---------------- [DEBUG brainterpreter::log] = stack after
4
[DEBUG brainterpreter::log] 0: fn:$main$ [DEBUG brainterpreter::log] 1: s:- [DEBUG brainterpreter::log] 2: &[] [DEBUG brainterpreter::log] 3: f:0 [DEBUG brainterpreter::log] 4: f:0
1start of instruction window
2a few previous instructions for context
3current instruction
4state of the stack after the instruction execution
Note:Tracing makes program execution extremely slow.

Disassembling chunks

You can see the assembly representation of your code. Run the following command to print assembly code to the standard output.
bauble source.bbl disassemble

Example

Source code
let ending = "!";

fun greet(name) {
    let greeting = "Hello, ";
    let text = greeting + name + ending;
    return text;
}

print greet("World");
Assembly
fn:$main$:
constants:
	0000	s:!
	0001	s:ending
	0002	fn:greet
	0003	s:greet
	0004	s:World
code:
	0000	CONST, 0
	0001	ST_G, 1 # ending
	0002	POP
	0003	CONST, 2
	0004	ST_G, 3 # greet
	0005	POP
	0006	LD_G, 3 # greet
	0007	CONST, 4
	0008	CALL, 1
	0009	PRN

fn:greet:
constants:
	0000	s:Hello,
	0001	s:ending
code:
	0000	CONST, 0
	0001	ST_L, 1
	0002	LD_G, 1 # ending
	0003	LD_L, 0
	0004	LD_L, 1
	0005	ADD
	0006	ADD
	0007	ST_L, 2
	0008	LD_L, 2
	0009	RET
	000a	POP
	000b	POP
	000c	CONST_NIL
	000d	RET