diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md index 2b0c06eb4..0e3844614 100644 --- a/hledger/hledger.m4.md +++ b/hledger/hledger.m4.md @@ -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 + +: -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). + + -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. + + + + + + + + + +### --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. + + + + + + + + ### Simple valuation examples