Skip to content

m-r-hunt/tjp

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

23 Commits
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Typed JSON Parser

Typed JSON Parser (TJP for short) is a Zig library for parsing JSON directly into Zig values, unlike std.json which returns a tree of unions which the user must marshal into their desired type. In fact TJP just provides the final unmarshalling step using a std.json Value tree.

TJP is currently unfinished (see TODOs below), but starting to be functional.

Example

    const tjp = @import("tjp");
    const std = @import("std");
    const json = std.json;

    const ExampleStruct = struct {
        an_int: i32,
        a_float: f32,
        optional: ?i32,
        an_array: [4]i32,
        nested_struct: struct {
            another_int: i32,
        },
    };
    var p = json.Parser.init(std.debug.global_allocator, false);
    defer p.deinit();

    const s =
        \\{
        \\ "an_int": 1,
        \\ "a_float": 3.5,
        \\ 
        \\ "an_array": [1, 2, 3, 4],
        \\ "nested_struct": {"another_int": 6}
        \\}
    ;
    var tree = try p.parse(s);
    defer tree.deinit();

    var result = try tjp.unmarshal(ExampleStruct, tree.root, std.debug.global_allocator);
    std.debug.warn("\n{}\n", result);
ExampleStruct{ .an_int = 1, .a_float = 3.5e+00, .optional = null, .an_array = i32@c6df9ff7a8, .nested_struct = struct:193:24{ .another_int = 6 } }

Usage

Zig's package management is still a WIP at the time of writing. To use this as a package, include the source somewhere (possibly as a git submodule) and add this to your build.zig:

lib_or_exe.addPackagePath("tjp", "path/to/tjp/src/tjp.zig");

Then you can @import("tjp") in your source files.

How it works

TJP uses comptime reflection to inspect the types passed to it, and generate the code needed to traverse the std.json ValueTree at runtime. It uses a recursive function to inspect potentially nested types.

Type mappings

Zig Type JSON Type
Any integer JSON Integer as parsed by std.JSON. Checked to fit in given size/signedness
Any float JSON Integer or Float as parsed by std.JSON. Converted by @intToFloat or @FloatCast respectively
Optional underlying type or null. Key may be omitted from JSON encoded structs (in which case the optional will be null)
Struct JSON Object with keys corresponding to struct fields and correctly typed values
Array JSON Array of correct typed values, with the exact length of the array type. (TODO Array of optionals?)
Enum JSON String of enum case name or integer enum value
[]const u8 JSON String (Memory is shared with the original std.json Value)
Tagged Union JSON Object with two fields: "tag", a string with the tag name, or the integer enum value, and "value", the value for that tag

Types not listed are not supported. Additionally, these standard library containers are also understood as a special case:

Zig Type JSON Type
ArrayList(T) As a normal Array, but any size
StringHashMap(T) JSON object with correctly typed values

Limitations

  1. TJP uses some fairly complex comptime features of Zig. I hit and worked around a number of compiler bugs while writing it. It's quite likely it may break unexpectedly as the compiler evolves. TJP certainly won't be considered stable (1.0) until Zig itself is.

  2. Due to the recursive nature of type parsing, recursive types are not supported. Likely you will crash the compiler if you pass one to TJP.

  3. Similarly, very deeply nested types may crash the compiler with a stack overflow.

Extensibility

Since TJP operates on a std.json Value tree, any other data format that could be parsed into that form could be run through TJP to perform final unmarshalling into real Zig types.

Future Enhancements

  • Better error reporting (preferably including the paths through the Zig type and JSON to where the error occurred).
  • A JSON writer that writes Zig types out in the format expected by the TJP parser.
  • An all-in-one wrapper around std.json that handles the initial JSON parsing too.

About

No description, website, or topics provided.

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages