slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

;doc:print: clarify amount styling

Browse Source
This commit is contained in:
Simon Michael 2025-10-11 18:02:23 -10:00
parent 13d1642e5c
commit 61b0190cf4
1 changed files with 25 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
hledger/Hledger/Cli/Commands/Print.md
View File

@ -62,7 +62,7 @@ $ hledger print -f examples/sample.journal date:200806
``` ```
### print explicitness ### print amount explicitness
Normally, whether posting amounts are implicit or explicit is preserved. Normally, whether posting amounts are implicit or explicit is preserved.
For example, when an amount is omitted in the journal, it will not appear in the output. For example, when an amount is omitted in the journal, it will not appear in the output.
@ -79,36 +79,40 @@ to be split into multiple single-commodity postings,
keeping the output parseable. keeping the output parseable.
### print amount style ### print alignment
Amounts are shown right-aligned within each transaction Amounts are shown right-aligned within each transaction
(but not aligned across all transactions; you can do that with ledger-mode in Emacs). (but not aligned across all transactions; you can achieve that with ledger-mode in Emacs).
Amounts will be (mostly) normalised to their [commodity display style](#commodity-display-style):
their symbol placement, decimal mark, and digit group marks will be made consistent.
By default, decimal digits are shown as they are written in the journal.
With the `--round` (*Added in 1.32*) option, `print` will try increasingly hard to ### print amount style
display decimal digits according to the [commodity display styles](#commodity-display-style):
Amounts will be displayed mostly in their [commodity's display style](#commodity-display-style),
with standardised symbol placement, decimal mark, and digit group marks.
This does not apply to their decimal digits;
`print` normally shows the same decimal digits that are recorded in each journal entry.
You can override the decimal precisions with `print`'s special `--round` option (*since 1.32*).
`--round` tries to show amounts with their commodities' standard decimal precisions, increasingly strongly:
- `--round=none` show amounts with original precisions (default) - `--round=none` show amounts with original precisions (default)
- `--round=soft` add/remove decimal zeros in amounts (except costs) - `--round=soft` add/remove decimal zeros in amounts (except costs)
- `--round=hard` round amounts (except costs), possibly hiding significant digits - `--round=hard` round amounts (except costs), possibly hiding significant digits
- `--round=all` round all amounts and costs - `--round=all` round all amounts and costs
`soft` is good for non-lossy cleanup, formatting amounts more `soft` is good for non-lossy cleanup, displaying more consistent decimals where possible, without making entries unbalanced.
consistently where it's safe to do so.
`hard` and `all` can cause `print` to show invalid unbalanced journal entries; `hard` or `all` can be good for stronger cleanup, when decimal rounding is wanted.
they may be useful eg for stronger cleanup, with manual fixups when needed. Note rounding can produce unbalanced journal entries, perhaps requiring manual fixup.
### print parseability ### print parseability
print's output is usually a valid [hledger journal](#journal), Normally, print's output is a valid [hledger journal](#journal),
and you can process it again with a second hledger command. which you can "pipe" to a second hledger command for further processing.
This can be useful for certain kinds of search
(though the same can be achieved with `expr:` queries now): This is sometimes convenient for achieving certain kinds of query
(though less needed now that queries have become more powerful).
```cli ```cli
# Show running total of food expenses paid from cash. # Show running total of food expenses paid from cash.
@ -116,12 +120,12 @@ This can be useful for certain kinds of search
$ hledger print assets:cash | hledger -f- -I reg expenses:food $ hledger print assets:cash | hledger -f- -I reg expenses:food
``` ```
There are some situations where print's output can become unparseable: Here are some things which can cause print's output to become unparseable:
- [Value reporting](#value-reporting) affects posting amounts but not [balance assertion](#balance-assertions) or [balance assignment](#balance-assignments) amounts, potentially causing those to [fail](https://github.com/simonmichael/hledger/issues/1429).
- [Auto postings](#auto-postings) can generate postings with [too many missing amounts](https://github.com/simonmichael/hledger/issues/1276).
- [Account aliases can generate bad account names](#aliases-can-generate-bad-account-names).
- `--round` (see above) can disrupt transaction balancing.
- [Account aliases](#alias-directive) or [pivoting](#pivoting) can disrupt account names, balance assertions, or balance assignments.
- [Value reporting](#value-reporting) also can disrupt balance assertions or balance assignments.
- [Auto postings](#auto-postings) can generate too many amountless postings.
### print, other features ### print, other features