zig-toml

Zig TOML v1.1.0 parser.

This is a top-down LL parser that parses directly into Zig structs.

Features

• TOML Syntax
  • Integers, hexadecimal, octal, and binary numbers
  • Floats
  • Booleans
  • Comments
  • Arrays
  • Tables
  • Array of Tables
  • Inline Table
  • Single-line strings
  • String escapes (also unicode)
  • Multi-line strings
  • Multi-line string leading space trimming
  • Trailing backslash in multi-line strings
  • Date, time, date-time, time offset
• Struct mapping
  • Mapping to structs
  • Mapping to enums
  • Mapping to slices
  • Mapping to arrays
  • Mapping to pointers
  • Mapping to integer and floats with lower bit number than defined by TOML, i.e. i16, f32.
  • Mapping to optional fields
  • Mapping to HashMaps
  • Optional strict mode that rejects unknown keys (disallow_unknown_fields)
• Serialization
  • Basic types like integers, floating points, strings, booleans etc.
  • Arrays
  • Top level tables
  • Sub tables
  • Pointers
  • Date, time, DateTime, time offset
  • Enums
  • Unions

Using with the Zig package manager

Add zig-toml to your build.zig.zon

# For zig-master
zig fetch --save git+https://github.com/sam701/zig-toml

# For zig 0.16
zig fetch --save git+https://github.com/sam701/zig-toml#zig-0.16

# For zig 0.15
zig fetch --save git+https://github.com/sam701/zig-toml#zig-0.15

Example

See example1.zig for the complete code that parses example.toml

Run it with zig build examples

// ....

const Address = struct {
    port: i64,
    host: []const u8,
};

const Config = struct {
    master: bool,
    expires_at: toml.DateTime,
    description: []const u8,

    local: *Address,
    peers: []const Address,
};

pub fn main(init: std.process.Init) anyerror!void {
    var parser = toml.Parser(Config).init(init.gpa);
    defer parser.deinit();

    var result = try parser.parseFile(init.io, "./examples/example1.toml");
    defer result.deinit();

    const config = result.value;
    std.debug.print("{s}\nlocal address: {s}:{}\n", .{ config.description, config.local.host, config.local.port });
    std.debug.print("peer0: {s}:{}\n", .{ config.peers[0].host, config.peers[0].port });
}

Strict mode

By default an unknown key in the TOML document (one with no matching struct field) is silently ignored, so a typo like nam instead of name goes unnoticed. Set disallow_unknown_fields on the parser to make such keys fail with error.UnknownField:

var parser = toml.Parser(Config).init(allocator);
parser.options.disallow_unknown_fields = true;
defer parser.deinit();

const result = parser.parseFile(init.io, "./config.toml") catch |err| {
    // On error.UnknownField, parser.error_info.?.unknown_fields lists every
    // unrecognized key: `.path` names the table, `.keys` are the unknown keys.
    return err;
};

Error Handling

TODO

License

MIT