Namek/zig-getty-json

Overview

Getty JSON is a serialization library for the JSON data format.

Installation

Gyro

Add Getty to your project:

gyro add -s github getty-zig/json
gyro fetch

Add the following to build.zig:

const std = @import("std");
+const pkgs = @import("deps.zig").pkgs;

pub fn build(b: *std.build.Builder) void {
    ...

    const exe = b.addExecutable("my-project", "src/main.zig");
    exe.setTarget(target);
    exe.setBuildMode(mode);
+   pkgs.addAllTo(exe);
    exe.install();

    ...
}

Zigmod

Add the following to zigmod.yml:

...

root_dependencies:
+  - src: git https://github.com/getty-zig/json

Fetch project dependencies:
```
zigmod fetch
```

Add the following to build.zig:

const std = @import("std");
+const deps = @import("deps.zig");

pub fn build(b: *std.build.Builder) void {
    ...

    const exe = b.addExecutable("my-project", "src/main.zig");
    exe.setTarget(target);
    exe.setBuildMode(mode);
+   deps.addAllTo(exe);
    exe.install();

    ...
}

API Reference

Serialization

toSlice - Serializes a value as a JSON string.

Synopsis

fn toSlice(allocator: std.mem.Allocator, value: anytype) ![]const u8

Example

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

const allocator = std.heap.page_allocator;

const Point = struct { x: i32, y: i32 };
const point = Point{ .x = 1, .y = 2 };

pub fn main() anyerror!void {
    const string = try json.toSlice(allocator, point);
    defer allocator.free(string);

    // {"x":1,"y":2}
    std.debug.print("{s}\n", .{string});
}

toPrettySlice - Serializes a value as a pretty-printed JSON string.

Synopsis

fn toPrettySlice(allocator: std.mem.Allocator, value: anytype) ![]const u8

Example

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

const allocator = std.heap.page_allocator;

const Point = struct { x: i32, y: i32 };
const point = Point{ .x = 1, .y = 2 };

pub fn main() anyerror!void {
    const string = try json.toPrettySlice(allocator, point);
    defer allocator.free(string);

    // {
    //   "x": 1,
    //   "y": 2
    // }
    std.debug.print("{s}\n", .{string});
}

toSliceWith - Serializes a value as a JSON string using a Serialization Block or Tuple.

Synopsis

fn toSliceWith(allocator: std.mem.Allocator, value: anytype, ser: anytype) ![]const u8

Example

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

const allocator = std.heap.page_allocator;

const Point = struct { x: i32, y: i32 };
const point = Point{ .x = 1, .y = 2 };

pub fn main() anyerror!void {
    const string = try json.toSliceWith(allocator, point, struct {
        pub fn is(comptime T: type) bool {
            return T == Point;
        }

        pub fn serialize(value: anytype, serializer: anytype) !@TypeOf(serializer).Ok {
            const seq = (try serializer.serializeSeq(2)).seq();
            inline for (std.meta.fields(Point)) |field| {
                try seq.serializeElement(@field(value, field.name));
            }
            return try seq.end();
        }
    });
    defer allocator.free(string);

    // [1,2]
    std.debug.print("{s}\n", .{string});
}

toPrettySliceWith - Serializes a value as a JSON string using a Serialization BLock or Tuple.

Synopsis

fn toPrettySliceWith(allocator: std.mem.Allocator, value: anytype, ser: anytype) ![]const u8

Example

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

const allocator = std.heap.page_allocator;

const Point = struct { x: i32, y: i32 };
const point = Point{ .x = 1, .y = 2 };

pub fn main() anyerror!void {
    const string = try json.toPrettySliceWith(allocator, point, struct {
        pub fn is(comptime T: type) bool {
            return T == Point;
        }

        pub fn serialize(value: anytype, serializer: anytype) !@TypeOf(serializer).Ok {
            const seq = (try serializer.serializeSeq(2)).seq();
            inline for (std.meta.fields(Point)) |field| {
                try seq.serializeElement(@field(value, field.name));
            }
            return try seq.end();
        }
    });
    defer allocator.free(string);

    // [
    //   1,
    //   2
    // ]
    std.debug.print("{s}\n", .{string});
}

toWriter - Serializes a value as JSON into an I/O stream.

Synopsis

fn toWriter(value: anytype, writer: anytype) !void

Example

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

const Point = struct { x: i32, y: i32 };
const point = Point{ .x = 1, .y = 2 };

pub fn main() anyerror!void {
    const stdout = std.io.getStdOut().writer();

    // {"x":1,"y":2}
    try json.toWriter(point, stdout);
}

toPrettyWriter - Serializes a value as pretty-printed JSON into an I/O stream.

Synopsis

