doc: clarify some transaction price details
- remove inaccurate print examples - note #551 - note Ledger's fixed price syntax - note how posting order can affect -B - edits for clarity
This commit is contained in:
Simon Michael
parent
7bc5ef3df0
commit
a5b545c4eb
@ -470,70 +470,93 @@ the calculations yourself, instead of just reading it.
|
||||
.SS Prices
|
||||
.SS Transaction prices
|
||||
.PP
|
||||
Within a transaction posting, you can record an amount\[aq]s price in
|
||||
another commodity.
|
||||
This can be used to document the cost (for a purchase), or selling price
|
||||
(for a sale), or the exchange rate that was used, for this transaction.
|
||||
These transaction prices are fixed, and do not change over time.
|
||||
Within a transaction, you can note an amount\[aq]s price in another
|
||||
commodity.
|
||||
This can be used to document the cost (in a purchase) or selling price
|
||||
(in a sale).
|
||||
For example, transaction prices are useful to record purchases of a
|
||||
foreign currency.
|
||||
.PP
|
||||
Amounts with transaction prices can be displayed in the transaction
|
||||
price\[aq]s commodity, by using the \f[C]\-\-cost/\-B\f[] flag supported
|
||||
by most hledger commands (mnemonic: "cost Basis").
|
||||
Transaction prices are fixed, and do not change over time.
|
||||
(Ledger users: Ledger uses a different syntax for fixed prices,
|
||||
\f[C]{=UNITPRICE}\f[], which hledger currently ignores).
|
||||
.PP
|
||||
There are several ways to record a transaction price:
|
||||
.IP "1." 3
|
||||
Write the unit price (aka exchange rate), as \f[C]\@\ UNITPRICE\f[]
|
||||
after the amount:
|
||||
Write the price per unit, as \f[C]\@\ UNITPRICE\f[] after the amount:
|
||||
.RS 4
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
2009/1/1
|
||||
\ \ assets:foreign\ currency\ \ \ €100\ \@\ $1.35\ \ ;\ one\ hundred\ euros\ at\ $1.35\ each
|
||||
\ \ assets:cash
|
||||
\ \ assets:euros\ \ \ \ \ €100\ \@\ $1.35\ \ ;\ one\ hundred\ euros\ purchased\ at\ $1.35\ each
|
||||
\ \ assets:dollars\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ;\ balancing\ amount\ is\ \-$135.00
|
||||
\f[]
|
||||
.fi
|
||||
.RE
|
||||
.IP "2." 3
|
||||
Or write the total price, as \f[C]\@\@\ TOTALPRICE\f[] after the amount:
|
||||
Write the total price, as \f[C]\@\@\ TOTALPRICE\f[] after the amount:
|
||||
.RS 4
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
2009/1/1
|
||||
\ \ assets:foreign\ currency\ \ \ €100\ \@\@\ $135\ \ ;\ one\ hundred\ euros\ at\ $135\ for\ the\ lot
|
||||
\ \ assets:cash
|
||||
\ \ assets:euros\ \ \ \ \ €100\ \@\@\ $135\ \ ;\ one\ hundred\ euros\ purchased\ at\ $135\ for\ the\ lot
|
||||
\ \ assets:dollars
|
||||
\f[]
|
||||
.fi
|
||||
.RE
|
||||
.IP "3." 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
|
||||
sum must have a non\-zero amount in exactly two commodities:
|
||||
Specify amounts for all postings, using exactly two commodities, and let
|
||||
hledger infer the price that balances the transaction:
|
||||
.RS 4
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
2009/1/1
|
||||
\ \ assets:foreign\ currency\ \ \ €100\ \ \ \ \ \ \ \ \ \ ;\ one\ hundred\ euros
|
||||
\ \ assets:cash\ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-135\ \ \ \ \ \ \ \ \ \ ;\ exchanged\ for\ $135
|
||||
\ \ assets:euros\ \ \ \ \ €100\ \ \ \ \ \ \ \ \ \ ;\ one\ hundred\ euros\ purchased
|
||||
\ \ assets:dollars\ \ $\-135\ \ \ \ \ \ \ \ \ \ ;\ for\ $135
|
||||
\f[]
|
||||
.fi
|
||||
.RE
|
||||
.PP
|
||||
With any of the above examples we get:
|
||||
Amounts with transaction prices can be displayed in the transaction
|
||||
price\[aq]s commodity by using the \f[C]\-B/\-\-cost\f[] flag (except
|
||||
for #551) ("B" is from "cost Basis").
|
||||
Eg for the above, here is how \-B affects the balance report:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
$\ hledger\ print\ \-B
|
||||
2009/01/01
|
||||
\ \ \ \ assets:foreign\ currency\ \ \ \ \ \ \ $135.00
|
||||
\ \ \ \ assets:cash\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-135.00
|
||||
$\ hledger\ bal\ \-N\ \-\-flat
|
||||
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-135\ \ assets:dollars
|
||||
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ €100\ \ assets:euros
|
||||
$\ hledger\ bal\ \-N\ \-\-flat\ \-B
|
||||
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-135\ \ assets:dollars
|
||||
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $135\ \ assets:euros\ \ \ \ #\ <\-\ the\ euros\[aq]\ cost
|
||||
\f[]
|
||||
.fi
|
||||
.PP
|
||||
Example use for transaction prices: recording the effective conversion
|
||||
rate of purchases made in a foreign currency.
|
||||
Note \-B is sensitive to the order of postings when a transaction price
|
||||
is inferred: the inferred price will be in the commodity of the last
|
||||
amount.
|
||||
So if example 3\[aq]s postings are reversed, while the transaction is
|
||||
equivalent, \-B shows something different:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
2009/1/1
|
||||
\ \ assets:dollars\ \ $\-135\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ;\ 135\ dollars\ sold
|
||||
\ \ assets:euros\ \ \ \ \ €100\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ;\ for\ 100\ euros
|
||||
\f[]
|
||||
.fi
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
$\ hledger\ bal\ \-N\ \-\-flat\ \-B
|
||||
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ €\-100\ \ assets:dollars\ \ #\ <\-\ the\ dollars\[aq]\ selling\ price
|
||||
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ €100\ \ assets:euros
|
||||
\f[]
|
||||
.fi
|
||||
.SS Market prices
|
||||
.PP
|
||||
Market prices are not tied to a particular transaction; they represent
|
||||
|
||||
@ -488,48 +488,60 @@ File: hledger_journal.5.info, Node: Transaction prices, Next: Market prices,
|
||||
1.8.1 Transaction prices
|
||||
------------------------
|
||||
|
||||
Within a transaction posting, you can record an amount's price in
|
||||
another commodity. This can be used to document the cost (for a
|
||||
purchase), or selling price (for a sale), or the exchange rate that was
|
||||
used, for this transaction. These transaction prices are fixed, and do
|
||||
not change over time.
|
||||
Within a transaction, you can note an amount's price in another
|
||||
commodity. This can be used to document the cost (in a purchase) or
|
||||
selling price (in a sale). For example, transaction prices are useful
|
||||
to record purchases of a foreign currency.
|
||||
|
||||
Amounts with transaction prices can be displayed in the transaction
|
||||
price's commodity, by using the '--cost/-B' flag supported by most
|
||||
hledger commands (mnemonic: "cost Basis").
|
||||
Transaction prices are fixed, and do not change over time. (Ledger
|
||||
users: Ledger uses a different syntax for fixed prices, '{=UNITPRICE}',
|
||||
which hledger currently ignores).
|
||||
|
||||
There are several ways to record a transaction price:
|
||||
|
||||
1. Write the unit price (aka exchange rate), as '@ UNITPRICE' after
|
||||
the amount:
|
||||
1. Write the price per unit, as '@ UNITPRICE' after the amount:
|
||||
|
||||
2009/1/1
|
||||
assets:foreign currency €100 @ $1.35 ; one hundred euros at $1.35 each
|
||||
assets:cash
|
||||
assets:euros €100 @ $1.35 ; one hundred euros purchased at $1.35 each
|
||||
assets:dollars ; balancing amount is -$135.00
|
||||
|
||||
2. Or write the total price, as '@@ TOTALPRICE' after the amount:
|
||||
2. Write the total price, as '@@ TOTALPRICE' after the amount:
|
||||
|
||||
2009/1/1
|
||||
assets:foreign currency €100 @@ $135 ; one hundred euros at $135 for the lot
|
||||
assets:cash
|
||||
assets:euros €100 @@ $135 ; one hundred euros purchased at $135 for the lot
|
||||
assets:dollars
|
||||
|
||||
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 sum must have a non-zero amount in exactly two commodities:
|
||||
3. Specify amounts for all postings, using exactly two commodities,
|
||||
and let hledger infer the price that balances the transaction:
|
||||
|
||||
2009/1/1
|
||||
assets:foreign currency €100 ; one hundred euros
|
||||
assets:cash $-135 ; exchanged for $135
|
||||
assets:euros €100 ; one hundred euros purchased
|
||||
assets:dollars $-135 ; for $135
|
||||
|
||||
With any of the above examples we get:
|
||||
Amounts with transaction prices can be displayed in the transaction
|
||||
price's commodity by using the '-B/--cost' flag (except for #551) ("B"
|
||||
is from "cost Basis"). Eg for the above, here is how -B affects the
|
||||
balance report:
|
||||
|
||||
$ hledger print -B
|
||||
2009/01/01
|
||||
assets:foreign currency $135.00
|
||||
assets:cash $-135.00
|
||||
$ hledger bal -N --flat
|
||||
$-135 assets:dollars
|
||||
€100 assets:euros
|
||||
$ hledger bal -N --flat -B
|
||||
$-135 assets:dollars
|
||||
$135 assets:euros # <- the euros' cost
|
||||
|
||||
Example use for transaction prices: recording the effective
|
||||
conversion rate of purchases made in a foreign currency.
|
||||
Note -B is sensitive to the order of postings when a transaction
|
||||
price is inferred: the inferred price will be in the commodity of the
|
||||
last amount. So if example 3's postings are reversed, while the
|
||||
transaction is equivalent, -B shows something different:
|
||||
|
||||
2009/1/1
|
||||
assets:dollars $-135 ; 135 dollars sold
|
||||
assets:euros €100 ; for 100 euros
|
||||
|
||||
$ hledger bal -N --flat -B
|
||||
€-100 assets:dollars # <- the dollars' selling price
|
||||
€100 assets:euros
|
||||
|
||||
|
||||
File: hledger_journal.5.info, Node: Market prices, Prev: Transaction prices, Up: Prices
|
||||
@ -1001,41 +1013,41 @@ Node: Prices18072
|
||||
Ref: #prices18205
|
||||
Node: Transaction prices18256
|
||||
Ref: #transaction-prices18401
|
||||
Node: Market prices19978
|
||||
Ref: #market-prices20113
|
||||
Node: Comments21073
|
||||
Ref: #comments21195
|
||||
Node: Tags22308
|
||||
Ref: #tags22428
|
||||
Node: Implicit tags23857
|
||||
Ref: #implicit-tags23965
|
||||
Node: Directives24482
|
||||
Ref: #directives24597
|
||||
Node: Account aliases24790
|
||||
Ref: #account-aliases24936
|
||||
Node: Basic aliases25540
|
||||
Ref: #basic-aliases25685
|
||||
Node: Regex aliases26375
|
||||
Ref: #regex-aliases26545
|
||||
Node: Multiple aliases27260
|
||||
Ref: #multiple-aliases27434
|
||||
Node: end aliases27932
|
||||
Ref: #end-aliases28074
|
||||
Node: account directive28175
|
||||
Ref: #account-directive28357
|
||||
Node: apply account directive28653
|
||||
Ref: #apply-account-directive28851
|
||||
Node: Multi-line comments29510
|
||||
Ref: #multi-line-comments29702
|
||||
Node: commodity directive29830
|
||||
Ref: #commodity-directive30016
|
||||
Node: Default commodity30888
|
||||
Ref: #default-commodity31063
|
||||
Node: Default year31600
|
||||
Ref: #default-year31767
|
||||
Node: Including other files32190
|
||||
Ref: #including-other-files32349
|
||||
Node: EDITOR SUPPORT32746
|
||||
Ref: #editor-support32866
|
||||
Node: Market prices20557
|
||||
Ref: #market-prices20692
|
||||
Node: Comments21652
|
||||
Ref: #comments21774
|
||||
Node: Tags22887
|
||||
Ref: #tags23007
|
||||
Node: Implicit tags24436
|
||||
Ref: #implicit-tags24544
|
||||
Node: Directives25061
|
||||
Ref: #directives25176
|
||||
Node: Account aliases25369
|
||||
Ref: #account-aliases25515
|
||||
Node: Basic aliases26119
|
||||
Ref: #basic-aliases26264
|
||||
Node: Regex aliases26954
|
||||
Ref: #regex-aliases27124
|
||||
Node: Multiple aliases27839
|
||||
Ref: #multiple-aliases28013
|
||||
Node: end aliases28511
|
||||
Ref: #end-aliases28653
|
||||
Node: account directive28754
|
||||
Ref: #account-directive28936
|
||||
Node: apply account directive29232
|
||||
Ref: #apply-account-directive29430
|
||||
Node: Multi-line comments30089
|
||||
Ref: #multi-line-comments30281
|
||||
Node: commodity directive30409
|
||||
Ref: #commodity-directive30595
|
||||
Node: Default commodity31467
|
||||
Ref: #default-commodity31642
|
||||
Node: Default year32179
|
||||
Ref: #default-year32346
|
||||
Node: Including other files32769
|
||||
Ref: #including-other-files32928
|
||||
Node: EDITOR SUPPORT33325
|
||||
Ref: #editor-support33445
|
||||
|
||||
End Tag Table
|
||||
|
||||
@ -380,61 +380,72 @@ instead of just reading it.
|
||||
|
||||
### Transaction prices
|
||||
|
||||
Within a transaction posting, you can record an amount's price in another commodity.
|
||||
This can be used to document the cost (for a purchase), or selling price (for a sale),
|
||||
or the exchange rate that was used, for this transaction.
|
||||
These transaction prices are fixed, and do not change over time.
|
||||
<!--
|
||||
This is different from Ledger, where transaction prices fluctuate by
|
||||
default. Ledger has a different syntax for specifying
|
||||
[fixed prices](http://ledger-cli.org/3.0/doc/ledger3.html#Fixing-Lot-Prices):
|
||||
`{=PRICE}`. hledger parses that syntax, and (currently) ignores it.
|
||||
-->
|
||||
<!-- hledger treats this as an alternate spelling of `@ PRICE`, for greater compatibility with Ledger files. -->
|
||||
Within a transaction, you can note an amount's price in another commodity.
|
||||
This can be used to document the cost (in a purchase) or selling price (in a sale).
|
||||
For example, transaction prices are useful to record purchases of a foreign currency.
|
||||
|
||||
Amounts with transaction prices can be displayed in the transaction price's
|
||||
commodity, by using the [`--cost/-B`](hledger.html#reporting-options) flag
|
||||
supported by most hledger commands (mnemonic: "cost Basis").
|
||||
Transaction prices are fixed, and do not change over time.
|
||||
(Ledger users: Ledger uses a different [syntax](http://ledger-cli.org/3.0/doc/ledger3.html#Fixing-Lot-Prices)
|
||||
for fixed prices, `{=UNITPRICE}`, which hledger currently ignores).
|
||||
|
||||
There are several ways to record a transaction price:
|
||||
|
||||
1. Write the unit price (aka exchange rate), as `@ UNITPRICE` after the amount:
|
||||
1. Write the price per unit, as `@ UNITPRICE` after the amount:
|
||||
|
||||
```journal
|
||||
2009/1/1
|
||||
assets:foreign currency €100 @ $1.35 ; one hundred euros at $1.35 each
|
||||
assets:cash
|
||||
assets:euros €100 @ $1.35 ; one hundred euros purchased at $1.35 each
|
||||
assets:dollars ; balancing amount is -$135.00
|
||||
```
|
||||
|
||||
2. Or write the total price, as `@@ TOTALPRICE` after the amount:
|
||||
2. Write the total price, as `@@ TOTALPRICE` after the amount:
|
||||
|
||||
```journal
|
||||
2009/1/1
|
||||
assets:foreign currency €100 @@ $135 ; one hundred euros at $135 for the lot
|
||||
assets:cash
|
||||
assets:euros €100 @@ $135 ; one hundred euros purchased at $135 for the lot
|
||||
assets:dollars
|
||||
```
|
||||
|
||||
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 sum must have a non-zero amount in exactly two commodities:
|
||||
3. Specify amounts for all postings, using exactly two commodities,
|
||||
and let hledger infer the price that balances the transaction:
|
||||
|
||||
```journal
|
||||
2009/1/1
|
||||
assets:foreign currency €100 ; one hundred euros
|
||||
assets:cash $-135 ; exchanged for $135
|
||||
assets:euros €100 ; one hundred euros purchased
|
||||
assets:dollars $-135 ; for $135
|
||||
```
|
||||
|
||||
With any of the above examples we get:
|
||||
Amounts with transaction prices can be displayed in the transaction price's
|
||||
commodity by using the [`-B/--cost`](hledger.html#reporting-options) flag
|
||||
(except for [#551](https://github.com/simonmichael/hledger/issues/551))
|
||||
("B" is from "cost Basis").
|
||||
Eg for the above, here is how -B affects the balance report:
|
||||
|
||||
```shell
|
||||
$ hledger print -B
|
||||
2009/01/01
|
||||
assets:foreign currency $135.00
|
||||
assets:cash $-135.00
|
||||
$ hledger bal -N --flat
|
||||
$-135 assets:dollars
|
||||
€100 assets:euros
|
||||
$ hledger bal -N --flat -B
|
||||
$-135 assets:dollars
|
||||
$135 assets:euros # <- the euros' cost
|
||||
```
|
||||
|
||||
Note -B is sensitive to the order of postings when a transaction price is inferred:
|
||||
the inferred price will be in the commodity of the last amount.
|
||||
So if example 3's postings are reversed, while the transaction
|
||||
is equivalent, -B shows something different:
|
||||
|
||||
```journal
|
||||
2009/1/1
|
||||
assets:dollars $-135 ; 135 dollars sold
|
||||
assets:euros €100 ; for 100 euros
|
||||
```
|
||||
```shell
|
||||
$ hledger bal -N --flat -B
|
||||
€-100 assets:dollars # <- the dollars' selling price
|
||||
€100 assets:euros
|
||||
```
|
||||
|
||||
Example use for transaction prices: recording the effective conversion
|
||||
rate of purchases made in a foreign currency.
|
||||
|
||||
### Market prices
|
||||
|
||||
|
||||
@ -364,48 +364,60 @@ FILE FORMAT
|
||||
|
||||
Prices
|
||||
Transaction prices
|
||||
Within a transaction posting, you can record an amount's price in
|
||||
another commodity. This can be used to document the cost (for a pur-
|
||||
chase), or selling price (for a sale), or the exchange rate that was
|
||||
used, for this transaction. These transaction prices are fixed, and do
|
||||
not change over time.
|
||||
Within a transaction, you can note an amount's price in another commod-
|
||||
ity. This can be used to document the cost (in a purchase) or selling
|
||||
price (in a sale). For example, transaction prices are useful to
|
||||
record purchases of a foreign currency.
|
||||
|
||||
Amounts with transaction prices can be displayed in the transaction
|
||||
price's commodity, by using the --cost/-B flag supported by most
|
||||
hledger commands (mnemonic: "cost Basis").
|
||||
Transaction prices are fixed, and do not change over time. (Ledger
|
||||
users: Ledger uses a different syntax for fixed prices, {=UNITPRICE},
|
||||
which hledger currently ignores).
|
||||
|
||||
There are several ways to record a transaction price:
|
||||
|
||||
1. Write the unit price (aka exchange rate), as @ UNITPRICE after the
|
||||
amount:
|
||||
1. Write the price per unit, as @ UNITPRICE after the amount:
|
||||
|
||||
2009/1/1
|
||||
assets:foreign currency 100 @ $1.35 ; one hundred euros at $1.35 each
|
||||
assets:cash
|
||||
assets:euros 100 @ $1.35 ; one hundred euros purchased at $1.35 each
|
||||
assets:dollars ; balancing amount is -$135.00
|
||||
|
||||
2. Or write the total price, as @@ TOTALPRICE after the amount:
|
||||
2. Write the total price, as @@ TOTALPRICE after the amount:
|
||||
|
||||
2009/1/1
|
||||
assets:foreign currency 100 @@ $135 ; one hundred euros at $135 for the lot
|
||||
assets:cash
|
||||
assets:euros 100 @@ $135 ; one hundred euros purchased at $135 for the lot
|
||||
assets:dollars
|
||||
|
||||
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
|
||||
sum must have a non-zero amount in exactly two commodities:
|
||||
3. Specify amounts for all postings, using exactly two commodities, and
|
||||
let hledger infer the price that balances the transaction:
|
||||
|
||||
2009/1/1
|
||||
assets:foreign currency 100 ; one hundred euros
|
||||
assets:cash $-135 ; exchanged for $135
|
||||
assets:euros 100 ; one hundred euros purchased
|
||||
assets:dollars $-135 ; for $135
|
||||
|
||||
With any of the above examples we get:
|
||||
Amounts with transaction prices can be displayed in the transaction
|
||||
price's commodity by using the -B/--cost flag (except for #551) ("B" is
|
||||
from "cost Basis"). Eg for the above, here is how -B affects the bal-
|
||||
ance report:
|
||||
|
||||
$ hledger print -B
|
||||
2009/01/01
|
||||
assets:foreign currency $135.00
|
||||
assets:cash $-135.00
|
||||
$ hledger bal -N --flat
|
||||
$-135 assets:dollars
|
||||
100 assets:euros
|
||||
$ hledger bal -N --flat -B
|
||||
$-135 assets:dollars
|
||||
$135 assets:euros # <- the euros' cost
|
||||
|
||||
Example use for transaction prices: recording the effective conversion
|
||||
rate of purchases made in a foreign currency.
|
||||
Note -B is sensitive to the order of postings when a transaction price
|
||||
is inferred: the inferred price will be in the commodity of the last
|
||||
amount. So if example 3's postings are reversed, while the transaction
|
||||
is equivalent, -B shows something different:
|
||||
|
||||
2009/1/1
|
||||
assets:dollars $-135 ; 135 dollars sold
|
||||
assets:euros 100 ; for 100 euros
|
||||
|
||||
$ hledger bal -N --flat -B
|
||||
-100 assets:dollars # <- the dollars' selling price
|
||||
100 assets:euros
|
||||
|
||||
Market prices
|
||||
Market prices are not tied to a particular transaction; they represent
|
||||
@ -734,6 +746,7 @@ EDITOR SUPPORT
|
||||
ting-started
|
||||
Sublime Text https://github.com/ledger/ledger/wiki/Using-Sub-
|
||||
lime-Text
|
||||
|
||||
Textmate https://github.com/ledger/ledger/wiki/Using-Text-
|
||||
Mate-2
|
||||
Text Wrangler https://github.com/ledger/ledger/wiki/Edit-
|
||||
|
||||
Loading…
Reference in New Issue
Block a user