Fizz

Fizz is a simple interpretted programming language meant for embedding in Zig.

Requires Zig 0.13.0

Fizz is not yet in a stable state. If you have a use case that you would like handled, file an 🪲 issue.

Links

GitHub	❤ Sponsor
📚 Documentation	Zig Discord

Quickstart

1. Download Fizz and place it in build.zig.zon.

   zig fetch --save https://github.com/wmedrano/fiz/archive/refs/tags/v0.3.0.tar.gz
   

2. Add Fizz as a dependency in build.zig.

   const fizz = b.dependency("fizz", .{.target = target, .optimize = optimize});
   ...
   // Use it for our executable or library.
   exe.root_module.addImport("fizz", fizz.module("fizz"));
   

3. Create the Fizz virtual machine.

   const fizz = @import("fizz");
   
   ...
   var vm = try fizz.Vm.init(allocator);
   defer vm.deinit();
   errdefer std.debug.print("Fizz VM failed:\n{any}\n", .{vm.env.errors});
   

4. Evaluate expressions in the VM.

   try vm.evalStr(void, allocator, "(define my-list (list 1 2 3 4))");
   const sum = vm.evalStr(i64, allocator, "(apply + my-list)");
   std.debug.print("Sum was: {d}\n", .{sum});
   

5. Call custom Zig functions.

   fn quack(vm: *fizz.Vm, _: []const fizz.Val) fizz.NativeFnError!fizz.Val {
       return vm.env.memory_manager.allocateStringVal("quack!") catch return fizz.NativnFnError.RuntimeError;
   }
   
   ...
   try vm.registerGlobalFn("quack!", quack);
   const text = try vm.evalStr([]u8, allocator, "(quack!)");
   defer allocator.free(text);
   

Goals

Simplicity

It should be easy to get started writing Fizz. Fizz supports the following:

• Simple Syntax - All expressions are of the form (<function> <operands>...).

  >> (define pi 3.14)
  >> (* 2 pi) ;; 6.28
  >> (define (plus a b) (+ a b))
  >> (plus 2 2) ;; 4
  >> (if (< 1 2) "red" "blue") ;; "red"
  

• Common datatypes like ints, floats, strings, structs, and lists.

  >> true
  >> 1
  >> 1.2
  >> "hello world"
  >> (list 1 2 3 4)
  >> (struct 'field "yes" 'the-list (list 1 2 3 4))
  

Zig Integration

Fizz is built in Zig and meant to easily integrate into a Zig codebase.

📚 documentation