mirror of
https://github.com/simonmichael/hledger.git
synced 2024-09-20 02:37:12 +03:00
doc: document balance assignments (#438)
This commit is contained in:
Simon Michael
parent
fe58ef7946
commit
47ca1965b2
@ -327,7 +327,7 @@ You can usually find an equivalent journal entry using real postings,
|
||||
which is more correct and provides better error checking.
|
||||
.SS Balance Assertions
|
||||
.PP
|
||||
hledger supports ledger\-style balance assertions in journal files.
|
||||
hledger supports Ledger\-style balance assertions in journal files.
|
||||
These look like \f[C]=EXPECTEDBALANCE\f[] following a posting\[aq]s
|
||||
amount.
|
||||
Eg in this example we assert the expected dollar balance in accounts a
|
||||
@ -423,6 +423,44 @@ Balance assertions are checked against all postings, both real and
|
||||
virtual.
|
||||
They are not affected by the \f[C]\-\-real/\-R\f[] flag or
|
||||
\f[C]real:\f[] query.
|
||||
.SS Balance Assignments
|
||||
.PP
|
||||
Ledger\-style balance assignments are also supported.
|
||||
These are like balance assertions, but with no posting amount on the
|
||||
left side of the equals sign; instead it is calculated automatically so
|
||||
as to satisfy the assertion.
|
||||
This can be a convenience during data entry, eg when setting opening
|
||||
balances:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
;\ starting\ a\ new\ journal,\ set\ asset\ account\ balances\
|
||||
2016/1/1\ opening\ balances
|
||||
\ \ assets:checking\ \ \ \ \ \ \ \ \ \ \ \ =\ $409.32
|
||||
\ \ assets:savings\ \ \ \ \ \ \ \ \ \ \ \ \ =\ $735.24
|
||||
\ \ assets:cash\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ =\ $42
|
||||
\ \ equity:opening\ balances
|
||||
\f[]
|
||||
.fi
|
||||
.PP
|
||||
or when adjusting a balance to reality:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
;\ no\ cash\ left;\ update\ balance,\ record\ any\ untracked\ spending\ as\ a\ generic\ expense
|
||||
2016/1/15
|
||||
\ \ assets:cash\ \ \ \ =\ $0
|
||||
\ \ expenses:misc
|
||||
\f[]
|
||||
.fi
|
||||
.PP
|
||||
The calculated amount depends on the account\[aq]s balance in the
|
||||
commodity at that point (which depends on the previously\-dated postings
|
||||
of the commodity to that account since the last balance assertion or
|
||||
assignment).
|
||||
Note that using balance assignments makes your journal a little less
|
||||
explicit; to know the exact amount posted, you have to run hledger or do
|
||||
the calculations yourself, instead of just reading it.
|
||||
.SS Prices
|
||||
.SS Transaction prices
|
||||
.PP
|
||||
|
||||
@ -70,6 +70,7 @@ File: hledger_journal.5.info, Node: FILE FORMAT, Next: EDITOR SUPPORT, Prev:
|
||||
* Amounts::
|
||||
* Virtual Postings::
|
||||
* Balance Assertions::
|
||||
* Balance Assignments::
|
||||
* Prices::
|
||||
* Comments::
|
||||
* Tags::
|
||||
@ -331,12 +332,12 @@ can usually find an equivalent journal entry using real postings, which
|
||||
is more correct and provides better error checking.
|
||||
|
||||
|
||||
File: hledger_journal.5.info, Node: Balance Assertions, Next: Prices, Prev: Virtual Postings, Up: FILE FORMAT
|
||||
File: hledger_journal.5.info, Node: Balance Assertions, Next: Balance Assignments, Prev: Virtual Postings, Up: FILE FORMAT
|
||||
|
||||
1.6 Balance Assertions
|
||||
======================
|
||||
|
||||
hledger supports ledger-style balance assertions in journal files. These
|
||||
hledger supports Ledger-style balance assertions in journal files. These
|
||||
look like `=EXPECTEDBALANCE' following a posting's amount. Eg in this
|
||||
example we assert the expected dollar balance in accounts a and b after
|
||||
each posting:
|
||||
@ -442,9 +443,44 @@ Balance assertions are checked against all postings, both real and
|
||||
virtual. They are not affected by the `--real/-R' flag or `real:' query.
|
||||
|
||||
|
||||
File: hledger_journal.5.info, Node: Prices, Next: Comments, Prev: Balance Assertions, Up: FILE FORMAT
|
||||
File: hledger_journal.5.info, Node: Balance Assignments, Next: Prices, Prev: Balance Assertions, Up: FILE FORMAT
|
||||
|
||||
1.7 Prices
|
||||
1.7 Balance Assignments
|
||||
=======================
|
||||
|
||||
Ledger-style balance assignments are also supported. These are like
|
||||
balance assertions, but with no posting amount on the left side of the
|
||||
equals sign; instead it is calculated automatically so as to satisfy the
|
||||
assertion. This can be a convenience during data entry, eg when setting
|
||||
opening balances:
|
||||
|
||||
|
||||
; starting a new journal, set asset account balances
|
||||
2016/1/1 opening balances
|
||||
assets:checking = $409.32
|
||||
assets:savings = $735.24
|
||||
assets:cash = $42
|
||||
equity:opening balances
|
||||
|
||||
or when adjusting a balance to reality:
|
||||
|
||||
|
||||
; no cash left; update balance, record any untracked spending as a generic expense
|
||||
2016/1/15
|
||||
assets:cash = $0
|
||||
expenses:misc
|
||||
|
||||
The calculated amount depends on the account's balance in the
|
||||
commodity at that point (which depends on the previously-dated postings
|
||||
of the commodity to that account since the last balance assertion or
|
||||
assignment). Note that using balance assignments makes your journal a
|
||||
little less explicit; to know the exact amount posted, you have to run
|
||||
hledger or do the calculations yourself, instead of just reading it.
|
||||
|
||||
|
||||
File: hledger_journal.5.info, Node: Prices, Next: Comments, Prev: Balance Assignments, Up: FILE FORMAT
|
||||
|
||||
1.8 Prices
|
||||
==========
|
||||
|
||||
* Menu:
|
||||
@ -455,7 +491,7 @@ File: hledger_journal.5.info, Node: Prices, Next: Comments, Prev: Balance Ass
|
||||
|
||||
File: hledger_journal.5.info, Node: Transaction prices, Next: Market prices, Up: Prices
|
||||
|
||||
1.7.1 Transaction prices
|
||||
1.8.1 Transaction prices
|
||||
------------------------
|
||||
|
||||
When recording a transaction, you can also record an amount's price in
|
||||
@ -509,7 +545,7 @@ conversion rate of purchases made in a foreign currency.
|
||||
|
||||
File: hledger_journal.5.info, Node: Market prices, Prev: Transaction prices, Up: Prices
|
||||
|
||||
1.7.2 Market prices
|
||||
1.8.2 Market prices
|
||||
-------------------
|
||||
|
||||
Market prices are not tied to a particular transaction; they represent
|
||||
@ -540,7 +576,7 @@ P 2010/1/1 € $1.40
|
||||
|
||||
File: hledger_journal.5.info, Node: Comments, Next: Tags, Prev: Prices, Up: FILE FORMAT
|
||||
|
||||
1.8 Comments
|
||||
1.9 Comments
|
||||
============
|
||||
|
||||
Lines in the journal beginning with a semicolon (`;') or hash (`#') or
|
||||
@ -581,8 +617,8 @@ end comment
|
||||
|
||||
File: hledger_journal.5.info, Node: Tags, Next: Directives, Prev: Comments, Up: FILE FORMAT
|
||||
|
||||
1.9 Tags
|
||||
========
|
||||
1.10 Tags
|
||||
=========
|
||||
|
||||
A _tag_ is a word followed by a full colon inside a transaction or
|
||||
posting comment. You can write multiple tags, comma separated. Eg: `; a
|
||||
@ -609,7 +645,7 @@ are simple strings.
|
||||
|
||||
File: hledger_journal.5.info, Node: Directives, Prev: Tags, Up: FILE FORMAT
|
||||
|
||||
1.10 Directives
|
||||
1.11 Directives
|
||||
===============
|
||||
|
||||
* Menu:
|
||||
@ -626,7 +662,7 @@ File: hledger_journal.5.info, Node: Directives, Prev: Tags, Up: FILE FORMAT
|
||||
|
||||
File: hledger_journal.5.info, Node: Account aliases, Next: account directive, Up: Directives
|
||||
|
||||
1.10.1 Account aliases
|
||||
1.11.1 Account aliases
|
||||
----------------------
|
||||
|
||||
You can define aliases which rewrite your account names (after reading
|
||||
@ -655,7 +691,7 @@ be useful for:
|
||||
|
||||
File: hledger_journal.5.info, Node: Basic aliases, Next: Regex aliases, Up: Account aliases
|
||||
|
||||
1.10.1.1 Basic aliases
|
||||
1.11.1.1 Basic aliases
|
||||
......................
|
||||
|
||||
To set an account alias, use the `alias' directive in your journal
|
||||
@ -680,7 +716,7 @@ alias checking = assets:bank:wells fargo:checking
|
||||
|
||||
File: hledger_journal.5.info, Node: Regex aliases, Next: Multiple aliases, Prev: Basic aliases, Up: Account aliases
|
||||
|
||||
1.10.1.2 Regex aliases
|
||||
1.11.1.2 Regex aliases
|
||||
......................
|
||||
|
||||
There is also a more powerful variant that uses a regular expression,
|
||||
@ -706,7 +742,7 @@ alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3
|
||||
|
||||
File: hledger_journal.5.info, Node: Multiple aliases, Next: end aliases, Prev: Regex aliases, Up: Account aliases
|
||||
|
||||
1.10.1.3 Multiple aliases
|
||||
1.11.1.3 Multiple aliases
|
||||
.........................
|
||||
|
||||
You can define as many aliases as you like using directives or
|
||||
@ -723,7 +759,7 @@ order:
|
||||
|
||||
File: hledger_journal.5.info, Node: end aliases, Prev: Multiple aliases, Up: Account aliases
|
||||
|
||||
1.10.1.4 end aliases
|
||||
1.11.1.4 end aliases
|
||||
....................
|
||||
|
||||
You can clear (forget) all currently defined aliases with the `end
|
||||
@ -735,7 +771,7 @@ end aliases
|
||||
|
||||
File: hledger_journal.5.info, Node: account directive, Next: apply account directive, Prev: Account aliases, Up: Directives
|
||||
|
||||
1.10.2 account directive
|
||||
1.11.2 account directive
|
||||
------------------------
|
||||
|
||||
The `account' directive predefines account names, as in Ledger and
|
||||
@ -757,7 +793,7 @@ account expenses:food
|
||||
|
||||
File: hledger_journal.5.info, Node: apply account directive, Next: Multi-line comments, Prev: account directive, Up: Directives
|
||||
|
||||
1.10.3 apply account directive
|
||||
1.11.3 apply account directive
|
||||
------------------------------
|
||||
|
||||
You can specify a parent account which will be prepended to all accounts
|
||||
@ -796,7 +832,7 @@ supported.
|
||||
|
||||
File: hledger_journal.5.info, Node: Multi-line comments, Next: commodity directive, Prev: apply account directive, Up: Directives
|
||||
|
||||
1.10.4 Multi-line comments
|
||||
1.11.4 Multi-line comments
|
||||
--------------------------
|
||||
|
||||
A line containing just `comment' starts a multi-line comment, and a
|
||||
@ -805,7 +841,7 @@ line containing just `end comment' ends it. See comments.
|
||||
|
||||
File: hledger_journal.5.info, Node: commodity directive, Next: Default commodity, Prev: Multi-line comments, Up: Directives
|
||||
|
||||
1.10.5 commodity directive
|
||||
1.11.5 commodity directive
|
||||
--------------------------
|
||||
|
||||
The `commodity' directive predefines commodities (currently this is
|
||||
@ -840,7 +876,7 @@ commodity INR
|
||||
|
||||
File: hledger_journal.5.info, Node: Default commodity, Next: Default year, Prev: commodity directive, Up: Directives
|
||||
|
||||
1.10.6 Default commodity
|
||||
1.11.6 Default commodity
|
||||
------------------------
|
||||
|
||||
The D directive sets a default commodity (and display format), to be
|
||||
@ -861,7 +897,7 @@ D $1,000.00
|
||||
|
||||
File: hledger_journal.5.info, Node: Default year, Next: Including other files, Prev: Default commodity, Up: Directives
|
||||
|
||||
1.10.7 Default year
|
||||
1.11.7 Default year
|
||||
-------------------
|
||||
|
||||
You can set a default year to be used for subsequent dates which don't
|
||||
@ -888,7 +924,7 @@ Y2010 ; change default year to 2010
|
||||
|
||||
File: hledger_journal.5.info, Node: Including other files, Prev: Default year, Up: Directives
|
||||
|
||||
1.10.8 Including other files
|
||||
1.11.8 Including other files
|
||||
----------------------------
|
||||
|
||||
You can pull in the content of additional journal files by writing an
|
||||
@ -929,69 +965,71 @@ Tag Table:
|
||||
Node: Top94
|
||||
Node: FILE FORMAT2284
|
||||
Ref: #file-format2410
|
||||
Node: Transactions2569
|
||||
Ref: #transactions2689
|
||||
Node: Dates3632
|
||||
Ref: #dates3760
|
||||
Node: Simple dates3825
|
||||
Ref: #simple-dates3953
|
||||
Node: Secondary dates4317
|
||||
Ref: #secondary-dates4473
|
||||
Node: Posting dates6033
|
||||
Ref: #posting-dates6164
|
||||
Node: Account names7535
|
||||
Ref: #account-names7674
|
||||
Node: Amounts8159
|
||||
Ref: #amounts8297
|
||||
Node: Virtual Postings10396
|
||||
Ref: #virtual-postings10557
|
||||
Node: Balance Assertions11777
|
||||
Ref: #balance-assertions11941
|
||||
Node: Assertions and ordering12763
|
||||
Ref: #assertions-and-ordering12948
|
||||
Node: Assertions and commodities13979
|
||||
Ref: #assertions-and-commodities14205
|
||||
Node: Assertions and subaccounts14897
|
||||
Ref: #assertions-and-subaccounts15131
|
||||
Node: Assertions and virtual postings15653
|
||||
Ref: #assertions-and-virtual-postings15862
|
||||
Node: Prices16003
|
||||
Ref: #prices16135
|
||||
Node: Transaction prices16186
|
||||
Ref: #transaction-prices16331
|
||||
Node: Market prices17938
|
||||
Ref: #market-prices18073
|
||||
Node: Comments18961
|
||||
Ref: #comments19083
|
||||
Node: Tags20195
|
||||
Ref: #tags20313
|
||||
Node: Directives21236
|
||||
Ref: #directives21351
|
||||
Node: Account aliases21544
|
||||
Ref: #account-aliases21690
|
||||
Node: Basic aliases22292
|
||||
Ref: #basic-aliases22437
|
||||
Node: Regex aliases23125
|
||||
Ref: #regex-aliases23295
|
||||
Node: Multiple aliases24065
|
||||
Ref: #multiple-aliases24239
|
||||
Node: end aliases24735
|
||||
Ref: #end-aliases24877
|
||||
Node: account directive24979
|
||||
Ref: #account-directive25161
|
||||
Node: apply account directive25457
|
||||
Ref: #apply-account-directive25655
|
||||
Node: Multi-line comments26315
|
||||
Ref: #multi-line-comments26507
|
||||
Node: commodity directive26634
|
||||
Ref: #commodity-directive26820
|
||||
Node: Default commodity27693
|
||||
Ref: #default-commodity27868
|
||||
Node: Default year28404
|
||||
Ref: #default-year28571
|
||||
Node: Including other files28994
|
||||
Ref: #including-other-files29153
|
||||
Node: EDITOR SUPPORT29549
|
||||
Ref: #editor-support29669
|
||||
Node: Transactions2593
|
||||
Ref: #transactions2713
|
||||
Node: Dates3656
|
||||
Ref: #dates3784
|
||||
Node: Simple dates3849
|
||||
Ref: #simple-dates3977
|
||||
Node: Secondary dates4341
|
||||
Ref: #secondary-dates4497
|
||||
Node: Posting dates6057
|
||||
Ref: #posting-dates6188
|
||||
Node: Account names7559
|
||||
Ref: #account-names7698
|
||||
Node: Amounts8183
|
||||
Ref: #amounts8321
|
||||
Node: Virtual Postings10420
|
||||
Ref: #virtual-postings10581
|
||||
Node: Balance Assertions11801
|
||||
Ref: #balance-assertions11978
|
||||
Node: Assertions and ordering12800
|
||||
Ref: #assertions-and-ordering12985
|
||||
Node: Assertions and commodities14016
|
||||
Ref: #assertions-and-commodities14242
|
||||
Node: Assertions and subaccounts14934
|
||||
Ref: #assertions-and-subaccounts15168
|
||||
Node: Assertions and virtual postings15690
|
||||
Ref: #assertions-and-virtual-postings15899
|
||||
Node: Balance Assignments16040
|
||||
Ref: #balance-assignments16209
|
||||
Node: Prices17327
|
||||
Ref: #prices17460
|
||||
Node: Transaction prices17511
|
||||
Ref: #transaction-prices17656
|
||||
Node: Market prices19263
|
||||
Ref: #market-prices19398
|
||||
Node: Comments20286
|
||||
Ref: #comments20408
|
||||
Node: Tags21520
|
||||
Ref: #tags21640
|
||||
Node: Directives22563
|
||||
Ref: #directives22678
|
||||
Node: Account aliases22871
|
||||
Ref: #account-aliases23017
|
||||
Node: Basic aliases23619
|
||||
Ref: #basic-aliases23764
|
||||
Node: Regex aliases24452
|
||||
Ref: #regex-aliases24622
|
||||
Node: Multiple aliases25392
|
||||
Ref: #multiple-aliases25566
|
||||
Node: end aliases26062
|
||||
Ref: #end-aliases26204
|
||||
Node: account directive26306
|
||||
Ref: #account-directive26488
|
||||
Node: apply account directive26784
|
||||
Ref: #apply-account-directive26982
|
||||
Node: Multi-line comments27642
|
||||
Ref: #multi-line-comments27834
|
||||
Node: commodity directive27961
|
||||
Ref: #commodity-directive28147
|
||||
Node: Default commodity29020
|
||||
Ref: #default-commodity29195
|
||||
Node: Default year29731
|
||||
Ref: #default-year29898
|
||||
Node: Including other files30321
|
||||
Ref: #including-other-files30480
|
||||
Node: EDITOR SUPPORT30876
|
||||
Ref: #editor-support30996
|
||||
|
||||
End Tag Table
|
||||
|
||||
@ -251,8 +251,8 @@ Virtual postings have some legitimate uses, but those are few. You can usually f
|
||||
|
||||
## Balance Assertions
|
||||
|
||||
hledger supports ledger-style
|
||||
[balance assertions](http://ledger-cli.org/3.0/doc/ledger3.html#Balance-assertions)
|
||||
hledger supports
|
||||
[Ledger-style balance assertions](http://ledger-cli.org/3.0/doc/ledger3.html#Balance-assertions)
|
||||
in journal files.
|
||||
These look like `=EXPECTEDBALANCE` following a posting's amount. Eg in
|
||||
this example we assert the expected dollar balance in accounts a and b after
|
||||
@ -339,6 +339,36 @@ Balance assertions are checked against all postings, both real and
|
||||
flag or `real:` query.
|
||||
|
||||
|
||||
## Balance Assignments
|
||||
|
||||
[Ledger-style balance assignments](http://ledger-cli.org/3.0/doc/ledger3.html#Balance-assignments) are also supported.
|
||||
These are like [balance assertions](#balance-assertions), but with no posting amount on the left side of the equals sign;
|
||||
instead it is calculated automatically so as to satisfy the assertion.
|
||||
This can be a convenience during data entry, eg when setting opening balances:
|
||||
```journal
|
||||
; starting a new journal, set asset account balances
|
||||
2016/1/1 opening balances
|
||||
assets:checking = $409.32
|
||||
assets:savings = $735.24
|
||||
assets:cash = $42
|
||||
equity:opening balances
|
||||
```
|
||||
or when adjusting a balance to reality:
|
||||
```journal
|
||||
; no cash left; update balance, record any untracked spending as a generic expense
|
||||
2016/1/15
|
||||
assets:cash = $0
|
||||
expenses:misc
|
||||
```
|
||||
|
||||
The calculated amount depends on the account's balance in the commodity at that point
|
||||
(which depends on the previously-dated postings of the commodity to that account
|
||||
since the last balance assertion or assignment).
|
||||
Note that using balance assignments makes your journal a little less explicit;
|
||||
to know the exact amount posted, you have to run hledger or do the calculations yourself,
|
||||
instead of just reading it.
|
||||
|
||||
|
||||
## Prices
|
||||
|
||||
### Transaction prices
|
||||
|
||||
@ -253,7 +253,7 @@ FILE FORMAT
|
||||
more correct and provides better error checking.
|
||||
|
||||
Balance Assertions
|
||||
hledger supports ledger-style balance assertions in journal files.
|
||||
hledger supports Ledger-style balance assertions in journal files.
|
||||
These look like =EXPECTEDBALANCE following a posting's amount. Eg in
|
||||
this example we assert the expected dollar balance in accounts a and b
|
||||
after each posting:
|
||||
@ -329,6 +329,34 @@ FILE FORMAT
|
||||
Balance assertions are checked against all postings, both real and vir-
|
||||
tual. They are not affected by the --real/-R flag or real: query.
|
||||
|
||||
Balance Assignments
|
||||
Ledger-style balance assignments are also supported. These are like
|
||||
balance assertions, but with no posting amount on the left side of the
|
||||
equals sign; instead it is calculated automatically so as to satisfy
|
||||
the assertion. This can be a convenience during data entry, eg when
|
||||
setting opening balances:
|
||||
|
||||
; starting a new journal, set asset account balances
|
||||
2016/1/1 opening balances
|
||||
assets:checking = $409.32
|
||||
assets:savings = $735.24
|
||||
assets:cash = $42
|
||||
equity:opening balances
|
||||
|
||||
or when adjusting a balance to reality:
|
||||
|
||||
; no cash left; update balance, record any untracked spending as a generic expense
|
||||
2016/1/15
|
||||
assets:cash = $0
|
||||
expenses:misc
|
||||
|
||||
The calculated amount depends on the account's balance in the commodity
|
||||
at that point (which depends on the previously-dated postings of the
|
||||
commodity to that account since the last balance assertion or assign-
|
||||
ment). Note that using balance assignments makes your journal a little
|
||||
less explicit; to know the exact amount posted, you have to run hledger
|
||||
or do the calculations yourself, instead of just reading it.
|
||||
|
||||
Prices
|
||||
Transaction prices
|
||||
When recording a transaction, you can also record an amount's price in
|
||||
|
||||
Loading…
Reference in New Issue
Block a user