v0.2.0 release

build.zig

@@ -5,7 +5,7 @@ pub fn build(b: *std.Build) void {
     const optimize = b.standardOptimizeOption(.{});
 
     // Module: fizz
-    _ = b.addModule("fizz", .{
+    const fizz = b.addModule("fizz", .{
         .root_source_file = b.path("src/root.zig"),
         .target = target,
         .optimize = optimize,
@@ -20,16 +20,23 @@ pub fn build(b: *std.Build) void {
         .target = target,
         .optimize = optimize,
     });
+    check_test.root_module.addImport("fizz", fizz);
     const check_step = b.step("check", "Check for compile errors");
     check_step.dependOn(&check_test.step);
 
     // Command: zig build test
-    const exe_unit_tests = b.addTest(.{
+    const golden_test = b.addTest(.{
         .root_source_file = b.path("src/golden_test.zig"),
         .target = target,
         .optimize = optimize,
     });
-    const run_exe_unit_tests = b.addRunArtifact(exe_unit_tests);
+    golden_test.root_module.addImport("fizz", fizz);
+    const unit_tests = b.addTest(.{
+        .root_source_file = b.path("src/root.zig"),
+        .target = target,
+        .optimize = optimize,
+    });
     const test_step = b.step("test", "Run unit tests");
-    test_step.dependOn(&run_exe_unit_tests.step);
+    test_step.dependOn(&b.addRunArtifact(unit_tests).step);
+    test_step.dependOn(&b.addRunArtifact(golden_test).step);
 }

site/CHANGELOG.md

@@ -22,11 +22,16 @@ following tradeoffs may happen:
 
 ### 0.2.0 (In Progress)
 
-Will focus on:
+**Zig API**
 
-- Improved error reporting.
-- Incorporating user feedback.
-- Performance & API tweaks.
+- `Vm.evalStr` returns a Zig type by default.
+- `Vm.env.errors` collects errors that may be printed.
+- Most functions that take `*Environment` now take a `*Vm`.
+- `Environment` has been renamed to `Env`.
+- Garbage collection happens automatically. May be set to manual.
+- `Vm.keepAlive` and `Vm.allowDeath` allow extending life of a `Val`.
+
+**Fizz Language**
 
 - Allow define within subexpressions.
 

site/fizz-language-reference.md

@@ -304,7 +304,7 @@ or equal to the length of the list.
 $1 = 2
 ```
 
-### map (0.2.0 candidate)
+### map
 
 `(map <function> <list>)`
 
@@ -315,7 +315,7 @@ Returns a list by applying `<function>` to each element in `<list>`.
 $1 = (2 3 4)
 ```
 
-### filter (0.2.0 candidate)
+### filter
 
 `(filter <function> <list>)`
 

site/index.md

@@ -19,6 +19,46 @@ Zig**.
 | [<img width=16px src="https://github.githubassets.com/images/icons/emoji/octocat.png"> GitHub](https://github.com/wmedrano/fizz) | [❤ Sponsor](https://github.com/sponsors/wmedrano)                                                             |
 | [📚 Documentation](https://wmedrano.github.io/fizz)                                                                              | [<img width=16px src="https://avatars.githubusercontent.com/u/27973237"> Zig Discord](https://discord.gg/zig) |
 
+## Quickstart
+
+1. Download Fizz and place it in `build.zig.zon`.
+   ```sh
+   zig fetch --save https://github.com/wmedrano/fiz/archive/refs/tags/v0.2.0.tar.gz
+   ```
+1. Add Fizz as a dependency in `build.zig`.
+   ```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"));
+   ```
+1. Create the Fizz virtual machine.
+   ```zig
+   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});
+   ```
+1. Evaluate expressions in the VM.
+   ```zig
+   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});
+   ```
+1. Call custom Zig functions.
+   ```zig
+   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
@@ -53,14 +93,3 @@ It should be easy to get started writing Fizz. Fizz supports the following:
 Fizz is built in Zig and meant to easily integrate into a Zig codebase.
 
 [📚 documentation](https://wmedrano.github.io/fizz/zig-api)
-
-```zig
-const fizz = @import("fizz");
-var vm = try fizz.Vm.init(std.testing.allocator);
-defer vm.deinit();
-
-const v = try vm.evalStr(std.testing.allocator, "(list 1 2 3 4)");
-const actual = try vm.env.toZig([]i64, std.testing.allocator, v);
-defer std.testing.allocator.free(actual);
-try std.testing.expectEqualDeep(&[_]i64{ 1, 2, 3, 4 }, actual);
-```