README

Brief

A very trivial scripting language implemented in C11. Only for educational purposes.

Usage - Building

• Requires CMake 4.2 (Actually, 3.16+ is fine!)
• Make, Ninja, or another build tool
• Clang is preferred
• Usage: ./project.sh help
  • Statically-linked binary: ./project.sh br
  • Dynamically-linked demo binary (uses shared lib): ./project.sh sr

Usage - Running

• Run ./build/tbasic -i for the debuggable binary.
• Run ./tbasic -i for the release binary. This is to keep a working release binary separate from the debug build.

Basic Features

• BASIC inspired but:
  • No line numbers or GOTO.
  • And even more QoL extras!

Roadmap

v0.1.x

• Add logical operator (&&, ||) support. OK
• Add assignment operator.
  • Add variable assignment. OK
• Add loops support. OK

v0.2.x

• Add object base. OK
• Add object heap. OK
• Add simple, fixed size list objects. OK
• Add mark & sweep GC. OK

v0.3.x: QoL 0

• Add native function library for: OK
  • I/O: print(...args)
  • Math: powf(), sqrtf(), clamp(), floorf(), and ceilf()

v0.4.x

• Add for-loop variation with BREAK; and CONTINUE; OK
• Add negative number literals. OK
• Add object display methods. OK

v0.5.x

• Add immutable strings as separate, interned values. OK
  • Create string type. OK
  • Add more library functions:
    • stoi, stof OK

v0.6.x:

• Add "dict objects": OK
• Add foo["bar"] syntax for accessing any keys of objects vs. ::. OK
• Add compiler support for not duplicating string constants. OK
• Add compiler support for dict literals. OK
• Add make_dict_dud opcode to VM & generation. OK

v0.7.x: QoL 1

• Make unified API to register native functions & manipulate VM state. OK
• Support shared object library builds, exposing a header API to the shared lib. OK

v0.8.x: QoL 2

• Fix IF-ELSE syntax to allow ELSE IF or premature END. OK
• Add null handling operators: OK
  • Prefix ? for compact null checks.
  • Binary Infix ?? for null coalescing.

v0.9.x: QoL 3

• Fix var hoisting. OK
  • Add RESERVE opcode.
  • Change variable generations to set a local offset in the RESERVE-d stack slots upon assignment or initialization.
  • Implement RESERVE opcode.
• Add try-catch & exceptions. OK
• Add bytecode optimization pass with super-instructions. OK

v0.10.x: BIG Refactor

• Refactor compiler to use cleaner tracking of flag changes, passing bitflags per callee. OK
• Refactor VM to trampoline into native calls vs. doing a branch each time. OK
• Fix exceptions to not naively unwind out of the nearest RET. What if a RET is in a TRY and makes that exception falsely uncaught? OK

v0.11.x: QoL 4

• Add ASSERT <expr>, <simple-expr, call or literal>; OK
• Add lambdas: OK

  LET foo : FUN (a, b):
    RET a + b;
  END;

• Add destructuring of lists into a finite set of names. OK

  BIND nums : [a, b, c];

v0.12.x: Diagnostic Improvements

• Fix the atrocious compiler errors to be more specific with column numbers per line. OK
• Add debug info per bytecode chunk e.g line & col per statement. OK

v0.13.x: QoL 5

• Add closures. OK

  FUN makeCounter(x, y):
    RET FUN() USES x, y:
      x := x + y;

      RET x;
    END
  END

• Add bitwise NOT, AND, OR, XOR, SHL, SHR... Remove RESERVE opcode in favor of a chunk's non-parameter local count. OK
• Add binary / hexadecimal literals. OK
• Add ASCII escapes in strings. OK

v0.14.x: QoL 6

• Add iterators. OK
  • tb_iterator_t: Semantics of a cursor through an object, allowing checking, peeking, and advancing.
  • NO chkiter function- iterators are testable to a boolean.
  • mkiter(obj): creates iterator.
  • mviter(obj): advances iterator, returns false on end.
  • pkiter(obj): peeks current value of iterator.
• Expand builtin library: OK
  • Add thaw function:
    • Args: an object reference
    • Sets the object's mutable flag to TRUE.
    • Returns FALSE on non-objects.
  • Add freeze function:
    • Args: an object reference
    • Sets the object's mutable flag to FALSE, disallowing mutation of any kind.
    • Returns FALSE for non-objects.
  • Add list functions:
    • lsrev(list): returns true if a list is fed.
    • lscat(dest, src): returns dest or NIL on success / failure.
    • lsclr(list): returns true if a list is fed.
    • lscut(list, begin, len): returns a new sliced list with given bounds.
  • Add file stream functions:
    • An fs object has the semantics of a tuple with (hidden-filename, 0 => pos, 1 => hasErr, 2 => isEOF).
    • fopen(path, mode: int): returns an fs on success but NIL on failure.
      • Modes:
        • 0: "r"
        • 1: "rb"
        • 2: "w"
        • 3: "wb"
    • fclose(fs): returns TRUE on success.
    • fgetc(fs): returns ASCII code as a 0-255 integer value but NIL on failure.
    • fputc(fs, ascii): returns TRUE on success.
    • fread(fs, buf, n): returns n for bytes successfully read but -1 on failure.
    • fwrite(fs, buf, n): return n for bytes successfully written but -1 on failure.

v0.16.x: QoL 7

• Make top-level declarations global by default. OK
• Add diagnostic annotations:
  • @DOC "This function sorts all items using a predicate."
  • @WARN "This function is too error prone.")

v0.17.x: QoL 8

• Add the ability to generate standalone C files which bundle TBasic bytecode & the interpreter as an executable.
• Add macro system.