//! Approved-journal parsing (M1-HIST-004, M1-HIST-005, M1-HIST-013). //! //! Reads back only what emit.zig writes. M1-HIST-004 allows whitespace and //! line-ending differences that do not alter the data, so indentation, the //! gap before an amount or a comment, blank lines between transactions and //! CRLF against LF are all free. What is *not* free is whitespace that is //! itself data: the text after a narration's date, and a comment payload, are //! taken exactly. §11.1 fixes the boundary -- one space after the `;` belongs //! to the syntax and everything beyond it is payload. //! //! M1-HIST-005 makes anything outside the subset an error rather than //! something to ignore or compare as text, so this parser is deliberately //! narrow: two postings, an amount on the first and none on the second, no //! status, code, price, cost or assertion, and no directives. const std = @import("std"); const Decimal = @import("../Decimal.zig"); const diag = @import("../diag.zig"); const row = @import("../row.zig"); const Date = @import("../Date.zig"); const Posting = @import("Posting.zig"); const Amount = @import("Amount.zig"); const Transaction = @import("Transaction.zig"); const Journal = @import("../Journal.zig"); pub const Error = error{ UnsupportedJournal, OutOfMemory }; pub fn parse( arena: std.mem.Allocator, file: []const u8, text: []const u8, diags: *diag.List, ) Error!Journal { var reader: Reader = .{ .arena = arena, .file = file, .diags = diags }; if (std.mem.startsWith(u8, text, "\xEF\xBB\xBF")) { return reader.fail(0, "journal begins with a byte-order mark", .{}); } if (!std.unicode.utf8ValidateSlice(text)) { return reader.fail(0, "journal is not valid UTF-8", .{}); } var lines = std.mem.splitScalar(u8, text, '\n'); var number: usize = 0; while (lines.next()) |raw| { number += 1; const line = std.mem.trimEnd(u8, raw, "\r"); if (isBlank(line)) continue; if (isIndented(line)) { try reader.addPosting(line, number); } else { try reader.closeTransaction(number); try reader.openTransaction(line, number); } } try reader.closeTransaction(number); return .{ .transactions = reader.transactions.items }; } const Reader = struct { arena: std.mem.Allocator, diags: *diag.List, file: []const u8, /// The header of the transaction currently being read, if any. open: ?struct { date: row.Date, line: usize, narration: []const u8 } = null, postings: std.ArrayList(Posting) = .empty, transactions: std.ArrayList(Transaction) = .empty, fn openTransaction(self: *Reader, line: []const u8, number: usize) Error!void { // A date, one space, then the narration exactly as written. if (line.len < 11 or line[10] != ' ') { return self.fail(number, "'{s}' is not a transaction header", .{line}); } const date = Date.parse(line[0..10], .iso) orelse return self.fail(number, "'{s}' is not a valid date", .{line[0..10]}); const narration = line[11..]; // M1-HIST-005: a status mark or transaction code is outside the subset. if (narration.len > 0) switch (narration[0]) { '*', '!' => return self.fail(number, "transaction statuses are not supported", .{}), '(' => return self.fail(number, "transaction codes are not supported", .{}), else => {}, }; self.open = .{ .date = date, .narration = narration, .line = number }; self.postings = .empty; } fn addPosting(self: *Reader, line: []const u8, number: usize) Error!void { if (self.open == null) { return self.fail(number, "posting appears before any transaction", .{}); } const body = std.mem.trimStart(u8, line, " \t"); // No account or amount may contain ';', so the first one opens the // comment (M1-JRN-009). var before = body; var comment: ?[]const u8 = null; if (std.mem.findScalar(u8, body, ';')) |position| { before = std.mem.trimEnd(u8, body[0..position], " \t"); const after = body[position + 1 ..]; // §11.1: exactly one separator space, then payload verbatim. comment = if (after.len > 0 and after[0] == ' ') after[1..] else after; } else { before = std.mem.trimEnd(u8, body, " \t"); } const split = separatorIndex(before); const account = if (split) |at| before[0..at] else before; const amount = if (split) |at| try self.parseAmount(std.mem.trimStart(u8, before[at..], " \t"), number) else null; switch (Posting.parse(account, amount, comment)) { .account_problem => |problem| return self.fail(number, "account '{s}': {s}", .{ account, problem }), .success => |posting| try self.postings.append(self.arena, posting), } } fn parseAmount(self: *Reader, text: []const u8, number: usize) Error!Amount { // M1-JRN-012: a price, cost or balance assertion is outside the subset. for ([_][]const u8{ "@", "=", "{", "}" }) |excluded| { if (std.mem.find(u8, text, excluded) != null) { return self.fail(number, "'{s}' is not a plain amount", .{text}); } } const space = std.mem.findScalar(u8, text, ' ') orelse return self.fail(number, "amount '{s}' has no currency", .{text}); const quantity = Decimal.parse(text[0..space], .dot) catch return self.fail(number, "'{s}' is not a decimal quantity", .{text[0..space]}); const currency_text = std.mem.trimStart(u8, text[space..], " "); const currency = row.Currency.parse(currency_text) orelse return self.fail(number, "'{s}' is not a supported currency", .{currency_text}); return .{ .quantity = quantity, .currency = currency }; } fn closeTransaction(self: *Reader, number: usize) Error!void { const header = self.open orelse return; self.open = null; // M1-HIST-005: exactly two postings, an amount on the source and none // on the destination. Anything else is syntax we do not emit. if (self.postings.items.len != 2) { return self.fail( header.line, "a transaction has exactly two postings, found {d}", .{self.postings.items.len}, ); } if (self.postings.items[0].amount == null) { return self.fail(header.line, "the source posting has no amount", .{}); } if (self.postings.items[1].amount != null) { return self.fail(header.line, "an explicit destination amount is not supported", .{}); } _ = number; try self.transactions.append(self.arena, .{ .date = header.date, .narration = header.narration, .postings = .{ self.postings.items[0], self.postings.items[1] }, }); } /// Every journal diagnostic names the line it was reading, so the line /// number is folded into the caller's format string rather than built as /// a second string. `diag.List` owns the arena the message goes in. fn fail(self: *Reader, line: usize, comptime fmt: []const u8, args: anytype) Error { self.diags.addFmt("line {d}: " ++ fmt, .{line} ++ args, .{ .file = self.file }) catch return error.OutOfMemory; return error.UnsupportedJournal; } }; /// hledger separates an account from its amount with two spaces or a tab. fn separatorIndex(text: []const u8) ?usize { for (text, 0..) |c, position| { if (c == '\t') return position; if (c == ' ' and position + 1 < text.len and text[position + 1] == ' ') return position; } return null; } fn isBlank(line: []const u8) bool { return std.mem.trim(u8, line, " \t").len == 0; } fn isIndented(line: []const u8) bool { return line.len > 0 and (line[0] == ' ' or line[0] == '\t'); } // -- tests ------------------------------------------------------------------- const expect = std.testing.expect; const expectEqual = std.testing.expectEqual; const expectEqualStrings = std.testing.expectEqualStrings; const expectError = std.testing.expectError; fn parseOf(arena: *std.heap.ArenaAllocator, text: []const u8) Error!Journal { const alloc = arena.allocator(); const diags = diag.List.create(alloc) catch return error.OutOfMemory; return parse(alloc, "bank/2026.csv.journal", text, diags); } const canonical = @embedFile("../testdata/journal/canonical.journal"); test "M1-HIST-004: the shape we emit parses back into the model" { var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const journal = try parseOf(&arena, canonical); try expectEqual(@as(usize, 1), journal.transactions.len); const transaction = journal.transactions[0]; try expectEqual(@as(u16, 2026), transaction.date.year); try expectEqual(@as(u8, 9), transaction.date.month); try expectEqual(@as(u8, 11), transaction.date.day); try expectEqualStrings("market", transaction.narration); const source = transaction.postings[0]; try expectEqualStrings("assets:bank:checking", source.account); try expect(source.amount.?.quantity.eql(try Decimal.parseLiteral("-1.5"))); try expectEqual(row.Currency.eur, source.amount.?.currency); try expectEqualStrings("bank/2026.csv:12", source.comment.?); const destination = transaction.postings[1]; try expectEqualStrings("expenses:food", destination.account); try expect(destination.amount == null); try expectEqualStrings("classified by groceries", destination.comment.?); } test "M1-HIST-004: an empty journal is supported" { var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); try expectEqual(@as(usize, 0), (try parseOf(&arena, "")).transactions.len); try expectEqual(@as(usize, 0), (try parseOf(&arena, "\n\n")).transactions.len); } test "M1-HIST-004: line endings and layout whitespace do not alter the data" { var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); // CRLF, one-space indent, three spaces before the amount, two blank lines. const relaxed = "2026-09-11 market\r\n \tassets:bank:checking -1.50 EUR ; c\r\n" ++ " expenses:food ; d\r\n\r\n\r\n"; const journal = try parseOf(&arena, relaxed); try expectEqual(@as(usize, 1), journal.transactions.len); try expectEqualStrings("assets:bank:checking", journal.transactions[0].postings[0].account); try expectEqualStrings("c", journal.transactions[0].postings[0].comment.?); try expectEqualStrings("d", journal.transactions[0].postings[1].comment.?); } test "M1-HIST-004: exactly one space after the semicolon belongs to the syntax" { var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); // §11.1: one separator space is consumed, everything after it is payload. const leading = "2026-09-11 x\n a:b 1 EUR ; led\n c:d\n"; const journal = try parseOf(&arena, leading); try expectEqualStrings(" led", journal.transactions[0].postings[0].comment.?); } test "M1-AC-014: a whitespace-only comment payload survives the round trip" { var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const spaces = "2026-09-11 x\n a:b 1 EUR\n c:d ; \n"; const journal = try parseOf(&arena, spaces); try expectEqualStrings(" ", journal.transactions[0].postings[1].comment.?); } test "M1-HIST-004: a posting without a comment has none, not an empty one" { var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const journal = try parseOf(&arena, "2026-09-11 x\n a:b 1 EUR\n c:d\n"); try expect(journal.transactions[0].postings[0].comment == null); try expect(journal.transactions[0].postings[1].comment == null); } test "M1-HIST-005: an explicit destination amount is unsupported syntax" { var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); try expectError(error.UnsupportedJournal, parseOf( &arena, "2026-09-11 x\n a:b -1 EUR\n c:d 1 EUR\n", )); } test "M1-HIST-005: a source posting must carry an amount" { var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); try expectError(error.UnsupportedJournal, parseOf( &arena, "2026-09-11 x\n a:b\n c:d\n", )); } test "M1-HIST-005: a transaction must have exactly two postings" { var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); try expectError(error.UnsupportedJournal, parseOf( &arena, "2026-09-11 x\n a:b 1 EUR\n", )); try expectError(error.UnsupportedJournal, parseOf( &arena, "2026-09-11 x\n a:b 1 EUR\n c:d\n e:f\n", )); } test "M1-HIST-005: constructs outside the subset are rejected" { var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); for ([_][]const u8{ "include other.journal\n", "account assets:bank\n", "2026-09-11 * cleared\n a:b 1 EUR\n c:d\n", "2026-09-11 (code) x\n a:b 1 EUR\n c:d\n", "2026-09-11 x\n a:b 1 EUR @ 2 USD\n c:d\n", "2026-09-11 x\n a:b 1 EUR = 3 EUR\n c:d\n", "2026-09-11 x\n (a:b) 1 EUR\n c:d\n", "not-a-date whatever\n", "2026-13-99 x\n a:b 1 EUR\n c:d\n", }) |unsupported| { try expectError(error.UnsupportedJournal, parseOf(&arena, unsupported)); } } test "M1-HIST-005: an unsupported currency is rejected" { var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); try expectError(error.UnsupportedJournal, parseOf( &arena, "2026-09-11 x\n a:b 1 GBP\n c:d\n", )); } test "M1-HIST-010: a rejection names the approved journal" { var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const alloc = arena.allocator(); const diags = try diag.List.create(alloc); _ = parse(alloc, "bank/2026.csv.journal", "include x\n", diags) catch {}; try expect(!diags.isEmpty()); try expectEqualStrings("bank/2026.csv.journal", diags.items.items[0].file.?); } test "M1-HIST-004: the journal must be UTF-8 without a byte-order mark" { var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); try expectError(error.UnsupportedJournal, parseOf(&arena, "\xEF\xBB\xBF2026-09-11 x\n")); try expectError(error.UnsupportedJournal, parseOf(&arena, "2026-09-11 \xC3\x28\n")); } test "M1-HIST-013: a legacy journal inside the subset is acceptable history" { var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); // Hand-written, differently spaced, but every construct is supported. const legacy = "2026-01-02 opening balance\n\tassets:bank 100.00 EUR\n\tequity:opening\n"; const journal = try parseOf(&arena, legacy); try expectEqualStrings("opening balance", journal.transactions[0].narration); try expectEqualStrings("equity:opening", journal.transactions[0].postings[1].account); } test "M1-HIST-009: a narration keeps its exact text" { var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); const journal = try parseOf(&arena, "2026-09-11 padded \n a:b 1 EUR\n c:d\n"); try expectEqualStrings(" padded ", journal.transactions[0].narration); } test "M1-SAFE-004: fail reports exhaustion rather than the unsupported journal" { var arena = std.heap.ArenaAllocator.init(std.testing.allocator); defer arena.deinit(); var failing = std.testing.FailingAllocator.init(std.testing.allocator, .{ .fail_index = 0 }); var diags = diag.List.init(failing.allocator()); defer diags.deinit(); var reader: Reader = .{ .arena = arena.allocator(), .file = "a.journal", .diags = &diags }; const outcome: Error = reader.fail(3, "is unsupported", .{}); try expectEqual(Error.OutOfMemory, outcome); }