diff --git a/hledger-lib/Hledger/Reports/ReportOptions.hs b/hledger-lib/Hledger/Reports/ReportOptions.hs index 02bc8c02c..2c5ddff12 100644 --- a/hledger-lib/Hledger/Reports/ReportOptions.hs +++ b/hledger-lib/Hledger/Reports/ReportOptions.hs @@ -334,14 +334,15 @@ reportOptsToggleStatus s ropts@ReportOpts{statuses_=ss} | otherwise = ropts{statuses_=simplifyStatuses (s:ss)} -- | Parse the type of valuation to be performed, if any, specified by --- -B/--cost/-V/--value flags. If there's more than one of these, the --- rightmost flag wins. +-- -B/--cost, -V, -X/--exchange, or --value flags. If there's more +-- than one of these, the rightmost flag wins. valuationTypeFromRawOpts :: RawOpts -> Maybe ValuationType valuationTypeFromRawOpts = lastDef Nothing . filter isJust . map valuationfromrawopt where valuationfromrawopt (n,v) -- option name, value | n == "B" = Just $ AtCost Nothing | n == "V" = Just $ AtDefault Nothing + | n == "X" = Just $ AtDefault (Just $ T.pack v) | n == "value" = Just $ valuation v | otherwise = Nothing valuation v @@ -353,12 +354,18 @@ valuationTypeFromRawOpts = lastDef Nothing . filter isJust . map valuationfromra Just d -> AtDate d mc Nothing -> usageError $ "could not parse \""++t++"\" as valuation type, should be: cost|end|now|c|e|n|YYYY-MM-DD" where - -- parse TYPE[,COMM] + -- parse --value's value: TYPE[,COMM] (t,c') = break (==',') v mc = case drop 1 c' of "" -> Nothing c -> Just $ T.pack c +valuationTypeIsCost :: ReportOpts -> Bool +valuationTypeIsCost ropts = + case value_ ropts of + Just (AtCost _) -> True + _ -> False + type DisplayExp = String maybedisplayopt :: Day -> RawOpts -> Maybe DisplayExp @@ -390,12 +397,6 @@ flat_ = (==ALFlat) . accountlistmode_ -- depthFromOpts :: ReportOpts -> Int -- depthFromOpts opts = min (fromMaybe 99999 $ depth_ opts) (queryDepth $ queryFromOpts nulldate opts) -valuationTypeIsCost :: ReportOpts -> Bool -valuationTypeIsCost ropts = - case value_ ropts of - Just (AtCost _) -> True - _ -> False - -- | Convert this journal's postings' amounts to cost using their -- transaction prices, if specified by options (-B/--value=cost). -- Maybe soon superseded by newer valuation code. diff --git a/hledger/Hledger/Cli/CliOptions.hs b/hledger/Hledger/Cli/CliOptions.hs index 05b4ff444..be9ada967 100644 --- a/hledger/Hledger/Cli/CliOptions.hs +++ b/hledger/Hledger/Cli/CliOptions.hs @@ -154,29 +154,28 @@ reportflags = [ -- valuation ,flagNone ["B","cost"] (setboolopt "B") - "show amounts converted to cost commodity, same as --value=cost" + "show amounts converted to their cost, using the transaction price. Equivalent to --value=cost." ,flagNone ["V","market"] (setboolopt "V") (unwords - ["show amounts converted to default valuation commodity," - ,"same as --value=now (single period reports)" - ,"or --value=end (multiperiod reports)" -- TODO + ["show amounts converted to current market value (single period reports)" + ,"or period-end market value (multiperiod reports) in their default valuation commodity." + ,"Equivalent to --value=now / --value=end." + ]) + ,flagReq ["X","exchange"] (\s opts -> Right $ setopt "X" s opts) "COMM" + (unwords + ["show amounts converted to current (single period reports)" + ,"or period-end (multiperiod reports) market value in the specified commodity." + ,"Equivalent to --value=now,COMM / --value=end,COMM." ]) - -- TODO: -X - -- ,flagReq ["X"] (\s opts -> Right $ setopt "X" s opts) "COMM" - -- (unwords - -- ["show amounts converted to this commodity" - -- ,"same as --value=now,COMM (single period reports)" - -- ,"or --value=end,COMM (multiperiod reports)" - -- ]) ,flagReq ["value"] (\s opts -> Right $ setopt "value" s opts) "TYPE[,COMM]" (unlines ["TYPE is cost, end, now or YYYY-MM-DD." ,"COMM is an optional commodity symbol." ,"Shows amounts converted to:" - ,"- cost commodity using transaction prices (then optionally to COMM using market prices at period end(s))" - ,"- default valuation commodity (or COMM) using market prices at period end(s)" - ,"- default valuation commodity (or COMM) using current market prices" - ,"- default valuation commodity (or COMM) using market prices at some date" + ,"- cost using transaction prices, then optionally to COMM using period-end market prices" + ,"- period-end market value, in default valuation commodity or COMM" + ,"- current market value, in default valuation commodity or COMM" + ,"- market value on the given date, in default valuation commodity or COMM" ]) -- generated postings/transactions diff --git a/hledger/hledger_options.m4.md b/hledger/hledger_options.m4.md index 52e6df63f..735d662f3 100644 --- a/hledger/hledger_options.m4.md +++ b/hledger/hledger_options.m4.md @@ -443,22 +443,32 @@ $ hledger balance --pivot member acct:. -2 EUR ``` -## Cost +## Valuation -The `-B/--cost` flag converts amounts to their cost at transaction time, +### -B: Cost + +The `-B/--cost` flag converts amounts to their cost (or selling price) at transaction time, if they have a [transaction price](/journal.html#transaction-prices) specified. This flag is equivalent to `--value=cost`, described below. -## Market value +### -V: Market value -The `-V/--market` flag converts reported amounts to their market value in another commodity. -It uses the default valuation commodity referenced in the latest [market price](journal.html#market-prices) (P directive) -dated on or before the default valuation date, which is: +The `-V/--market` flag converts reported amounts to their market value in a default valuation commodity, +using the [historical market prices](journal.html#market-prices) in effect on a default valuation date. -- today for single period reports (equivalent to `--value=now`) -- the end of each subperiod for multiperiod reports, ie reports with a [report interval](#report-intervals) (equivalent to `--value=end`). +For single period reports, the valuation date is today. +For [multiperiod reports](#report-intervals), it is the last day of each subperiod. -A quick example of `-V`: +The valuation commodity will be 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. + +`-V/--market` is similar to the same flag in Ledger, except +unlike Ledger it does not infer market prices from [transaction prices](/manual.html#transaction-prices). +(Mnemonic: in hledger, -B uses transaction prices, -V and -X use market prices.) +It is equivalent to `--value=now` or `--value=end`. + +Here's a quick example: ```journal # one euro is worth this many dollars from nov 1 @@ -488,15 +498,18 @@ $ hledger -f t.j bal -N euros -V $103.00 assets:euros ``` -Ledger users: Ledger's -V also infers market prices from journal entries, -but we don't do that. hledger's -V uses only market prices declared explicitly, with P directives. -(Mnemonic: -B/--cost uses transaction prices, -V/--market uses market prices.) +### -X: Market value in specified commodity -### More control over valuation +The `-X/--exchange` option is like `-V/--market` except it takes a +commodity symbol argument, so that you can select a different target commodity. +It is similar to the same option in Ledger, with the same caveat mentioned for `-V`/`--value` above. +It is equivalent to `--value=now,COMM` or `--value=end,COMM`; for more details, read on. + +### --value *(experimental, added 201905)* -You can control valuation more precisely with the `--value` option: +`-B`, `-V` and `-X` are special cases of the more general `--value` option: --value=TYPE[,COMM] TYPE is cost, end, now or YYYY-MM-DD. COMM is an optional commodity symbol. @@ -506,20 +519,21 @@ You can control valuation more precisely with the `--value` option: - default valuation commodity (or COMM) using current market prices - default valuation commodity (or COMM) using market prices at some date -TYPE is one of the keywords shown, or their first letter, or a date -(which must be 8 digits with `-` or `/` or `.` separators). -Here they are in more detail: +#### Valuation type -`--value=cost` (or `c`) +TYPE is one of these keywords, or their first letter, or a date (which +must be 8 digits with `-` or `/` or `.` separators): + +`--value=cost` : Convert amounts to cost, using the prices recorded in transactions. `-B`/`--cost` is equivalent to this. -`--value=end` (or `e`) +`--value=end` : Convert amounts to their value in default valuation commodity using market prices on the last day of the report period (or of each subperiod in a multiperiod report). When no report period is specified, uses the journal's last transaction date. -`--value=now` (or `n`) +`--value=now` : Convert amounts to their value in default valuation commodity using current market prices (as of when report is generated). `-V`/`--market` is equivalent to this. @@ -527,17 +541,20 @@ Here they are in more detail: : Convert amounts to their value in default valuation commodity using market prices on this date. Eg `--value=2019-04-25`. +#### Valuation commodity + The default valuation commodity is the commodity mentioned in the most recent applicable market price declaration. When all your price -declarations lead to a single home currency, that will be the default -valuation currency, which is generally what you want. +declarations lead to a single home currency, this will usually do what +you want. -To select a different valuation currency, you can write a comma and -the commodity symbol after the valuation type above. - -Note this does not yet follow chains of market prices; -it can only use market prices leading directly from A to B, -or prices from B to A (which will be inverted). +To select a different valuation commodity: write the commodity symbol +after the valuation type, separated by a comma (eg: **`--value=now,EUR`**). +Currently this will only use market prices leading directly from A to +B, or (after inverting them) prices from B to A; +it does not yet follow chains of market prices. + +#### --value examples Here are the effects of `--value` as seen with `print`: @@ -624,7 +641,7 @@ $ hledger -f- print --value=2000-01-15 ``` -### Effect of --value on reports +#### Effect of --value on reports Below is how `--value` affects each of hledger's reports, currently. You're not expected to remember all this, but when troubleshooting a report, look here. @@ -649,15 +666,7 @@ messages being printed - please report them (with reproducible examples) eg at | budget amounts with --budget | costs of budget amounts | budget-setting periodic txns are valued at period end | budget-setting periodic txns are valued at DATE | | column/row/grand totals/averages | sum/average of the displayed values | market value at period end of sum/average of postings | market value at DATE of sum/average of postings | -### Some useful value reports - -Here are some probably useful reports, please send suggestions if you find more: - -| Command: | Description of report: | Could answer: | -|---------------------------|----------------------------------------------------|--------------------------------------------------| -| `hledger bs -M --value=e` | Monthly historical value of assets/liabilities | How are my investments performing ? | - -### Combining -B, -V, --value +### Combining -B, -V, -X, --value The rightmost of these flags wins.