Commit959a593eRecorded25 Mar 2026Repositorysigil-ledger

Add comprehensive README

Changed
 README.md | 82 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 81 insertions(+), 1 deletion(-)
Diff
README.mdmodified
@@ -1,3 +1,83 @@
1
# sigil-ledger
2
−3
Ledger/hledger journal file library for Sigil
3
No newline at end of file
+4
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
+6
## Features
+7
+8
- **Journal parsing** — read hledger journal files into structured records (transactions, postings, amounts, commodities, tags)
+9
- **Journal writing** — write and append transactions in valid hledger format
+10
- **Multi-currency** — full support for cost notation (`@` and `@@`) and balance assertions
+11
- **Deduplication** — filter out already-imported transactions by reference ID tag
+12
- **Report generation** — run hledger CLI commands (balance, register, income statement) and parse output
+13
- **Round-trip fidelity** — parse and re-serialize journals without losing information
+14
+15
## Usage
+16
+17
```scheme
+18
(import (sigil ledger))
+19
+20
;; Parse a journal file
+21
(define txns (read-journal "/path/to/finances.journal"))
+22
+23
;; Create a new transaction
+24
(define txn (make-journal-transaction
+25
date: "2026-03-25"
+26
status: "*"
+27
description: "Coffee Shop"
+28
postings: (list
+29
(make-journal-posting
+30
account: "expenses:food:coffee"
+31
amount: (make-journal-amount quantity: 4.50 commodity: "EUR"))
+32
(make-journal-posting
+33
account: "assets:wise:eur"))))
+34
+35
;; Append to journal with dedup
+36
(append-transactions "/path/to/finances.journal"
+37
(list txn)
+38
dedup-tag: "ref")
+39
```
+40
+41
### Reports via hledger CLI
+42
+43
```scheme
+44
(import (sigil ledger report))
+45
+46
;; Run a balance report
+47
(define bal (hledger-balance journal: "/path/to/finances.journal"
+48
args: '("--tree" "assets")))
+49
+50
;; Income statement for a period
+51
(define is (hledger-income-statement
+52
journal: "/path/to/finances.journal"
+53
args: '("--period" "2026-03")))
+54
```
+55
+56
## Journal Format Support
+57
+58
Handles standard hledger journal syntax:
+59
- Dates, status flags (`*`, `!`), transaction codes
+60
- Payee/note separator (`|`)
+61
- Account names with amounts and commodities
+62
- Inline and line comments (`;`)
+63
- Tags in comments (`tag:value`)
+64
- Cost notation (`@ PRICE` and `@@ TOTAL`)
+65
- Balance assertions (`= AMOUNT`)
+66
+67
## Dependencies
+68
+69
- sigil-stdlib
+70
- sigil-json (for hledger JSON output parsing)
+71
- sigil-log
+72
+73
Requires `hledger` on PATH for report generation features.
+74
+75
## Building
+76
+77
```
+78
sigil build --redirects dev-redirects.sgl
+79
sigil test
+80
```
+81
+82
## License
+83
+84
BSD-3-Clause