Something went wrong. Try again.
A YAML 1.2.2 parser and emitter for Zig 0.16 with the shape of std.json, built from the spec's grammar.
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie <jeff@ocjtech.us>// SPDX-License-Identifier: MIT
//! Parsing YAML into Zig types, the way `std.json.parseFromSlice` parses//! JSON into them.//!//! The target type decides how each node is read://!//! | Type | Node |//! | --- | --- |//! | `bool` | a scalar spelled as a boolean (`true`, `False`, …) |//! | integers | a scalar spelled as an integer (`12`, `0x1F`, `0o17`), or as a float with a whole value |//! | floats | a scalar spelled as a number (`1.5`, `.inf`, `-.NaN`, `12`) |//! | `?T` | a null scalar (`null`, `~`, nothing at all), or whatever `T` accepts |//! | enums | a scalar naming a tag, or its integer value |//! | tagged unions | a single-pair mapping from the tag to its payload; a bare scalar naming the tag for a `void` payload |//! | structs | a mapping from field names to values; tuples, a sequence |//! | `[N]T`, `@Vector` | a sequence of exactly N entries; `[N]u8` also a string of exactly N bytes |//! | `[]T` | a sequence |//! | `[]u8` and the like | any scalar, as its text: `version: 1.10` gives `"1.10"` |//! | `*T` | whatever `T` accepts, allocated |//! | `Value` | anything |//!//! Scalars are matched on their text, whatever their style, so `"8080"`//! parses as a `u16` just as `8080` does — as `std.json` accepts a number in//! a string.//!//! A type takes over its own parsing by declaring either or both of//!//! pub fn yamlParse(allocator: Allocator, source: anytype, options: ParseOptions) !@This()//! pub fn yamlParseFromValue(allocator: Allocator, source: Value, options: ParseOptions) !@This()//!//! where `source` is a `*Scanner` or `*Reader` positioned at the node, which//! the function must consume exactly. `innerParse` and `innerParseFromValue`//! are how such a function parses the parts it does not handle itself.
const std = @import("std");const Allocator = std.mem.Allocator;const ArenaAllocator = std.heap.ArenaAllocator;
const dynamic = @import("dynamic.zig");const event = @import("event.zig");const schema_mod = @import("schema.zig");const Scanner = @import("Scanner.zig");const Value = dynamic.Value;const Schema = schema_mod.Schema;
pub const AllocWhen = enum { alloc_if_needed, alloc_always };
pub const ParseOptions = struct { /// What to do with a key that appears twice in a mapping: in a struct, /// the same field twice; in a `Value`, two equal keys. The spec requires /// keys to be unique, so it is an error by default. duplicate_field_behavior: enum { use_first, @"error", use_last } = .@"error",
/// Skip mapping keys that name no field of the struct being parsed, /// rather than failing with `error.UnknownField`. ignore_unknown_fields: bool = false,
/// Whether strings may point into the input rather than being copied. /// Null means `.alloc_if_needed` for a `Scanner`, whose input is the /// caller's, and `.alloc_always` for a `Reader`, whose buffer is its own. /// Mutable slices (`[]u8`) are always copied. allocate: ?AllocWhen = null,
/// How untagged plain scalars are resolved into a `Value`, and which /// spellings of booleans and numbers typed parsing accepts. schema: Schema = .core,
/// The deepest nesting of collections accepted, bounding the recursion /// both of the grammar and of the parse into types. max_depth: u32 = 512,
/// The most events aliases may expand to across a stream. max_alias_expansion: usize = 1 << 20,
/// What to do with a tag this library does not know. Ignoring it parses /// the node as though it were untagged, except that a scalar is then a /// string (the tag having said it is not to be resolved by its text). unknown_tag_behavior: enum { ignore, @"error" } = .ignore,};
pub const ParseFromValueError = schema_mod.IntError || Allocator.Error || error{ /// The node was not of a kind the target type accepts. UnexpectedToken, /// A number too large for the target type. Overflow, InvalidNumber, InvalidEnumTag, DuplicateField, UnknownField, MissingField, LengthMismatch, /// A scalar whose text its tag, or the JSON schema, does not allow: /// `!!int twelve`. InvalidScalar, /// A tag this library does not know, with `unknown_tag_behavior = .error`. UnknownTag, /// A single value was asked for and the stream holds more than one /// document. MultipleDocuments,};
pub fn ParseError(comptime Source: type) type { return ParseFromValueError || Source.NextError || Source.PeekError || Source.AllocError;}
/// A value and the arena everything it points to was allocated in.pub fn Parsed(comptime T: type) type { return struct { arena: *ArenaAllocator, value: T,
pub fn deinit(self: @This()) void { const allocator = self.arena.child_allocator; self.arena.deinit(); allocator.destroy(self.arena); } };}
fn configure(scanner: *Scanner, options: ParseOptions) void { scanner.max_depth = options.max_depth; scanner.max_alias_expansion = options.max_alias_expansion;}
/// Parses a stream holding one document (or none, which reads as a null/// node) into a `T`.pub fn parseFromSlice(comptime T: type, gpa: Allocator, s: []const u8, options: ParseOptions) ParseError(Scanner)!Parsed(T) { var scanner: Scanner = .initCompleteInput(gpa, s); defer scanner.deinit(); configure(&scanner, options); return parseFromTokenSource(T, gpa, &scanner, options);}
/// As `parseFromSlice`, allocating into `allocator` with no arena of its own;/// meant for an arena the caller manages.pub fn parseFromSliceLeaky(comptime T: type, allocator: Allocator, s: []const u8, options: ParseOptions) ParseError(Scanner)!T { var scanner: Scanner = .initCompleteInput(allocator, s); defer scanner.deinit(); configure(&scanner, options); return parseFromTokenSourceLeaky(T, allocator, &scanner, options);}
/// Parses every document of a stream, each into a `T`.pub fn parseAllFromSlice(comptime T: type, gpa: Allocator, s: []const u8, options: ParseOptions) ParseError(Scanner)!Parsed([]T) { var scanner: Scanner = .initCompleteInput(gpa, s); defer scanner.deinit(); configure(&scanner, options); return parseAllFromTokenSource(T, gpa, &scanner, options);}
pub fn parseAllFromSliceLeaky(comptime T: type, allocator: Allocator, s: []const u8, options: ParseOptions) ParseError(Scanner)![]T { var scanner: Scanner = .initCompleteInput(allocator, s); defer scanner.deinit(); configure(&scanner, options); return parseAllFromTokenSourceLeaky(T, allocator, &scanner, options);}
/// `source` is a `*Scanner` or a `*Reader`, which has not yet been read from.pub fn parseFromTokenSource(comptime T: type, gpa: Allocator, source: anytype, options: ParseOptions) ParseError(@TypeOf(source.*))!Parsed(T) { var parsed: Parsed(T) = .{ .arena = try gpa.create(ArenaAllocator), .value = undefined }; errdefer gpa.destroy(parsed.arena); parsed.arena.* = .init(gpa); errdefer parsed.arena.deinit(); parsed.value = try parseFromTokenSourceLeaky(T, parsed.arena.allocator(), source, options); return parsed;}
pub fn parseAllFromTokenSource(comptime T: type, gpa: Allocator, source: anytype, options: ParseOptions) ParseError(@TypeOf(source.*))!Parsed([]T) { var parsed: Parsed([]T) = .{ .arena = try gpa.create(ArenaAllocator), .value = undefined }; errdefer gpa.destroy(parsed.arena); parsed.arena.* = .init(gpa); errdefer parsed.arena.deinit(); parsed.value = try parseAllFromTokenSourceLeaky(T, parsed.arena.allocator(), source, options); return parsed;}
fn withDefaults(comptime Source: type, options: ParseOptions) ParseOptions { var opts = options; if (opts.allocate == null) opts.allocate = if (Source == Scanner) .alloc_if_needed else .alloc_always; return opts;}
pub fn parseFromTokenSourceLeaky(comptime T: type, allocator: Allocator, source: anytype, options: ParseOptions) ParseError(@TypeOf(source.*))!T { const opts = withDefaults(@TypeOf(source.*), options); try expect(source, .stream_start); if (try source.peekNextEventType() == .stream_end) { _ = try source.next(); return parseFromValueLeaky(T, allocator, .null, opts); } const value = try parseDocument(T, allocator, source, opts); if (try source.peekNextEventType() == .document_start) return error.MultipleDocuments; try expect(source, .stream_end); return value;}
pub fn parseAllFromTokenSourceLeaky(comptime T: type, allocator: Allocator, source: anytype, options: ParseOptions) ParseError(@TypeOf(source.*))![]T { const opts = withDefaults(@TypeOf(source.*), options); try expect(source, .stream_start); var values: std.ArrayList(T) = .empty; while (try source.peekNextEventType() == .document_start) { try values.append(allocator, try parseDocument(T, allocator, source, opts)); } try expect(source, .stream_end); return values.toOwnedSlice(allocator);}
fn parseDocument(comptime T: type, allocator: Allocator, source: anytype, options: ParseOptions) ParseError(@TypeOf(source.*))!T { try expect(source, .document_start); const value = try innerParse(T, allocator, source, options); try expect(source, .document_end); return value;}
fn expect(source: anytype, comptime kind: event.EventType) ParseError(@TypeOf(source.*))!void { const ev = try source.next(); if (ev != kind) return error.UnexpectedToken;}
fn nextScalar(source: anytype) ParseError(@TypeOf(source.*))!event.Scalar { return switch (try source.next()) { .scalar => |s| s, else => error.UnexpectedToken, };}
/// The schema typed parsing reads numbers and booleans with: the one asked/// for, except that the failsafe schema — which would recognize none — reads/// them as the core schema does, the target type having said what to expect.fn typedSchema(options: ParseOptions) Schema { return if (options.schema == .json) .json else .core;}
const null_tag = schema_mod.tag_prefix ++ "null";
/// Whether a scalar is null: tagged `!!null`, or plain and spelled as a null.pub fn isNullScalar(s: event.Scalar, options: ParseOptions) bool { if (s.tag) |tag| return std.mem.eql(u8, tag, null_tag); return s.style == .plain and schema_mod.isNull(typedSchema(options), s.value);}
fn keepString(allocator: Allocator, source: anytype, s: []const u8, options: ParseOptions) Allocator.Error![]const u8 { if (options.allocate == .alloc_if_needed and @hasDecl(@TypeOf(source.*), "isInInput") and source.isInInput(s)) return s; return allocator.dupe(u8, s);}
/// Parses the node the source is positioned at as a `T`. This is what a/// `yamlParse` function calls for the parts of itself it leaves to the/// defaults.pub fn innerParse(comptime T: type, allocator: Allocator, source: anytype, options: ParseOptions) ParseError(@TypeOf(source.*))!T { switch (@typeInfo(T)) { .bool => { const s = try nextScalar(source); return schema_mod.parseBool(typedSchema(options), s.value) orelse error.UnexpectedToken; }, .float, .comptime_float => { const s = try nextScalar(source); return schema_mod.parseFloat(T, typedSchema(options), s.value); }, .int, .comptime_int => { const s = try nextScalar(source); return schema_mod.parseInt(T, typedSchema(options), s.value); }, .optional => |info| { switch (try source.peek()) { .scalar => |s| if (isNullScalar(s, options)) { _ = try source.next(); return null; }, else => {}, } return try innerParse(info.child, allocator, source, options); }, .void => { try source.skipValue(); return {}; }, .@"enum" => { if (comptime std.meta.hasFn(T, "yamlParse")) return T.yamlParse(allocator, source, options); const s = try nextScalar(source); return enumFromText(T, s.value, options); }, .@"union" => |info| { if (comptime std.meta.hasFn(T, "yamlParse")) return T.yamlParse(allocator, source, options); if (info.tag_type == null) @compileError("Unable to parse into untagged union '" ++ @typeName(T) ++ "'"); // A bare scalar naming a variant with no payload. if (try source.peekNextEventType() == .scalar) { const s = try nextScalar(source); inline for (info.fields) |field| { if (field.type == void and std.mem.eql(u8, field.name, s.value)) return @unionInit(T, field.name, {}); } return error.UnknownField; } try expect(source, .mapping_start); const key = try nextScalar(source); inline for (info.fields) |field| { if (std.mem.eql(u8, field.name, key.value)) { const result = @unionInit(T, field.name, try innerParse(field.type, allocator, source, options)); try expect(source, .mapping_end); return result; } } return error.UnknownField; }, .@"struct" => |info| { if (comptime std.meta.hasFn(T, "yamlParse")) return T.yamlParse(allocator, source, options); if (info.is_tuple) { try expect(source, .sequence_start); var r: T = undefined; inline for (0..info.fields.len) |i| { if (try source.peekNextEventType() == .sequence_end) return error.LengthMismatch; r[i] = try innerParse(info.fields[i].type, allocator, source, options); } if (try source.peekNextEventType() != .sequence_end) return error.LengthMismatch; _ = try source.next(); return r; } try expect(source, .mapping_start); var r: T = undefined; var seen = [_]bool{false} ** info.fields.len; while (true) { if (try source.peekNextEventType() == .mapping_end) { _ = try source.next(); break; } if (try source.peekNextEventType() != .scalar) { // A key that is a collection can name no field. if (!options.ignore_unknown_fields) return error.UnknownField; try source.skipValue(); try source.skipValue(); continue; } const key = try nextScalar(source); const matched = inline for (info.fields, 0..) |field, i| { if (field.is_comptime) @compileError("comptime fields are not supported: " ++ @typeName(T) ++ "." ++ field.name); if (std.mem.eql(u8, field.name, key.value)) { if (seen[i]) switch (options.duplicate_field_behavior) { .use_first => { try source.skipValue(); break true; }, .@"error" => return error.DuplicateField, .use_last => {}, }; @field(r, field.name) = try innerParse(field.type, allocator, source, options); seen[i] = true; break true; } } else false; if (!matched) { if (!options.ignore_unknown_fields) return error.UnknownField; try source.skipValue(); } } try fillDefaults(T, &r, &seen); return r; }, .array => |info| { if (info.child == u8 and try source.peekNextEventType() == .scalar) { const s = try nextScalar(source); if (s.value.len != info.len) return error.LengthMismatch; var r: T = undefined; @memcpy(r[0..], s.value); return r; } try expect(source, .sequence_start); var r: T = undefined; for (&r) |*item| { if (try source.peekNextEventType() == .sequence_end) return error.LengthMismatch; item.* = try innerParse(info.child, allocator, source, options); } if (try source.peekNextEventType() != .sequence_end) return error.LengthMismatch; _ = try source.next(); return r; }, .vector => |info| { try expect(source, .sequence_start); var r: T = undefined; var i: usize = 0; while (i < info.len) : (i += 1) { if (try source.peekNextEventType() == .sequence_end) return error.LengthMismatch; r[i] = try innerParse(info.child, allocator, source, options); } if (try source.peekNextEventType() != .sequence_end) return error.LengthMismatch; _ = try source.next(); return r; }, .pointer => |info| switch (info.size) { .one => { const r = try allocator.create(info.child); r.* = try innerParse(info.child, allocator, source, options); return r; }, .slice => { if (info.child == u8 and try source.peekNextEventType() == .scalar) { const s = try nextScalar(source); if (info.sentinel()) |sentinel| { if (sentinel != 0) @compileError("only a zero sentinel is supported for strings: " ++ @typeName(T)); return allocator.dupeZ(u8, s.value); } if (info.is_const) return keepString(allocator, source, s.value, options); return allocator.dupe(u8, s.value); } try expect(source, .sequence_start); var list: std.ArrayList(info.child) = .empty; while (try source.peekNextEventType() != .sequence_end) { try list.append(allocator, try innerParse(info.child, allocator, source, options)); } _ = try source.next(); if (info.sentinel()) |sentinel| return list.toOwnedSliceSentinel(allocator, sentinel); return list.toOwnedSlice(allocator); }, else => @compileError("Unable to parse into type '" ++ @typeName(T) ++ "'"), }, else => @compileError("Unable to parse into type '" ++ @typeName(T) ++ "'"), }}
fn enumFromText(comptime T: type, text: []const u8, options: ParseOptions) error{InvalidEnumTag}!T { if (std.meta.stringToEnum(T, text)) |v| return v; const Int = @typeInfo(T).@"enum".tag_type; const n = schema_mod.parseInt(Int, typedSchema(options), text) catch return error.InvalidEnumTag; return std.enums.fromInt(T, n) orelse error.InvalidEnumTag;}
fn fillDefaults(comptime T: type, r: *T, seen: []const bool) error{MissingField}!void { inline for (@typeInfo(T).@"struct".fields, 0..) |field, i| { if (!seen[i]) { if (field.defaultValue()) |default| { @field(r, field.name) = default; } else return error.MissingField; } }}
/// Parses a `Value` already in hand as a `T`, by the same rules as parsing/// from events.pub fn parseFromValue(comptime T: type, gpa: Allocator, source: Value, options: ParseOptions) ParseFromValueError!Parsed(T) { var parsed: Parsed(T) = .{ .arena = try gpa.create(ArenaAllocator), .value = undefined }; errdefer gpa.destroy(parsed.arena); parsed.arena.* = .init(gpa); errdefer parsed.arena.deinit(); parsed.value = try parseFromValueLeaky(T, parsed.arena.allocator(), source, options); return parsed;}
pub fn parseFromValueLeaky(comptime T: type, allocator: Allocator, source: Value, options: ParseOptions) ParseFromValueError!T { return innerParseFromValue(T, allocator, source, options);}
/// The counterpart of `innerParse` for a `Value`.pub fn innerParseFromValue(comptime T: type, allocator: Allocator, source: Value, options: ParseOptions) ParseFromValueError!T { switch (@typeInfo(T)) { .bool => return switch (source) { .bool => |b| b, .string => |s| schema_mod.parseBool(typedSchema(options), s) orelse error.UnexpectedToken, else => error.UnexpectedToken, }, .float, .comptime_float => return switch (source) { .float => |f| @floatCast(f), .integer => |i| @floatFromInt(i), .number_string, .string => |s| try schema_mod.parseFloat(T, typedSchema(options), s), else => error.UnexpectedToken, }, .int, .comptime_int => return switch (source) { .integer => |i| std.math.cast(T, i) orelse error.Overflow, .float => |f| try schema_mod.floatToInt(T, f), .number_string, .string => |s| try schema_mod.parseInt(T, typedSchema(options), s), else => error.UnexpectedToken, }, .optional => |info| return switch (source) { .null => null, else => try innerParseFromValue(info.child, allocator, source, options), }, .void => return {}, .@"enum" => { if (comptime std.meta.hasFn(T, "yamlParseFromValue")) return T.yamlParseFromValue(allocator, source, options); return switch (source) { .string => |s| enumFromText(T, s, options), .integer => |i| std.enums.fromInt(T, i) orelse error.InvalidEnumTag, else => error.UnexpectedToken, }; }, .@"union" => |info| { if (comptime std.meta.hasFn(T, "yamlParseFromValue")) return T.yamlParseFromValue(allocator, source, options); if (info.tag_type == null) @compileError("Unable to parse into untagged union '" ++ @typeName(T) ++ "'"); switch (source) { .string => |s| { inline for (info.fields) |field| { if (field.type == void and std.mem.eql(u8, field.name, s)) return @unionInit(T, field.name, {}); } return error.UnknownField; }, .mapping => |m| { if (m.count() != 1) return error.UnexpectedToken; const key = m.keys()[0]; if (key != .string) return error.UnexpectedToken; inline for (info.fields) |field| { if (std.mem.eql(u8, field.name, key.string)) return @unionInit(T, field.name, try innerParseFromValue(field.type, allocator, m.values()[0], options)); } return error.UnknownField; }, else => return error.UnexpectedToken, } }, .@"struct" => |info| { if (comptime std.meta.hasFn(T, "yamlParseFromValue")) return T.yamlParseFromValue(allocator, source, options); if (info.is_tuple) { if (source != .sequence) return error.UnexpectedToken; const items = source.sequence.items; if (items.len != info.fields.len) return error.LengthMismatch; var r: T = undefined; inline for (0..info.fields.len) |i| { r[i] = try innerParseFromValue(info.fields[i].type, allocator, items[i], options); } return r; } if (source != .mapping) return error.UnexpectedToken; var r: T = undefined; var seen = [_]bool{false} ** info.fields.len; var it = source.mapping.iterator(); while (it.next()) |entry| { const key = entry.key_ptr.*; const matched = key == .string and inline for (info.fields, 0..) |field, i| { if (field.is_comptime) @compileError("comptime fields are not supported: " ++ @typeName(T) ++ "." ++ field.name); if (std.mem.eql(u8, field.name, key.string)) { @field(r, field.name) = try innerParseFromValue(field.type, allocator, entry.value_ptr.*, options); seen[i] = true; break true; } } else false; if (!matched and !options.ignore_unknown_fields) return error.UnknownField; } try fillDefaults(T, &r, &seen); return r; }, .array => |info| switch (source) { .string => |s| { if (info.child != u8) return error.UnexpectedToken; if (s.len != info.len) return error.LengthMismatch; var r: T = undefined; @memcpy(r[0..], s); return r; }, .sequence => |seq| { if (seq.items.len != info.len) return error.LengthMismatch; var r: T = undefined; for (&r, seq.items) |*dst, item| dst.* = try innerParseFromValue(info.child, allocator, item, options); return r; }, else => return error.UnexpectedToken, }, .vector => |info| { if (source != .sequence) return error.UnexpectedToken; if (source.sequence.items.len != info.len) return error.LengthMismatch; var r: T = undefined; for (source.sequence.items, 0..) |item, i| r[i] = try innerParseFromValue(info.child, allocator, item, options); return r; }, .pointer => |info| switch (info.size) { .one => { const r = try allocator.create(info.child); r.* = try innerParseFromValue(info.child, allocator, source, options); return r; }, .slice => switch (source) { .string, .number_string => |s| { if (info.child != u8) return error.UnexpectedToken; if (info.sentinel()) |sentinel| { if (sentinel != 0) @compileError("only a zero sentinel is supported for strings: " ++ @typeName(T)); return allocator.dupeZ(u8, s); } return allocator.dupe(u8, s); }, .sequence => |seq| { const r = if (info.sentinel()) |sentinel| try allocator.allocSentinel(info.child, seq.items.len, sentinel) else try allocator.alloc(info.child, seq.items.len); for (r, seq.items) |*dst, item| dst.* = try innerParseFromValue(info.child, allocator, item, options); return r; }, else => return error.UnexpectedToken, }, else => @compileError("Unable to parse into type '" ++ @typeName(T) ++ "'"), }, else => @compileError("Unable to parse into type '" ++ @typeName(T) ++ "'"), }}