Runs faster than CPython.
BANDIT Language Specification
Nov 4, 2026 @Jesse
Overview
BANDIT is an ahead-of-time compiled language that reads like Python, runs like a systems language, and exposes the machine like assembly. Source compiles straight to native code for x86-64 and AArch64, with no VM and no interpreter. File extension: .bt. Command: bandit build main.bt produces one static binary.
The borrowed pieces:
- Python: indentation blocks, terse syntax,
and/or/not, f-strings.
- Go:
thread (goroutine-style), channels, one static binary.
- BASIC:
goto, gosub, print, input, labeled sections instead of functions, no declarations.
- Assembly: inline
asm blocks, peek/poke, bit operations, wrapping arithmetic.
Speed comes from one bet: the compiler sees the whole program at once (every file in the folder plus every URL import), and every variable is global, so it can infer one concrete type for most variables and emit unboxed native instructions. A tagged-value slow path exists only for variables that really change type.
Where your requirements collide
Several requirements pull against each other or against speed. Each is resolved below.
| Conflict |
Resolution |
| No functions vs. reusable code |
Code lives in labeled sections written [section-title], with the code indented beneath. goto [x] jumps there, gosub [x] jumps and remembers where to come back to, and a section returns to its caller when its indented block ends. Values pass through ordinary global variables, by naming convention. |
| All variables global vs. recursion and threads |
Now without exception: one variable per name, shared by every thread, with no per-call copies. Recursion is possible by keeping your own stack in a JSON array (using append and remove) around a gosub. Threads coordinate with lock, atomic and channels. |
| Types on the fly vs. speed |
Whole-program inference. Each variable’s type is the union of everything ever assigned to it. One type means unboxed native storage; two or more means a 64-bit tagged word with runtime dispatch. |
| Infinite numbers vs. speed |
int is one type. Values that fit in 62 bits are immediates; arithmetic checks for overflow and promotes to a heap bigint. Range analysis removes the check where the compiler can prove it is unnecessary. “Infinite” means limited only by memory. Floats stay IEEE binary64. |
| Auto-import every file vs. name clashes |
Every file is a namespace for its variables and its sections. Bare names resolve in the current file first, then to a unique match elsewhere. Ambiguity is a compile error, not a silent override. |
| Import from URL vs. safety |
Remote files are fetched at compile time only, pinned by SHA-256 in a lockfile, and barred from asm, peek, poke and the low-level schemes by default. |
goto vs. optimization |
Section titles can only appear at column 0, so a jump can never land in the middle of an indented block. Jumping out of blocks is allowed. This keeps the control-flow graph analyzable. |
Syntax
- Blocks: one tab per level; spaces in indentation are a compile error. A line ending in
: opens a block.
- Comments:
to end of line.
- Statements: one per line;
separates several on one line; an open bracket or a trailing \ continues a line.
- Assignment:
x = 1, augmented forms (x += 1), and tuple form (a, b = b, a). There are no declarations; the first assignment creates the variable.
- Member access: JSON objects use dot notation,
user.name, user.address.city, and it chains with brackets: user.langs[0]. Brackets with a string, user["first name"], handle keys that are not plain names or are computed at run time. A member name after a dot may be any word, including a keyword. Reading a path that does not exist yields null at every step. Writing to a path creates any missing intermediate objects. A dot followed by a name and parentheses is a method call (see Operations by type). Member access without parentheses on a value that is not JSON (an int, a string) is a compile error where the type is known, and a runtime error otherwise.
- Operators:
+ - * / , bitwise & | ^ ~ << >>, wrapping 64-bit +% -% *%, comparison == != < <= > >=, logic and or not.
- Sections:
[section-title] alone on a line at column 0, with the section’s code indented one level beneath it. Targets of goto, gosub and thread. Code at column 0 outside sections is the file’s top-level flow, which starts at the first line and skips over section blocks. A line consisting only of a bracketed title is always a section title; a bare array literal is not a valid statement, so there is no ambiguity.
- Numbers:
42, 1_000_000, 0xFF, 0b1010, 3.14, 1e-9. Integer literals may have any number of digits.
- Strings:
"text" or 'text' with escapes, f"x = {x}" interpolation, r"raw", triple-quoted multiline.
- Bytes:
b"\x00\xff".
- JSON: written directly as literals:
{"a": [1, 2, null, true]}.
- Keywords:
if elif else while break continue goto gosub thread join yield lock atomic send recv close import asm exit and or not true false null print input line.
Types
Five types, as requested. Booleans are JSON values (true, false), not a sixth type.
| Type |
Representation |
Literal |
Notes |
| int |
62-bit immediate, promoted to heap bigint on overflow |
42, 10**1000 |
Exact; never wraps unless you use +% -% *%. |
| float |
IEEE-754 binary64 |
3.14, 1e-9 |
Not arbitrary precision. A bigint too large for a double raises a runtime error instead of becoming inf. |
| string |
Immutable UTF-8 |
"hi" |
len(s) counts bytes; s[i] is the byte at offset i (an int), as in Go. s.runes() returns an array of code points. |
| bytes |
Mutable contiguous buffer |
b"\x01" |
b[i] is an int 0-255; slices copy. |
| JSON |
Tagged tree: null, bool, number, string, array, object |
{"k": [1, 2]} |
The only container type. Objects keep insertion order. A missing key reads as null; an out-of-range array index is a runtime error. |
Inference rules
- Literals have the types above.
int / int is float; use for integer division.
int op float gives float. string + string and bytes + bytes concatenate. string * int repeats. string + int is an error: conversions are explicit (str(), int(), float(), bytes(), parse_json()).
- A variable’s type is the union of the types of every assignment to it across the whole program. A single type compiles to unboxed storage. A union compiles to a tagged word.
- Where the compiler can prove a variable has one type within a loop or branch, it splits the variable’s live ranges and uses native types there even if the variable is a union elsewhere.
- An operation invalid for every possible type is a compile error. One invalid for only some types gets a runtime check.
- Truthiness follows Python:
false, null, 0, 0.0, empty string, empty bytes, empty array and empty object are false.
- A variable read before any assignment holds the zero value of its type (
0, 0.0, "", empty bytes, null). There is no undefined behavior.
input guesses the type of what the user typed: 42 becomes int, 3.5 float, [1,2] JSON, anything else string. line reads the raw text as a string.
Operations by type
Type-specific operations are methods, called as value.name(args) and chainable (s.trim().upper()). A dot followed by a name and parentheses is always a method call. A dot without parentheses is JSON member access, so obj.keys() calls the method and obj.keys reads the key "keys". A float literal needs a digit after the dot, so 10.abs() calls a method on the int 10.
Operations that apply to several types, or that build a value, stay functions: len(x), str(x), copy(x), type(x), min(a, b), max(a, b), int(s, base), float(s), bytes(n), from_hex(s), from_base64(s) and parse_json(s). type(x) returns "int", "float", "string", "bytes", "null", "bool", "array" or "object". Every type also supports ==.
Methods on ints, floats and strings return a new value, because those types are immutable. Methods that mutate a JSON value or a bytes buffer (append, insert, remove, fill, copy_into, set_*) change it in place. A method that does not exist for the receiver’s type is a compile error where the type is known and a runtime error otherwise.
Slices and negative indexes. x[a:b] copies a range of a string, bytes value or array; either bound may be omitted. A negative index counts from the end, so x[-1] is the last element. String slices use byte offsets and must fall on UTF-8 boundaries.
Sharing. Assigning a JSON array, JSON object or bytes buffer shares it instead of copying it: after b = a, both names refer to the same value. copy(x) makes an independent deep copy. Ints, floats and strings are immutable, so sharing is invisible for them.
int
| Method |
Result |
x.abs() |
Absolute value |
x.pow(b, m) |
x to the power b, modulo m, without building the huge intermediate value |
x.gcd(y), x.lcm(y) |
Greatest common divisor, least common multiple |
x.isqrt() |
Integer square root, rounded down |
x.bit_length() |
Number of bits in the magnitude |
x.hex(), x.bin() |
Text in base 16 or base 2 |
x.chr() |
The one-character string for this code point |
Ints also accept every float method below and convert first, so 16.sqrt() is 4.0. Where both define a method, as with abs, the int version applies.
float
| Method |
Result |
x.floor(), x.ceil(), x.trunc() |
Round toward minus infinity, plus infinity, zero. The result is an exact int, even for huge floats |
x.round(), x.round(digits) |
Round half to even; an int without digits, a float with it |
x.abs() |
Absolute value |
x.sqrt(), x.exp(), x.log(), x.log2(), x.log10() |
Square root, exponential, natural and base-2 and base-10 logarithms |
x.sin(), x.cos(), x.tan(), y.atan2(x) |
Trigonometry, in radians |
x.isnan(), x.isinf() |
true or false |
PI, E, INF, NAN |
Predefined constants |
string
| Method |
Result |
s + t, s * n |
Concatenate, repeat (operators) |
s.upper(), s.lower() |
Case conversion |
s.trim() |
Remove whitespace from both ends |
s.split(sep), s.lines() |
JSON array of strings, split on sep or on newlines |
s.replace(old, new) |
Replace every occurrence |
s.find(sub) |
Byte offset of the first occurrence, or -1 |
s.contains(sub), s.starts_with(sub), s.ends_with(sub) |
true or false |
s.runes(), s.ord() |
Array of code points; the code point of a one-character string |
s.encode() |
The UTF-8 bytes |
bytes
| Method |
Result |
b + c, b[a:c] |
Concatenate, copy a range (operators) |
b.decode() |
UTF-8 string; a runtime error if the bytes are invalid |
b.hex(), b.base64() |
Hex or base64 text. from_hex(s) and from_base64(s) go the other way |
b.find(sub) |
Offset of the first occurrence, or -1 |
b.fill(v) |
Set every byte to v |
b.copy_into(at, src) |
Write src into b starting at offset at |
b.get_u16(at), b.get_u32(at), b.get_u64(at) |
Read a little-endian integer; add _be to the name for big-endian |
b.set_u16(at, v), b.set_u32(at, v), b.set_u64(at, v) |
Write a little-endian integer; add _be to the name for big-endian |
bytes(n) makes a zero-filled buffer of n bytes.
JSON
| Method |
Result |
arr.append(v), arr.insert(i, v) |
Add at the end, add at an index |
j.remove(k) |
Delete an index or a key and return the removed value |
obj.keys(), obj.values() |
Arrays of the keys or values, in insertion order |
obj.has(key) |
true or false; unlike reading the key, it tells a stored null from a missing key |
arr.contains(v), arr.index(v) |
Membership; position or -1 |
arr.sorted(), arr.reversed() |
New arrays |
arr.sum(), arr.min(), arr.max() |
Over an array of numbers |
arr.join(sep) |
Join an array of strings with sep |
a.merge(b) |
New object with b’s keys layered over a’s |
j.to_json(), j.pretty() |
Serialize compactly or indented. parse_json(s) goes the other way |
len(j) gives the number of elements of an array or keys of an object.
Variables, namespaces and sections
Namespaces. Each source file is a namespace for its variables and sections. The entry file is the root namespace, so x in main.bt is the program-wide x. In geo.bt, a bare x means geo.x, and [area] means [geo.area]. Anything anywhere is reachable by qualified name: geo.x, [geo.area].
Namespaces versus members. Dots serve both purposes, so a dotted name such as a.b.c is resolved left to right. If a is the name of a file namespace, a.b is that file’s variable b, and .c is a member of its JSON value. Otherwise a is an ordinary variable and .b.c are members of its JSON value. A variable may not share its name with a file namespace; that is a compile error.
Sections. There are no user-defined functions. The program starts on the first line of the entry file and runs downward at column 0, like a BASIC program. A section is a title alone on a line at column 0, written [section-title] (letters, digits, _, -, .), followed by its code indented one level. Straight-line flow skips over section blocks: a section runs only when entered by goto, gosub or thread.
square_in = 12
gosub [square]
print square_out
[square]
square_out = square_in * square_in
- Top-level flow. Reaching the end of the entry file ends the program with status 0.
goto [x] jumps to a section. gosub [x] jumps and pushes the return point on the thread’s return stack.
- Ending a section. There is no
ret. When control reaches the end of a section’s indented block, or executes a break that is not inside a loop, the thread pops the return stack and continues after the gosub that led there. If the stack is empty the thread ends, and when that is the main thread the program ends with status 0. Control never falls into the next section. A section entered by goto from inside a gosub therefore returns to that gosub’s caller.
- Leaving early. Outside a loop,
break ends the section immediately, exactly as reaching its end, and continue restarts the section from its first line without touching the return stack. Inside a while loop they keep their usual meaning for the innermost loop. At top level, outside any loop or section, they are compile errors. exit ends the whole program from anywhere.
- Passing values. There are no parameters or return values. By convention a section reads variables named
section_in and writes section_out. The compiler does not check this.
- Recursion. There is no data-stack statement. A section that calls itself keeps its own stack in a JSON array:
stack.append(n) saves a value and n = stack.remove(-1) restores it (see the Fibonacci example below). Because every variable is global, a stack shared by two threads is shared state, so give each thread its own stack variable. Forgetting to restore a variable is your bug, as in assembly.
- Built-ins such as
len() and str() are compiler intrinsics. You cannot define your own functions.
Control flow and I/O
if x > 10:
print "big"
elif x > 5:
print "medium"
else:
print "small"
while n > 0:
n -= 1
if n == 3:
continue
if n == 1:
break
i = 0
while i < len(items):
print items[i]
i += 1
gosub [setup]
goto [done]
[setup]
ready = true
[done]
print "finished"
break and continue act on the innermost enclosing loop or section. In a loop, break leaves the loop and continue starts the next iteration. In a section but outside any loop, break ends the section (returning to its gosub caller, or ending the thread) and continue restarts the section from its first line:
[drain]
if queue_len == 0:
break # leave [drain] now
queue_len -= 1
continue # run [drain] again from the top
print a, b, c writes the values separated by single spaces plus a newline. JSON values print as compact JSON. A trailing comma (print a, b,) suppresses the newline. The name write is reserved for the file built-in, so there is no separate no-newline statement.
input [prompt,] name shows the optional prompt, reads one line, and assigns it with its type guessed (see Types, rule 8). line [prompt,] name assigns the raw text as a string.
exit ends the whole program immediately with status 0, from any section, loop or thread. Other threads are stopped, open handles are closed and buffered output is flushed. It takes no argument, so there is no way to report a different status.
Concurrency
t = thread [name] starts the section on a new lightweight thread and returns a handle. The thread ends when the section’s block ends with an empty return stack. There are no arguments: pass work through variables or channels.
join t waits for a thread. yield gives up the CPU voluntarily.
- Channels:
c = chan(8) creates a buffered channel (chan(0) is unbuffered). send c, v and v = recv c carry any value. close c ends it, after which recv returns null.
lock name: runs the indented block holding a mutex named name.
atomic x += 1 performs the update as one indivisible operation. It works on int variables that fit in a machine word.
Memory model. Every variable is shared by every thread; only the return stack is per thread. Reads and writes of a single int, float, string or pointer-sized value are atomic, so racy code cannot corrupt the runtime. Compound mutation of a shared JSON value or bytes buffer without a lock is a data race and its result is unspecified. Two threads running the same section share every variable it writes, so give each thread its own section, or hand out work through a channel and keep a thread’s working state in the values it receives.
Runtime. An M:N scheduler with work stealing multiplexes threads over OS threads, one per core by default. Thread stacks start small and grow.
Low-level features
Local files need no opt-in to use anything in this section. Imported files may not use it unless you build with --allow-unsafe-remote.
- Raw memory:
peek8/16/32/64(addr) and poke8/16/32/64(addr, v). addr(b) returns the address of a bytes buffer’s first byte; the buffer stays pinned while referenced.
- Bit tools:
rol, ror, popcount, clz, ctz, u64(x) and i64(x) (truncate a bigint to 64 bits), plus the wrapping operators +%, -%, *% that compile to a single machine instruction. These are for hashing, checksums and codecs, where the exactness of int would only cost time.
- Inline assembly:
a = 40
b = 2
c = 0
asm x86_64 clobbers rax:
mov rax, [a]
add rax, [b]
mov [c], rax
asm aarch64 clobbers x0, x1:
ldr x0, [a]
ldr x1, [b]
add x0, x0, x1
str x0, [c]
asm else:
c = a + b
print c
[name] refers to a variable’s storage (it appears only inside an indented asm block, so it never clashes with a section label). The compiler allows it only for variables it has proven to be a single native type that fits a machine word (small int, float, or a bytes address); otherwise it is a compile error that names the variable. The block matching the target architecture is used, and asm else: is a portable fallback written in BANDIT. If none matches and there is no else, compilation fails.
Modules and imports
Folder auto-import. When you build main.bt, every .bt file in its folder and subfolders is compiled into the program with no import statement. Folders whose names start with . or _ are skipped. A file’s namespace is its path relative to the entry file, with dots for slashes: util/text.bt becomes util.text.
- Use a section or variable in another file by qualified name (
gosub [util.text.trim], util.text.trim_in), or by bare name (gosub [trim]) when exactly one file defines it and the current file does not.
- Two files defining the same bare name is only an error if you use that bare name from a third file; qualified access always works.
- Each library file’s top-level flow runs once before the entry file’s, in alphabetical path order, and ends at the end of that file. Libraries should expose sections rather than rely on top-level side effects.
URL import.
import "https://example.com/vec.bt" as vec sha256 "9f2c...e41"
vec.a = [1, 2]
vec.b = [3, 4]
gosub [vec.dot]
print vec.out
- HTTPS only. The file is fetched at compile time, never at run time, and cached under
.bandit/cache/.
bandit.lock records each URL and its SHA-256. With a sha256 clause, a mismatch is a compile error. Without one, the first build records the hash and prints a warning (trust on first use); later builds enforce it.
- A remote file may import other URLs, and each is locked the same way.
bandit build --offline uses the cache only.
- Remote files may not use
asm, peek, poke or the low-level schemes (see System interface) unless you build with --allow-unsafe-remote.
- The namespace is the
as name, or the file name without extension.
Hash pinning guarantees that the code does not change under you. It does not make unknown code safe: an imported library runs with the full privileges of your program.
System interface
BANDIT reaches the operating system through five built-in calls. Every resource, from a text file to a raw system call, is named by a URI string, and supporting a new kind of resource means adding a scheme, never a new function. A string with no scheme is a file path, so read("notes.txt") works. Most schemes are conveniences. Two are universal: syscall:// makes any operating-system call and lib: calls any function in any dynamic library, so the five calls reach the whole machine.
The five calls
| Call |
Does |
open(uri, mode, opts) |
Opens a resource and returns a handle (an int), or null on failure. mode is "r", "w" (create or truncate), "a" (append) or "rw". opts is an optional JSON object of scheme-specific settings such as timeout, baud, endpoint or args. |
read(x, n, at) |
x is a handle or a URI. Returns up to n bytes, or everything up to the end when n is omitted. Structured resources return JSON or a string instead. at reads from an offset. Given a URI, it opens, reads and closes. |
write(x, data, at) |
Writes to a handle or URI and returns the byte count. Bytes and strings are written as they are, numbers as text, arrays and objects as compact JSON. Given a URI, it opens in "w" mode, writes and closes. Writing a JSON object to meta: sends a command. |
close(h) |
Releases a handle. Closing twice is harmless. |
delete(uri, recursive) |
Removes a file, symlink, empty directory, named pipe, shared-memory object or registry key. With recursive true, removes a whole directory tree. |
A failed call returns null. The reason for the thread’s most recent failure is read("err://"). Handles are plain ints, valid in every thread.
Control commands. Anything beyond reading and writing goes through meta:. Reading it returns the handle’s details (kind, uri, position, address for memory, pid and status for processes, and result of the last command). Writing a JSON object sends a command. The strings "kill", "shutdown" and "flush" are shorthand.
| Command |
Does |
{"rename": "new"} |
Move or rename the file or directory the handle names |
{"link": "new"}, {"symlink": "new"} |
Create a hard link or a symbolic link at new |
{"chmod": "644"}, {"chown": {"user": "x", "group": "y"}} |
Change permission bits or owner |
{"truncate": n}, {"sync": true} |
Set the file size; flush it to disk |
{"lock": "exclusive", "wait": true} |
Take a file lock; the mode is "shared", "exclusive" or "unlock" |
{"ioctl": [request, arg]} |
Device control; arg is an int or bytes, and the result lands in result |
{"signal": "TERM"}, {"wait": true} |
Send a signal to a process handle; block until it exits |
{"shutdown": "write"} |
Close one direction of a socket: "read", "write" or "both" |
{"sockopt": {"nodelay": true}} |
Set socket options such as nodelay, keepalive, broadcast, ttl or join for multicast |
{"protect": "rx"} |
Change the protection of a mem: region to any of r, w, x |
{"timeout": 5} |
Set the timeout in seconds for later calls on the handle |
Resource schemes
| Scheme |
read returns |
write or open with "w" |
Notes |
file: or a bare path |
File contents as bytes |
Replaces the file |
Mode "a" appends; at gives random access. Device nodes such as /dev/ttyUSB0 work too |
dir://path |
Array of {name, kind, size, modified, mode} entries |
open("dir://p", "w") creates the directory |
delete(uri, true) removes a tree |
stat://path |
One entry (with target for symlinks and owner), or null if missing |
None |
The way to test whether something exists |
watch://path |
Blocks until something changes, then returns {path, event} |
None |
Files and directory trees |
mmap://path |
Bytes of the mapped file |
Writes through to the mapping |
meta: reports the base address |
mem://size |
Bytes of an anonymous allocation |
Writes into it |
Page-aligned; meta: reports address; {"protect": "rx"} makes it executable |
shm://name |
Bytes of a named shared-memory object |
Writes into it |
Shared between processes; opts.size creates it |
stdin:, stdout:, stderr: |
Bytes from standard input |
Bytes to the stream |
For binary data; print and input cover text |
tcp://host:port |
Bytes from the stream |
Bytes to the stream |
Open with "rw"; opts takes tls, cert, key and ca |
udp://host:port |
One datagram per read |
One datagram per write |
udp: binds; multicast through sockopt |
listen://host:port |
Accepts one connection and returns its handle |
None |
Open with "r"; the host may be empty |
unix://path |
Bytes from a Unix-domain socket or Windows named pipe |
Bytes to it |
{"listen": true} in opts makes reads accept connections |
raw://iface |
One Ethernet frame |
Sends one frame |
Packet capture and injection; needs operating-system privilege |
http://..., https://... |
Response body |
Request body, sent when you next read |
read(url) is a GET. For other methods use open(url, "rw", {"method": "POST", "headers": {}}), then write, then read. Status via meta: |
ws://..., wss://... |
One message |
One message |
opts takes headers |
dns://name |
Array of address strings |
None |
{"type": "MX"} in opts returns records of that type |
exec://program |
The process’s standard output |
Its standard input |
opts takes args, env and cwd; the process starts when opened |
proc://pid |
{pid, parent, name, command, status, memory}; proc: alone lists all processes |
None |
Open it for a handle you can signal |
signal: |
Blocks until that signal arrives, then returns its name |
None |
For example signal: |
env://NAME |
The variable’s value as a string, or null |
Sets it |
env:// alone reads all variables as an object |
args: |
Array of command-line arguments |
None |
|
time://now |
Seconds since the epoch, as a float |
None |
|
time://mono |
Monotonic nanoseconds, as an int |
None |
For measuring durations |
time://sleep |
None |
Sleeps for the number of seconds written |
Parks only the calling thread |
rand:// |
n bytes from the operating system’s secure generator |
None |
read("rand://", 8).get_u64(0) gives a random int |
sys://info, sys://net, sys://mounts, sys://load |
Machine details, network interfaces, mounted filesystems, load averages (JSON) |
None |
info is {os, arch, cpus, memory, hostname, user} |
reg://HKLM/path |
A registry value, or the subkeys, as JSON |
Sets the value |
Windows only; delete removes a key |
clip: |
Clipboard text |
Sets the clipboard |
|
screen: |
A screen capture as PNG bytes |
None |
opts.display picks the display |
audio://in, audio://out |
Captured PCM samples |
Plays PCM samples |
opts takes rate, channels and format |
serial://port |
Bytes from the port |
Bytes to the port |
opts takes baud, parity, stop and flow |
usb://vid:pid |
A bulk or interrupt transfer in |
A transfer out |
opts takes endpoint and type |
gpio://chip/line, i2c://bus/address, spi://bus/chip |
The pin level, or bytes from the device |
Sets the pin, or sends bytes |
Linux character-device interfaces |
syscall:// |
The result of the last call, as an int (negative error number on failure) |
A JSON array [number, arg1, ...]; bytes arguments are pinned and passed as pointers |
Open with "rw". Needs an operating system with a stable syscall interface, and numbers differ by architecture |
lib://name |
The result of the last call |
A JSON array of arguments; performs the call |
opts gives the signature: {"args": ["f64"], "ret": "f64"} with i8 to i64, u8 to u64, f32, f64, ptr, cstr and void. lib://@0xADDR calls a raw address |
meta: |
Details of a handle (see Control commands) |
A command |
|
err: |
Message for this thread’s most recent failed call, or null |
None |
|
Callbacks. Native code can call BANDIT code. cb = open("callback://section-title", "r", {"args": ["ptr", "ptr"], "ret": "i32"}) turns a section into a native function and returns a handle.
args and ret use the same type names as lib:, which also accepts the type callback. Pass a callback handle where a lib: signature says "callback" and the runtime substitutes the native function pointer. meta: on the handle reports the pointer as address, for APIs that take it through memory.
- When native code calls the pointer, the runtime stores the arguments as a JSON array in the variable
<section>_in (hyphens and dots in the title become underscores; opts.in and opts.out choose other variable names), runs the section as if by gosub, then converts the variable <section>_out to the declared return type. Pointer arguments arrive as ints, which peek8 to peek64 can read.
- Any operating-system thread may call it. A thread BANDIT did not create is adopted for the length of the call. Calls to the same callback are serialized, so concurrent native callers cannot trample its
_in and _out variables. A callback that re-enters itself overwrites them, so it must save them first, as in recursion.
- The handle must stay open while native code may call the pointer.
close frees it, and a later native call crashes the program instead of raising a BANDIT error.
exit inside a callback ends the program, and break ends the section like reaching its end.
- A callback installed as a native signal handler cannot run inside the interrupted code. The runtime queues the section to a BANDIT thread and lets the native handler return at once, so its return value is ignored.
signal: is simpler when you only need to wait for a signal.
data = bytes(40)
cmp = open("callback://compare", "r", {"args": ["ptr", "ptr"], "ret": "i32"})
q = open("lib://libc.so.6#qsort", "rw", {"args": ["ptr", "u64", "u64", "callback"], "ret": "void"})
write(q, [data, 10, 4, cmp])
close(cmp)
print data.get_u32(0)
[compare]
x = peek32(compare_in[0])
y = peek32(compare_in[1])
compare_out = 0
if x < y:
compare_out = -1
if x > y:
compare_out = 1
Examples
text = read("notes.txt").decode()
print len(text.lines()), "lines"
resp = read("https://api.example.com/items")
if resp == null:
print "failed:", read("err://")
else:
items = parse_json(resp.decode())
print len(items), "items"
p = open("exec://git", "r", {"args": ["log", "--oneline", "-5"]})
out = read(p)
info = read("meta://" + str(p))
close(p)
print out.decode()
print "exit status", info.status
t0 = read("time://mono")
write("time://sleep", 0.25)
print (read("time://mono") - t0) // 1000000, "ms"
f = open("data.log", "rw")
write("meta://" + str(f), {"lock": "exclusive", "wait": true})
write("meta://" + str(f), {"rename": "data.old"})
close(f)
sc = open("syscall://", "rw")
write(sc, [39])
print read(sc)
c = open("lib://libm.so.6#cos", "rw", {"args": ["f64"], "ret": "f64"})
write(c, [0.0])
print read(c)
Least privilege. Files that run locally, meaning the entry file and every local library file, need no permissions and may use any scheme, including the low-level ones. Only code from URL imports is restricted. It gets no system access at all unless a rule in a bandit.perms manifest grants it, embedded in the binary at build time:
allow https://api.example.com/** r for vec
allow file://./cache/** rw for vec
allow exec://git for tools
- A rule is
allow, a URI pattern (* within one path segment, ** across segments), the modes allowed (r, w or rw; omitted means all), and for <namespace>, naming the imported file the rule applies to. The for clause is required.
- With no manifest, or no rule for a namespace, imported code cannot use any resource. A denied call returns
null and err: reads permission denied.
- The compiler tags every system call with the namespace of the file it appears in, so imported code cannot borrow your access. When your code calls a section in an imported file, the system calls inside that section are checked against the imported file’s rules, not yours.
- Paths are normalized and symlinks resolved before matching, so
.. cannot escape a pattern.
- Low-level schemes.
syscall://, lib:, callback:, mem:, mmap:, shm:, raw:, usb: and the hardware buses need no opt-in in local files. Imported files may not use them at all, whatever the manifest says, unless you build with --allow-unsafe-remote. The same bar applies to asm, peek and poke.
Backend design
- All five calls compile to one runtime entry point,
sys(op, uri, data, opts). It checks permissions for code from URL imports, picks a driver by scheme and returns. A driver implements open, read, write, close and delete for one scheme, so a new kind of resource is a new driver and the API stays at five calls.
lib: loads libraries with dlopen or LoadLibrary, and the runtime builds a call thunk for each signature for the System V, Windows x64 and AArch64 conventions, so there is no libffi dependency. syscall:// issues the system call instruction directly.
- Each callback gets a small executable thunk (a
mem: region made rx). The thunk marshals the native arguments into a JSON array, adopts the calling operating-system thread if BANDIT did not create it, runs the section through the scheduler, and converts the result back to the declared return type.
- No call blocks an OS thread. Sockets, pipes, signals and timers use epoll, kqueue or IOCP. File I/O uses io_uring where present and a small thread pool otherwise. A thread waiting on a call is parked and the scheduler runs another.
- Handles live in one process-wide table and are closed automatically at exit.
- Targets are Linux, macOS and Windows. A scheme the platform cannot provide returns
null with unsupported in err:. Linux and the BSDs have stable system call interfaces; on macOS and Windows use lib: (libSystem, kernel32) for the same reach.
- Limits: a callback crosses into the scheduler, so it is much slower than a native call. A callback that blocks while native code holds a lock can deadlock against a BANDIT
lock section if the two take their locks in opposite orders.
Compiler and runtime
Pipeline (one command, one binary, no intermediate C):
- Tokenize with INDENT/DEDENT tokens and parse each file.
- Gather the program: every file in the folder tree, plus URL imports fetched and hash-checked.
- Resolve names into namespaces and build one program-wide variable table.
- Infer types across the whole program, then refine within loops and branches by splitting live ranges.
- Lower to SSA, run range analysis to drop bigint overflow checks, inline short sections, and remove unreachable labels.
- Emit machine code for x86-64 or AArch64, link the runtime statically, write the executable.
Runtime (statically linked, a few hundred KB):
- Bigint: own implementation with schoolbook, Karatsuba and Toom-3 multiplication, switching to FFT for very large operands. Avoids a GMP dependency and its LGPL terms.
- Memory: precise, generational garbage collector with a per-thread nursery. Stop-the-world at first; concurrent collection is a later optimization.
- JSON: parser and serializer built in; objects are insertion-ordered hash tables.
- Scheduler and channels: as described under Concurrency.
- Built-in functions:
open read write close delete. The type operations are listed under Operations by type. System access is described under System interface.
Backend choice. Version 1 generates code through LLVM for good optimization with little effort, still with no C and no VM. A hand-written backend can replace it later if compile time or binary size matters.
The main performance risk. One shared root variable assigned an int in one file and a string in another becomes a tagged value everywhere it is used, which is slower than a typed variable. Namespacing contains this: libraries cannot pollute root variables, only your own code can. The compiler should report which variables fell back to tagged storage (bandit build --report-types) so the cause is visible.
Grammar sketch and examples
program = { import | statement NEWLINE | sectiondef } ;
sectiondef = "[" title "]" block ;
title = name { ( "." | "-" ) name } ;
block = NEWLINE INDENT statement NEWLINE { statement NEWLINE } DEDENT ;
statement = assign | if | while | goto | gosub | "break" | "continue"
| thread | join | lock | atomic | send | close | yield
| print | input | line | asm | exit | expr ;
assign = target { "," target } assignop expr { "," expr } ;
target = name { "." name | "[" expr "]" } ;
method = expr "." name "(" [ expr { "," expr } ] ")" ;
if = "if" expr ":" block { "elif" expr ":" block } [ "else" ":" block ] ;
while = "while" expr ":" block ;
goto = "goto" "[" title "]" ;
gosub = "gosub" "[" title "]" ;
thread = [ name "=" ] "thread" "[" title "]" ;
lock = "lock" name ":" block ;
import = "import" string [ "as" name ] [ "sha256" string ] ;
asm = "asm" ( arch [ "clobbers" names ] | "else" ) ":" asmblock ;
The expr grammar is Python-like with the operators listed under Syntax; recv c is a prefix expression and chan(n) is a built-in call. Top-level statements run in order; sectiondef blocks are skipped by that flow and entered only by goto, gosub or thread.
Hello, with type guessing
input "Your name? ", name
input "Your age? ", age
print f"Hi {name}, next year you will be {age + 1}"
Bignum: how many digits in 1000!
acc = 1
i = 2
while i <= 1000:
acc *= i
i += 1
print len(str(acc)), "digits"
Pure goto and gosub
total = 0
n = 5
goto [again]
[again]
if n == 0:
goto [finish]
gosub [add-n]
n -= 1
goto [again]
[add-n]
total += n
[finish]
print total # 15
Recursion with a JSON-array stack: Fibonacci
n = 10
stack = []
gosub [fib]
print fib_out # 55
[fib]
if n < 2:
fib_out = n
else:
stack.append(n) # save n
n -= 1
gosub [fib] # fib_out = fib(n - 1)
n = stack.remove(-1) # restore n
stack.append(fib_out) # save fib(n - 1)
stack.append(n)
n -= 2
gosub [fib] # fib_out = fib(n - 2)
n = stack.remove(-1) # restore n
fib_tmp = stack.remove(-1) # fib(n - 1)
fib_out += fib_tmp
JSON as the container type
user = {"name": "Ada", "langs": ["bandit", "asm"]}
user.age = 36
user.langs[0] = "go"
user.address.city = "Reykjavik" # creates user.address on the way
print user.name, user.age # Ada 36
print user # {"name":"Ada","langs":["go","asm"],"age":36,"address":{"city":"Reykjavik"}}
print user.phone.number # null: a missing path reads as null
print user["name"] # brackets still work and accept any expression
Threads and channels
jobs = chan(8)
done = chan(8)
t = thread [worker]
send jobs, 7
send jobs, 12
close jobs
print recv done
print recv done
join t
[worker]
while true:
n = recv jobs
if n == null:
break
send done, n * n
Open questions
Decisions I made on your behalf that you may want to overrule, most consequential first.
- Threads share every variable. With no function scope, nothing is private to a thread, so two threads cannot safely run the same section. A per-thread variable marker would fix it at the cost of strict “all variables global”. Say if you want it.
- No
push, pop or ret. You asked for pure goto plus gosub, break and continue, so there is no data stack. Recursion keeps a manual stack in a JSON array, which is slower and easier to get wrong than a built-in one. Say if you want push and pop back.
- Sections are skipped by straight-line flow. Because the program starts on line 1 and sections sit among top-level code, flow steps over section blocks rather than falling into them. The alternative is that flow runs into the next section, BASIC-style, which makes accidental fall-through easy.
- Dot access is forgiving. Reading a missing path gives
null and writing creates missing intermediate objects, so a typo such as user.nmae = 1 quietly adds a new key. The alternative is a runtime error for reads of missing keys and for writes through a missing object.
- Methods, names and sharing. A dot followed by parentheses is always a method call and a dot alone is JSON member access, so a key named
keys is read as obj.keys while the method is obj.keys(). Names after a dot are free, so join is a method (arr.join(sep)) even though join is also a statement. Assigning JSON or bytes shares the value and copy(x) makes a deep copy. Say if you would rather copy on assignment, which is safer but slower.
- Passing values by naming convention (
section_in, section_out) is unchecked. Optional declarations could let the compiler verify it. Callbacks use the same convention, with the runtime filling _in and reading _out.
input guessing types. 007 becomes the int 7 and loses its zeros. Say if you would rather input always return a string.
- Strings index by byte. This matches Go and is O(1). Indexing by code point would be more Python-like but O(n).
- Backend. LLVM first, own backend later, or an own backend from the start (more work, faster compiles, smaller toolchain).
- System interface scope. The five calls reach files and devices, memory mapping and shared memory, sockets (TCP, UDP, Unix, raw, WebSocket), processes and signals, hardware buses, audio, clipboard, screen, the registry, raw system calls and any dynamic library function, and native code can call back into BANDIT sections, so anything the operating system offers is reachable. The growth is in scheme names and
meta: commands, not in calls. Local files need no opt-in for any of it. Imported files are barred from the low-level schemes, asm, peek and poke unless you build with --allow-unsafe-remote.
- Errors are
null plus err:. A failed system call returns null and the reason is read from err:. The alternatives are a fatal runtime error, which the language cannot catch, or Go-style value and error pairs, which make every simple call clumsier.
- No
for, and exit has no status. Iterating a JSON array takes a while loop with an index. exit always ends with status 0, so a program cannot report failure to the shell. exit n is easy to add back.
Happy Halloween!
No, but when you modify a public work, you regain ownership. Especially when it’s a massive overhaul of the document. Did you not read my comment?