README.md — sigil-ledger

1# sigil-ledger

A Sigil library for reading, writing, and querying [hledger](https://hledger.org) journal files. Build financial automation tools that work with plain-text accounting.

5## Features

- **Journal parsing** — read hledger journal files into structured records (transactions, postings, amounts, commodities, tags)

8- **Journal writing** — write and append transactions in valid hledger format

9- **Multi-currency** — full support for cost notation (`@` and `@@`) and balance assertions

10- **Deduplication** — filter out already-imported transactions by reference ID tag

11- **Report generation** — run hledger CLI commands (balance, register, income statement) and parse output

12- **Round-trip fidelity** — parse and re-serialize journals without losing information

14## Usage

16```scheme

17(import (ledger))

19;; Parse a journal file

20(define txns (read-journal "/path/to/finances.journal"))

22;; Create a new transaction

23(define txn (journal-transaction

24 date: "2026-03-25"

25 status: "*"

26 description: "Coffee Shop"

27 postings: (list

28 (journal-posting

29 account: "expenses:food:coffee"

30 amount: (journal-amount quantity: 4.50 commodity: "EUR"))

31 (journal-posting

32 account: "assets:wise:eur"))))

34;; Append new transactions to journal

35(append-transactions "/path/to/finances.journal" (list txn))

36```

38### Reports via hledger CLI

40```scheme

41(import (ledger report))

43;; Run a balance report

44(hledger-balance "/path/to/finances.journal" "assets" tree: #t)

46;; Income statement for a period

47(hledger-income-statement "/path/to/finances.journal" period: "2026-03")

48```

50## Journal Format Support

52Handles standard hledger journal syntax:

53- Dates, status flags (`*`, `!`), transaction codes

54- Payee/note separator (`|`)

55- Account names with amounts and commodities

56- Inline and line comments (`;`)

57- Tags in comments (`tag:value`)

58- Cost notation (`@ PRICE` and `@@ TOTAL`)

59- Balance assertions (`= AMOUNT`, `== AMOUNT`, `=* AMOUNT`)

61## Known Limitations

- **European number format** — amounts using period as thousands separator and comma as decimal separator (e.g. `1.000,50 EUR`) are not supported. Use US-style formatting (`1,000.50 EUR`) or omit thousands separators. This matches the most common hledger usage; full `decimal-mark` directive support may be added in a future release.

65## Dependencies

67- sigil-stdlib

68- sigil-json (for hledger JSON output parsing)

70Requires `hledger` on PATH for report generation features.

72## Building

74```bash

75sigil deps install

76sigil build

77sigil test

78```

80## License

82BSD-3-Clause