Something went wrong. Try again.
BIND zone files for Zig 0.16: read one, edit it, write it back
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie <jeff@ocjtech.us>// SPDX-License-Identifier: MIT
//! The tokens a zone file is made of.//!//! RFC 1035 §5.1 gives the master file a lexical structure that is almost, but//! not quite, "split on whitespace"://!//! * A newline ends an entry, **unless** an unclosed parenthesis is open, in//! which case it is whitespace like any other. That is how a long `soa` is//! written across six lines.//! * A `;` begins a comment that runs to the end of the line, and the newline//! still ends the entry.//! * A `"` begins a string that may hold spaces, parentheses and semicolons,//! none of which mean anything inside it.//! * A backslash escapes the character after it anywhere at all, which is what//! lets a label hold a dot and a `txt` hold a quote.//! * **Whether a line begins with whitespace is significant.** A line starting//! in the first column names an owner; a line starting with a space or a tab//! is another record for the owner above it. It is the only place in the//! format where indentation carries meaning, and it is why `next` reports//! `leading_whitespace` rather than quietly skipping the gap.//!//! Tokens borrow a buffer this lexer owns, and they are given as offsets into//! it rather than as slices, because appending the next token may move it. Ask//! for the bytes with `text`, and only once the whole entry has been read --//! which is what `Parser` does, and why `reset` is its call to make and not//! this one's.//!//! Nothing here opens a file: the lexer reads from a `std.Io.Reader` the//! caller supplies, one byte at a time, which is what makes `$INCLUDE` the//! caller's business too.
const std = @import("std");const Allocator = std.mem.Allocator;const Reader = std.Io.Reader;
const Lexer = @This();
/// Where the characters come from. Anything that is a `std.Io.Reader`: a file,/// a socket, or `std.Io.Reader.fixed` over a string in a test.reader: *Reader,/// The text of every token in the entry being read, back to back.buffer: std.ArrayList(u8) = .empty,/// One character read and put back, which is how a token knows it has ended/// without losing the character that ended it.pending: ?u8 = null,/// The line the next character will be on, counting from one.line: u32 = 1,/// The column the next character will be in, counting from one.column: u32 = 1,/// How many parentheses are open. Inside them a newline is whitespace.depth: u32 = 0,/// Where the token that `next` refused began, so that a diagnostic can point/// at the quote that never closed rather than at the line after it.failed_line: u32 = 0,failed_column: u32 = 0,/// Whether anything has been read on the entry in progress, so that a blank/// line and a comment line do not produce an entry of no tokens.started: bool = false,
pub const Error = error{ /// The file ended, or an entry did, with a parenthesis still open. UnbalancedParentheses, /// A `)` with no `(` before it. UnexpectedParenthesis, /// A newline or the end of the file inside a quoted string. Refused where /// it happens rather than at the far end of the file, because an /// unterminated quote otherwise swallows everything after it and the /// error lands nowhere near the mistake. UnterminatedString, /// A backslash as the last character in the file. BadEscape,} || Allocator.Error || Reader.Error;
pub const Kind = enum { /// A word, or a quoted string. `quoted` says which it was, because a /// `txt` record of `""` is one empty string and not no strings at all. string, /// The end of an entry: a newline outside any parentheses. end_of_entry, /// The end of the input. Returned for ever once reached. end_of_file,};
pub const Token = struct { kind: Kind, /// Where the text starts in the lexer's buffer. Ask `text` for the bytes. start: u32 = 0, len: u32 = 0, /// Whether it was written in double quotes. quoted: bool = false, /// Whether there was a space, a tab, a parenthesis or a newline /// immediately before it. For the first token of an entry this is the /// difference between an owner name and the same name a line later /// meaning something else entirely. leading_whitespace: bool = false, /// Where the token began, for an error message that can be looked up. line: u32 = 1, column: u32 = 1,};
/// Frees the token buffer. The reader is the caller's and is left alone.pub fn deinit(self: *Lexer, gpa: Allocator) void { self.buffer.deinit(gpa); self.* = undefined;}
/// The bytes of a token, exactly as they were written: escapes are still/// escapes and a quoted string has lost only its quotes. Undoing the escapes/// is the reader's job, and what it means to undo them depends on the field --/// in a name a `\.` is part of a label, and in a `txt` it is a full stop.pub fn text(self: *const Lexer, token: Token) []const u8 { return self.buffer.items[token.start..][0..token.len];}
/// Forgets the text of every token read so far. The parser calls this when it/// has finished with an entry; until then, the tokens of the entry it is/// building all point in here.pub fn reset(self: *Lexer) void { self.buffer.clearRetainingCapacity();}
fn get(self: *Lexer) Reader.Error!?u8 { if (self.pending) |c| { self.pending = null; return c; } return self.reader.takeByte() catch |err| switch (err) { error.EndOfStream => null, else => |e| return e, };}
fn unget(self: *Lexer, c: u8) void { std.debug.assert(self.pending == null); self.pending = c;}
/// Advances the line and column counters over a character that has been taken.fn count(self: *Lexer, c: u8) void { if (c == '\n') { self.line += 1; self.column = 1; } else { self.column += 1; }}
fn take(self: *Lexer) Reader.Error!?u8 { const c = try self.get() orelse return null; self.count(c); return c;}
fn fail(self: *Lexer, err: Error, line: u32, column: u32) Error { self.failed_line = line; self.failed_column = column; return err;}
/// The next token. Keeps returning `end_of_file` once the input is exhausted.pub fn next(self: *Lexer, gpa: Allocator) Error!Token { var leading = false; while (true) { const line = self.line; const column = self.column; const c = try self.take() orelse { if (self.depth != 0) return self.fail(error.UnbalancedParentheses, line, column); if (self.started) { self.started = false; return .{ .kind = .end_of_entry, .line = line, .column = column }; } return .{ .kind = .end_of_file, .line = line, .column = column }; }; switch (c) { ' ', '\t', '\r' => leading = true, '\n' => { // Inside parentheses a newline is just more whitespace, which // is the whole point of them. if (self.depth != 0) { leading = true; continue; } if (self.started) { self.started = false; return .{ .kind = .end_of_entry, .line = line, .column = column }; } // A blank line, or one holding nothing but a comment. The // indentation of a line that turned out to be empty says // nothing about the line after it. leading = false; }, ';' => { while (try self.get()) |comment| { if (comment == '\n') { self.unget(comment); break; } self.count(comment); } }, '(' => { self.depth += 1; self.started = true; leading = true; }, ')' => { if (self.depth == 0) return self.fail(error.UnexpectedParenthesis, line, column); self.depth -= 1; leading = true; }, '"' => { self.started = true; const start: u32 = @intCast(self.buffer.items.len); while (true) { const q = try self.take() orelse return self.fail(error.UnterminatedString, line, column); switch (q) { '"' => break, '\n' => return self.fail(error.UnterminatedString, line, column), '\\' => { const escaped = try self.take() orelse return self.fail(error.BadEscape, line, column); if (escaped == '\n') return self.fail(error.UnterminatedString, line, column); try self.buffer.appendSlice(gpa, &.{ '\\', escaped }); }, else => try self.buffer.append(gpa, q), } } return .{ .kind = .string, .start = start, .len = @intCast(self.buffer.items.len - start), .quoted = true, .leading_whitespace = leading, .line = line, .column = column, }; }, else => { self.started = true; const start: u32 = @intCast(self.buffer.items.len); // `c` has been taken and counted already; everything after it // is looked at before being counted, so that the character // which ends the token can be put back unread. var w = c; while (true) { if (w == '\\') { const escaped = try self.take() orelse return self.fail(error.BadEscape, line, column); try self.buffer.appendSlice(gpa, &.{ '\\', escaped }); } else { try self.buffer.append(gpa, w); } const peeked = try self.get() orelse break; switch (peeked) { ' ', '\t', '\r', '\n', ';', '(', ')', '"' => { // Not consumed: the character that ended the token // may end the entry as well -- and a quote begins // the next one, which is what makes // `alpn="h2,h3"` two tokens and its value the // quoted half. self.unget(peeked); break; }, else => { self.count(peeked); w = peeked; }, } } return .{ .kind = .string, .start = start, .len = @intCast(self.buffer.items.len - start), .leading_whitespace = leading, .line = line, .column = column, }; }, } }}
const testing = std.testing;
test next { const gpa = testing.allocator; var reader: Reader = .fixed("www IN A 192.0.2.1 ; the web server\n"); var lexer: Lexer = .{ .reader = &reader }; defer lexer.deinit(gpa);
for ([_][]const u8{ "www", "IN", "A", "192.0.2.1" }) |expected| { const token = try lexer.next(gpa); try testing.expectEqual(Kind.string, token.kind); try testing.expectEqualStrings(expected, lexer.text(token)); } try testing.expectEqual(Kind.end_of_entry, (try lexer.next(gpa)).kind); try testing.expectEqual(Kind.end_of_file, (try lexer.next(gpa)).kind);}
test text { const gpa = testing.allocator; var reader: Reader = .fixed("\"say \\\"hello\\\"\" a\\.b\n"); var lexer: Lexer = .{ .reader = &reader }; defer lexer.deinit(gpa);
// The quotes are gone and the escapes are not. const quoted = try lexer.next(gpa); try testing.expect(quoted.quoted); try testing.expectEqualStrings("say \\\"hello\\\"", lexer.text(quoted)); const label = try lexer.next(gpa); try testing.expect(!label.quoted); try testing.expectEqualStrings("a\\.b", lexer.text(label));}
test reset { const gpa = testing.allocator; var reader: Reader = .fixed("first entry\nsecond\n"); var lexer: Lexer = .{ .reader = &reader }; defer lexer.deinit(gpa);
while ((try lexer.next(gpa)).kind != .end_of_entry) {} // Done with the first entry, so its text can go. lexer.reset(); const token = try lexer.next(gpa); try testing.expectEqual(@as(u32, 0), token.start); try testing.expectEqualStrings("second", lexer.text(token));}
test deinit { const gpa = testing.allocator; var reader: Reader = .fixed("www A 192.0.2.1\n"); var lexer: Lexer = .{ .reader = &reader }; _ = try lexer.next(gpa); lexer.deinit(gpa);}
/// Every token of a string, as `text|text|...` with `/` for the end of an/// entry, and a `_` in front of a token that had whitespace before it.fn lex(gpa: Allocator, input: []const u8, out: *std.ArrayList(u8)) !void { var reader = Reader.fixed(input); var lexer: Lexer = .{ .reader = &reader }; defer lexer.deinit(gpa); var first = true; while (true) { const token = try lexer.next(gpa); if (token.kind == .end_of_file) break; if (!first) try out.append(gpa, '|'); first = false; switch (token.kind) { .end_of_entry => try out.append(gpa, '/'), .string => { if (token.leading_whitespace) try out.append(gpa, '_'); if (token.quoted) try out.append(gpa, '"'); try out.appendSlice(gpa, lexer.text(token)); }, .end_of_file => unreachable, } }}
fn expectLex(expected: []const u8, input: []const u8) !void { const gpa = testing.allocator; var out: std.ArrayList(u8) = .empty; defer out.deinit(gpa); try lex(gpa, input, &out); try testing.expectEqualStrings(expected, out.items);}
test "words, entries and indentation" { try expectLex("a|_b|/|c|/", "a b\nc"); try expectLex("_a|_b|/", "\ta b"); // A trailing newline is the end of an entry and nothing more. try expectLex("a|/", "a\n"); // A file that ends without one still ends the entry. try expectLex("a|/|b|/", "a\nb\n"); try expectLex("", ""); try expectLex("", "\n\n\n");}
test "comments are not tokens, and do not change the indentation of the line after" { try expectLex("a|/", "a ; and a comment\n"); try expectLex("a|/", "; a comment\na\n"); try expectLex("a|/", " ; an indented comment\na\n"); try expectLex("_a|/", " ; an indented comment\n a\n"); try expectLex("a\\;b|/", "a\\;b ; the escape is not a comment\n");}
test "parentheses hide the newlines inside them" { try expectLex("a|_b|_c|/", "a ( b\n c )\n"); try expectLex("a|_b|/|c|/", "a ( b\n) \nc\n"); try testing.expectError(error.UnbalancedParentheses, expectLex("", "a ( b\n")); try testing.expectError(error.UnexpectedParenthesis, expectLex("", "a ) b\n"));}
test "quoted strings hold what would otherwise be punctuation" { try expectLex("\"a b ; ( ) c|/", "\"a b ; ( ) c\"\n"); try expectLex("\"|/", "\"\"\n"); try expectLex("\"a\\\"b|/", "\"a\\\"b\"\n"); // The quotes are the token's delimiters, so two of them are two tokens // even without a space between, and so are a word and the string after // it -- which is what `alpn="h2,h3"` relies on. try expectLex("\"a|\"b|/", "\"a\"\"b\"\n"); try expectLex("alpn=|\"h2,h3|/", "alpn=\"h2,h3\"\n"); try testing.expectError(error.UnterminatedString, expectLex("", "\"a\n\"\n")); try testing.expectError(error.UnterminatedString, expectLex("", "\"a"));}
test "an escape keeps its backslash, because what it means depends on the field" { try expectLex("a\\.b|/", "a\\.b\n"); try expectLex("a\\032b|/", "a\\032b\n"); try expectLex("a\\ b|/", "a\\ b\n"); try testing.expectError(error.BadEscape, expectLex("", "a\\"));}
test "the line and column of a token are where it began" { const gpa = testing.allocator; var reader = Reader.fixed("first\n second third\n"); var lexer: Lexer = .{ .reader = &reader }; defer lexer.deinit(gpa);
const first = try lexer.next(gpa); try testing.expectEqual(@as(u32, 1), first.line); try testing.expectEqual(@as(u32, 1), first.column); _ = try lexer.next(gpa); // the end of the entry
const second = try lexer.next(gpa); try testing.expectEqual(@as(u32, 2), second.line); try testing.expectEqual(@as(u32, 3), second.column); const third = try lexer.next(gpa); try testing.expectEqual(@as(u32, 2), third.line); try testing.expectEqual(@as(u32, 10), third.column);}