JSON Module

GX includes a JSON module powered by yyjson, one of the fastest JSON libraries in C. It supports both reading (immutable API) and building/modifying JSON (mutable API), with pretty-printing, JSON Pointer, and file I/O.

Prerequisites

The module ships with yyjson bundled — no external dependencies needed. The C source (yyjson.c) is compiled automatically via @cfile.

Usage

import json

Build with -I modules:

gx myapp.gx -I modules -o myapp.exe

Quick Example

import json

fn main() {
    // Parse JSON
    var text = "{\"name\": \"Alice\", \"age\": 30}"
    var doc = json.gx_json_parse(text.cstr, text.len, 0)
    defer json.gx_json_free(doc)

    var r = json.gx_json_root(doc)
    var name = json.gx_json_get_str(json.gx_json_obj_get(r, "name"))
    var age  = json.gx_json_get_int(json.gx_json_obj_get(r, "age"))
    print("Name: {name}, Age: {age}\n")

    // Build JSON
    var mdoc = json.gx_json_new_doc()
    defer json.gx_json_mut_free(mdoc)

    var obj = json.gx_json_new_obj(mdoc)
    json.gx_json_set_root(mdoc, obj)
    json.gx_json_obj_add_str(mdoc, obj, "language", "GX")
    json.gx_json_obj_add_int(mdoc, obj, "version", 2)

    var result = json.gx_json_mut_write(mdoc, json.WRITE_PRETTY)
    print("{result}\n")
}

Constants

Read Flags

Pass 0 for strict RFC 8259 parsing. Combine flags with |:

Write Flags

Pass 0 for minified output:

Type Constants

Returned by gx_json_type() and gx_json_mut_type():

Immutable API — Reading JSON

The immutable API parses JSON into a read-only document. Use this when you only need to query values.

Parsing

var doc = json.gx_json_parse(text.cstr, text.len, 0)
if (doc == 0) { print("Parse error\n"); return }
defer json.gx_json_free(doc)
var root = json.gx_json_root(doc)

For lenient parsing (comments, trailing commas):

var flags = json.READ_ALLOW_COMMENTS | json.READ_ALLOW_TRAILING_COMMAS
var doc = json.gx_json_parse(text.cstr, text.len, flags)

Type Inspection

Value Extraction

Object Navigation

var val = json.gx_json_obj_get(root, "name")
if (val != 0) {
    var name = json.gx_json_get_str(val)
    print("name = {name}\n")
}

Array Navigation

var arr = json.gx_json_obj_get(root, "items")
var first = json.gx_json_arr_get(arr, 0)
var second = json.gx_json_arr_get(arr, 1)

Serialization

var pretty = json.gx_json_write(doc, json.WRITE_PRETTY)
print("{pretty}\n")

JSON Pointer (RFC 6901)

Navigate nested structures with a path string:

// For {"data": {"users": [{"name": "Alice"}]}}
var name_val = json.gx_json_ptr_get(doc, "/data/users/0/name")
var name = json.gx_json_get_str(name_val)

Mutable API — Building JSON

The mutable API creates documents from scratch or modifies parsed JSON.

Document Lifecycle

var doc = json.gx_json_new_doc()
defer json.gx_json_mut_free(doc)

var root = json.gx_json_new_obj(doc)
json.gx_json_set_root(doc, root)

Creating Values

Object Mutation

Convenience functions that add a key-value pair in one call:

json.gx_json_obj_add_str(doc, obj, "name", "Alice")
json.gx_json_obj_add_int(doc, obj, "age", 30)

// Nested object
var address = json.gx_json_obj_add_obj(doc, obj, "address")
json.gx_json_obj_add_str(doc, address, "city", "Berlin")

Array Mutation

var tags = json.gx_json_obj_add_arr(doc, obj, "tags")
json.gx_json_arr_add_str(doc, tags, "fast")
json.gx_json_arr_add_str(doc, tags, "lightweight")
json.gx_json_arr_add_str(doc, tags, "zero-copy")

Mutable Type Inspection

Mutable Value Extraction

Mutable Navigation

Mutable Serialization

var json_str = json.gx_json_mut_write(doc, json.WRITE_PRETTY)
print("{json_str}\n")

Conversion & File I/O

Immutable ↔ Mutable Conversion

// Parse, then edit
var doc = json.gx_json_parse(text.cstr, text.len, 0)
var mdoc = json.gx_json_to_mut(doc)
json.gx_json_free(doc)
defer json.gx_json_mut_free(mdoc)

var root = json.gx_json_mut_root(mdoc)
json.gx_json_obj_add_str(mdoc, root, "modified", "true")

File I/O

// Read from file
var doc = json.gx_json_parse_file("config.json", 0)
defer json.gx_json_free(doc)

// Write to file (pretty)
json.gx_json_write_to_file("output.json", doc, json.WRITE_PRETTY)

Common Patterns

Checking for Missing Keys

gx_json_obj_get returns 0 (null pointer) if the key doesn’t exist:

var val = json.gx_json_obj_get(root, "optional_key")
if (val != 0) {
    var s = json.gx_json_get_str(val)
    print("Found: {s}\n")
}

Building a JSON Response

var doc = json.gx_json_new_doc()
defer json.gx_json_mut_free(doc)

var root = json.gx_json_new_obj(doc)
json.gx_json_set_root(doc, root)

json.gx_json_obj_add_bool(doc, root, "success", true)
json.gx_json_obj_add_int(doc, root, "status", 200)

var data = json.gx_json_obj_add_obj(doc, root, "data")
json.gx_json_obj_add_str(doc, data, "message", "OK")

var items = json.gx_json_obj_add_arr(doc, data, "items")
json.gx_json_arr_add_int(doc, items, 1)
json.gx_json_arr_add_int(doc, items, 2)
json.gx_json_arr_add_int(doc, items, 3)

var result = json.gx_json_mut_write(doc, json.WRITE_PRETTY)
print("{result}\n")

Output:

{
    "success": true,
    "status": 200,
    "data": {
        "message": "OK",
        "items": [
            1,
            2,
            3
        ]
    }
}

Module Layout

modules/
  json/
    c/
      yyjson.c         yyjson source (compiled via @cfile)
      yyjson.h         yyjson header
      gx_json.h        GX helper wrappers (void* interface)
    gx/
      json.gx          Module declarations, constants, extern functions