Simon Michael
parent
122309ced7
commit
e143ad2695
@ -1147,7 +1147,7 @@ if they have a [transaction price](journal.html#transaction-prices) specified.
|
||||
The `-V/--market` flag converts amounts to market value in their
|
||||
default *valuation commodity*, using the
|
||||
[market prices](#market-prices) in effect on the *valuation date(s)*, if any.
|
||||
More on these in a minute.
|
||||
More on these things in a minute.
|
||||
|
||||
### -X: Value in specified commodity
|
||||
|
||||
@ -1160,59 +1160,120 @@ For single period reports, if an explicit
|
||||
[report end date](#report-start-end-date) is specified, that will be
|
||||
used as the valuation date; otherwise the valuation date is "today".
|
||||
|
||||
For [multiperiod reports](#report-intervals), each column is valued on
|
||||
the last day of its period (displayed in the column heading).
|
||||
For [multiperiod reports](#report-intervals), each column/period is
|
||||
valued on the last day of the period.
|
||||
|
||||
### Market prices
|
||||
|
||||
To convert a commodity A to its market value in commodity B, hledger
|
||||
looks for a suitable market price (exchange rate) in these ways,
|
||||
in this order of preference:
|
||||
*(experimental)*
|
||||
|
||||
1. a *declared market price* -
|
||||
the latest [P directive](journal.html#declaring-market-prices)
|
||||
on or before the valuation date that declares A's price in B.
|
||||
To convert a commodity A to its market value in another commodity B,
|
||||
hledger looks for a suitable market price (exchange rate) as follows,
|
||||
in this order of preference
|
||||
<!-- (-X tries all of these; -V tries only 1) -->
|
||||
:
|
||||
|
||||
2. an *implied market price* -
|
||||
we look for the latest transaction on or before the valuation date
|
||||
where A is converted to B,
|
||||
and use its [transaction price](journal.html#transaction-prices),
|
||||
on the assumption that this is probably close to the market price.
|
||||
(*since hledger 1.18; experimental*)
|
||||
1. A *declared market price* or *inferred market price*:
|
||||
A's latest market price in B on or before the valuation date
|
||||
as declared by a [P directive](journal.html#declaring-market-prices),
|
||||
or (if the `--infer-value` flag is used)
|
||||
inferred from [transaction prices](journal.html#transaction-prices).
|
||||
<!-- (Latest by date, then parse order.) -->
|
||||
<!-- (A declared price overrides an inferred price on the same date.) -->
|
||||
|
||||
3. a *reverse declared market price* -
|
||||
if there is a declared market price from B to A, we invert it.
|
||||
2. A *reverse market price*:
|
||||
the inverse of a declared or inferred market price from B to A.
|
||||
|
||||
4. a *reverse implied market price* -
|
||||
if there is an implied market price from B to A, we invert it.
|
||||
3. A *chained market price*:
|
||||
a synthetic price formed by combining the shortest chain of market
|
||||
prices (any of the above types) leading from A to B.
|
||||
|
||||
5. an *indirect market price* -
|
||||
we look for the shortest chain of market prices (any of the above
|
||||
types) leading from A to B, and combine them to give an approximate
|
||||
A to B price.
|
||||
Amounts for which no applicable market price can be found, are not converted.
|
||||
|
||||
Amounts for which no suitable market price is found are not converted.
|
||||
<!-- You can add the `--debug` or `--debug=2` option to any command to see -->
|
||||
<!-- output useful for troubleshooting market prices and valuation. -->
|
||||
|
||||
<!-- Summary: -->
|
||||
|
||||
<!-- - `-V` and `-X` convert using market prices from P directives, only. -->
|
||||
<!-- - `-V --infer-value` and `-X --infer-value` convert using prices from P directives and from transactions. -->
|
||||
<!-- - Other needed prices will be generated by reversing and chaining if possible. -->
|
||||
|
||||
### --infer-value: market prices from transactions
|
||||
|
||||
*(experimental)*
|
||||
|
||||
Normally, market value in hledger is fully controlled by, and requires,
|
||||
[P directives](journal.html#declaring-market-prices) in your journal.
|
||||
Since adding and updating those can be a chore,
|
||||
and since transactions usually take place at close to market value,
|
||||
why not use the recorded [transaction prices](journal.html#transaction-prices)
|
||||
as additional market prices (as Ledger does) ?
|
||||
We could produce value reports without needing P directives at all.
|
||||
|
||||
Adding the `--infer-value` flag to `-V`, `-X` or `--value` enables
|
||||
this. So for example, `hledger bs -V --infer-value` will get market
|
||||
prices both from P directives and from transactions.
|
||||
|
||||
There is a downside to this: value reports can be affected in
|
||||
confusing/undesired ways by your journal entries. If this happens to
|
||||
you, read all of this [Valuation](#valuation) section carefully,
|
||||
and try adding `--debug` or `--debug=2` to troubleshoot the reason.
|
||||
|
||||
`--infer-value` can infer market prices from:
|
||||
|
||||
- multicommodity transactions with explicit prices (`@`/`@@`)
|
||||
|
||||
- multicommodity transactions with implicit prices (no `@`, two commodities, unbalanced).
|
||||
(With these, the order of postings matters. `hledger print -x` can be useful for troubleshooting.)
|
||||
|
||||
- but not, currently, from
|
||||
"[more correct](investments.html#a-more-correct-entry)" multicommodity transactions
|
||||
(no `@`, multiple commodities, balanced).
|
||||
|
||||
### Valuation commodity
|
||||
|
||||
With `-X COMM`, the valuation commodity is COMM, and hledger tries to
|
||||
convert all amounts to COMM.
|
||||
*(experimental)*
|
||||
|
||||
With `-V` (or `--value` with COMM unspecified), hledger tries to pick
|
||||
a valuation commodity - or possibly more than one - automatically.
|
||||
Currently, for each source commodity A, it chooses the commodity of
|
||||
the latest-dated declared market price (P directive) for A.
|
||||
(*hledger 1.18; previously, it was the latest-dated on or before valuation date. experimental*)
|
||||
If hledger can't identify a valuation commodity for an amount, it will not be converted.
|
||||
**When you specify a valuation commodity (`-X COMM` or `--value TYPE,COMM`):**\
|
||||
hledger will convert all amounts to COMM,
|
||||
wherever it can find a suitable market price (including by reversing or chaining prices).
|
||||
|
||||
How does this work in practice ? Typically you will have P directives,
|
||||
all declaring prices in a single base currency, and -V will convert to
|
||||
that currency. This makes it slightly more convenient than -X. But if
|
||||
you don't have any P directives, you will need to use -X instead, for now.
|
||||
**When you leave the valuation commodity unspecified (`-V` or `--value TYPE`):**\
|
||||
For each commodity A, hledger picks a default valuation commodity as
|
||||
follows, in this order of preference:
|
||||
|
||||
(Choosing valuation commodity based on transaction-implied market
|
||||
prices can be confusing, so currently
|
||||
[we don't do it](https://github.com/simonmichael/hledger/issues/1239).)
|
||||
1. The price commodity from the latest P-declared market price for A
|
||||
on or before valuation date.
|
||||
|
||||
2. The price commodity from the latest P-declared market price for A on
|
||||
any date. (Allows conversion to proceed when there are inferred
|
||||
prices before the valuation date.)
|
||||
|
||||
3. If there are no P directives at all (any commodity or date) and the
|
||||
`--infer-value` flag is used: the price commodity from the latest
|
||||
transaction-inferred price for A on or before valuation date.
|
||||
|
||||
Amounts for which no valuation commodity can be found are not converted.
|
||||
|
||||
This means:
|
||||
|
||||
- If you have any [P directives](journal.html#declaring-market-prices),
|
||||
they alone determine which commodities `-V` will convert, and to what.
|
||||
|
||||
- If you have no P directives, and you add the `--infer-value` flag,
|
||||
[transaction prices](journal.html#transaction-prices) determine
|
||||
what `-V` converts.
|
||||
|
||||
- `-X` tries harder to convert everything to just one commodity.
|
||||
|
||||
<!-- Summary: -->
|
||||
|
||||
<!-- - `-X` converts everything to a commodity you specify. -->
|
||||
<!-- - `-V` converts each commodity to the price commodity mentioned in its latest P directive. -->
|
||||
<!-- - If you have no P directives, `-V --infer-value` converts each commodity to the price commodity mentioned in a recent transaction. -->
|
||||
|
||||
<!-- [#1239](https://github.com/simonmichael/hledger/issues/1239) -->
|
||||
|
||||
### Simple valuation examples
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user