fn toPrettyWriter(value: anytype, writer: anytype) !void

Example

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

const Point = struct { x: i32, y: i32 };
const point = Point{ .x = 1, .y = 2 };

pub fn main() anyerror!void {
    const stdout = std.io.getStdOut().writer();

    // {
    //   "x": 1,
    //   "y": 2
    // }
    try json.toPrettyWriter(point, stdout);
}

toWriterWith - Serializes a value as JSON into an I/O stream using a Serialization Block or Tuple.

Synopsis

fn toWriterWith(value: anytype, writer: anytype, ser: anytype) !void

Example

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

const allocator = std.heap.page_allocator;

const Point = struct { x: i32, y: i32 };
const point = Point{ .x = 1, .y = 2 };

pub fn main() anyerror!void {
    const stdout = std.io.getStdOut().writer();

    // [1,2]
    try json.toWriterWith(point, stdout, struct {
        pub fn is(comptime T: type) bool {
            return T == Point;
        }

        pub fn serialize(value: anytype, serializer: anytype) !@TypeOf(serializer).Ok {
            const seq = (try serializer.serializeSeq(2)).seq();
            try seq.serializeElement(value.x);
            try seq.serializeElement(value.y);
            return try seq.end();
        }
    });
}

toPrettyWriterWith - Serializes a value as pretty-printed JSON into an I/O stream using a Serialization Block or Tuple.

Synopsis

fn toPrettyWriterWith(value: anytype, writer: anytype, ser: anytype) !void

Example

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

const allocator = std.heap.page_allocator;

const Point = struct { x: i32, y: i32 };
const point = Point{ .x = 1, .y = 2 };

pub fn main() anyerror!void {
    const stdout = std.io.getStdOut().writer();

    // [
    //   1,
    //   2
    // ]
    try json.toPrettyWriterWith(point, stdout, struct {
        pub fn is(comptime T: type) bool {
            return T == Point;
        }

        pub fn serialize(value: anytype, serializer: anytype) !@TypeOf(serializer).Ok {
            const seq = (try serializer.serializeSeq(2)).seq();
            try seq.serializeElement(value.x);
            try seq.serializeElement(value.y);
            return try seq.end();
        }
    });
}

Deserialization

fromSlice - Deserializes a value of type T from a string of JSON text.

Synopsis

fn fromSlice(allocator: ?std.mem.Allocator, comptime T: type, slice: []const u8) !T

Example

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

const Point = struct { x: i32, y: i32 };
const string =
    \\{
    \\  "x": 1,
    \\  "y": 2
    \\}
;

pub fn main() anyerror!void {
    const point = try json.fromSlice(null, Point, string);

    // Point{ .x = 1, .y = 2 }
    std.debug.print("{any}\n", .{point});
}

fromSliceWith - Deserializes a value of type T from a string of JSON text using a Deserialization Block or Tuple.

Synopsis

fn fromSliceWith(
    allocator: ?std.mem.Allocator,
    comptime T: type,
    slice: []const u8,
    de: anytype,
) !T

Example

const std = @import("std");
const getty = @import("getty");
const json = @import("json");

const Point = struct { x: i32, y: i32 };

pub fn main() anyerror!void {
    const point = try json.fromSliceWith(null, Point, "[1,2]", struct {
        pub fn is(comptime T: type) bool {
            return T == Point;
        }

        pub fn deserialize(
            allocator: ?std.mem.Allocator,
            comptime _: type,
            deserializer: anytype,
            visitor: anytype,
        ) !Point {
            return try deserializer.deserializeSeq(allocator, visitor);
        }

        pub fn Visitor(comptime _: type) type {
            return struct {
                pub usingnamespace getty.de.Visitor(
                    @This(),
                    Point,
                    undefined,
                    undefined,
                    undefined,
                    undefined,
                    undefined,
                    undefined,
                    visitSeq,
                    undefined,
                    undefined,
                    undefined,
                );

                pub fn visitSeq(
                    _: @This(),
                    allocator: ?std.mem.Allocator,
                    comptime _: type,
                    seq: anytype,
                ) !Point {
                    var point: Point = undefined;

                    inline for (std.meta.fields(Point)) |field| {
                        if (try seq.nextElement(allocator, i32)) |elem| {
                            @field(point, field.name) = elem;
                        }
                    }

                    if ((try seq.nextElement(allocator, i32)) != null) {
                        return error.InvalidLength;
                    }

                    return point;
                }
            };
        }
    });

    // Point{ .x = 1, .y = 2 }
    std.debug.print("{any}\n", .{point});
}

Contributing

See CONTRIBUTING.md.

Namek / zig-getty-json

Overview

Installation

Gyro

Zigmod

API Reference

Serialization

Deserialization

Contributing

About

Languages