Repository files navigation

Zig is a general-purpose programming language andtoolchain for maintaining robust, optimal, and reusable software.

Janet is a functional and imperative programminglanguage and bytecode interpreter. It is a lisp-like language, but lists arereplaced by other data structures (arrays, tables (hash table), struct(immutable hash table), tuples). The language also supports bridging to nativecode written in C, meta-programming with macros, and bytecode assembly.

Jzignet - Zig library to connect Janetand Zig together.

You can:

• Embed Janet programs into Zig
• Write Janet modules in Zig
• Write bindings in Zig for a C library to be used as a Janet module

Why use these bindings, besides obvious reasons such as connecting together twowonderful languages:

• You don't need to care about conversion between Zig and C. But you have fullaccess to C internals if you need to.
• Plenty of tests which are great examples and guarantee minimal regressionswhen updating.
• Idiomatic Zig code - everything is typed, names are properly cased,operations on types use methods instead of prefixed global functions.

Currently supported versions:

• Zig 0.13.0
• Janet 1.37.1

Repository is available atsourcehutand atGitHub.

If you want to just start using it, jump to the examples. Copy them or lookat the source code, it is heavily commented.

• Embed Janet into Zig --run this example withzig build run-embed_janet.
  For a more in-depth overview of this use case you can take a look at@iacore'sblog postas well as theexample repository.

WARNING: examples are currentlynot working:

• Write Janet module in Zig -- the template is brokenand needs some investigation on how to fix it.

Write bindings in Zig for a C library to be used as a Janet module - thisis very close to "Write Janet module in Zig" example, you just need toknow how to wrap a C library in Zig, this repository is a perfect examplefor this.

1. Create a file namedbuild.zig.zon with the following content. Put thecorrect version for tar archive, and change the.hash value when you getand error.

.{    .name="janet-zig-test",    .version="0.0.1",    .dependencies= .{        .jzignet= .{            .url="https://git.sr.ht/~greenfork/jzignet/archive/0.7.2.tar.gz",            .hash="122087fa45b016bd8ce5fbadd17ef2bd84cd1389119edd3c345486870032ea2b7217",        },    },}

2. Add this tobuild.zig.

constjzignet=b.dependency("jzignet", .{ .target=target, .optimize=optimize });// your executable defined here// const exe = ...;exe.addModule("jzignet",jzignet.module("jzignet"));exe.linkLibrary(jzignet.artifact("jzignet"));

3. Use in your Zig code

constjzignet=@import("jzignet");

Currently you can include jzignet as a git submodule. Janet is bundled asa single C source amalgamation file and is compiled directly into thislibrary.

1. Include git submodule into your library, assuming further thatlibpath isthe directory where this library is installed

git submodule add https://github.com/greenfork/jzignet libpath

2. Include the library inbuild.zig

constjzignet=b.anonymousDependency("lib/jzignet",@import("lib/jzignet/build.zig"), .{});// your executable defined here// const exe = ...;exe.addModule("jzignet",jzignet.module("jzignet"));exe.linkLibrary(jzignet.artifact("jzignet"));

3. Use in your Zig code

constjzignet=@import("jzignet");

• janet_ prefix is mostly not present.
• Every type is a Zig struct and corresponding functions are called asmethods, for example,janet_table_get(table, key) becomestable.get(key).
• All bindings have idiomatic Zig naming even when Janet uses differentones, for examplearity andfixarity arearity andfixArity in Zig.
• Functions likejanet_table are available asTable.init, please consultthe source code for that.

• Function return types return error sets as well as optional values where itmakes sense to do so, for example,table.get returns?Janet andpcallreturnsSignal.Error!void.

• All types are wrapped into structs. Most of the types support this nativelysince they are structs in C too, others (Tuple, Struct, String, Keyword,Symbol) cannot be represented as structs directly and they are wrapperswith aptr orslice field containing the original value.

• All functions that have a type at the end, for example,janet_get_number,instead use this signature:get(comptime T: type, ...). Currently thesefunctions exist:get,opt,wrap,Janet.unwrap.

• When you need to supply a pointer to the array and a length in the C version,in Zig version you need to supply just a slice since it has both the pointerand the length, so it's one parameter instead of two. For example,

  intjanet_dobytes(JanetTable*env,constuint8_t*bytes,int32_tlen,constchar*sourcePath,Janet*out);

  becomes

  pubfndoBytes(env:*Environment,bytes: []constu8,source_path: [:0]constu8)!Janet

• Abstracts are fully typed, no *void pointers to @ptrCast. Take a look attests for examples with abstracts, they are generally reworked to makethem easier to use.

• All functions returningSignal instead returnvoid onOK and returnerror otherwise with the specified signal, signature isSignal.Error!void.

• doString anddoBytes are aliases and return!Janet directly instead ofaccepting a reference for the return value.

• string,keyword,symbol,nil top-level functions are the only ones tocreate these types and they do what you want.

• Environment type introduced which is internally aTable but allowsconceptually different operations such as defining values and executing code.

Bindings are not complete 100% but all the generally useful things are there.If you need any specific part of the API, feel free to contribute or justask (and you shall receive).

Q: What's with the name?

A: "janet".replace("a", "zig")

Q: I hate that name.

A: Yes, I know.

MIT, see LICENSE file.