From 93154e9251056ee9f347d004f6e6f686b6683198 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sun, 24 May 2020 12:21:40 -0700 Subject: [PATCH] update and clean up valuation docs (#1239) --- hledger-lib/hledger_journal.m4.md | 6 +-- hledger/hledger.m4.md | 68 ++++++++++++++++++++++++------- 2 files changed, 56 insertions(+), 18 deletions(-) diff --git a/hledger-lib/hledger_journal.m4.md b/hledger-lib/hledger_journal.m4.md index b44b0a70e..1ee5ff461 100644 --- a/hledger-lib/hledger_journal.m4.md +++ b/hledger-lib/hledger_journal.m4.md @@ -989,7 +989,7 @@ D $1,000.00 b ``` -### Market prices +### Declaring market prices The `P` directive declares a market price, which is an exchange rate between two commodities on a certain date. @@ -1016,8 +1016,8 @@ P 2009/1/1 € $1.35 P 2010/1/1 € $1.40 ``` -The [`-V/--value`](hledger.html#v-market-value) flag can be used to convert reported amounts -to another commodity using these prices. +The `-V`, `-X` and `--value` flags use these market prices to show amount values +in another commodity. See [Valuation](hledger.html#valuation). ### Declaring accounts diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md index 6077b0e55..136368e59 100644 --- a/hledger/hledger.m4.md +++ b/hledger/hledger.m4.md @@ -1121,28 +1121,44 @@ $ hledger balance --pivot member acct:. ## Valuation +hledger can show +cost reports, where amounts are converted to their cost or sale amount +at transaction time; +or value reports, where amounts are converted to their market value in +another currency/commodity at a specified date +(using market prices inferred from your transactions, or declared with P directives). + +We call this "valuation", and it is controlled by the `--value=VALUATIONTYPE[,COMMODITY]` option. +It can get a little involved, so we cover all the details below. +But most of the time, all you need to do is use these simpler flags instead: + +- `-B` to convert to cost/sale amount, or +- `-V` to convert to market value in your base currency. Or occasionally, +- `-X COMMODITY` to convert to market value in some other currency. + + + ### -B: Cost -The `-B/--cost` flag converts amounts to their cost (or selling price) at transaction time, +The `-B/--cost` flag converts amounts to their cost or sale amount at transaction time, if they have a [transaction price](journal.html#transaction-prices) specified. -This flag is equivalent to `--value=cost`, described below. +(It is equivalent to `--value=cost`.) -### -V: Market value +### -V: Value -The `-V/--market` flag converts reported amounts to their market value in a default valuation commodity, -using the [market prices](journal.html#market-prices) in effect on a default valuation date. -For single period reports, the valuation date is today (equivalent to `--value=now`); -for [multiperiod reports](#report-intervals), it is the last day of each subperiod (equivalent to `--value=end`). +The `-V/--market` flag converts reported amounts to market value in +their *default valuation commodity*, using the [market prices](#market-prices) +in effect on a *default valuation date*. (More on these below.) The default valuation commodity is the one referenced in the latest applicable market price dated on or before the valuation date. -If most of your P declarations lead to a single home currency, this will usually be what you want. -(To specify the commodity, see -X below.) +Typically your P declarations or currency exchange transactions +reference a single base currency, and -V will pick that. -Note that in hledger, market prices are always declared explicitly with P directives; -we do not infer them from [transaction prices](journal.html#transaction-prices) as Ledger does. +The default valuation date is today for single period reports (equivalent to `--value=now`), +or the last day of each subperiod for [multiperiod reports](#report-intervals) (equivalent to `--value=end`). -Here's a quick example of -V: +An example: ```journal ; one euro is worth this many dollars from nov 1 @@ -1175,7 +1191,31 @@ $ hledger -f t.j bal -N euros -V ### -X: Market value in specified commodity The `-X/--exchange` option is like `-V`, except it specifies the target commodity you would like to convert to. -It is equivalent to `--value=now,COMM` or `--value=end,COMM`. +(It is equivalent to `--value=now,COMM` or `--value=end,COMM`.) + +### Market prices + +To convert a commodity A to commodity B, hledger looks for a suitable +market price (exchange rate) in the following ways, in this order of +preference: + +1. a *declared market price* - the latest [P directive](journal.html#declaring-market-prices) + specifying the exchange rate from A to B, dated on or before the valuation date. + +2. a *transaction-implied market price* - a market price matching the + [transaction price](journal.html#transaction-prices) used in the + latest transaction where A is converted to B, + dated on or before the valuation date. + (*since hledger 1.18; experimental*) + +3. a *reverse declared market price* - calculated by inverting a + declared market price from B to A. + +4. a *reverse transaction-implied market price* - calculated by + inverting a transaction-implied market price from B to A. + +5. an *indirect market price* - calculated by combining the shortest + chain of market prices (any of the above types) leading from A to B. ### --value: Flexible valuation @@ -1408,9 +1448,7 @@ Related: : a flag (-D/-W/-M/-Q/-Y) or period expression that activates the report's multi-period mode (whether showing one or many subperiods). -### Combining -B, -V, -X, --value -The rightmost of these flags wins. # COMMANDS