rledger is a lightweight double-entry accounting tool. It's based on the principles of plain text accounting and written in Rust, making it robust and extremely fast.
Brought to you by Alexander Keliris
print commandIt's often useful to simply print the journal, particularly to see inferred amounts or to find a specific transaction.
rledger now supports the print command with the optional explicit toggle for printing inferred amounts: print -x.
Another speed boost just landed by replacing Strings with Rc<str>. After parsing the journal, we don't need to mutate the string. This means we can use an immutable type that has lower overhead Rc<str>.
This update was inspired by a brilliant YouTube video: Use Arc Instead of Vec.
Performance took a hit after implementing the balance assertions feature. After parsing the .journal, we then need to sort transactions/postings by date and sum each account/commodity pair to check the balance assertions.
Looking at the code, there were some simple optimisations we could make. Namely, reducing allocations.
By changing .into_iter() to .iter() and borrowing values instead of .clone(), we clawed back some of that lost performance.
There are plenty of other opportunities to improve performance further in the future: experiment with parallel processing (probably using rayon), using more optimised data structures, and reducing yet more allocations.
You can now add date range filters before the report commands.
-b, --begin <DATE> include postings/txns on or after this date
-e, --end <DATE> include postings/txns before this date
For example, to see your income statement for the UK 22/23 tax year:
rledger -f 2023.journal -b 2022-04-06 -e 2023-04-06 incomestatement
Postings can contain "balance assertions" and "balance assignments".
2023-05-04 opening balances
assets:bank = $500 ; <- this is an "assignment"
equity:opening/closing balances
2023-05-05
assets:bank $1000 = $1500 ; <- this is an "assertion"
income:work $-1000
After reading a journal file, rledger will check all balance assertions and report an error if any of them fail.
Balance assertions can protect you from e.g. inadvertently disrupting reconciled balances while cleaning up old entries.
These are like balance assertions, but with no posting amount on the left side of the equals sign; instead it is calculated automatically to satisfy the assertion. This can be a convenience during data entry e.g. when setting opening balances.
Example assertion error:
In the .journal file, you can declare "directives" that influence how the journal is processed. We have already implemented the include directive (for including other .journal files in the main journal).
This update adds the account and commodity directives, which are useful for error checking. For example, checking that the accounts and commodities in the journal are expected (protect against typos).
commodity directiveaccount directiveNow, they have no impact on journal parsing. But we will use them when we implement strict checking later on.
The commodity for a given amount controls how the amount will be displayed. I introduced the rusty_money crate to handle the formatting.
"$" => USD
"£" => GBP
"€" => EUR
"Â¥" => JPY
include supportWithin a journal, you can now include other journal files:
include 2022.journal
2023-01-20 Client A | Invoice #1
assets:receivables $10,000.00
revenue:clients:A -$10,000.00
2022.journal, and then include all the years in a all-years.journal.
The balance command produces a foundational report for listing account balances, balance changes, values, value changes and more, during one time period or many. Generally it shows a table, with rows representing accounts, and columns representing periods.
The higher level reports such as the balance sheet and income statement are special cases of the balance report.
On an AMD Ryzen 9 5950X 16-Core Processor, I am getting 275,549 transactions per second 🚀.
By comparison, hledger is running at 13,982 per second.
rledger is now ~19x faster than hledger 🤯⚡.
Run benchmarks using criterion with cargo bench. This will show how performance has changed between runs.
Ad hoc tests can be taken with hyperfine:
cargo build --release
hyperfine './target/release/rledger -f benches/10000x1000x10.journal bs'
This approach is good for comparing performance with hledger (how the results above were found):
hyperfine -w 5 './target/release/rledger -f benches/10000x1000x10.journal bs' 'hledger -f benches/10000x1000x10.journal bs'
Since this is a plain text accounting CLI, we can make use of snapshot testing. The idea is that we run a CLI command given some input and compare the output with our expected result.
I had rolled my own testing framework using nom to parse the test files. However, a colleague of mine, Austin McBee, tipped me on to trycmd.
This crate provides a harness for test case files and asserting stdout/stderr are expected.
trycmd allows for tests to be written in markdown files. This makes tests also serve as documentation and reduces the number of test files.miettestdinSo far, rledger has only been able to read the journal from a file. But it can be convenient to read from stdin, allowing clean integration with other unix tools like cat, grep etc.
Use the argument -f - to read from stdin:
cat examples/example.journal | rledger -f - bs
In plain text accounting, you can use any account names you like. However, you normally want to use the traditional accounting categories: assets, `liabiliti