zig-nickel-ffi

Table of Contents

• Overview
• Features
• Requirements
• Building
• Usage
  • Zig
  • From Other Languages (via Zig exports)
• Architecture
• API Reference
  • Context
  • Exported Functions (C ABI)
• License

Zig FFI bindings for the Nickel configuration language.

Overview

Direct access to Nickel’s evaluation engine from Zig, via a Rust shim that wraps nickel-lang-core.

Unlike bunsenite (which embeds Nickel in a larger system), this provides standalone FFI access for any project that needs Nickel evaluation.

Features

• Evaluate Nickel source code and get JSON results

• Type-check Nickel configurations

• C FFI exports for use from Rust, Deno, ReScript, etc.

Requirements

• Zig 0.15+

• Rust (for building the shim)

• nickel-lang-core 0.10+

Building

# Build the Rust shim first
cd shim && cargo build --release && cd ..

# Build the Zig library
zig build

# Or build both with:
zig build shim && zig build

Usage

Zig

const nickel = @import("zig-nickel-ffi");

var ctx = try nickel.Context.init(allocator);
defer ctx.deinit();

// Evaluate Nickel source
const result = try ctx.eval(allocator, "{ x = 1 + 2, y = \"hello\" }");
defer allocator.free(result);
// result: { x = 3, y = "hello" }

// Type-check
const valid = try ctx.typecheck(allocator, "{ x : Number = 42 }");

From Other Languages (via Zig exports)

The Zig library exports C-ABI functions that can be called from any language:

// Link against libnickel_ffi.so
void* ctx = zig_nickel_init();
char* result = zig_nickel_eval(ctx, "1 + 2");
// result: "3"
zig_nickel_string_free(result);
zig_nickel_free(ctx);

Architecture

No C code involved - Zig declares extern "C" functions that link directly to Rust’s C-ABI exports.

┌─────────────────────────────────────┐
│         Your Application            │
└─────────────────┬───────────────────┘
                  │
┌─────────────────▼───────────────────┐
│       zig-nickel-ffi (Zig)          │
│   extern "C" declarations           │
│   + high-level Zig API              │
└─────────────────┬───────────────────┘
                  │ C ABI (calling convention only)
┌─────────────────▼───────────────────┐
│     nickel-ffi-shim (Rust)          │
│   #[no_mangle] extern "C" exports   │
└─────────────────┬───────────────────┘
                  │
┌─────────────────▼───────────────────┐
│        nickel-lang-core             │
└─────────────────────────────────────┘

API Reference

Context

Function	Description
Context.init(allocator)	Create new evaluation context
Context.deinit()	Free context
Context.eval(allocator, source)	Evaluate Nickel source, return result string
Context.typecheck(allocator, source)	Type-check source, return validity

Exported Functions (C ABI)

Function	Description
zig_nickel_init()	Create context
zig_nickel_free(ctx)	Free context
zig_nickel_eval(ctx, source)	Evaluate, return string (caller frees)
zig_nickel_typecheck(ctx, source)	Type-check, return bool
zig_nickel_string_free(str)	Free string from eval
zig_nickel_version()	Get Nickel version

License

AGPL-3.0-or-later