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,21 +329,49 @@ 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
|
||||
another commodity. This documents the exchange rate, cost (of a pur-
|
||||
chase), or selling price (of a sale) that was in effect within this
|
||||
particular transaction (or more precisely, within the particular post-
|
||||
When recording a transaction, you can also record an amount's price in
|
||||
another commodity. This documents the exchange rate, cost (of a pur-
|
||||
chase), or selling price (of a sale) that was in effect within this
|
||||
particular transaction (or more precisely, within the particular post-
|
||||
ing). These transaction prices are fixed, and do not change.
|
||||
|
||||
Such priced amounts can be displayed in their transaction price's com-
|
||||
modity, by using the --cost/-B flag (B for "cost Basis"), supported by
|
||||
Such priced amounts can be displayed in their transaction price's com-
|
||||
modity, by using the --cost/-B flag (B for "cost Basis"), supported by
|
||||
most hledger commands.
|
||||
|
||||
There are three ways to specify a transaction price:
|
||||
|
||||
1. Write the unit price (aka exchange rate), as @ UNITPRICE after the
|
||||
1. Write the unit price (aka exchange rate), as @ UNITPRICE after the
|
||||
amount:
|
||||
|
||||
2009/1/1
|
||||
@ -357,7 +385,7 @@ FILE FORMAT
|
||||
assets:cash
|
||||
|
||||
3. Or let hledger infer the price so as to balance the transaction. To
|
||||
permit this, you must fully specify all posting amounts, and their
|
||||
permit this, you must fully specify all posting amounts, and their
|
||||
sum must have a non-zero amount in exactly two commodities:
|
||||
|
||||
2009/1/1
|
||||
@ -371,17 +399,17 @@ FILE FORMAT
|
||||
assets:foreign currency $135.00
|
||||
assets:cash $-135.00
|
||||
|
||||
Example use for transaction prices: recording the effective conversion
|
||||
Example use for transaction prices: recording the effective conversion
|
||||
rate of purchases made in a foreign currency.
|
||||
|
||||
Market prices
|
||||
Market prices are not tied to a particular transaction; they represent
|
||||
historical exchange rates between two commodities, usually from some
|
||||
Market prices are not tied to a particular transaction; they represent
|
||||
historical exchange rates between two commodities, usually from some
|
||||
public market which publishes such rates.
|
||||
|
||||
When market prices are known, the -V/--value option will use them to
|
||||
convert reported amounts to their market value as of the report end
|
||||
date. This option is currently available only with the balance com-
|
||||
When market prices are known, the -V/--value option will use them to
|
||||
convert reported amounts to their market value as of the report end
|
||||
date. This option is currently available only with the balance com-
|
||||
mand.
|
||||
|
||||
You record market prices (Ledger calls them historical prices) with a P
|
||||
@ -391,7 +419,7 @@ FILE FORMAT
|
||||
P DATE COMMODITYSYMBOL UNITPRICE
|
||||
|
||||
For example, the following directives say that the euro's exchange rate
|
||||
was 1.35 US dollars during 2009, and $1.40 from 2010 onward (and
|
||||
was 1.35 US dollars during 2009, and $1.40 from 2010 onward (and
|
||||
unknown before 2009).
|
||||
|
||||
P 2009/1/1 $1.35
|
||||
@ -400,17 +428,17 @@ FILE FORMAT
|
||||
Example use for market prices: tracking the value of stocks.
|
||||
|
||||
Comments
|
||||
Lines in the journal beginning with a semicolon (;) or hash (#) or
|
||||
asterisk (*) are comments, and will be ignored. (Asterisk comments
|
||||
make it easy to treat your journal like an org-mode outline in emacs.)
|
||||
Lines in the journal beginning with a semicolon (;) or hash (#) or
|
||||
asterisk (*) are comments, and will be ignored. (Asterisk comments
|
||||
make it easy to treat your journal like an org-mode outline in emacs.)
|
||||
|
||||
Also, anything between comment and end comment directives is a
|
||||
(multi-line) comment. If there is no end comment, the comment extends
|
||||
Also, anything between comment and end comment directives is a
|
||||
(multi-line) comment. If there is no end comment, the comment extends
|
||||
to the end of the file.
|
||||
|
||||
You can attach comments to a transaction by writing them after the
|
||||
description and/or indented on the following lines (before the post-
|
||||
ings). Similarly, you can attach comments to an individual posting by
|
||||
You can attach comments to a transaction by writing them after the
|
||||
description and/or indented on the following lines (before the post-
|
||||
ings). Similarly, you can attach comments to an individual posting by
|
||||
writing them after the amount and/or indented on the following lines.
|
||||
|
||||
Some examples:
|
||||
@ -435,30 +463,30 @@ FILE FORMAT
|
||||
; a journal comment (because not indented)
|
||||
|
||||
Tags
|
||||
A tag is a word followed by a full colon inside a transaction or post-
|
||||
ing comment. You can write multiple tags, comma separated. Eg:
|
||||
; a comment containing sometag:, anothertag:. You can search for tags
|
||||
A tag is a word followed by a full colon inside a transaction or post-
|
||||
ing comment. You can write multiple tags, comma separated. Eg:
|
||||
; a comment containing sometag:, anothertag:. You can search for tags
|
||||
with the tag: query.
|
||||
|
||||
A tag can also have a value, which is any text between the colon and
|
||||
the next comma or newline, excluding leading/trailing whitespace. (So
|
||||
A tag can also have a value, which is any text between the colon and
|
||||
the next comma or newline, excluding leading/trailing whitespace. (So
|
||||
hledger tag values can not contain commas or newlines).
|
||||
|
||||
Tags in a transaction comment affect the transaction and all of its
|
||||
postings, while tags in a posting comment affect only that posting.
|
||||
For example, the following transaction has three tags (A, TAG2,
|
||||
Tags in a transaction comment affect the transaction and all of its
|
||||
postings, while tags in a posting comment affect only that posting.
|
||||
For example, the following transaction has three tags (A, TAG2,
|
||||
third-tag) and the posting has four (A, TAG2, third-tag, posting-tag):
|
||||
|
||||
1/1 a transaction ; A:, TAG2:
|
||||
; third-tag: a third transaction tag, this time with a value
|
||||
(a) $1 ; posting-tag:
|
||||
|
||||
Tags are like Ledger's metadata feature, except hledger's tag values
|
||||
Tags are like Ledger's metadata feature, except hledger's tag values
|
||||
are simple strings.
|
||||
|
||||
Directives
|
||||
Account aliases
|
||||
You can define aliases which rewrite your account names (after reading
|
||||
You can define aliases which rewrite your account names (after reading
|
||||
the journal, before generating reports). hledger's account aliases can
|
||||
be useful for:
|
||||
|
||||
@ -475,8 +503,8 @@ FILE FORMAT
|
||||
See also How to use account aliases.
|
||||
|
||||
Basic aliases
|
||||
To set an account alias, use the alias directive in your journal file.
|
||||
This affects all subsequent journal entries in the current file or its
|
||||
To set an account alias, use the alias directive in your journal file.
|
||||
This affects all subsequent journal entries in the current file or its
|
||||
included files. The spaces around the = are optional:
|
||||
|
||||
alias OLD = NEW
|
||||
@ -484,53 +512,53 @@ FILE FORMAT
|
||||
Or, you can use the --alias 'OLD=NEW' option on the command line. This
|
||||
affects all entries. It's useful for trying out aliases interactively.
|
||||
|
||||
OLD and NEW are full account names. hledger will replace any occur-
|
||||
rence of the old account name with the new one. Subaccounts are also
|
||||
OLD and NEW are full account names. hledger will replace any occur-
|
||||
rence of the old account name with the new one. Subaccounts are also
|
||||
affected. Eg:
|
||||
|
||||
alias checking = assets:bank:wells fargo:checking
|
||||
# rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a"
|
||||
|
||||
Regex aliases
|
||||
There is also a more powerful variant that uses a regular expression,
|
||||
indicated by the forward slashes. (This was the default behaviour in
|
||||
There is also a more powerful variant that uses a regular expression,
|
||||
indicated by the forward slashes. (This was the default behaviour in
|
||||
hledger 0.24-0.25):
|
||||
|
||||
alias /REGEX/ = REPLACEMENT
|
||||
|
||||
or --alias '/REGEX/=REPLACEMENT'.
|
||||
|
||||
REGEX is a case-insensitive regular expression. Anywhere it matches
|
||||
inside an account name, the matched part will be replaced by REPLACE-
|
||||
MENT. If REGEX contains parenthesised match groups, these can be ref-
|
||||
REGEX is a case-insensitive regular expression. Anywhere it matches
|
||||
inside an account name, the matched part will be replaced by REPLACE-
|
||||
MENT. If REGEX contains parenthesised match groups, these can be ref-
|
||||
erenced by the usual numeric backreferences in REPLACEMENT. Note, cur-
|
||||
rently regular expression aliases may cause noticeable slow-downs.
|
||||
rently regular expression aliases may cause noticeable slow-downs.
|
||||
(And if you use Ledger on your hledger file, they will be ignored.) Eg:
|
||||
|
||||
alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3
|
||||
# rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking"
|
||||
|
||||
Multiple aliases
|
||||
You can define as many aliases as you like using directives or com-
|
||||
mand-line options. Aliases are recursive - each alias sees the result
|
||||
of applying previous ones. (This is different from Ledger, where
|
||||
You can define as many aliases as you like using directives or com-
|
||||
mand-line options. Aliases are recursive - each alias sees the result
|
||||
of applying previous ones. (This is different from Ledger, where
|
||||
aliases are non-recursive by default). Aliases are applied in the fol-
|
||||
lowing order:
|
||||
|
||||
1. alias directives, most recently seen first (recent directives take
|
||||
1. alias directives, most recently seen first (recent directives take
|
||||
precedence over earlier ones; directives not yet seen are ignored)
|
||||
|
||||
2. alias options, in the order they appear on the command line
|
||||
|
||||
end aliases
|
||||
You can clear (forget) all currently defined aliases with the
|
||||
You can clear (forget) all currently defined aliases with the
|
||||
end aliases directive:
|
||||
|
||||
end aliases
|
||||
|
||||
account directive
|
||||
The account directive predefines account names, as in Ledger and Bean-
|
||||
count. This may be useful for your own documentation; hledger doesn't
|
||||
The account directive predefines account names, as in Ledger and Bean-
|
||||
count. This may be useful for your own documentation; hledger doesn't
|
||||
make use of it yet.
|
||||
|
||||
; account ACCT
|
||||
@ -545,8 +573,8 @@ FILE FORMAT
|
||||
; etc.
|
||||
|
||||
apply account directive
|
||||
You can specify a parent account which will be prepended to all
|
||||
accounts within a section of the journal. Use the apply account and
|
||||
You can specify a parent account which will be prepended to all
|
||||
accounts within a section of the journal. Use the apply account and
|
||||
end apply account directives like so:
|
||||
|
||||
apply account home
|
||||
@ -563,7 +591,7 @@ FILE FORMAT
|
||||
home:food $10
|
||||
home:cash $-10
|
||||
|
||||
If end apply account is omitted, the effect lasts to the end of the
|
||||
If end apply account is omitted, the effect lasts to the end of the
|
||||
file. Included files are also affected, eg:
|
||||
|
||||
apply account business
|
||||
@ -572,16 +600,16 @@ FILE FORMAT
|
||||
apply account personal
|
||||
include personal.journal
|
||||
|
||||
Prior to hledger 1.0, legacy account and end spellings were also sup-
|
||||
Prior to hledger 1.0, legacy account and end spellings were also sup-
|
||||
ported.
|
||||
|
||||
Multi-line comments
|
||||
A line containing just comment starts a multi-line comment, and a line
|
||||
A line containing just comment starts a multi-line comment, and a line
|
||||
containing just end comment ends it. See comments.
|
||||
|
||||
commodity directive
|
||||
The commodity directive predefines commodities (currently this is just
|
||||
informational), and also it may define the display format for amounts
|
||||
The commodity directive predefines commodities (currently this is just
|
||||
informational), and also it may define the display format for amounts
|
||||
in this commodity (overriding the automatically inferred format).
|
||||
|
||||
It may be written on a single line, like this:
|
||||
@ -593,8 +621,8 @@ FILE FORMAT
|
||||
; separating thousands with comma.
|
||||
commodity 1,000.0000 AAAA
|
||||
|
||||
or on multiple lines, using the "format" subdirective. In this case
|
||||
the commodity symbol appears twice and should be the same in both
|
||||
or on multiple lines, using the "format" subdirective. In this case
|
||||
the commodity symbol appears twice and should be the same in both
|
||||
places:
|
||||
|
||||
; commodity SYMBOL
|
||||
@ -607,10 +635,10 @@ FILE FORMAT
|
||||
format INR 9,99,99,999.00
|
||||
|
||||
Default commodity
|
||||
The D directive sets a default commodity (and display format), to be
|
||||
The D directive sets a default commodity (and display format), to be
|
||||
used for amounts without a commodity symbol (ie, plain numbers). (Note
|
||||
this differs from Ledger's default commodity directive.) The commodity
|
||||
and display format will be applied to all subsequent commodity-less
|
||||
this differs from Ledger's default commodity directive.) The commodity
|
||||
and display format will be applied to all subsequent commodity-less
|
||||
amounts, or until the next D directive.
|
||||
|
||||
# commodity-less amounts should be treated as dollars
|
||||
@ -622,8 +650,8 @@ FILE FORMAT
|
||||
b
|
||||
|
||||
Default year
|
||||
You can set a default year to be used for subsequent dates which don't
|
||||
specify a year. This is a line beginning with Y followed by the year.
|
||||
You can set a default year to be used for subsequent dates which don't
|
||||
specify a year. This is a line beginning with Y followed by the year.
|
||||
Eg:
|
||||
|
||||
Y2009 ; set default year to 2009
|
||||
@ -643,24 +671,24 @@ FILE FORMAT
|
||||
assets
|
||||
|
||||
Including other files
|
||||
You can pull in the content of additional journal files by writing an
|
||||
You can pull in the content of additional journal files by writing an
|
||||
include directive, like this:
|
||||
|
||||
include path/to/file.journal
|
||||
|
||||
If the path does not begin with a slash, it is relative to the current
|
||||
If the path does not begin with a slash, it is relative to the current
|
||||
file. Glob patterns (*) are not currently supported.
|
||||
|
||||
The include directive can only be used in journal files. It can
|
||||
The include directive can only be used in journal files. It can
|
||||
include journal, timeclock or timedot files, but not CSV files.
|
||||
|
||||
EDITOR SUPPORT
|
||||
Add-on modes exist for various text editors, to make working with jour-
|
||||
nal files easier. They add colour, navigation aids and helpful com-
|
||||
mands. For hledger users who edit the journal file directly (the
|
||||
nal files easier. They add colour, navigation aids and helpful com-
|
||||
mands. For hledger users who edit the journal file directly (the
|
||||
majority), using one of these modes is quite recommended.
|
||||
|
||||
These were written with Ledger in mind, but also work with hledger
|
||||
These were written with Ledger in mind, but also work with hledger
|
||||
files:
|
||||
|
||||
|
||||
@ -677,7 +705,7 @@ EDITOR SUPPORT
|
||||
|
||||
|
||||
REPORTING BUGS
|
||||
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
|
||||
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
|
||||
or hledger mail list)
|
||||
|
||||
|
||||
@ -691,7 +719,7 @@ COPYRIGHT
|
||||
|
||||
|
||||
SEE ALSO
|
||||
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
|
||||
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
|
||||
hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
|
||||
dot(5), ledger(1)
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user