Skip to content

Commit

Permalink
Add instructions on how to import.
Browse files Browse the repository at this point in the history
  • Loading branch information
wmedrano committed Aug 25, 2024
1 parent 076d461 commit 3671a69
Show file tree
Hide file tree
Showing 5 changed files with 66 additions and 21 deletions.
7 changes: 7 additions & 0 deletions build.zig
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,13 @@ pub fn build(b: *std.Build) void {
check_step.dependOn(&check_exe.step);
check_step.dependOn(&check_test.step);

// Module: fizz
_ = b.addModule("fizz", .{
.root_source_file = b.path("src/root.zig"),
.target = target,
.optimize = optimize,
});

// Command: zig build run
const run_cmd = b.addRunArtifact(exe);
run_cmd.step.dependOn(b.getInstallStep());
Expand Down
2 changes: 1 addition & 1 deletion site/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ Will focus on:

- Improved error reporting.
- Incorporating user feedback.
- Performance tweaks.
- Performance & API tweaks.

### 0.1.0 (Current)

Expand Down
4 changes: 2 additions & 2 deletions site/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,8 +56,8 @@ Fizz is built in Zig and meant to easily integrate into a Zig codebase.
const fizz = @import("fizz");
var vm = try fizz.Vm.init(std.testing.allocator);
defer vm.deinit();
_ = try vm.evalStr(std.testing.allocator, "(define args (list 1 2 3 4))");
const v = try vm.evalStr(std.testing.allocator, "args");
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);
Expand Down
65 changes: 47 additions & 18 deletions site/zig-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,32 +9,43 @@ nav_order: 1

## Quickstart

In the following example, we:

1. Add fizz as a dependency.
> TODO
1. Create the Fizz virtual machine.
1. Download Fizz and place it in `build.zig.zon`.
```sh
zig fetch --save https://github.com/wmedrano/fizz/archive/refs/tags/0.1.0.tar.gz
```
1. Add Fizz as a dependency in `build.zig`.
```zig
const fizz = b.dependency("fizz", .{
.target = target,
.optimize = optimize,
});
```
1. Create the Fizz virtual machine in your code, for example, `src/main.zig`.
```zig
const fizz = @import("fizz");
var vm = try fizz.Vm.init(allocator);
defer vm.deinit();
```
1. Run some code within the virtual machine.
```zig
_ = try vm.EvalStr(allocator, "(define magic-numbers (list 1 2 3 4))");
const val = try vm.evalStr(
allocator,
"(struct 'numbers magic-numbers 'numbers-sum (apply + magic-numbers))");
const src = \\
\\ (define magic-numbers (list 1 2 3 4))
\\ (struct
\\ 'numbers magic-numbers
\\ 'numbers-sum (apply + magic-numbers)
\\ )
;
const val = try vm.EvalStr(allocator, src);
```
1. Convert VM values into Zig.
```zig
const ResultType = struct { numbers: []const i64, numbers_sum: i64 };
const result = try vm.env.toZig(
ResultType,
allocator,
val,
);
defer allocator.free(result.numbers);
const ResultType = struct { numbers: []const i64, numbers_sum: i64 };
const result = try vm.env.toZig(
ResultType,
allocator,
val,
);
defer allocator.free(result.numbers);
```
1. Run the garbage collector from time to time.
```zig
Expand Down Expand Up @@ -64,17 +75,35 @@ try vm.runGc();
defer vm.deinit();
```
## Evaluating Expressions
Expressions can be evaluated with `vm.evalStr`. The value of the returned
`fizz.Val` is guaranteed to exist until the next garbage collection run. See
[Extracting Values](#extracting-values) to extend the lifetime of the returned
values.
```zig
fn evalStr(self: *fizz.Vm, tmp_allocator: std.mem.Allocator, expr: []const u8) fizz.Val
```
- `self`: Pointer to the virtual machine.
- `tmp_allocator`: Allocator used for temporary memory for AST and ByteCode
compiler.
- `expr`: Lisp expression to evaluate. If multiple expressions are provided, the
returned `fizz.Val` will contain the value of the final expression.
## Extracting Values
Values are extracted using `vm.env.toZig`.
```zig
fn toZig(self: *Env, comptime T: type, allocator: Allocator, val: Val) !T
fn toZig(self: *fizz.Env, comptime T: type, allocator: std.mem.Allocator, val: fizz.Val) !T
```
- `self`: A pointer to the environment.
- `T`: The desired output Zig type.
- `allocator`: Memory allocator for dynamic memory allocation
- `allocator`: Memory allocator for any string or slice allocations.
- `val`: The input value to be converted
**Example**
Expand Down
9 changes: 9 additions & 0 deletions src/Vm.zig
Original file line number Diff line number Diff line change
Expand Up @@ -107,6 +107,15 @@ test "can eval basic expression" {
try std.testing.expectEqual(1, vm.env.runtime_stats.function_calls);
}

test "multiple expressions returns last expression" {
var vm = try Vm.init(std.testing.allocator);
defer vm.deinit();
const actual = try vm.evalStr(std.testing.allocator, "4 5 6");
try vm.env.runGc();
try std.testing.expectEqual(Val{ .int = 6 }, actual);
try std.testing.expectEqual(1, vm.env.runtime_stats.function_calls);
}

test "can deref symbols" {
var vm = try Vm.init(std.testing.allocator);
defer vm.deinit();
Expand Down

0 comments on commit 3671a69

Please sign in to comment.