layout	title	nav_enabled	nav_order
home	Home	true	0

Fizz

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

{: .warning}

Requires Zig 0.13.0

{: .warning}

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