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

;doc: journal: virtual postings rewrite

Browse Source 
[ci skip]
This commit is contained in:
Simon Michael 2020-01-29 06:19:19 -08:00
parent 181de60ff7
commit c920bd3169
1 changed files with 24 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
hledger-lib/hledger_journal.m4.md
View File

@ -86,7 +86,7 @@ This can be followed by any of the following, separated by spaces:
Then comes zero or more (but usually at least 2) indented lines representing... Then comes zero or more (but usually at least 2) indented lines representing...
## Postings ## Postings
A posting is an addition of some amount to, or removal of some amount from, an account. A posting is an addition of some amount to, or removal of some amount from, an account.
Each posting line begins with at least one space or tab (2 or 4 spaces is common), followed by: Each posting line begins with at least one space or tab (2 or 4 spaces is common), followed by:
@ -359,31 +359,39 @@ commodity directive to set the display format.
## Virtual Postings ## Virtual Postings
When you parenthesise the account name in a posting, we call that a *virtual posting*, which A posting with a parenthesised account name is called a *virtual posting*
means: or *unbalanced posting*, which means it is exempt from the usual rule
that a transaction's postings must balance (add up to zero).
- it is ignored when checking that the transaction is balanced This is not part of double entry accounting, so you might choose to
- it is excluded from reports when the `--real/-R` flag is used, or the `real:1` query. avoid this feature. Or you can use it sparingly for certain special
cases where it can be convenient. Eg, you could set opening balances
You could use this, eg, to set an account's opening balance without needing to use the without using a balancing equity account:
`equity:opening balances` account:
```journal ```journal
1/1 special unbalanced posting to set initial balance 1/1 opening balances
(assets:checking) $1000 (assets:checking) $1000
(assets:savings) $2000
``` ```
When the account name is bracketed, we call it a *balanced virtual posting*. This is like an ordinary virtual posting except the balanced virtual postings in a transaction must balance to 0, like the real postings (but separately from them). Balanced virtual postings are also excluded by `--real/-R` or `real:1`. A posting with a bracketed account name is called a *balanced virtual
posting*. The balanced virtual postings in a transaction must add up
to zero (separately from other postings). Eg:
```journal ```journal
1/1 buy food with cash, and update some budget-tracking subaccounts elsewhere 1/1 buy food with cash, update budget envelope subaccounts, & something else
expenses:food $10 assets:cash $-10 ; <- these balance
assets:cash $-10 expenses:food $7 ; <-
[assets:checking:available] $10 expenses:food $3 ; <-
[assets:checking:budget:food] $-10 [assets:checking:budget:food] $-10 ; <- and these balance
[assets:checking:available] $10 ; <-
(something:else) $5 ; <- not required to balance
``` ```
Virtual postings have some legitimate uses, but those are few. You can usually find an equivalent journal entry using real postings, which is more correct and provides better error checking. Ordinary non-parenthesised, non-bracketed postings are called *real postings*.
You can exclude virtual postings from reports with the `-R/--real`
flag or `real:1` query.
## Balance Assertions ## Balance Assertions