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

;valuation: doc specifying new proposed behaviour (#1239, #1253)

Browse Source
This commit is contained in:
Simon Michael 2020-06-16 18:07:16 -07:00
parent 122309ced7
commit e143ad2695
1 changed files with 100 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

139
hledger/hledger.m4.md
View File

@ -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 The `-V/--market` flag converts amounts to market value in their
default *valuation commodity*, using the default *valuation commodity*, using the
[market prices](#market-prices) in effect on the *valuation date(s)*, if any. [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 ### -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 [report end date](#report-start-end-date) is specified, that will be
used as the valuation date; otherwise the valuation date is "today". used as the valuation date; otherwise the valuation date is "today".
For [multiperiod reports](#report-intervals), each column is valued on For [multiperiod reports](#report-intervals), each column/period is
the last day of its period (displayed in the column heading). valued on the last day of the period.
### Market prices ### Market prices
To convert a commodity A to its market value in commodity B, hledger *(experimental)*
looks for a suitable market price (exchange rate) in these ways,
in this order of preference:
1. a *declared market price* - To convert a commodity A to its market value in another commodity B,
the latest [P directive](journal.html#declaring-market-prices) hledger looks for a suitable market price (exchange rate) as follows,
on or before the valuation date that declares A's price in B. in this order of preference
<!-- (-X tries all of these; -V tries only 1) -->
:
2. an *implied market price* - 1. A *declared market price* or *inferred market price*:
we look for the latest transaction on or before the valuation date A's latest market price in B on or before the valuation date
where A is converted to B, as declared by a [P directive](journal.html#declaring-market-prices),
and use its [transaction price](journal.html#transaction-prices), or (if the `--infer-value` flag is used)
on the assumption that this is probably close to the market price. inferred from [transaction prices](journal.html#transaction-prices).
(*since hledger 1.18; experimental*) <!-- (Latest by date, then parse order.) -->
<!-- (A declared price overrides an inferred price on the same date.) -->
3. a *reverse declared market price* - 2. A *reverse market price*:
if there is a declared market price from B to A, we invert it. the inverse of a declared or inferred market price from B to A.
4. a *reverse implied market price* - 3. A *chained market price*:
if there is an implied market price from B to A, we invert it. 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* - Amounts for which no applicable market price can be found, are not converted.
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 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 ### Valuation commodity
With `-X COMM`, the valuation commodity is COMM, and hledger tries to *(experimental)*
convert all amounts to COMM.
With `-V` (or `--value` with COMM unspecified), hledger tries to pick **When you specify a valuation commodity (`-X COMM` or `--value TYPE,COMM`):**\
a valuation commodity - or possibly more than one - automatically. hledger will convert all amounts to COMM,
Currently, for each source commodity A, it chooses the commodity of wherever it can find a suitable market price (including by reversing or chaining prices).
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.
How does this work in practice ? Typically you will have P directives, **When you leave the valuation commodity unspecified (`-V` or `--value TYPE`):**\
all declaring prices in a single base currency, and -V will convert to For each commodity A, hledger picks a default valuation commodity as
that currency. This makes it slightly more convenient than -X. But if follows, in this order of preference:
you don't have any P directives, you will need to use -X instead, for now.
(Choosing valuation commodity based on transaction-implied market 1. The price commodity from the latest P-declared market price for A
prices can be confusing, so currently on or before valuation date.
[we don't do it](https://github.com/simonmichael/hledger/issues/1239).)
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 ### Simple valuation examples