diff --git a/CHANGES.md b/CHANGES.md --- a/CHANGES.md +++ b/CHANGES.md @@ -1,6 +1,19 @@ User-visible changes in the hledger command line tool and library. +# 1.18.1 2020-06-21 + +- journal: document recursive wildcards + +- by default, value reports work as in 1.17; to infer market prices from + transactions, add the new --infer-value flag. (#1239, #1253) + +- organise debug output better + +- print: amounts in csv output now have commodity symbol, digit group + separators and prices removed (Dmitry Astapov) + + # 1.18 2020-06-07 ## General @@ -18,9 +31,10 @@ - We now show `..` instead of `-` to indicate date ranges, eg in report titles, to stand out more from hyphenated dates. + (Stephen Morgan) - Period expressions (eg in -p, date:, and periodic rules) now accept - `to`, `until`, `-`, or `..` as synonyms. + `to`, `until`, `-`, or `..` as synonyms. (Stephen Morgan) - When parsing amounts, whitespace between sign and number is now allowed. @@ -153,12 +167,12 @@ hledger ui 'amt:>200' - failed. This was becasue the process of dispatching from `hledger ui` + failed. This was because the process of dispatching from `hledger ui` to `hledger-ui` (note addition of `-`) lost the quotes around `amt:>20` and the `>` character was interpreted as a shell redirection operator, rather than as part of the argument. - The machinery for quoting or escaping arguements which contain + The machinery for quoting or escaping arguments which contain characters which require quoting or escaping (thus far whitespace and quotes) already existed. This solution simply adds shell stdio redirection characters to this set. diff --git a/Hledger/Cli/CliOptions.hs b/Hledger/Cli/CliOptions.hs --- a/Hledger/Cli/CliOptions.hs +++ b/Hledger/Cli/CliOptions.hs @@ -155,7 +155,7 @@ -- valuation ,flagNone ["B","cost"] (setboolopt "B") - "show amounts converted to their cost, using the transaction price. Equivalent to --value=cost." + "show amounts converted to their cost/selling amount, using the transaction price. Equivalent to --value=cost." ,flagNone ["V","market"] (setboolopt "V") (unwords ["show amounts converted to current market value (single period reports)" @@ -178,6 +178,7 @@ ,"- current market value, in default valuation commodity or COMM" ,"- market value on the given date, in default valuation commodity or COMM" ]) + ,flagNone ["infer-value"] (setboolopt "infer-value") "with -V/-X/--value, also infer market prices from transactions" -- generated postings/transactions ,flagNone ["auto"] (setboolopt "auto") "apply automated posting rules to modify transactions" diff --git a/Hledger/Cli/Commands/Print.hs b/Hledger/Cli/Commands/Print.hs --- a/Hledger/Cli/Commands/Print.hs +++ b/Hledger/Cli/Commands/Print.hs @@ -148,7 +148,9 @@ postingToCSV :: Posting -> CSV postingToCSV p = map (\(a@(Amount {aquantity=q,acommodity=c})) -> - let a_ = a{acommodity=""} in + -- commodity goes into separate column, so we suppress it, along with digit group + -- separators and prices + let a_ = a{acommodity="",astyle=(astyle a){asdigitgroups=Nothing},aprice=Nothing} in let amount = showAmount a_ in let commodity = T.unpack c in let credit = if q < 0 then showAmount $ negate a_ else "" in diff --git a/Hledger/Cli/CompoundBalanceCommand.hs b/Hledger/Cli/CompoundBalanceCommand.hs --- a/Hledger/Cli/CompoundBalanceCommand.hs +++ b/Hledger/Cli/CompoundBalanceCommand.hs @@ -146,7 +146,7 @@ -- make a CompoundBalanceReport. -- For efficiency, generate a price oracle here and reuse it with each subreport. - priceoracle = journalPriceOracle j + priceoracle = journalPriceOracle infer_value_ j subreports = map (\CBCSubreportSpec{..} -> (cbcsubreporttitle @@ -270,7 +270,7 @@ | otherwise = PeriodicReport dates rows' totals where nonzeroaccounts = - dbg1 "nonzeroaccounts" $ + dbg5 "nonzeroaccounts" $ mapMaybe (\(PeriodicReportRow act _ amts _ _) -> if not (all mixedAmountLooksZero amts) then Just act else Nothing) rows rows' = filter (not . emptyRow) rows diff --git a/Hledger/Cli/Main.hs b/Hledger/Cli/Main.hs --- a/Hledger/Cli/Main.hs +++ b/Hledger/Cli/Main.hs @@ -115,7 +115,7 @@ (argsbeforecmd, argsaftercmd') = break (==rawcmd) args argsaftercmd = drop 1 argsaftercmd' dbgIO :: Show a => String -> a -> IO () - dbgIO = ptraceAtIO 2 + dbgIO = ptraceAtIO 6 dbgIO "running" prognameandversion dbgIO "raw args" args diff --git a/embeddedfiles/hledger-ui.1 b/embeddedfiles/hledger-ui.1 --- a/embeddedfiles/hledger-ui.1 +++ b/embeddedfiles/hledger-ui.1 @@ -1,5 +1,5 @@ -.TH "hledger-ui" "1" "June 2020" "hledger-ui 1.18" "hledger User Manuals" +.TH "hledger-ui" "1" "June 2020" "hledger-ui 1.18.1" "hledger User Manuals" @@ -139,12 +139,19 @@ hledger-ui/hledger-web) .TP \f[B]\f[CB]-B --cost\f[B]\f[R] -convert amounts to their cost at transaction time (using the transaction -price, if any) +convert amounts to their cost/selling amount at transaction time .TP -\f[B]\f[CB]-V --value\f[B]\f[R] -convert amounts to their market value on the report end date (using the -most recent applicable market price, if any) +\f[B]\f[CB]-V --market\f[B]\f[R] +convert amounts to their market value in default valuation commodities +.TP +\f[B]\f[CB]-X --exchange=COMM\f[B]\f[R] +convert amounts to their market value in commodity COMM +.TP +\f[B]\f[CB]--value\f[B]\f[R] +convert amounts to cost or market value, more flexibly than -B/-V/-X +.TP +\f[B]\f[CB]--infer-value\f[B]\f[R] +with -V/-X/--value, also infer market prices from transactions .TP \f[B]\f[CB]--auto\f[B]\f[R] apply automated posting rules to modify transactions. diff --git a/embeddedfiles/hledger-ui.info b/embeddedfiles/hledger-ui.info --- a/embeddedfiles/hledger-ui.info +++ b/embeddedfiles/hledger-ui.info @@ -3,8 +3,8 @@  File: hledger-ui.info, Node: Top, Next: OPTIONS, Up: (dir) -hledger-ui(1) hledger-ui 1.18 -***************************** +hledger-ui(1) hledger-ui 1.18.1 +******************************* hledger-ui - terminal interface for the hledger accounting tool @@ -152,12 +152,21 @@ hledger-ui/hledger-web) '-B --cost' - convert amounts to their cost at transaction time (using the - transaction price, if any) -'-V --value' + convert amounts to their cost/selling amount at transaction time +'-V --market' - convert amounts to their market value on the report end date (using - the most recent applicable market price, if any) + convert amounts to their market value in default valuation + commodities +'-X --exchange=COMM' + + convert amounts to their market value in commodity COMM +'--value' + + convert amounts to cost or market value, more flexibly than + -B/-V/-X +'--infer-value' + + with -V/-X/-value, also infer market prices from transactions '--auto' apply automated posting rules to modify transactions. @@ -499,26 +508,26 @@  Tag Table: Node: Top71 -Node: OPTIONS1470 -Ref: #options1567 -Node: KEYS4998 -Ref: #keys5093 -Node: SCREENS9369 -Ref: #screens9474 -Node: Accounts screen9564 -Ref: #accounts-screen9692 -Node: Register screen11908 -Ref: #register-screen12063 -Node: Transaction screen14060 -Ref: #transaction-screen14218 -Node: Error screen15088 -Ref: #error-screen15210 -Node: ENVIRONMENT15454 -Ref: #environment15568 -Node: FILES16375 -Ref: #files16474 -Node: BUGS16687 -Ref: #bugs16764 +Node: OPTIONS1474 +Ref: #options1571 +Node: KEYS5186 +Ref: #keys5281 +Node: SCREENS9557 +Ref: #screens9662 +Node: Accounts screen9752 +Ref: #accounts-screen9880 +Node: Register screen12096 +Ref: #register-screen12251 +Node: Transaction screen14248 +Ref: #transaction-screen14406 +Node: Error screen15276 +Ref: #error-screen15398 +Node: ENVIRONMENT15642 +Ref: #environment15756 +Node: FILES16563 +Ref: #files16662 +Node: BUGS16875 +Ref: #bugs16952  End Tag Table diff --git a/embeddedfiles/hledger-ui.txt b/embeddedfiles/hledger-ui.txt --- a/embeddedfiles/hledger-ui.txt +++ b/embeddedfiles/hledger-ui.txt @@ -135,13 +135,22 @@ hledger-ui/hledger-web) -B --cost - convert amounts to their cost at transaction time (using the - transaction price, if any) + convert amounts to their cost/selling amount at transaction time - -V --value - convert amounts to their market value on the report end date - (using the most recent applicable market price, if any) + -V --market + convert amounts to their market value in default valuation com- + modities + -X --exchange=COMM + convert amounts to their market value in commodity COMM + + --value + convert amounts to cost or market value, more flexibly than + -B/-V/-X + + --infer-value + with -V/-X/--value, also infer market prices from transactions + --auto apply automated posting rules to modify transactions. --forecast @@ -441,4 +450,4 @@ -hledger-ui 1.18 June 2020 hledger-ui(1) +hledger-ui 1.18.1 June 2020 hledger-ui(1) diff --git a/embeddedfiles/hledger-web.1 b/embeddedfiles/hledger-web.1 --- a/embeddedfiles/hledger-web.1 +++ b/embeddedfiles/hledger-web.1 @@ -1,5 +1,5 @@ -.TH "hledger-web" "1" "June 2020" "hledger-web 1.18" "hledger User Manuals" +.TH "hledger-web" "1" "June 2020" "hledger-web 1.18.1" "hledger User Manuals" @@ -165,13 +165,20 @@ hledger-ui/hledger-web) .TP \f[B]\f[CB]-B --cost\f[B]\f[R] -convert amounts to their cost at transaction time (using the transaction -price, if any) +convert amounts to their cost/selling amount at transaction time .TP -\f[B]\f[CB]-V --value\f[B]\f[R] -convert amounts to their market value on the report end date (using the -most recent applicable market price, if any) +\f[B]\f[CB]-V --market\f[B]\f[R] +convert amounts to their market value in default valuation commodities .TP +\f[B]\f[CB]-X --exchange=COMM\f[B]\f[R] +convert amounts to their market value in commodity COMM +.TP +\f[B]\f[CB]--value\f[B]\f[R] +convert amounts to cost or market value, more flexibly than -B/-V/-X +.TP +\f[B]\f[CB]--infer-value\f[B]\f[R] +with -V/-X/--value, also infer market prices from transactions +.TP \f[B]\f[CB]--auto\f[B]\f[R] apply automated posting rules to modify transactions. .TP @@ -225,7 +232,7 @@ behind a reverse proxy that handles authentication for different users. The path can be derived in a predictable way, eg by using the username within the path. -As an example, \f[C]nginx\f[R] as reverse proxy can use the variabel +As an example, \f[C]nginx\f[R] as reverse proxy can use the variable \f[C]$remote_user\f[R] to derive a path from the username used in a HTTP basic authentication. The following \f[C]proxy_pass\f[R] directive allows access to all diff --git a/embeddedfiles/hledger-web.info b/embeddedfiles/hledger-web.info --- a/embeddedfiles/hledger-web.info +++ b/embeddedfiles/hledger-web.info @@ -3,8 +3,8 @@  File: hledger-web.info, Node: Top, Next: OPTIONS, Up: (dir) -hledger-web(1) hledger-web 1.18 -******************************* +hledger-web(1) hledger-web 1.18.1 +********************************* hledger-web - web interface for the hledger accounting tool @@ -176,12 +176,21 @@ hledger-ui/hledger-web) '-B --cost' - convert amounts to their cost at transaction time (using the - transaction price, if any) -'-V --value' + convert amounts to their cost/selling amount at transaction time +'-V --market' - convert amounts to their market value on the report end date (using - the most recent applicable market price, if any) + convert amounts to their market value in default valuation + commodities +'-X --exchange=COMM' + + convert amounts to their market value in commodity COMM +'--value' + + convert amounts to cost or market value, more flexibly than + -B/-V/-X +'--infer-value' + + with -V/-X/-value, also infer market prices from transactions '--auto' apply automated posting rules to modify transactions. @@ -234,7 +243,7 @@ hledger-web instances behind a reverse proxy that handles authentication for different users. The path can be derived in a predictable way, eg by using the username within the path. As an example, 'nginx' as -reverse proxy can use the variabel '$remote_user' to derive a path from +reverse proxy can use the variable '$remote_user' to derive a path from the username used in a HTTP basic authentication. The following 'proxy_pass' directive allows access to all 'hledger-web' instances that created a socket in '/tmp/hledger/': @@ -564,22 +573,22 @@  Tag Table: Node: Top72 -Node: OPTIONS1746 -Ref: #options1851 -Node: PERMISSIONS8195 -Ref: #permissions8334 -Node: EDITING UPLOADING DOWNLOADING9546 -Ref: #editing-uploading-downloading9727 -Node: RELOADING10561 -Ref: #reloading10695 -Node: JSON API11128 -Ref: #json-api11242 -Node: ENVIRONMENT16723 -Ref: #environment16839 -Node: FILES17572 -Ref: #files17672 -Node: BUGS17885 -Ref: #bugs17963 +Node: OPTIONS1750 +Ref: #options1855 +Node: PERMISSIONS8383 +Ref: #permissions8522 +Node: EDITING UPLOADING DOWNLOADING9734 +Ref: #editing-uploading-downloading9915 +Node: RELOADING10749 +Ref: #reloading10883 +Node: JSON API11316 +Ref: #json-api11430 +Node: ENVIRONMENT16911 +Ref: #environment17027 +Node: FILES17760 +Ref: #files17860 +Node: BUGS18073 +Ref: #bugs18151  End Tag Table diff --git a/embeddedfiles/hledger-web.txt b/embeddedfiles/hledger-web.txt --- a/embeddedfiles/hledger-web.txt +++ b/embeddedfiles/hledger-web.txt @@ -156,13 +156,22 @@ hledger-ui/hledger-web) -B --cost - convert amounts to their cost at transaction time (using the - transaction price, if any) + convert amounts to their cost/selling amount at transaction time - -V --value - convert amounts to their market value on the report end date - (using the most recent applicable market price, if any) + -V --market + convert amounts to their market value in default valuation com- + modities + -X --exchange=COMM + convert amounts to their market value in commodity COMM + + --value + convert amounts to cost or market value, more flexibly than + -B/-V/-X + + --infer-value + with -V/-X/--value, also infer market prices from transactions + --auto apply automated posting rules to modify transactions. --forecast @@ -212,7 +221,7 @@ hledger-web instances behind a reverse proxy that handles authentica- tion for different users. The path can be derived in a predictable way, eg by using the username within the path. As an example, nginx as - reverse proxy can use the variabel $remote_user to derive a path from + reverse proxy can use the variable $remote_user to derive a path from the username used in a HTTP basic authentication. The following proxy_pass directive allows access to all hledger-web instances that created a socket in /tmp/hledger/: @@ -529,4 +538,4 @@ -hledger-web 1.18 June 2020 hledger-web(1) +hledger-web 1.18.1 June 2020 hledger-web(1) diff --git a/embeddedfiles/hledger.1 b/embeddedfiles/hledger.1 --- a/embeddedfiles/hledger.1 +++ b/embeddedfiles/hledger.1 @@ -1,6 +1,6 @@ .\"t -.TH "hledger" "1" "June 2020" "hledger 1.18" "hledger User Manuals" +.TH "hledger" "1" "June 2020" "hledger 1.18.1" "hledger User Manuals" @@ -617,13 +617,20 @@ hledger-ui/hledger-web) .TP \f[B]\f[CB]-B --cost\f[B]\f[R] -convert amounts to their cost at transaction time (using the transaction -price, if any) +convert amounts to their cost/selling amount at transaction time .TP -\f[B]\f[CB]-V --value\f[B]\f[R] -convert amounts to their market value on the report end date (using the -most recent applicable market price, if any) +\f[B]\f[CB]-V --market\f[B]\f[R] +convert amounts to their market value in default valuation commodities .TP +\f[B]\f[CB]-X --exchange=COMM\f[B]\f[R] +convert amounts to their market value in commodity COMM +.TP +\f[B]\f[CB]--value\f[B]\f[R] +convert amounts to cost or market value, more flexibly than -B/-V/-X +.TP +\f[B]\f[CB]--infer-value\f[B]\f[R] +with -V/-X/--value, also infer market prices from transactions +.TP \f[B]\f[CB]--auto\f[B]\f[R] apply automated posting rules to modify transactions. .TP @@ -1671,47 +1678,139 @@ .fi .SS Valuation .PP -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). -.PP -We call this \[dq]valuation\[dq], and it is controlled by the -\f[C]--value=VALUATIONTYPE[,COMMODITY]\f[R] 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: -.IP \[bu] 2 -\f[C]-B\f[R] to convert to cost/sale amount, or -.IP \[bu] 2 -\f[C]-V\f[R] to convert to market value in your base currency. -Or occasionally, -.IP \[bu] 2 -\f[C]-X COMMODITY\f[R] to convert to market value in some other -currency. +Instead of reporting amounts in their original commodity, hledger can +convert them to cost/sale amount (using the conversion rate recorded in +the transaction), or to market value (using some market price on a +certain date). +This is controlled by the \f[C]--value=TYPE[,COMMODITY]\f[R] option, but +we also provide the simpler \f[C]-B\f[R]/\f[C]-V\f[R]/\f[C]-X\f[R] +flags, and usually one of those is all you need. .SS -B: Cost .PP The \f[C]-B/--cost\f[R] flag converts amounts to their cost or sale amount at transaction time, if they have a transaction price specified. -(It is equivalent to \f[C]--value=cost\f[R].) .SS -V: Value .PP -The \f[C]-V/--market\f[R] flag converts reported amounts to market value -in their \f[I]default valuation commodity\f[R], using the market prices -in effect on a \f[I]default valuation date\f[R]. -(More on these below.) +The \f[C]-V/--market\f[R] flag converts amounts to market value in their +default \f[I]valuation commodity\f[R], using the market prices in effect +on the \f[I]valuation date(s)\f[R], if any. +More on these in a minute. +.SS -X: Value in specified commodity .PP -The default valuation commodity is the one referenced in the latest -applicable market price dated on or before the valuation date. -Typically your P declarations or currency exchange transactions -reference a single base currency, and -V will pick that. +The \f[C]-X/--exchange=COMM\f[R] option is like \f[C]-V\f[R], except you +tell it which currency you want to convert to, and it tries to convert +everything to that. +.SS Valuation date .PP -The default valuation date is today for single period reports -(equivalent to \f[C]--value=now\f[R]), or the last day of each subperiod -for multiperiod reports (equivalent to \f[C]--value=end\f[R]). +Since market prices can change from day to day, market value reports +have a valuation date (or more than one), which determines which market +prices will be used. .PP -An example: +For single period reports, if an explicit report end date is specified, +that will be used as the valuation date; otherwise the valuation date is +\[dq]today\[dq]. +.PP +For multiperiod reports, each column/period is valued on the last day of +the period. +.SS Market prices +.PP +\f[I](experimental)\f[R] +.PP +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 : +.IP "1." 3 +A \f[I]declared market price\f[R] or \f[I]inferred market price\f[R]: +A\[aq]s latest market price in B on or before the valuation date as +declared by a P directive, or (if the \f[C]--infer-value\f[R] flag is +used) inferred from transaction prices. +.IP "2." 3 +A \f[I]reverse market price\f[R]: the inverse of a declared or inferred +market price from B to A. +.IP "3." 3 +A \f[I]chained market price\f[R]: a synthetic price formed by combining +the shortest chain of market prices (any of the above types) leading +from A to B. +.PP +Amounts for which no applicable market price can be found, are not +converted. +.SS --infer-value: market prices from transactions +.PP +\f[I](experimental)\f[R] +.PP +Normally, market value in hledger is fully controlled by, and requires, +P directives 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 as additional market prices (as Ledger does) ? +We could produce value reports without needing P directives at all. +.PP +Adding the \f[C]--infer-value\f[R] flag to \f[C]-V\f[R], \f[C]-X\f[R] or +\f[C]--value\f[R] enables this. +So for example, \f[C]hledger bs -V --infer-value\f[R] will get market +prices both from P directives and from transactions. +.PP +There is a downside: value reports can sometimes be affected in +confusing/undesired ways by your journal entries. +If this happens to you, read all of this Valuation section carefully, +and try adding \f[C]--debug\f[R] or \f[C]--debug=2\f[R] to troubleshoot. +.PP +\f[C]--infer-value\f[R] can infer market prices from: +.IP \[bu] 2 +multicommodity transactions with explicit prices +(\f[C]\[at]\f[R]/\f[C]\[at]\[at]\f[R]) +.IP \[bu] 2 +multicommodity transactions with implicit prices (no \f[C]\[at]\f[R], +two commodities, unbalanced). +(With these, the order of postings matters. +\f[C]hledger print -x\f[R] can be useful for troubleshooting.) +.IP \[bu] 2 +but not, currently, from \[dq]more correct\[dq] multicommodity +transactions (no \f[C]\[at]\f[R], multiple commodities, balanced). +.SS Valuation commodity +.PP +\f[I](experimental)\f[R] +.PP +\f[B]When you specify a valuation commodity (\f[CB]-X COMM\f[B] or +\f[CB]--value TYPE,COMM\f[B]):\f[R] +.PD 0 +.P +.PD +hledger will convert all amounts to COMM, wherever it can find a +suitable market price (including by reversing or chaining prices). +.PP +\f[B]When you leave the valuation commodity unspecified (\f[CB]-V\f[B] +or \f[CB]--value TYPE\f[B]):\f[R] +.PD 0 +.P +.PD +For each commodity A, hledger picks a default valuation commodity as +follows, in this order of preference: +.IP "1." 3 +The price commodity from the latest P-declared market price for A on or +before valuation date. +.IP "2." 3 +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.) +.IP "3." 3 +If there are no P directives at all (any commodity or date) and the +\f[C]--infer-value\f[R] flag is used: the price commodity from the +latest transaction-inferred price for A on or before valuation date. +.PP +This means: +.IP \[bu] 2 +If you have P directives, they determine which commodities \f[C]-V\f[R] +will convert, and to what. +.IP \[bu] 2 +If you have no P directives, and use the \f[C]--infer-value\f[R] flag, +transaction prices determine it. +.PP +Amounts for which no valuation commodity can be found are not converted. +.SS Simple valuation examples +.PP +Here are some quick examples of \f[C]-V\f[R]: .IP .nf \f[C] @@ -1755,39 +1854,8 @@ $103.00 assets:euros \f[R] .fi -.SS -X: Market value in specified commodity -.PP -The \f[C]-X/--exchange\f[R] option is like \f[C]-V\f[R], except it -specifies the target commodity you would like to convert to. -(It is equivalent to \f[C]--value=now,COMM\f[R] or -\f[C]--value=end,COMM\f[R].) -.SS Market prices -.PP -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: -.IP "1." 3 -a \f[I]declared market price\f[R] - the latest P directive specifying -the exchange rate from A to B, dated on or before the valuation date. -.IP "2." 3 -a \f[I]transaction-implied market price\f[R] - a market price matching -the transaction price used in the latest transaction where A is -converted to B, dated on or before the valuation date. -(\f[I]since hledger 1.18; experimental\f[R]) -.IP "3." 3 -a \f[I]reverse declared market price\f[R] - calculated by inverting a -declared market price from B to A. -.IP "4." 3 -a \f[I]reverse transaction-implied market price\f[R] - calculated by -inverting a transaction-implied market price from B to A. -.IP "5." 3 -an \f[I]indirect market price\f[R] - calculated by combining the -shortest chain of market prices (any of the above types) leading from A -to B. .SS --value: Flexible valuation .PP -\f[I](experimental, added 201905)\f[R] -.PP \f[C]-B\f[R], \f[C]-V\f[R] and \f[C]-X\f[R] are special cases of the more general \f[C]--value\f[R] option: .IP @@ -1804,52 +1872,38 @@ \f[R] .fi .PP -The TYPE part basically selects either \[dq]cost\[dq], or \[dq]market -value\[dq] plus a valuation date: +The TYPE part selects cost or value and valuation date: .TP \f[B]\f[CB]--value=cost\f[B]\f[R] Convert amounts to cost, using the prices recorded in transactions. .TP \f[B]\f[CB]--value=then\f[B]\f[R] -Convert amounts to their value in a default valuation commodity, using +Convert amounts to their value in the default valuation commodity, using market prices on each posting\[aq]s date. This is currently supported only by the print and register commands. .TP \f[B]\f[CB]--value=end\f[B]\f[R] -Convert amounts to their value in a default valuation commodity, using +Convert amounts to their value in the default valuation commodity, using market prices on the last day of the report period (or if unspecified, the journal\[aq]s end date); or in multiperiod reports, market prices on the last day of each subperiod. .TP \f[B]\f[CB]--value=now\f[B]\f[R] -Convert amounts to their value in default valuation commodity using +Convert amounts to their value in the default valuation commodity using current market prices (as of when report is generated). .TP \f[B]\f[CB]--value=YYYY-MM-DD\f[B]\f[R] -Convert amounts to their value in default valuation commodity using +Convert amounts to their value in the default valuation commodity using market prices on this date. .PP -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, this -will usually do what you want. -.PP To select a different valuation commodity, add the optional \f[C],COMM\f[R] part: a comma, then the target commodity\[aq]s symbol. Eg: \f[B]\f[CB]--value=now,EUR\f[B]\f[R]. -hledger will do its best to convert amounts to this commodity, using: -.IP \[bu] 2 -declared prices (from source commodity to valuation commodity) -.IP \[bu] 2 -reverse prices (declared prices from valuation to source commodity, -inverted) -.IP \[bu] 2 -indirect prices (prices calculated from the shortest chain of declared -or reverse prices from source to valuation commodity) -.PP -in that order. +hledger will do its best to convert amounts to this commodity, deducing +market prices as described above. +.SS More valuation examples .PP -Here are some examples showing the effect of \f[C]--value\f[R] as seen +Here are some examples showing the effect of \f[C]--value\f[R], as seen with \f[C]print\f[R]: .IP .nf @@ -1997,13 +2051,12 @@ b -0.50A \f[R] .fi -.SS Effect of --value on reports +.SS Effect of valuation on reports .PP -Here is a reference for how \f[C]--value\f[R] currently affects each -part of hledger\[aq]s reports. -It\[aq]s work in progress, but may be useful for troubleshooting or -reporting bugs. -See also the definitions and notes below. +Here is a reference for how valuation is supposed to affect each part of +hledger\[aq]s reports (and a glossary). +(It\[aq]s wide, you\[aq]ll have to scroll sideways.) It may be useful +when troubleshooting. If you find problems, please report them, ideally with a reproducible example. Related: #329, #1083. @@ -2254,7 +2307,7 @@ T} .TE .PP -\f[B]Additional notes\f[R] +\f[B]Glossary:\f[R] .TP \f[I]cost\f[R] calculated using price(s) recorded in the transaction(s). diff --git a/embeddedfiles/hledger.info b/embeddedfiles/hledger.info --- a/embeddedfiles/hledger.info +++ b/embeddedfiles/hledger.info @@ -3,8 +3,8 @@  File: hledger.info, Node: Top, Next: COMMON TASKS, Up: (dir) -hledger(1) hledger 1.18 -*********************** +hledger(1) hledger 1.18.1 +************************* hledger - a command-line accounting tool @@ -610,12 +610,21 @@ hledger-ui/hledger-web) '-B --cost' - convert amounts to their cost at transaction time (using the - transaction price, if any) -'-V --value' + convert amounts to their cost/selling amount at transaction time +'-V --market' - convert amounts to their market value on the report end date (using - the most recent applicable market price, if any) + convert amounts to their market value in default valuation + commodities +'-X --exchange=COMM' + + convert amounts to their market value in commodity COMM +'--value' + + convert amounts to cost or market value, more flexibly than + -B/-V/-X +'--infer-value' + + with -V/-X/-value, also infer market prices from transactions '--auto' apply automated posting rules to modify transactions. @@ -1363,30 +1372,26 @@ 2.17 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. +Instead of reporting amounts in their original commodity, hledger can +convert them to cost/sale amount (using the conversion rate recorded in +the transaction), or to market value (using some market price on a +certain date). This is controlled by the '--value=TYPE[,COMMODITY]' +option, but we also provide the simpler '-B'/'-V'/'-X' flags, and +usually one of those is all you need. * Menu: * -B Cost:: * -V Value:: -* -X Market value in specified commodity:: +* -X Value in specified commodity:: +* Valuation date:: * Market prices:: +* --infer-value market prices from transactions:: +* Valuation commodity:: +* Simple valuation examples:: * --value Flexible valuation:: -* Effect of --value on reports:: +* More valuation examples:: +* Effect of valuation on reports::  File: hledger.info, Node: -B Cost, Next: -V Value, Up: Valuation @@ -1395,30 +1400,155 @@ --------------- The '-B/--cost' flag converts amounts to their cost or sale amount at -transaction time, if they have a transaction price specified. (It is -equivalent to '--value=cost'.) +transaction time, if they have a transaction price specified.  -File: hledger.info, Node: -V Value, Next: -X Market value in specified commodity, Prev: -B Cost, Up: Valuation +File: hledger.info, Node: -V Value, Next: -X Value in specified commodity, Prev: -B Cost, Up: Valuation 2.17.2 -V: Value ---------------- -The '-V/--market' flag converts reported amounts to market value in -their _default valuation commodity_, using the market prices in effect -on a _default valuation date_. (More on these below.) +The '-V/--market' flag converts amounts to market value in their default +_valuation commodity_, using the market prices in effect on the +_valuation date(s)_, if any. More on these in a minute. - The default valuation commodity is the one referenced in the latest -applicable market price dated on or before the valuation date. -Typically your P declarations or currency exchange transactions -reference a single base currency, and -V will pick that. + +File: hledger.info, Node: -X Value in specified commodity, Next: Valuation date, Prev: -V Value, Up: Valuation - The default valuation date is today for single period reports -(equivalent to '--value=now'), or the last day of each subperiod for -multiperiod reports (equivalent to '--value=end'). +2.17.3 -X: Value in specified commodity +--------------------------------------- - An example: +The '-X/--exchange=COMM' option is like '-V', except you tell it which +currency you want to convert to, and it tries to convert everything to +that. + +File: hledger.info, Node: Valuation date, Next: Market prices, Prev: -X Value in specified commodity, Up: Valuation + +2.17.4 Valuation date +--------------------- + +Since market prices can change from day to day, market value reports +have a valuation date (or more than one), which determines which market +prices will be used. + + For single period reports, if an explicit report end date is +specified, that will be used as the valuation date; otherwise the +valuation date is "today". + + For multiperiod reports, each column/period is valued on the last day +of the period. + + +File: hledger.info, Node: Market prices, Next: --infer-value market prices from transactions, Prev: Valuation date, Up: Valuation + +2.17.5 Market prices +-------------------- + +_(experimental)_ + + 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 : + + 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, or (if the '--infer-value' flag is used) inferred from + transaction prices. + + 2. A _reverse market price_: the inverse of a declared or inferred + market price from B to A. + + 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. + + Amounts for which no applicable market price can be found, are not +converted. + + +File: hledger.info, Node: --infer-value market prices from transactions, Next: Valuation commodity, Prev: Market prices, Up: Valuation + +2.17.6 -infer-value: market prices from transactions +---------------------------------------------------- + +_(experimental)_ + + Normally, market value in hledger is fully controlled by, and +requires, P directives 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 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: value reports can sometimes be affected in +confusing/undesired ways by your journal entries. If this happens to +you, read all of this Valuation section carefully, and try adding +'--debug' or '--debug=2' to troubleshoot. + + '--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" multicommodity transactions + (no '@', multiple commodities, balanced). + + +File: hledger.info, Node: Valuation commodity, Next: Simple valuation examples, Prev: --infer-value market prices from transactions, Up: Valuation + +2.17.7 Valuation commodity +-------------------------- + +_(experimental)_ + + *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). + + *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: + + 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. + + This means: + + * If you have P directives, they determine which commodities '-V' + will convert, and to what. + + * If you have no P directives, and use the '--infer-value' flag, + transaction prices determine it. + + Amounts for which no valuation commodity can be found are not +converted. + + +File: hledger.info, Node: Simple valuation examples, Next: --value Flexible valuation, Prev: Valuation commodity, Up: Valuation + +2.17.8 Simple valuation examples +-------------------------------- + +Here are some quick examples of '-V': + ; one euro is worth this many dollars from nov 1 P 2016/11/01 € $1.10 @@ -1447,52 +1577,12 @@ $103.00 assets:euros  -File: hledger.info, Node: -X Market value in specified commodity, Next: Market prices, Prev: -V Value, Up: Valuation - -2.17.3 -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'.) - - -File: hledger.info, Node: Market prices, Next: --value Flexible valuation, Prev: -X Market value in specified commodity, Up: Valuation - -2.17.4 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 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 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. - - -File: hledger.info, Node: --value Flexible valuation, Next: Effect of --value on reports, Prev: Market prices, Up: Valuation +File: hledger.info, Node: --value Flexible valuation, Next: More valuation examples, Prev: Simple valuation examples, Up: Valuation -2.17.5 -value: Flexible valuation +2.17.9 -value: Flexible valuation --------------------------------- -_(experimental, added 201905)_ - - '-B', '-V' and '-X' are special cases of the more general '--value' +'-B', '-V' and '-X' are special cases of the more general '--value' option: --value=TYPE[,COMM] TYPE is cost, then, end, now or YYYY-MM-DD. @@ -1504,51 +1594,43 @@ - default valuation commodity (or COMM) using current market prices - default valuation commodity (or COMM) using market prices at some date - The TYPE part basically selects either "cost", or "market value" plus -a valuation date: + The TYPE part selects cost or value and valuation date: '--value=cost' Convert amounts to cost, using the prices recorded in transactions. '--value=then' - Convert amounts to their value in a default valuation commodity, + Convert amounts to their value in the default valuation commodity, using market prices on each posting's date. This is currently supported only by the print and register commands. '--value=end' - Convert amounts to their value in a default valuation commodity, + Convert amounts to their value in the default valuation commodity, using market prices on the last day of the report period (or if unspecified, the journal's end date); or in multiperiod reports, market prices on the last day of each subperiod. '--value=now' - Convert amounts to their value in default valuation commodity using - current market prices (as of when report is generated). + Convert amounts to their value in the default valuation commodity + using current market prices (as of when report is generated). '--value=YYYY-MM-DD' - Convert amounts to their value in default valuation commodity using - market prices on this date. - - 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, this will usually do what -you want. + Convert amounts to their value in the default valuation commodity + using market prices on this date. To select a different valuation commodity, add the optional ',COMM' part: a comma, then the target commodity's symbol. Eg: *'--value=now,EUR'*. hledger will do its best to convert amounts to -this commodity, using: +this commodity, deducing market prices as described above. - * declared prices (from source commodity to valuation commodity) - * reverse prices (declared prices from valuation to source commodity, - inverted) - * indirect prices (prices calculated from the shortest chain of - declared or reverse prices from source to valuation commodity) + +File: hledger.info, Node: More valuation examples, Next: Effect of valuation on reports, Prev: --value Flexible valuation, Up: Valuation - in that order. +2.17.10 More valuation examples +------------------------------- - Here are some examples showing the effect of '--value' as seen with +Here are some examples showing the effect of '--value', as seen with 'print': P 2000-01-01 A 1 B @@ -1657,16 +1739,16 @@ b -0.50A  -File: hledger.info, Node: Effect of --value on reports, Prev: --value Flexible valuation, Up: Valuation +File: hledger.info, Node: Effect of valuation on reports, Prev: More valuation examples, Up: Valuation -2.17.6 Effect of -value on reports ----------------------------------- +2.17.11 Effect of valuation on reports +-------------------------------------- -Here is a reference for how '--value' currently affects each part of -hledger's reports. It's work in progress, but may be useful for -troubleshooting or reporting bugs. See also the definitions and notes -below. If you find problems, please report them, ideally with a -reproducible example. Related: #329, #1083. +Here is a reference for how valuation is supposed to affect each part of +hledger's reports (and a glossary). (It's wide, you'll have to scroll +sideways.) It may be useful when troubleshooting. If you find +problems, please report them, ideally with a reproducible example. +Related: #329, #1083. Report '-B', '-V', '-X' '--value=then' '--value=end' '--value=DATE', type '--value=cost' '--value=now' @@ -1739,7 +1821,7 @@ totals totals totals column totals - *Additional notes* + *Glossary:* _cost_ @@ -3776,187 +3858,197 @@  Tag Table: Node: Top68 -Node: COMMON TASKS2315 -Ref: #common-tasks2427 -Node: Getting help2834 -Ref: #getting-help2966 -Node: Constructing command lines3519 -Ref: #constructing-command-lines3711 -Node: Starting a journal file4408 -Ref: #starting-a-journal-file4606 -Node: Setting opening balances5794 -Ref: #setting-opening-balances5990 -Node: Recording transactions9131 -Ref: #recording-transactions9311 -Node: Reconciling9867 -Ref: #reconciling10010 -Node: Reporting12267 -Ref: #reporting12407 -Node: Migrating to a new file16406 -Ref: #migrating-to-a-new-file16554 -Node: OPTIONS16853 -Ref: #options16960 -Node: General options17330 -Ref: #general-options17455 -Node: Command options20225 -Ref: #command-options20376 -Node: Command arguments20774 -Ref: #command-arguments20921 -Node: Queries21801 -Ref: #queries21956 -Node: Special characters in arguments and queries25918 -Ref: #special-characters-in-arguments-and-queries26146 -Node: More escaping26597 -Ref: #more-escaping26759 -Node: Even more escaping27055 -Ref: #even-more-escaping27249 -Node: Less escaping27920 -Ref: #less-escaping28082 -Node: Unicode characters28327 -Ref: #unicode-characters28509 -Node: Input files29921 -Ref: #input-files30064 -Node: Output destination31993 -Ref: #output-destination32145 -Node: Output format32570 -Ref: #output-format32720 -Node: Regular expressions34302 -Ref: #regular-expressions34459 -Node: Smart dates36195 -Ref: #smart-dates36346 -Node: Report start & end date37707 -Ref: #report-start-end-date37879 -Node: Report intervals39376 -Ref: #report-intervals39541 -Node: Period expressions39931 -Ref: #period-expressions40091 -Node: Depth limiting44227 -Ref: #depth-limiting44371 -Node: Pivoting44703 -Ref: #pivoting44826 -Node: Valuation46502 -Ref: #valuation46604 -Node: -B Cost47524 -Ref: #b-cost47628 -Node: -V Value47800 -Ref: #v-value47953 -Node: -X Market value in specified commodity49226 -Ref: #x-market-value-in-specified-commodity49445 -Node: Market prices49623 -Ref: #market-prices49808 -Node: --value Flexible valuation50733 -Ref: #value-flexible-valuation50934 -Node: Effect of --value on reports55439 -Ref: #effect-of---value-on-reports55620 -Node: COMMANDS61166 -Ref: #commands61274 -Node: accounts62358 -Ref: #accounts62456 -Node: activity63155 -Ref: #activity63265 -Node: add63648 -Ref: #add63747 -Node: balance66486 -Ref: #balance66597 -Node: Classic balance report68055 -Ref: #classic-balance-report68228 -Node: Customising the classic balance report69597 -Ref: #customising-the-classic-balance-report69825 -Node: Colour support71901 -Ref: #colour-support72068 -Node: Flat mode72241 -Ref: #flat-mode72389 -Node: Depth limited balance reports72802 -Ref: #depth-limited-balance-reports72987 -Node: Percentages73443 -Ref: #percentages73609 -Node: Multicolumn balance report74746 -Ref: #multicolumn-balance-report74926 -Node: Budget report80188 -Ref: #budget-report80331 -Node: Nested budgets85597 -Ref: #nested-budgets85709 -Ref: #output-format-189190 -Node: balancesheet89387 -Ref: #balancesheet89523 -Node: balancesheetequity90989 -Ref: #balancesheetequity91138 -Node: cashflow91861 -Ref: #cashflow91989 -Node: check-dates93168 -Ref: #check-dates93295 -Node: check-dupes93574 -Ref: #check-dupes93698 -Node: close93991 -Ref: #close94105 -Node: close usage95627 -Ref: #close-usage95720 -Node: commodities98533 -Ref: #commodities98660 -Node: descriptions98742 -Ref: #descriptions98870 -Node: diff99051 -Ref: #diff99157 -Node: files100204 -Ref: #files100304 -Node: help100451 -Ref: #help100551 -Node: import101632 -Ref: #import101746 -Node: Importing balance assignments102639 -Ref: #importing-balance-assignments102787 -Node: incomestatement103436 -Ref: #incomestatement103569 -Node: notes105056 -Ref: #notes105169 -Node: payees105295 -Ref: #payees105401 -Node: prices105559 -Ref: #prices105665 -Node: print106006 -Ref: #print106116 -Node: print-unique110902 -Ref: #print-unique111028 -Node: register111313 -Ref: #register111440 -Node: Custom register output115612 -Ref: #custom-register-output115741 -Node: register-match117078 -Ref: #register-match117212 -Node: rewrite117563 -Ref: #rewrite117678 -Node: Re-write rules in a file119533 -Ref: #re-write-rules-in-a-file119667 -Node: Diff output format120877 -Ref: #diff-output-format121046 -Node: rewrite vs print --auto122138 -Ref: #rewrite-vs.-print---auto122317 -Node: roi122873 -Ref: #roi122971 -Node: stats123983 -Ref: #stats124082 -Node: tags124870 -Ref: #tags124968 -Node: test125262 -Ref: #test125370 -Node: Add-on commands126117 -Ref: #add-on-commands126234 -Node: ui127577 -Ref: #ui127665 -Node: web127719 -Ref: #web127822 -Node: iadd127938 -Ref: #iadd128049 -Node: interest128131 -Ref: #interest128238 -Node: ENVIRONMENT128478 -Ref: #environment128590 -Node: FILES129419 -Ref: #files-1129522 -Node: LIMITATIONS129735 -Ref: #limitations129854 -Node: TROUBLESHOOTING130596 -Ref: #troubleshooting130709 +Node: COMMON TASKS2319 +Ref: #common-tasks2431 +Node: Getting help2838 +Ref: #getting-help2970 +Node: Constructing command lines3523 +Ref: #constructing-command-lines3715 +Node: Starting a journal file4412 +Ref: #starting-a-journal-file4610 +Node: Setting opening balances5798 +Ref: #setting-opening-balances5994 +Node: Recording transactions9135 +Ref: #recording-transactions9315 +Node: Reconciling9871 +Ref: #reconciling10014 +Node: Reporting12271 +Ref: #reporting12411 +Node: Migrating to a new file16410 +Ref: #migrating-to-a-new-file16558 +Node: OPTIONS16857 +Ref: #options16964 +Node: General options17334 +Ref: #general-options17459 +Node: Command options20413 +Ref: #command-options20564 +Node: Command arguments20962 +Ref: #command-arguments21109 +Node: Queries21989 +Ref: #queries22144 +Node: Special characters in arguments and queries26106 +Ref: #special-characters-in-arguments-and-queries26334 +Node: More escaping26785 +Ref: #more-escaping26947 +Node: Even more escaping27243 +Ref: #even-more-escaping27437 +Node: Less escaping28108 +Ref: #less-escaping28270 +Node: Unicode characters28515 +Ref: #unicode-characters28697 +Node: Input files30109 +Ref: #input-files30252 +Node: Output destination32181 +Ref: #output-destination32333 +Node: Output format32758 +Ref: #output-format32908 +Node: Regular expressions34490 +Ref: #regular-expressions34647 +Node: Smart dates36383 +Ref: #smart-dates36534 +Node: Report start & end date37895 +Ref: #report-start-end-date38067 +Node: Report intervals39564 +Ref: #report-intervals39729 +Node: Period expressions40119 +Ref: #period-expressions40279 +Node: Depth limiting44415 +Ref: #depth-limiting44559 +Node: Pivoting44891 +Ref: #pivoting45014 +Node: Valuation46690 +Ref: #valuation46792 +Node: -B Cost47481 +Ref: #b-cost47585 +Node: -V Value47718 +Ref: #v-value47864 +Node: -X Value in specified commodity48059 +Ref: #x-value-in-specified-commodity48258 +Node: Valuation date48407 +Ref: #valuation-date48575 +Node: Market prices48985 +Ref: #market-prices49165 +Node: --infer-value market prices from transactions49942 +Ref: #infer-value-market-prices-from-transactions50191 +Node: Valuation commodity51473 +Ref: #valuation-commodity51682 +Node: Simple valuation examples52908 +Ref: #simple-valuation-examples53110 +Node: --value Flexible valuation53769 +Ref: #value-flexible-valuation53977 +Node: More valuation examples55924 +Ref: #more-valuation-examples56133 +Node: Effect of valuation on reports58138 +Ref: #effect-of-valuation-on-reports58326 +Node: COMMANDS63847 +Ref: #commands63955 +Node: accounts65039 +Ref: #accounts65137 +Node: activity65836 +Ref: #activity65946 +Node: add66329 +Ref: #add66428 +Node: balance69167 +Ref: #balance69278 +Node: Classic balance report70736 +Ref: #classic-balance-report70909 +Node: Customising the classic balance report72278 +Ref: #customising-the-classic-balance-report72506 +Node: Colour support74582 +Ref: #colour-support74749 +Node: Flat mode74922 +Ref: #flat-mode75070 +Node: Depth limited balance reports75483 +Ref: #depth-limited-balance-reports75668 +Node: Percentages76124 +Ref: #percentages76290 +Node: Multicolumn balance report77427 +Ref: #multicolumn-balance-report77607 +Node: Budget report82869 +Ref: #budget-report83012 +Node: Nested budgets88278 +Ref: #nested-budgets88390 +Ref: #output-format-191871 +Node: balancesheet92068 +Ref: #balancesheet92204 +Node: balancesheetequity93670 +Ref: #balancesheetequity93819 +Node: cashflow94542 +Ref: #cashflow94670 +Node: check-dates95849 +Ref: #check-dates95976 +Node: check-dupes96255 +Ref: #check-dupes96379 +Node: close96672 +Ref: #close96786 +Node: close usage98308 +Ref: #close-usage98401 +Node: commodities101214 +Ref: #commodities101341 +Node: descriptions101423 +Ref: #descriptions101551 +Node: diff101732 +Ref: #diff101838 +Node: files102885 +Ref: #files102985 +Node: help103132 +Ref: #help103232 +Node: import104313 +Ref: #import104427 +Node: Importing balance assignments105320 +Ref: #importing-balance-assignments105468 +Node: incomestatement106117 +Ref: #incomestatement106250 +Node: notes107737 +Ref: #notes107850 +Node: payees107976 +Ref: #payees108082 +Node: prices108240 +Ref: #prices108346 +Node: print108687 +Ref: #print108797 +Node: print-unique113583 +Ref: #print-unique113709 +Node: register113994 +Ref: #register114121 +Node: Custom register output118293 +Ref: #custom-register-output118422 +Node: register-match119759 +Ref: #register-match119893 +Node: rewrite120244 +Ref: #rewrite120359 +Node: Re-write rules in a file122214 +Ref: #re-write-rules-in-a-file122348 +Node: Diff output format123558 +Ref: #diff-output-format123727 +Node: rewrite vs print --auto124819 +Ref: #rewrite-vs.-print---auto124998 +Node: roi125554 +Ref: #roi125652 +Node: stats126664 +Ref: #stats126763 +Node: tags127551 +Ref: #tags127649 +Node: test127943 +Ref: #test128051 +Node: Add-on commands128798 +Ref: #add-on-commands128915 +Node: ui130258 +Ref: #ui130346 +Node: web130400 +Ref: #web130503 +Node: iadd130619 +Ref: #iadd130730 +Node: interest130812 +Ref: #interest130919 +Node: ENVIRONMENT131159 +Ref: #environment131271 +Node: FILES132100 +Ref: #files-1132203 +Node: LIMITATIONS132416 +Ref: #limitations132535 +Node: TROUBLESHOOTING133277 +Ref: #troubleshooting133390  End Tag Table diff --git a/embeddedfiles/hledger.txt b/embeddedfiles/hledger.txt --- a/embeddedfiles/hledger.txt +++ b/embeddedfiles/hledger.txt @@ -515,13 +515,22 @@ hledger-ui/hledger-web) -B --cost - convert amounts to their cost at transaction time (using the - transaction price, if any) + convert amounts to their cost/selling amount at transaction time - -V --value - convert amounts to their market value on the report end date - (using the most recent applicable market price, if any) + -V --market + convert amounts to their market value in default valuation com- + modities + -X --exchange=COMM + convert amounts to their market value in commodity COMM + + --value + convert amounts to cost or market value, more flexibly than + -B/-V/-X + + --infer-value + with -V/-X/--value, also infer market prices from transactions + --auto apply automated posting rules to modify transactions. --forecast @@ -934,7 +943,6 @@ 2004/10/1, 2004-01-01, exact date, several separators allowed. Year 2004.9.1 is 4+ digits, month is 1-12, day is 1-31 2004 start of year - 2004/10 start of month 10/1 month and day in current year 21 day in current month @@ -1067,6 +1075,8 @@ -p "weekly from 2009/1/1 starts on 2008/12/29, closest preceding Mon- to 2009/4/1" day + + -p "monthly in starts on 2018/11/01 2008/11/25" -p "quarterly from starts on 2009/04/01, ends on 2009/06/30, @@ -1179,45 +1189,128 @@ -2 EUR 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/commod- - ity at a specified date (using market prices inferred from your trans- - actions, or declared with P directives). + Instead of reporting amounts in their original commodity, hledger can + convert them to cost/sale amount (using the conversion rate recorded in + the transaction), or to market value (using some market price on a cer- + tain date). This is controlled by the --value=TYPE[,COMMODITY] option, + but we also provide the simpler -B/-V/-X flags, and usually one of + those is all you need. - We call this "valuation", and it is controlled by the --value=VALUA- - TIONTYPE[,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: Cost + The -B/--cost flag converts amounts to their cost or sale amount at + transaction time, if they have a transaction price specified. - o -B to convert to cost/sale amount, or + -V: Value + The -V/--market flag converts amounts to market value in their default + valuation commodity, using the market prices in effect on the valuation + date(s), if any. More on these in a minute. - o -V to convert to market value in your base currency. Or occasion- - ally, + -X: Value in specified commodity + The -X/--exchange=COMM option is like -V, except you tell it which cur- + rency you want to convert to, and it tries to convert everything to + that. - o -X COMMODITY to convert to market value in some other currency. + Valuation date + Since market prices can change from day to day, market value reports + have a valuation date (or more than one), which determines which market + prices will be used. - -B: Cost - The -B/--cost flag converts amounts to their cost or sale amount at - transaction time, if they have a transaction price specified. (It is - equivalent to --value=cost.) + For single period reports, if an explicit report end date is specified, + that will be used as the valuation date; otherwise the valuation date + is "today". - -V: Value - The -V/--market flag converts reported amounts to market value in their - default valuation commodity, using the market prices in effect on a de- - fault valuation date. (More on these below.) + For multiperiod reports, each column/period is valued on the last day + of the period. - The default valuation commodity is the one referenced in the latest ap- - plicable market price dated on or before the valuation date. Typically - your P declarations or currency exchange transactions reference a sin- - gle base currency, and -V will pick that. + Market prices + (experimental) - The default valuation date is today for single period reports (equiva- - lent to --value=now), or the last day of each subperiod for multiperiod - reports (equivalent to --value=end). + 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 : - An example: + 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 direc- + tive, or (if the --infer-value flag is used) inferred from transac- + tion prices. + 2. A reverse market price: the inverse of a declared or inferred market + price from B to A. + + 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. + + Amounts for which no applicable market price can be found, are not con- + verted. + + --infer-value: market prices from transactions + (experimental) + + Normally, market value in hledger is fully controlled by, and requires, + P directives 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 as additional market + prices (as Ledger does) ? We could produce value reports without need- + ing 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: value reports can sometimes be affected in confus- + ing/undesired ways by your journal entries. If this happens to you, + read all of this Valuation section carefully, and try adding --debug or + --debug=2 to troubleshoot. + + --infer-value can infer market prices from: + + o multicommodity transactions with explicit prices (@/@@) + + o multicommodity transactions with implicit prices (no @, two commodi- + ties, unbalanced). (With these, the order of postings matters. + hledger print -x can be useful for troubleshooting.) + + o but not, currently, from "more correct" multicommodity transactions + (no @, multiple commodities, balanced). + + Valuation commodity + (experimental) + + When you specify a valuation commodity (-X COMM or --value TYPE,COMM): + hledger will convert all amounts to COMM, wherever it can find a suit- + able market price (including by reversing or chaining prices). + + 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: + + 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. + + This means: + + o If you have P directives, they determine which commodities -V will + convert, and to what. + + o If you have no P directives, and use the --infer-value flag, transac- + tion prices determine it. + + Amounts for which no valuation commodity can be found are not con- + verted. + + Simple valuation examples + Here are some quick examples of -V: + ; one euro is worth this many dollars from nov 1 P 2016/11/01 EUR $1.10 @@ -1239,42 +1332,13 @@ $ hledger -f t.j bal -N euros -V -e 2016/11/4 $110.00 assets:euros - What are they worth after 2016/12/21 ? (no report end date specified, + What are they worth after 2016/12/21 ? (no report end date specified, defaults to today) $ hledger -f t.j bal -N euros -V $103.00 assets:euros - -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.) - - 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 specifying the ex- - change 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 used in the latest transaction where A is con- - verted 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 - (experimental, added 201905) - -B, -V and -X are special cases of the more general --value option: --value=TYPE[,COMM] TYPE is cost, then, end, now or YYYY-MM-DD. @@ -1286,52 +1350,39 @@ - default valuation commodity (or COMM) using current market prices - default valuation commodity (or COMM) using market prices at some date - The TYPE part basically selects either "cost", or "market value" plus a - valuation date: + The TYPE part selects cost or value and valuation date: --value=cost - Convert amounts to cost, using the prices recorded in transac- + Convert amounts to cost, using the prices recorded in transac- tions. --value=then - Convert amounts to their value in a default valuation commodity, - using market prices on each posting's date. This is currently - supported only by the print and register commands. + Convert amounts to their value in the default valuation commod- + ity, using market prices on each posting's date. This is cur- + rently supported only by the print and register commands. --value=end - Convert amounts to their value in a default valuation commodity, - using market prices on the last day of the report period (or if - unspecified, the journal's end date); or in multiperiod reports, - market prices on the last day of each subperiod. + Convert amounts to their value in the default valuation commod- + ity, using market prices on the last day of the report period + (or if unspecified, the journal's end date); or in multiperiod + reports, market prices on the last day of each subperiod. --value=now - Convert amounts to their value in default valuation commodity - using current market prices (as of when report is generated). + Convert amounts to their value in the default valuation commod- + ity using current market prices (as of when report is gener- + ated). --value=YYYY-MM-DD - Convert amounts to their value in default valuation commodity - using market prices on this date. - - The default valuation commodity is the commodity mentioned in the most - recent applicable market price declaration. When all your price decla- - rations lead to a single home currency, this will usually do what you - want. + Convert amounts to their value in the default valuation commod- + ity using market prices on this date. To select a different valuation commodity, add the optional ,COMM part: - a comma, then the target commodity's symbol. Eg: --value=now,EUR. - hledger will do its best to convert amounts to this commodity, using: - - o declared prices (from source commodity to valuation commodity) - - o reverse prices (declared prices from valuation to source commodity, - inverted) - - o indirect prices (prices calculated from the shortest chain of de- - clared or reverse prices from source to valuation commodity) - - in that order. + a comma, then the target commodity's symbol. Eg: --value=now,EUR. + hledger will do its best to convert amounts to this commodity, deducing + market prices as described above. - Here are some examples showing the effect of --value as seen with + More valuation examples + Here are some examples showing the effect of --value, as seen with print: P 2000-01-01 A 1 B @@ -1438,12 +1489,12 @@ a 0.50A b -0.50A - Effect of --value on reports - Here is a reference for how --value currently affects each part of - hledger's reports. It's work in progress, but may be useful for trou- - bleshooting or reporting bugs. See also the definitions and notes be- - low. If you find problems, please report them, ideally with a repro- - ducible example. Related: #329, #1083. + Effect of valuation on reports + Here is a reference for how valuation is supposed to affect each part + of hledger's reports (and a glossary). (It's wide, you'll have to + scroll sideways.) It may be useful when troubleshooting. If you find + problems, please report them, ideally with a reproducible example. Re- + lated: #329, #1083. Report type -B, -V, -X --value=then --value=end --value=DATE, --value=cost --value=now @@ -1492,9 +1543,6 @@ (with report postings be- fore report fore report report start interval and fore report start start -H) start - - - budget like bal- like bal- not supported like bal- like balances amounts with ances ances ances --budget @@ -1514,7 +1562,7 @@ totals totals totals tals - Additional notes + Glossary: cost calculated using price(s) recorded in the transaction(s). @@ -3231,4 +3279,4 @@ -hledger 1.18 June 2020 hledger(1) +hledger 1.18.1 June 2020 hledger(1) diff --git a/embeddedfiles/hledger_csv.5 b/embeddedfiles/hledger_csv.5 --- a/embeddedfiles/hledger_csv.5 +++ b/embeddedfiles/hledger_csv.5 @@ -1,6 +1,6 @@ .\"t -.TH "hledger_csv" "5" "June 2020" "hledger 1.18" "hledger User Manuals" +.TH "hledger_csv" "5" "June 2020" "hledger 1.18.1" "hledger User Manuals" @@ -961,7 +961,7 @@ .PP A posting amount can be set in one of these ways: .IP \[bu] 2 -by assigning (with a fields list or field assigment) to +by assigning (with a fields list or field assignment) to \f[C]amountN\f[R] (posting N\[aq]s amount) or \f[C]amount\f[R] (posting 1\[aq]s amount) .IP \[bu] 2 diff --git a/embeddedfiles/hledger_csv.info b/embeddedfiles/hledger_csv.info --- a/embeddedfiles/hledger_csv.info +++ b/embeddedfiles/hledger_csv.info @@ -3,8 +3,8 @@  File: hledger_csv.info, Node: Top, Next: EXAMPLES, Up: (dir) -hledger_csv(5) hledger 1.18 -*************************** +hledger_csv(5) hledger 1.18.1 +***************************** CSV - how hledger reads CSV data, and the CSV rules file format @@ -907,7 +907,7 @@ A posting amount can be set in one of these ways: - * by assigning (with a fields list or field assigment) to 'amountN' + * by assigning (with a fields list or field assignment) to 'amountN' (posting N's amount) or 'amount' (posting 1's amount) * by assigning to 'amountN-in' and 'amountN-out' (or 'amount-in' and @@ -1036,74 +1036,74 @@  Tag Table: Node: Top72 -Node: EXAMPLES2174 -Ref: #examples2280 -Node: Basic2488 -Ref: #basic2588 -Node: Bank of Ireland3130 -Ref: #bank-of-ireland3265 -Node: Amazon4727 -Ref: #amazon4845 -Node: Paypal6564 -Ref: #paypal6658 -Node: CSV RULES14302 -Ref: #csv-rules14411 -Node: skip14687 -Ref: #skip14780 -Node: fields15155 -Ref: #fields15277 -Node: Transaction field names16442 -Ref: #transaction-field-names16602 -Node: Posting field names16713 -Ref: #posting-field-names16865 -Node: account16935 -Ref: #account17051 -Node: amount17588 -Ref: #amount17719 -Node: currency18826 -Ref: #currency18961 -Node: balance19167 -Ref: #balance19301 -Node: comment19618 -Ref: #comment19735 -Node: field assignment19898 -Ref: #field-assignment20041 -Node: separator20859 -Ref: #separator20988 -Node: if21399 -Ref: #if21501 -Node: end23657 -Ref: #end23763 -Node: date-format23987 -Ref: #date-format24119 -Node: newest-first24868 -Ref: #newest-first25006 -Node: include25689 -Ref: #include25818 -Node: balance-type26262 -Ref: #balance-type26382 -Node: TIPS27082 -Ref: #tips27164 -Node: Rapid feedback27420 -Ref: #rapid-feedback27537 -Node: Valid CSV27997 -Ref: #valid-csv28127 -Node: File Extension28319 -Ref: #file-extension28471 -Node: Reading multiple CSV files28881 -Ref: #reading-multiple-csv-files29066 -Node: Valid transactions29307 -Ref: #valid-transactions29485 -Node: Deduplicating importing30113 -Ref: #deduplicating-importing30292 -Node: Setting amounts31325 -Ref: #setting-amounts31494 -Node: Setting currency/commodity32480 -Ref: #setting-currencycommodity32672 -Node: Referencing other fields33475 -Ref: #referencing-other-fields33675 -Node: How CSV rules are evaluated34572 -Ref: #how-csv-rules-are-evaluated34745 +Node: EXAMPLES2178 +Ref: #examples2284 +Node: Basic2492 +Ref: #basic2592 +Node: Bank of Ireland3134 +Ref: #bank-of-ireland3269 +Node: Amazon4731 +Ref: #amazon4849 +Node: Paypal6568 +Ref: #paypal6662 +Node: CSV RULES14306 +Ref: #csv-rules14415 +Node: skip14691 +Ref: #skip14784 +Node: fields15159 +Ref: #fields15281 +Node: Transaction field names16446 +Ref: #transaction-field-names16606 +Node: Posting field names16717 +Ref: #posting-field-names16869 +Node: account16939 +Ref: #account17055 +Node: amount17592 +Ref: #amount17723 +Node: currency18830 +Ref: #currency18965 +Node: balance19171 +Ref: #balance19305 +Node: comment19622 +Ref: #comment19739 +Node: field assignment19902 +Ref: #field-assignment20045 +Node: separator20863 +Ref: #separator20992 +Node: if21403 +Ref: #if21505 +Node: end23661 +Ref: #end23767 +Node: date-format23991 +Ref: #date-format24123 +Node: newest-first24872 +Ref: #newest-first25010 +Node: include25693 +Ref: #include25822 +Node: balance-type26266 +Ref: #balance-type26386 +Node: TIPS27086 +Ref: #tips27168 +Node: Rapid feedback27424 +Ref: #rapid-feedback27541 +Node: Valid CSV28001 +Ref: #valid-csv28131 +Node: File Extension28323 +Ref: #file-extension28475 +Node: Reading multiple CSV files28885 +Ref: #reading-multiple-csv-files29070 +Node: Valid transactions29311 +Ref: #valid-transactions29489 +Node: Deduplicating importing30117 +Ref: #deduplicating-importing30296 +Node: Setting amounts31329 +Ref: #setting-amounts31498 +Node: Setting currency/commodity32485 +Ref: #setting-currencycommodity32677 +Node: Referencing other fields33480 +Ref: #referencing-other-fields33680 +Node: How CSV rules are evaluated34577 +Ref: #how-csv-rules-are-evaluated34750  End Tag Table diff --git a/embeddedfiles/hledger_csv.txt b/embeddedfiles/hledger_csv.txt --- a/embeddedfiles/hledger_csv.txt +++ b/embeddedfiles/hledger_csv.txt @@ -710,7 +710,7 @@ Setting amounts A posting amount can be set in one of these ways: - o by assigning (with a fields list or field assigment) to amountN + o by assigning (with a fields list or field assignment) to amountN (posting N's amount) or amount (posting 1's amount) o by assigning to amountN-in and amountN-out (or amount-in and amount- @@ -852,4 +852,4 @@ -hledger 1.18 June 2020 hledger_csv(5) +hledger 1.18.1 June 2020 hledger_csv(5) diff --git a/embeddedfiles/hledger_journal.5 b/embeddedfiles/hledger_journal.5 --- a/embeddedfiles/hledger_journal.5 +++ b/embeddedfiles/hledger_journal.5 @@ -1,6 +1,6 @@ .\"t -.TH "hledger_journal" "5" "June 2020" "hledger 1.18" "hledger User Manuals" +.TH "hledger_journal" "5" "June 2020" "hledger 1.18.1" "hledger User Manuals" @@ -1143,15 +1143,20 @@ If the file path does not begin with a slash, it is relative to the current file\[aq]s folder. .PP -It may contain glob patterns to match multiple files, eg: +A tilde means home directory, eg: \f[C]include \[ti]/main.journal\f[R]. +.PP +The path may contain glob patterns to match multiple files, eg: \f[C]include *.journal\f[R]. .PP -Or a tilde, meaning home directory: -\f[C]include \[ti]/main.journal\f[R]. +There is limited support for recursive wildcards: \f[C]**/\f[R] (the +slash is required) matches 0 or more subdirectories. +It\[aq]s not super convenient since you have to avoid include cycles and +including directories, but this can be done, eg: +\f[C]include */**/*.journal\f[R]. .PP -It may also be prefixed to force a specific file format, overriding the -file extension (as described in hledger.1 -> Input files): -\f[C]include timedot:\[ti]/notes/2020*.md\f[R]. +The path may also be prefixed to force a specific file format, +overriding the file extension (as described in hledger.1 -> Input +files): \f[C]include timedot:\[ti]/notes/2020*.md\f[R]. .SS Default year .PP You can set a default year to be used for subsequent dates which diff --git a/embeddedfiles/hledger_journal.info b/embeddedfiles/hledger_journal.info --- a/embeddedfiles/hledger_journal.info +++ b/embeddedfiles/hledger_journal.info @@ -4,8 +4,8 @@  File: hledger_journal.info, Node: Top, Up: (dir) -hledger_journal(5) hledger 1.18 -******************************* +hledger_journal(5) hledger 1.18.1 +********************************* Journal - hledger's default file format, representing a General Journal @@ -1023,15 +1023,20 @@ If the file path does not begin with a slash, it is relative to the current file's folder. - It may contain glob patterns to match multiple files, eg: 'include -*.journal'. + A tilde means home directory, eg: 'include ~/main.journal'. - Or a tilde, meaning home directory: 'include ~/main.journal'. + The path may contain glob patterns to match multiple files, eg: +'include *.journal'. - It may also be prefixed to force a specific file format, overriding -the file extension (as described in hledger.1 -> Input files): 'include -timedot:~/notes/2020*.md'. + There is limited support for recursive wildcards: '**/' (the slash is +required) matches 0 or more subdirectories. It's not super convenient +since you have to avoid include cycles and including directories, but +this can be done, eg: 'include */**/*.journal'. + The path may also be prefixed to force a specific file format, +overriding the file extension (as described in hledger.1 -> Input +files): 'include timedot:~/notes/2020*.md'. +  File: hledger_journal.info, Node: Default year, Next: Declaring commodities, Prev: Including other files, Up: Directives @@ -1823,124 +1828,124 @@  Tag Table: Node: Top76 -Node: Transactions1869 -Ref: #transactions1961 -Node: Dates3245 -Ref: #dates3344 -Node: Simple dates3409 -Ref: #simple-dates3535 -Node: Secondary dates4044 -Ref: #secondary-dates4198 -Node: Posting dates5534 -Ref: #posting-dates5663 -Node: Status7035 -Ref: #status7156 -Node: Description8864 -Ref: #description8998 -Node: Payee and note9318 -Ref: #payee-and-note9432 -Node: Comments9767 -Ref: #comments9893 -Node: Tags11087 -Ref: #tags11202 -Node: Postings12595 -Ref: #postings12723 -Node: Virtual postings13749 -Ref: #virtual-postings13866 -Node: Account names15171 -Ref: #account-names15312 -Node: Amounts15799 -Ref: #amounts15938 -Node: Digit group marks17046 -Ref: #digit-group-marks17194 -Node: Amount display style18132 -Ref: #amount-display-style18286 -Node: Transaction prices19723 -Ref: #transaction-prices19895 -Node: Lot prices and lot dates22227 -Ref: #lot-prices-and-lot-dates22424 -Node: Balance assertions22912 -Ref: #balance-assertions23098 -Node: Assertions and ordering24131 -Ref: #assertions-and-ordering24319 -Node: Assertions and included files25019 -Ref: #assertions-and-included-files25262 -Node: Assertions and multiple -f options25595 -Ref: #assertions-and-multiple--f-options25851 -Node: Assertions and commodities25983 -Ref: #assertions-and-commodities26215 -Node: Assertions and prices27372 -Ref: #assertions-and-prices27586 -Node: Assertions and subaccounts28026 -Ref: #assertions-and-subaccounts28255 -Node: Assertions and virtual postings28579 -Ref: #assertions-and-virtual-postings28821 -Node: Assertions and precision28963 -Ref: #assertions-and-precision29156 -Node: Balance assignments29423 -Ref: #balance-assignments29597 -Node: Balance assignments and prices30761 -Ref: #balance-assignments-and-prices30933 -Node: Directives31157 -Ref: #directives31316 -Node: Directives and multiple files37007 -Ref: #directives-and-multiple-files37190 -Node: Comment blocks37854 -Ref: #comment-blocks38037 -Node: Including other files38213 -Ref: #including-other-files38393 -Node: Default year39044 -Ref: #default-year39213 -Node: Declaring commodities39620 -Ref: #declaring-commodities39803 -Node: Default commodity41609 -Ref: #default-commodity41795 -Node: Declaring market prices42684 -Ref: #declaring-market-prices42879 -Node: Declaring accounts43736 -Ref: #declaring-accounts43922 -Node: Account comments44847 -Ref: #account-comments45010 -Node: Account subdirectives45434 -Ref: #account-subdirectives45629 -Node: Account types45942 -Ref: #account-types46126 -Node: Account display order47765 -Ref: #account-display-order47935 -Node: Rewriting accounts49086 -Ref: #rewriting-accounts49271 -Node: Basic aliases50028 -Ref: #basic-aliases50174 -Node: Regex aliases50878 -Ref: #regex-aliases51050 -Node: Combining aliases51768 -Ref: #combining-aliases51961 -Node: Aliases and multiple files53237 -Ref: #aliases-and-multiple-files53446 -Node: end aliases54025 -Ref: #end-aliases54182 -Node: Default parent account54283 -Ref: #default-parent-account54451 -Node: Periodic transactions55335 -Ref: #periodic-transactions55510 -Node: Periodic rule syntax57382 -Ref: #periodic-rule-syntax57588 -Node: Two spaces between period expression and description!58292 -Ref: #two-spaces-between-period-expression-and-description58611 -Node: Forecasting with periodic transactions59295 -Ref: #forecasting-with-periodic-transactions59600 -Node: Budgeting with periodic transactions61655 -Ref: #budgeting-with-periodic-transactions61894 -Node: Auto postings62343 -Ref: #auto-postings62483 -Node: Auto postings and multiple files64662 -Ref: #auto-postings-and-multiple-files64866 -Node: Auto postings and dates65075 -Ref: #auto-postings-and-dates65349 -Node: Auto postings and transaction balancing / inferred amounts / balance assertions65524 -Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions65875 -Node: Auto posting tags66217 -Ref: #auto-posting-tags66432 +Node: Transactions1873 +Ref: #transactions1965 +Node: Dates3249 +Ref: #dates3348 +Node: Simple dates3413 +Ref: #simple-dates3539 +Node: Secondary dates4048 +Ref: #secondary-dates4202 +Node: Posting dates5538 +Ref: #posting-dates5667 +Node: Status7039 +Ref: #status7160 +Node: Description8868 +Ref: #description9002 +Node: Payee and note9322 +Ref: #payee-and-note9436 +Node: Comments9771 +Ref: #comments9897 +Node: Tags11091 +Ref: #tags11206 +Node: Postings12599 +Ref: #postings12727 +Node: Virtual postings13753 +Ref: #virtual-postings13870 +Node: Account names15175 +Ref: #account-names15316 +Node: Amounts15803 +Ref: #amounts15942 +Node: Digit group marks17050 +Ref: #digit-group-marks17198 +Node: Amount display style18136 +Ref: #amount-display-style18290 +Node: Transaction prices19727 +Ref: #transaction-prices19899 +Node: Lot prices and lot dates22231 +Ref: #lot-prices-and-lot-dates22428 +Node: Balance assertions22916 +Ref: #balance-assertions23102 +Node: Assertions and ordering24135 +Ref: #assertions-and-ordering24323 +Node: Assertions and included files25023 +Ref: #assertions-and-included-files25266 +Node: Assertions and multiple -f options25599 +Ref: #assertions-and-multiple--f-options25855 +Node: Assertions and commodities25987 +Ref: #assertions-and-commodities26219 +Node: Assertions and prices27376 +Ref: #assertions-and-prices27590 +Node: Assertions and subaccounts28030 +Ref: #assertions-and-subaccounts28259 +Node: Assertions and virtual postings28583 +Ref: #assertions-and-virtual-postings28825 +Node: Assertions and precision28967 +Ref: #assertions-and-precision29160 +Node: Balance assignments29427 +Ref: #balance-assignments29601 +Node: Balance assignments and prices30765 +Ref: #balance-assignments-and-prices30937 +Node: Directives31161 +Ref: #directives31320 +Node: Directives and multiple files37011 +Ref: #directives-and-multiple-files37194 +Node: Comment blocks37858 +Ref: #comment-blocks38041 +Node: Including other files38217 +Ref: #including-other-files38397 +Node: Default year39321 +Ref: #default-year39490 +Node: Declaring commodities39897 +Ref: #declaring-commodities40080 +Node: Default commodity41886 +Ref: #default-commodity42072 +Node: Declaring market prices42961 +Ref: #declaring-market-prices43156 +Node: Declaring accounts44013 +Ref: #declaring-accounts44199 +Node: Account comments45124 +Ref: #account-comments45287 +Node: Account subdirectives45711 +Ref: #account-subdirectives45906 +Node: Account types46219 +Ref: #account-types46403 +Node: Account display order48042 +Ref: #account-display-order48212 +Node: Rewriting accounts49363 +Ref: #rewriting-accounts49548 +Node: Basic aliases50305 +Ref: #basic-aliases50451 +Node: Regex aliases51155 +Ref: #regex-aliases51327 +Node: Combining aliases52045 +Ref: #combining-aliases52238 +Node: Aliases and multiple files53514 +Ref: #aliases-and-multiple-files53723 +Node: end aliases54302 +Ref: #end-aliases54459 +Node: Default parent account54560 +Ref: #default-parent-account54728 +Node: Periodic transactions55612 +Ref: #periodic-transactions55787 +Node: Periodic rule syntax57659 +Ref: #periodic-rule-syntax57865 +Node: Two spaces between period expression and description!58569 +Ref: #two-spaces-between-period-expression-and-description58888 +Node: Forecasting with periodic transactions59572 +Ref: #forecasting-with-periodic-transactions59877 +Node: Budgeting with periodic transactions61932 +Ref: #budgeting-with-periodic-transactions62171 +Node: Auto postings62620 +Ref: #auto-postings62760 +Node: Auto postings and multiple files64939 +Ref: #auto-postings-and-multiple-files65143 +Node: Auto postings and dates65352 +Ref: #auto-postings-and-dates65626 +Node: Auto postings and transaction balancing / inferred amounts / balance assertions65801 +Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions66152 +Node: Auto posting tags66494 +Ref: #auto-posting-tags66709  End Tag Table diff --git a/embeddedfiles/hledger_journal.txt b/embeddedfiles/hledger_journal.txt --- a/embeddedfiles/hledger_journal.txt +++ b/embeddedfiles/hledger_journal.txt @@ -792,18 +792,23 @@ If the file path does not begin with a slash, it is relative to the current file's folder. - It may contain glob patterns to match multiple files, eg: include + A tilde means home directory, eg: include ~/main.journal. + + The path may contain glob patterns to match multiple files, eg: include *.journal. - Or a tilde, meaning home directory: include ~/main.journal. + There is limited support for recursive wildcards: **/ (the slash is re- + quired) matches 0 or more subdirectories. It's not super convenient + since you have to avoid include cycles and including directories, but + this can be done, eg: include */**/*.journal. - It may also be prefixed to force a specific file format, overriding the - file extension (as described in hledger.1 -> Input files): include - timedot:~/notes/2020*.md. + The path may also be prefixed to force a specific file format, overrid- + ing the file extension (as described in hledger.1 -> Input files): in- + clude timedot:~/notes/2020*.md. Default year - You can set a default year to be used for subsequent dates which don't - specify a year. This is a line beginning with Y followed by the year. + You can set a default year to be used for subsequent dates which don't + specify a year. This is a line beginning with Y followed by the year. Eg: Y2009 ; set default year to 2009 @@ -825,19 +830,19 @@ Declaring commodities The commodity directive has several functions: - 1. It declares commodities which may be used in the journal. This is + 1. It declares commodities which may be used in the journal. This is currently not enforced, but can serve as documentation. - 2. It declares what decimal mark character (period or comma) to expect - when parsing input - useful to disambiguate international number - formats in your data. (Without this, hledger will parse both 1,000 + 2. It declares what decimal mark character (period or comma) to expect + when parsing input - useful to disambiguate international number + formats in your data. (Without this, hledger will parse both 1,000 and 1.000 as 1). - 3. It declares the amount display style to use in output - decimal and + 3. It declares the amount display style to use in output - decimal and digit group marks, number of decimal places, symbol placement etc. - You are likely to run into one of the problems solved by commodity di- - rectives, sooner or later, so it's a good idea to just always use them + You are likely to run into one of the problems solved by commodity di- + rectives, sooner or later, so it's a good idea to just always use them to declare your commodities. A commodity directive is just the word commodity followed by an amount. @@ -850,8 +855,8 @@ ; separating thousands with comma. commodity 1,000.0000 AAAA - or on multiple lines, using the "format" subdirective. (In this case - the commodity symbol appears twice and should be the same in both + or on multiple lines, using the "format" subdirective. (In this case + the commodity symbol appears twice and should be the same in both places.): ; commodity SYMBOL @@ -864,22 +869,22 @@ format INR 1,00,00,000.00 The quantity of the amount does not matter; only the format is signifi- - cant. The number must include a decimal mark: either a period or a + cant. The number must include a decimal mark: either a period or a comma, followed by 0 or more decimal digits. - Note hledger normally uses banker's rounding, so 0.5 displayed with + Note hledger normally uses banker's rounding, so 0.5 displayed with zero decimal digits is "0". (More at Amount display style.) Default commodity - The D directive sets a default commodity, to be used for amounts with- + The D directive sets a default commodity, to be used for amounts with- out a commodity symbol (ie, plain numbers). This commodity will be ap- plied to all subsequent commodity-less amounts, or until the next D di- rective. (Note, this is different from Ledger's D.) - For compatibility/historical reasons, D also acts like a commodity di- + For compatibility/historical reasons, D also acts like a commodity di- rective, setting the commodity's display style (for output) and decimal mark (for parsing input). As with commodity, the amount must always be - written with a decimal mark (period or comma). If both directives are + written with a decimal mark (period or comma). If both directives are used, commodity's style takes precedence. The syntax is D AMOUNT. Eg: @@ -893,9 +898,9 @@ b Declaring market prices - The P directive declares a market price, which is an exchange rate be- - tween two commodities on a certain date. (In Ledger, they are called - "historical prices".) These are often obtained from a stock exchange, + The P directive declares a market price, which is an exchange rate be- + tween two commodities on a certain date. (In Ledger, they are called + "historical prices".) These are often obtained from a stock exchange, cryptocurrency exchange, or the foreign exchange market. Here is the format: @@ -906,16 +911,16 @@ o COMMODITYA is the symbol of the commodity being priced - o COMMODITYBAMOUNT is an amount (symbol and quantity) in a second com- + o COMMODITYBAMOUNT is an amount (symbol and quantity) in a second com- modity, giving the price in commodity B of one unit of commodity A. - These two market price directives say that one euro was worth 1.35 US + These two market price directives say that one euro was worth 1.35 US dollars during 2009, and $1.40 from 2010 onward: P 2009/1/1 EUR $1.35 P 2010/1/1 EUR $1.40 - The -V, -X and --value flags use these market prices to show amount + The -V, -X and --value flags use these market prices to show amount values in another commodity. See Valuation. Declaring accounts @@ -925,20 +930,20 @@ o They can document your intended chart of accounts, providing a refer- ence. - o They can store extra information about accounts (account numbers, + o They can store extra information about accounts (account numbers, notes, etc.) - o They can help hledger know your accounts' types (asset, liability, - equity, revenue, expense), useful for reports like balancesheet and + o They can help hledger know your accounts' types (asset, liability, + equity, revenue, expense), useful for reports like balancesheet and incomestatement. - o They control account display order in reports, allowing non-alpha- + o They control account display order in reports, allowing non-alpha- betic sorting (eg Revenues to appear above Expenses). - o They help with account name completion in the add command, hledger- + o They help with account name completion in the add command, hledger- iadd, hledger-web, ledger-mode etc. - The simplest form is just the word account followed by a hledger-style + The simplest form is just the word account followed by a hledger-style account name, eg: account assets:bank:checking @@ -946,7 +951,7 @@ Account comments Comments, beginning with a semicolon, can be added: - o on the same line, after two or more spaces (because ; is allowed in + o on the same line, after two or more spaces (because ; is allowed in account names) o on the next lines, indented @@ -960,7 +965,7 @@ Same-line comments are not supported by Ledger, or hledger <1.13. Account subdirectives - We also allow (and ignore) Ledger-style indented subdirectives, just + We also allow (and ignore) Ledger-style indented subdirectives, just for compatibility.: account assets:bank:checking @@ -973,18 +978,18 @@ [LEDGER-STYLE SUBDIRECTIVES, IGNORED] Account types - hledger recognises five types (or classes) of account: Asset, Liabil- - ity, Equity, Revenue, Expense. This is used by a few accounting-aware + hledger recognises five types (or classes) of account: Asset, Liabil- + ity, Equity, Revenue, Expense. This is used by a few accounting-aware reports such as balancesheet, incomestatement and cashflow. Auto-detected account types If you name your top-level accounts with some variation of assets, lia- - bilities/debts, equity, revenues/income, or expenses, their types are + bilities/debts, equity, revenues/income, or expenses, their types are detected automatically. Account types declared with tags - More generally, you can declare an account's type with an account di- - rective, by writing a type: tag in a comment, followed by one of the + More generally, you can declare an account's type with an account di- + rective, by writing a type: tag in a comment, followed by one of the words Asset, Liability, Equity, Revenue, Expense, or one of the letters ALERX (case insensitive): @@ -995,8 +1000,8 @@ account expenses ; type:Expense Account types declared with account type codes - Or, you can write one of those letters separated from the account name - by two or more spaces, but this should probably be considered depre- + Or, you can write one of those letters separated from the account name + by two or more spaces, but this should probably be considered depre- cated as of hledger 1.13: account assets A @@ -1006,7 +1011,7 @@ account expenses X Overriding auto-detected types - If you ever override the types of those auto-detected english account + If you ever override the types of those auto-detected english account names mentioned above, you might need to help the reports a bit. Eg: ; make "liabilities" not have the liability type - who knows why @@ -1017,8 +1022,8 @@ account - ; type:L Account display order - Account directives also set the order in which accounts are displayed, - eg in reports, the hledger-ui accounts screen, and the hledger-web + Account directives also set the order in which accounts are displayed, + eg in reports, the hledger-ui accounts screen, and the hledger-web sidebar. By default accounts are listed in alphabetical order. But if you have these account directives in the journal: @@ -1040,20 +1045,20 @@ Undeclared accounts, if any, are displayed last, in alphabetical order. - Note that sorting is done at each level of the account tree (within - each group of sibling accounts under the same parent). And currently, + Note that sorting is done at each level of the account tree (within + each group of sibling accounts under the same parent). And currently, this directive: account other:zoo - would influence the position of zoo among other's subaccounts, but not + would influence the position of zoo among other's subaccounts, but not the position of other among the top-level accounts. This means: - o you will sometimes declare parent accounts (eg account other above) + o you will sometimes declare parent accounts (eg account other above) that you don't intend to post to, just to customize their display or- der - o sibling accounts stay together (you couldn't display x:y in between + o sibling accounts stay together (you couldn't display x:y in between a:b and a:c). Rewriting accounts @@ -1071,14 +1076,14 @@ o customising reports Account aliases also rewrite account names in account directives. They - do not affect account names being entered via hledger add or hledger- + do not affect account names being entered via hledger add or hledger- web. See also Rewrite account names. Basic aliases - To set an account alias, use the alias directive in your journal file. - This affects all subsequent journal entries in the current file or its + To set an account alias, use the alias directive in your journal file. + This affects all subsequent journal entries in the current file or its included files. The spaces around the = are optional: alias OLD = NEW @@ -1086,49 +1091,49 @@ Or, you can use the --alias 'OLD=NEW' option on the command line. This affects all entries. It's useful for trying out aliases interactively. - OLD and NEW are case sensitive full account names. hledger will re- - place any occurrence of the old account name with the new one. Subac- + OLD and NEW are case sensitive full account names. hledger will re- + place any occurrence of the old account name with the new one. Subac- counts are also affected. Eg: alias checking = assets:bank:wells fargo:checking ; rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a" Regex aliases - There is also a more powerful variant that uses a regular expression, + There is also a more powerful variant that uses a regular expression, indicated by the forward slashes: alias /REGEX/ = REPLACEMENT or --alias '/REGEX/=REPLACEMENT'. - REGEX is a case-insensitive regular expression. Anywhere it matches - inside an account name, the matched part will be replaced by REPLACE- - MENT. If REGEX contains parenthesised match groups, these can be ref- + REGEX is a case-insensitive regular expression. Anywhere it matches + inside an account name, the matched part will be replaced by REPLACE- + MENT. If REGEX contains parenthesised match groups, these can be ref- erenced by the usual numeric backreferences in REPLACEMENT. Eg: alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3 ; rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking" - Also note that REPLACEMENT continues to the end of line (or on command - line, to end of option argument), so it can contain trailing white- + Also note that REPLACEMENT continues to the end of line (or on command + line, to end of option argument), so it can contain trailing white- space. Combining aliases - You can define as many aliases as you like, using journal directives + You can define as many aliases as you like, using journal directives and/or command line options. - Recursive aliases - where an account name is rewritten by one alias, - then by another alias, and so on - are allowed. Each alias sees the + Recursive aliases - where an account name is rewritten by one alias, + then by another alias, and so on - are allowed. Each alias sees the effect of previously applied aliases. - In such cases it can be important to understand which aliases will be - applied and in which order. For (each account name in) each journal + In such cases it can be important to understand which aliases will be + applied and in which order. For (each account name in) each journal entry, we apply: - 1. alias directives preceding the journal entry, most recently parsed + 1. alias directives preceding the journal entry, most recently parsed first (ie, reading upward from the journal entry, bottom to top) - 2. --alias options, in the order they appeared on the command line + 2. --alias options, in the order they appeared on the command line (left to right). In other words, for (an account name in) a given journal entry: @@ -1139,20 +1144,20 @@ o aliases defined after/below the entry do not affect it. - This gives nearby aliases precedence over distant ones, and helps pro- - vide semantic stability - aliases will keep working the same way inde- + This gives nearby aliases precedence over distant ones, and helps pro- + vide semantic stability - aliases will keep working the same way inde- pendent of which files are being read and in which order. - In case of trouble, adding --debug=6 to the command line will show + In case of trouble, adding --debug=6 to the command line will show which aliases are being applied when. Aliases and multiple files - As explained at Directives and multiple files, alias directives do not + As explained at Directives and multiple files, alias directives do not affect parent or sibling files. Eg in this command, hledger -f a.aliases -f b.journal - account aliases defined in a.aliases will not affect b.journal. In- + account aliases defined in a.aliases will not affect b.journal. In- cluding the aliases doesn't work either: include a.aliases @@ -1174,14 +1179,14 @@ include c.journal ; also affected end aliases - You can clear (forget) all currently defined aliases with the end + You can clear (forget) all currently defined aliases with the end aliases directive: end aliases Default parent account - You can specify a parent account which will be prepended to all ac- - counts within a section of the journal. Use the apply account and end + You can specify a parent account which will be prepended to all ac- + counts within a section of the journal. Use the apply account and end apply account directives like so: apply account home @@ -1198,7 +1203,7 @@ home:food $10 home:cash $-10 - If end apply account is omitted, the effect lasts to the end of the + If end apply account is omitted, the effect lasts to the end of the file. Included files are also affected, eg: apply account business @@ -1207,50 +1212,50 @@ apply account personal include personal.journal - Prior to hledger 1.0, legacy account and end spellings were also sup- + Prior to hledger 1.0, legacy account and end spellings were also sup- ported. - A default parent account also affects account directives. It does not - affect account names being entered via hledger add or hledger-web. If - account aliases are present, they are applied after the default parent + A default parent account also affects account directives. It does not + affect account names being entered via hledger add or hledger-web. If + account aliases are present, they are applied after the default parent account. Periodic transactions - Periodic transaction rules describe transactions that recur. They al- - low hledger to generate temporary future transactions to help with - forecasting, so you don't have to write out each one in the journal, - and it's easy to try out different forecasts. Secondly, they are also + Periodic transaction rules describe transactions that recur. They al- + low hledger to generate temporary future transactions to help with + forecasting, so you don't have to write out each one in the journal, + and it's easy to try out different forecasts. Secondly, they are also used to define the budgets shown in budget reports. - Periodic transactions can be a little tricky, so before you use them, + Periodic transactions can be a little tricky, so before you use them, read this whole section - or at least these tips: - 1. Two spaces accidentally added or omitted will cause you trouble - + 1. Two spaces accidentally added or omitted will cause you trouble - read about this below. - 2. For troubleshooting, show the generated transactions with hledger - print --forecast tag:generated or hledger register --forecast + 2. For troubleshooting, show the generated transactions with hledger + print --forecast tag:generated or hledger register --forecast tag:generated. - 3. Forecasted transactions will begin only after the last non-fore- + 3. Forecasted transactions will begin only after the last non-fore- casted transaction's date. - 4. Forecasted transactions will end 6 months from today, by default. + 4. Forecasted transactions will end 6 months from today, by default. See below for the exact start/end rules. - 5. period expressions can be tricky. Their documentation needs im- + 5. period expressions can be tricky. Their documentation needs im- provement, but is worth studying. - 6. Some period expressions with a repeating interval must begin on a - natural boundary of that interval. Eg in weekly from DATE, DATE - must be a monday. ~ weekly from 2019/10/1 (a tuesday) will give an + 6. Some period expressions with a repeating interval must begin on a + natural boundary of that interval. Eg in weekly from DATE, DATE + must be a monday. ~ weekly from 2019/10/1 (a tuesday) will give an error. 7. Other period expressions with an interval are automatically expanded - to cover a whole number of that interval. (This is done to improve + to cover a whole number of that interval. (This is done to improve reports, but it also affects periodic transactions. Yes, it's a bit - inconsistent with the above.) Eg: ~ every 10th day of month from - 2020/01, which is equivalent to ~ every 10th day of month from + inconsistent with the above.) Eg: ~ every 10th day of month from + 2020/01, which is equivalent to ~ every 10th day of month from 2020/01/01, will be adjusted to start on 2019/12/10. Periodic rule syntax @@ -1262,17 +1267,17 @@ expenses:rent $2000 assets:bank:checking - There is an additional constraint on the period expression: the start - date must fall on a natural boundary of the interval. Eg monthly from + There is an additional constraint on the period expression: the start + date must fall on a natural boundary of the interval. Eg monthly from 2018/1/1 is valid, but monthly from 2018/1/15 is not. - Partial or relative dates (M/D, D, tomorrow, last week) in the period - expression can work (useful or not). They will be relative to today's - date, unless a Y default year directive is in effect, in which case + Partial or relative dates (M/D, D, tomorrow, last week) in the period + expression can work (useful or not). They will be relative to today's + date, unless a Y default year directive is in effect, in which case they will be relative to Y/1/1. Two spaces between period expression and description! - If the period expression is followed by a transaction description, + If the period expression is followed by a transaction description, these must be separated by two or more spaces. This helps hledger know where the period expression ends, so that descriptions can not acciden- tally alter their meaning, as in this example: @@ -1286,68 +1291,68 @@ So, - o Do write two spaces between your period expression and your transac- + o Do write two spaces between your period expression and your transac- tion description, if any. - o Don't accidentally write two spaces in the middle of your period ex- + o Don't accidentally write two spaces in the middle of your period ex- pression. Forecasting with periodic transactions - The --forecast flag activates any periodic transaction rules in the - journal. They will generate temporary recurring transactions, which - are not saved in the journal, but will appear in all reports (eg + The --forecast flag activates any periodic transaction rules in the + journal. They will generate temporary recurring transactions, which + are not saved in the journal, but will appear in all reports (eg print). This can be useful for estimating balances into the future, or - experimenting with different scenarios. Or, it can be used as a data + experimenting with different scenarios. Or, it can be used as a data entry aid: describe recurring transactions, and every so often copy the output of print --forecast into the journal. - These transactions will have an extra tag indicating which periodic + These transactions will have an extra tag indicating which periodic rule generated them: generated-transaction:~ PERIODICEXPR. And a simi- - lar, hidden tag (beginning with an underscore) which, because it's - never displayed by print, can be used to match transactions generated + lar, hidden tag (beginning with an underscore) which, because it's + never displayed by print, can be used to match transactions generated "just now": _generated-transaction:~ PERIODICEXPR. - Periodic transactions are generated within some forecast period. By + Periodic transactions are generated within some forecast period. By default, this o begins on the later of o the report start date if specified with -b/-p/date: - o the day after the latest normal (non-periodic) transaction in the + o the day after the latest normal (non-periodic) transaction in the journal, or today if there are no normal transactions. - o ends on the report end date if specified with -e/-p/date:, or 6 + o ends on the report end date if specified with -e/-p/date:, or 6 months (180 days) from today. - This means that periodic transactions will begin only after the latest - recorded transaction. And a recorded transaction dated in the future - can prevent generation of periodic transactions. (You can avoid that + This means that periodic transactions will begin only after the latest + recorded transaction. And a recorded transaction dated in the future + can prevent generation of periodic transactions. (You can avoid that by writing the future transaction as a one-time periodic rule instead - put tilde before the date, eg ~ YYYY-MM-DD ...). Or, you can set your own arbitrary "forecast period", which can overlap - recorded transactions, and need not be in the future, by providing an - option argument, like --forecast=PERIODEXPR. Note the equals sign is + recorded transactions, and need not be in the future, by providing an + option argument, like --forecast=PERIODEXPR. Note the equals sign is required, a space won't work. PERIODEXPR is a period expression, which - can specify the start date, end date, or both, like in a date: query. - (See also hledger.1 -> Report start & end date). Some examples: + can specify the start date, end date, or both, like in a date: query. + (See also hledger.1 -> Report start & end date). Some examples: --forecast=202001-202004, --forecast=jan-, --forecast=2020. Budgeting with periodic transactions - With the --budget flag, currently supported by the balance command, - each periodic transaction rule declares recurring budget goals for the - specified accounts. Eg the first example above declares a goal of - spending $2000 on rent (and also, a goal of depositing $2000 into - checking) every month. Goals and actual performance can then be com- + With the --budget flag, currently supported by the balance command, + each periodic transaction rule declares recurring budget goals for the + specified accounts. Eg the first example above declares a goal of + spending $2000 on rent (and also, a goal of depositing $2000 into + checking) every month. Goals and actual performance can then be com- pared in budget reports. - For more details, see: balance: Budget report and Budgeting and Fore- + For more details, see: balance: Budget report and Budgeting and Fore- casting. Auto postings - "Automated postings" or "auto postings" are extra postings which get - added automatically to transactions which match certain queries, de- + "Automated postings" or "auto postings" are extra postings which get + added automatically to transactions which match certain queries, de- fined by "auto posting rules", when you use the --auto flag. An auto posting rule looks a bit like a transaction: @@ -1357,27 +1362,27 @@ ... ACCOUNT [AMOUNT] - except the first line is an equals sign (mnemonic: = suggests match- - ing), followed by a query (which matches existing postings), and each - "posting" line describes a posting to be generated, and the posting + except the first line is an equals sign (mnemonic: = suggests match- + ing), followed by a query (which matches existing postings), and each + "posting" line describes a posting to be generated, and the posting amounts can be: - o a normal amount with a commodity symbol, eg $2. This will be used + o a normal amount with a commodity symbol, eg $2. This will be used as-is. o a number, eg 2. The commodity symbol (if any) from the matched post- ing will be added to this. - o a numeric multiplier, eg *2 (a star followed by a number N). The + o a numeric multiplier, eg *2 (a star followed by a number N). The matched posting's amount (and total price, if any) will be multiplied by N. - o a multiplier with a commodity symbol, eg *$2 (a star, number N, and + o a multiplier with a commodity symbol, eg *$2 (a star, number N, and symbol S). The matched posting's amount will be multiplied by N, and its commodity symbol will be replaced with S. - Any query term containing spaces must be enclosed in single or double - quotes, as on the command line. Eg, note the quotes around the second + Any query term containing spaces must be enclosed in single or double + quotes, as on the command line. Eg, note the quotes around the second query term below: = expenses:groceries 'expenses:dining out' @@ -1416,24 +1421,24 @@ Auto postings and multiple files An auto posting rule can affect any transaction in the current file, or - in any parent file or child file. Note, currently it will not affect + in any parent file or child file. Note, currently it will not affect sibling files (when multiple -f/--file are used - see #1212). Auto postings and dates - A posting date (or secondary date) in the matched posting, or (taking - precedence) a posting date in the auto posting rule itself, will also + A posting date (or secondary date) in the matched posting, or (taking + precedence) a posting date in the auto posting rule itself, will also be used in the generated posting. Auto postings and transaction balancing / inferred amounts / balance asser- tions Currently, auto postings are added: - o after missing amounts are inferred, and transactions are checked for + o after missing amounts are inferred, and transactions are checked for balancedness, o but before balance assertions are checked. - Note this means that journal entries must be balanced both before and + Note this means that journal entries must be balanced both before and after auto postings are added. This changed in hledger 1.12+; see #893 for background. @@ -1443,11 +1448,11 @@ o generated-posting:= QUERY - shows this was generated by an auto post- ing rule, and the query - o _generated-posting:= QUERY - a hidden tag, which does not appear in + o _generated-posting:= QUERY - a hidden tag, which does not appear in hledger's output. This can be used to match postings generated "just now", rather than generated in the past and saved to the journal. - Also, any transaction that has been changed by auto posting rules will + Also, any transaction that has been changed by auto posting rules will have these tags added: o modified: - this transaction was modified @@ -1458,7 +1463,7 @@ REPORTING BUGS - Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel + Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel or hledger mail list) @@ -1472,7 +1477,7 @@ SEE ALSO - hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), + hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- dot(5), ledger(1) @@ -1480,4 +1485,4 @@ -hledger 1.18 June 2020 hledger_journal(5) +hledger 1.18.1 June 2020 hledger_journal(5) diff --git a/embeddedfiles/hledger_timeclock.5 b/embeddedfiles/hledger_timeclock.5 --- a/embeddedfiles/hledger_timeclock.5 +++ b/embeddedfiles/hledger_timeclock.5 @@ -1,5 +1,5 @@ -.TH "hledger_timeclock" "5" "June 2020" "hledger 1.18" "hledger User Manuals" +.TH "hledger_timeclock" "5" "June 2020" "hledger 1.18.1" "hledger User Manuals" diff --git a/embeddedfiles/hledger_timeclock.info b/embeddedfiles/hledger_timeclock.info --- a/embeddedfiles/hledger_timeclock.info +++ b/embeddedfiles/hledger_timeclock.info @@ -4,8 +4,8 @@  File: hledger_timeclock.info, Node: Top, Up: (dir) -hledger_timeclock(5) hledger 1.18 -********************************* +hledger_timeclock(5) hledger 1.18.1 +*********************************** Timeclock - the time logging format of timeclock.el, as read by hledger diff --git a/embeddedfiles/hledger_timeclock.txt b/embeddedfiles/hledger_timeclock.txt --- a/embeddedfiles/hledger_timeclock.txt +++ b/embeddedfiles/hledger_timeclock.txt @@ -78,4 +78,4 @@ -hledger 1.18 June 2020 hledger_timeclock(5) +hledger 1.18.1 June 2020 hledger_timeclock(5) diff --git a/embeddedfiles/hledger_timedot.5 b/embeddedfiles/hledger_timedot.5 --- a/embeddedfiles/hledger_timedot.5 +++ b/embeddedfiles/hledger_timedot.5 @@ -1,5 +1,5 @@ -.TH "hledger_timedot" "5" "June 2020" "hledger 1.18" "hledger User Manuals" +.TH "hledger_timedot" "5" "June 2020" "hledger 1.18.1" "hledger User Manuals" diff --git a/embeddedfiles/hledger_timedot.info b/embeddedfiles/hledger_timedot.info --- a/embeddedfiles/hledger_timedot.info +++ b/embeddedfiles/hledger_timedot.info @@ -4,8 +4,8 @@  File: hledger_timedot.info, Node: Top, Up: (dir) -hledger_timedot(5) hledger 1.18 -******************************* +hledger_timedot(5) hledger 1.18.1 +********************************* Timedot - hledger's human-friendly time logging format diff --git a/embeddedfiles/hledger_timedot.txt b/embeddedfiles/hledger_timedot.txt --- a/embeddedfiles/hledger_timedot.txt +++ b/embeddedfiles/hledger_timedot.txt @@ -161,4 +161,4 @@ -hledger 1.18 June 2020 hledger_timedot(5) +hledger 1.18.1 June 2020 hledger_timedot(5) diff --git a/hledger.1 b/hledger.1 --- a/hledger.1 +++ b/hledger.1 @@ -1,6 +1,6 @@ .\"t -.TH "hledger" "1" "June 2020" "hledger 1.18" "hledger User Manuals" +.TH "hledger" "1" "June 2020" "hledger 1.18.1" "hledger User Manuals" @@ -617,13 +617,20 @@ hledger-ui/hledger-web) .TP \f[B]\f[CB]-B --cost\f[B]\f[R] -convert amounts to their cost at transaction time (using the transaction -price, if any) +convert amounts to their cost/selling amount at transaction time .TP -\f[B]\f[CB]-V --value\f[B]\f[R] -convert amounts to their market value on the report end date (using the -most recent applicable market price, if any) +\f[B]\f[CB]-V --market\f[B]\f[R] +convert amounts to their market value in default valuation commodities .TP +\f[B]\f[CB]-X --exchange=COMM\f[B]\f[R] +convert amounts to their market value in commodity COMM +.TP +\f[B]\f[CB]--value\f[B]\f[R] +convert amounts to cost or market value, more flexibly than -B/-V/-X +.TP +\f[B]\f[CB]--infer-value\f[B]\f[R] +with -V/-X/--value, also infer market prices from transactions +.TP \f[B]\f[CB]--auto\f[B]\f[R] apply automated posting rules to modify transactions. .TP @@ -1671,47 +1678,139 @@ .fi .SS Valuation .PP -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). -.PP -We call this \[dq]valuation\[dq], and it is controlled by the -\f[C]--value=VALUATIONTYPE[,COMMODITY]\f[R] 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: -.IP \[bu] 2 -\f[C]-B\f[R] to convert to cost/sale amount, or -.IP \[bu] 2 -\f[C]-V\f[R] to convert to market value in your base currency. -Or occasionally, -.IP \[bu] 2 -\f[C]-X COMMODITY\f[R] to convert to market value in some other -currency. +Instead of reporting amounts in their original commodity, hledger can +convert them to cost/sale amount (using the conversion rate recorded in +the transaction), or to market value (using some market price on a +certain date). +This is controlled by the \f[C]--value=TYPE[,COMMODITY]\f[R] option, but +we also provide the simpler \f[C]-B\f[R]/\f[C]-V\f[R]/\f[C]-X\f[R] +flags, and usually one of those is all you need. .SS -B: Cost .PP The \f[C]-B/--cost\f[R] flag converts amounts to their cost or sale amount at transaction time, if they have a transaction price specified. -(It is equivalent to \f[C]--value=cost\f[R].) .SS -V: Value .PP -The \f[C]-V/--market\f[R] flag converts reported amounts to market value -in their \f[I]default valuation commodity\f[R], using the market prices -in effect on a \f[I]default valuation date\f[R]. -(More on these below.) +The \f[C]-V/--market\f[R] flag converts amounts to market value in their +default \f[I]valuation commodity\f[R], using the market prices in effect +on the \f[I]valuation date(s)\f[R], if any. +More on these in a minute. +.SS -X: Value in specified commodity .PP -The default valuation commodity is the one referenced in the latest -applicable market price dated on or before the valuation date. -Typically your P declarations or currency exchange transactions -reference a single base currency, and -V will pick that. +The \f[C]-X/--exchange=COMM\f[R] option is like \f[C]-V\f[R], except you +tell it which currency you want to convert to, and it tries to convert +everything to that. +.SS Valuation date .PP -The default valuation date is today for single period reports -(equivalent to \f[C]--value=now\f[R]), or the last day of each subperiod -for multiperiod reports (equivalent to \f[C]--value=end\f[R]). +Since market prices can change from day to day, market value reports +have a valuation date (or more than one), which determines which market +prices will be used. .PP -An example: +For single period reports, if an explicit report end date is specified, +that will be used as the valuation date; otherwise the valuation date is +\[dq]today\[dq]. +.PP +For multiperiod reports, each column/period is valued on the last day of +the period. +.SS Market prices +.PP +\f[I](experimental)\f[R] +.PP +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 : +.IP "1." 3 +A \f[I]declared market price\f[R] or \f[I]inferred market price\f[R]: +A\[aq]s latest market price in B on or before the valuation date as +declared by a P directive, or (if the \f[C]--infer-value\f[R] flag is +used) inferred from transaction prices. +.IP "2." 3 +A \f[I]reverse market price\f[R]: the inverse of a declared or inferred +market price from B to A. +.IP "3." 3 +A \f[I]chained market price\f[R]: a synthetic price formed by combining +the shortest chain of market prices (any of the above types) leading +from A to B. +.PP +Amounts for which no applicable market price can be found, are not +converted. +.SS --infer-value: market prices from transactions +.PP +\f[I](experimental)\f[R] +.PP +Normally, market value in hledger is fully controlled by, and requires, +P directives 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 as additional market prices (as Ledger does) ? +We could produce value reports without needing P directives at all. +.PP +Adding the \f[C]--infer-value\f[R] flag to \f[C]-V\f[R], \f[C]-X\f[R] or +\f[C]--value\f[R] enables this. +So for example, \f[C]hledger bs -V --infer-value\f[R] will get market +prices both from P directives and from transactions. +.PP +There is a downside: value reports can sometimes be affected in +confusing/undesired ways by your journal entries. +If this happens to you, read all of this Valuation section carefully, +and try adding \f[C]--debug\f[R] or \f[C]--debug=2\f[R] to troubleshoot. +.PP +\f[C]--infer-value\f[R] can infer market prices from: +.IP \[bu] 2 +multicommodity transactions with explicit prices +(\f[C]\[at]\f[R]/\f[C]\[at]\[at]\f[R]) +.IP \[bu] 2 +multicommodity transactions with implicit prices (no \f[C]\[at]\f[R], +two commodities, unbalanced). +(With these, the order of postings matters. +\f[C]hledger print -x\f[R] can be useful for troubleshooting.) +.IP \[bu] 2 +but not, currently, from \[dq]more correct\[dq] multicommodity +transactions (no \f[C]\[at]\f[R], multiple commodities, balanced). +.SS Valuation commodity +.PP +\f[I](experimental)\f[R] +.PP +\f[B]When you specify a valuation commodity (\f[CB]-X COMM\f[B] or +\f[CB]--value TYPE,COMM\f[B]):\f[R] +.PD 0 +.P +.PD +hledger will convert all amounts to COMM, wherever it can find a +suitable market price (including by reversing or chaining prices). +.PP +\f[B]When you leave the valuation commodity unspecified (\f[CB]-V\f[B] +or \f[CB]--value TYPE\f[B]):\f[R] +.PD 0 +.P +.PD +For each commodity A, hledger picks a default valuation commodity as +follows, in this order of preference: +.IP "1." 3 +The price commodity from the latest P-declared market price for A on or +before valuation date. +.IP "2." 3 +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.) +.IP "3." 3 +If there are no P directives at all (any commodity or date) and the +\f[C]--infer-value\f[R] flag is used: the price commodity from the +latest transaction-inferred price for A on or before valuation date. +.PP +This means: +.IP \[bu] 2 +If you have P directives, they determine which commodities \f[C]-V\f[R] +will convert, and to what. +.IP \[bu] 2 +If you have no P directives, and use the \f[C]--infer-value\f[R] flag, +transaction prices determine it. +.PP +Amounts for which no valuation commodity can be found are not converted. +.SS Simple valuation examples +.PP +Here are some quick examples of \f[C]-V\f[R]: .IP .nf \f[C] @@ -1755,39 +1854,8 @@ $103.00 assets:euros \f[R] .fi -.SS -X: Market value in specified commodity -.PP -The \f[C]-X/--exchange\f[R] option is like \f[C]-V\f[R], except it -specifies the target commodity you would like to convert to. -(It is equivalent to \f[C]--value=now,COMM\f[R] or -\f[C]--value=end,COMM\f[R].) -.SS Market prices -.PP -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: -.IP "1." 3 -a \f[I]declared market price\f[R] - the latest P directive specifying -the exchange rate from A to B, dated on or before the valuation date. -.IP "2." 3 -a \f[I]transaction-implied market price\f[R] - a market price matching -the transaction price used in the latest transaction where A is -converted to B, dated on or before the valuation date. -(\f[I]since hledger 1.18; experimental\f[R]) -.IP "3." 3 -a \f[I]reverse declared market price\f[R] - calculated by inverting a -declared market price from B to A. -.IP "4." 3 -a \f[I]reverse transaction-implied market price\f[R] - calculated by -inverting a transaction-implied market price from B to A. -.IP "5." 3 -an \f[I]indirect market price\f[R] - calculated by combining the -shortest chain of market prices (any of the above types) leading from A -to B. .SS --value: Flexible valuation .PP -\f[I](experimental, added 201905)\f[R] -.PP \f[C]-B\f[R], \f[C]-V\f[R] and \f[C]-X\f[R] are special cases of the more general \f[C]--value\f[R] option: .IP @@ -1804,52 +1872,38 @@ \f[R] .fi .PP -The TYPE part basically selects either \[dq]cost\[dq], or \[dq]market -value\[dq] plus a valuation date: +The TYPE part selects cost or value and valuation date: .TP \f[B]\f[CB]--value=cost\f[B]\f[R] Convert amounts to cost, using the prices recorded in transactions. .TP \f[B]\f[CB]--value=then\f[B]\f[R] -Convert amounts to their value in a default valuation commodity, using +Convert amounts to their value in the default valuation commodity, using market prices on each posting\[aq]s date. This is currently supported only by the print and register commands. .TP \f[B]\f[CB]--value=end\f[B]\f[R] -Convert amounts to their value in a default valuation commodity, using +Convert amounts to their value in the default valuation commodity, using market prices on the last day of the report period (or if unspecified, the journal\[aq]s end date); or in multiperiod reports, market prices on the last day of each subperiod. .TP \f[B]\f[CB]--value=now\f[B]\f[R] -Convert amounts to their value in default valuation commodity using +Convert amounts to their value in the default valuation commodity using current market prices (as of when report is generated). .TP \f[B]\f[CB]--value=YYYY-MM-DD\f[B]\f[R] -Convert amounts to their value in default valuation commodity using +Convert amounts to their value in the default valuation commodity using market prices on this date. .PP -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, this -will usually do what you want. -.PP To select a different valuation commodity, add the optional \f[C],COMM\f[R] part: a comma, then the target commodity\[aq]s symbol. Eg: \f[B]\f[CB]--value=now,EUR\f[B]\f[R]. -hledger will do its best to convert amounts to this commodity, using: -.IP \[bu] 2 -declared prices (from source commodity to valuation commodity) -.IP \[bu] 2 -reverse prices (declared prices from valuation to source commodity, -inverted) -.IP \[bu] 2 -indirect prices (prices calculated from the shortest chain of declared -or reverse prices from source to valuation commodity) -.PP -in that order. +hledger will do its best to convert amounts to this commodity, deducing +market prices as described above. +.SS More valuation examples .PP -Here are some examples showing the effect of \f[C]--value\f[R] as seen +Here are some examples showing the effect of \f[C]--value\f[R], as seen with \f[C]print\f[R]: .IP .nf @@ -1997,13 +2051,12 @@ b -0.50A \f[R] .fi -.SS Effect of --value on reports +.SS Effect of valuation on reports .PP -Here is a reference for how \f[C]--value\f[R] currently affects each -part of hledger\[aq]s reports. -It\[aq]s work in progress, but may be useful for troubleshooting or -reporting bugs. -See also the definitions and notes below. +Here is a reference for how valuation is supposed to affect each part of +hledger\[aq]s reports (and a glossary). +(It\[aq]s wide, you\[aq]ll have to scroll sideways.) It may be useful +when troubleshooting. If you find problems, please report them, ideally with a reproducible example. Related: #329, #1083. @@ -2254,7 +2307,7 @@ T} .TE .PP -\f[B]Additional notes\f[R] +\f[B]Glossary:\f[R] .TP \f[I]cost\f[R] calculated using price(s) recorded in the transaction(s). diff --git a/hledger.cabal b/hledger.cabal --- a/hledger.cabal +++ b/hledger.cabal @@ -4,10 +4,10 @@ -- -- see: https://github.com/sol/hpack -- --- hash: 7c3d5511ae3e0b87af5d89a1f2b127fb9c33cacb05894148d9169c77a6309362 +-- hash: a143aaa15c1e629724eac79aa6eb29b5a1af4432366e8855450a1e53ee8c30e4 name: hledger -version: 1.18 +version: 1.18.1 synopsis: Command-line interface for the hledger accounting system description: The command-line interface for the hledger accounting system. Its basic function is to read a plain text file describing @@ -144,7 +144,7 @@ other-modules: Paths_hledger ghc-options: -Wall -fno-warn-unused-do-bind -fno-warn-name-shadowing -fno-warn-missing-signatures -fno-warn-type-defaults -fno-warn-orphans -optP-Wno-nonportable-include-path - cpp-options: -DVERSION="1.18" + cpp-options: -DVERSION="1.18.1" build-depends: Decimal >=0.5.1 , Diff @@ -161,7 +161,7 @@ , filepath , hashable >=1.2.4 , haskeline >=0.6 - , hledger-lib >=1.18 && <1.19 + , hledger-lib >=1.18.1 && <1.19 , lucid , math-functions >=0.3.3.0 , megaparsec >=7.0.0 && <8.1 @@ -197,7 +197,7 @@ hs-source-dirs: app ghc-options: -Wall -fno-warn-unused-do-bind -fno-warn-name-shadowing -fno-warn-missing-signatures -fno-warn-type-defaults -fno-warn-orphans -optP-Wno-nonportable-include-path - cpp-options: -DVERSION="1.18" + cpp-options: -DVERSION="1.18.1" build-depends: Decimal >=0.5.1 , aeson @@ -213,7 +213,7 @@ , filepath , haskeline >=0.6 , hledger - , hledger-lib >=1.18 && <1.19 + , hledger-lib >=1.18.1 && <1.19 , math-functions >=0.3.3.0 , megaparsec >=7.0.0 && <8.1 , mtl >=2.2.1 @@ -249,7 +249,7 @@ hs-source-dirs: test ghc-options: -Wall -fno-warn-unused-do-bind -fno-warn-name-shadowing -fno-warn-missing-signatures -fno-warn-type-defaults -fno-warn-orphans -optP-Wno-nonportable-include-path - cpp-options: -DVERSION="1.18" + cpp-options: -DVERSION="1.18.1" build-depends: Decimal >=0.5.1 , aeson @@ -265,7 +265,7 @@ , filepath , haskeline >=0.6 , hledger - , hledger-lib >=1.18 && <1.19 + , hledger-lib >=1.18.1 && <1.19 , math-functions >=0.3.3.0 , megaparsec >=7.0.0 && <8.1 , mtl >=2.2.1 @@ -315,7 +315,7 @@ , filepath , haskeline >=0.6 , hledger - , hledger-lib >=1.18 && <1.19 + , hledger-lib >=1.18.1 && <1.19 , html , math-functions >=0.3.3.0 , megaparsec >=7.0.0 && <8.1 diff --git a/hledger.info b/hledger.info --- a/hledger.info +++ b/hledger.info @@ -3,8 +3,8 @@  File: hledger.info, Node: Top, Next: COMMON TASKS, Up: (dir) -hledger(1) hledger 1.18 -*********************** +hledger(1) hledger 1.18.1 +************************* hledger - a command-line accounting tool @@ -610,12 +610,21 @@ hledger-ui/hledger-web) '-B --cost' - convert amounts to their cost at transaction time (using the - transaction price, if any) -'-V --value' + convert amounts to their cost/selling amount at transaction time +'-V --market' - convert amounts to their market value on the report end date (using - the most recent applicable market price, if any) + convert amounts to their market value in default valuation + commodities +'-X --exchange=COMM' + + convert amounts to their market value in commodity COMM +'--value' + + convert amounts to cost or market value, more flexibly than + -B/-V/-X +'--infer-value' + + with -V/-X/-value, also infer market prices from transactions '--auto' apply automated posting rules to modify transactions. @@ -1363,30 +1372,26 @@ 2.17 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. +Instead of reporting amounts in their original commodity, hledger can +convert them to cost/sale amount (using the conversion rate recorded in +the transaction), or to market value (using some market price on a +certain date). This is controlled by the '--value=TYPE[,COMMODITY]' +option, but we also provide the simpler '-B'/'-V'/'-X' flags, and +usually one of those is all you need. * Menu: * -B Cost:: * -V Value:: -* -X Market value in specified commodity:: +* -X Value in specified commodity:: +* Valuation date:: * Market prices:: +* --infer-value market prices from transactions:: +* Valuation commodity:: +* Simple valuation examples:: * --value Flexible valuation:: -* Effect of --value on reports:: +* More valuation examples:: +* Effect of valuation on reports::  File: hledger.info, Node: -B Cost, Next: -V Value, Up: Valuation @@ -1395,30 +1400,155 @@ --------------- The '-B/--cost' flag converts amounts to their cost or sale amount at -transaction time, if they have a transaction price specified. (It is -equivalent to '--value=cost'.) +transaction time, if they have a transaction price specified.  -File: hledger.info, Node: -V Value, Next: -X Market value in specified commodity, Prev: -B Cost, Up: Valuation +File: hledger.info, Node: -V Value, Next: -X Value in specified commodity, Prev: -B Cost, Up: Valuation 2.17.2 -V: Value ---------------- -The '-V/--market' flag converts reported amounts to market value in -their _default valuation commodity_, using the market prices in effect -on a _default valuation date_. (More on these below.) +The '-V/--market' flag converts amounts to market value in their default +_valuation commodity_, using the market prices in effect on the +_valuation date(s)_, if any. More on these in a minute. - The default valuation commodity is the one referenced in the latest -applicable market price dated on or before the valuation date. -Typically your P declarations or currency exchange transactions -reference a single base currency, and -V will pick that. + +File: hledger.info, Node: -X Value in specified commodity, Next: Valuation date, Prev: -V Value, Up: Valuation - The default valuation date is today for single period reports -(equivalent to '--value=now'), or the last day of each subperiod for -multiperiod reports (equivalent to '--value=end'). +2.17.3 -X: Value in specified commodity +--------------------------------------- - An example: +The '-X/--exchange=COMM' option is like '-V', except you tell it which +currency you want to convert to, and it tries to convert everything to +that. + +File: hledger.info, Node: Valuation date, Next: Market prices, Prev: -X Value in specified commodity, Up: Valuation + +2.17.4 Valuation date +--------------------- + +Since market prices can change from day to day, market value reports +have a valuation date (or more than one), which determines which market +prices will be used. + + For single period reports, if an explicit report end date is +specified, that will be used as the valuation date; otherwise the +valuation date is "today". + + For multiperiod reports, each column/period is valued on the last day +of the period. + + +File: hledger.info, Node: Market prices, Next: --infer-value market prices from transactions, Prev: Valuation date, Up: Valuation + +2.17.5 Market prices +-------------------- + +_(experimental)_ + + 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 : + + 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, or (if the '--infer-value' flag is used) inferred from + transaction prices. + + 2. A _reverse market price_: the inverse of a declared or inferred + market price from B to A. + + 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. + + Amounts for which no applicable market price can be found, are not +converted. + + +File: hledger.info, Node: --infer-value market prices from transactions, Next: Valuation commodity, Prev: Market prices, Up: Valuation + +2.17.6 -infer-value: market prices from transactions +---------------------------------------------------- + +_(experimental)_ + + Normally, market value in hledger is fully controlled by, and +requires, P directives 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 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: value reports can sometimes be affected in +confusing/undesired ways by your journal entries. If this happens to +you, read all of this Valuation section carefully, and try adding +'--debug' or '--debug=2' to troubleshoot. + + '--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" multicommodity transactions + (no '@', multiple commodities, balanced). + + +File: hledger.info, Node: Valuation commodity, Next: Simple valuation examples, Prev: --infer-value market prices from transactions, Up: Valuation + +2.17.7 Valuation commodity +-------------------------- + +_(experimental)_ + + *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). + + *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: + + 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. + + This means: + + * If you have P directives, they determine which commodities '-V' + will convert, and to what. + + * If you have no P directives, and use the '--infer-value' flag, + transaction prices determine it. + + Amounts for which no valuation commodity can be found are not +converted. + + +File: hledger.info, Node: Simple valuation examples, Next: --value Flexible valuation, Prev: Valuation commodity, Up: Valuation + +2.17.8 Simple valuation examples +-------------------------------- + +Here are some quick examples of '-V': + ; one euro is worth this many dollars from nov 1 P 2016/11/01 € $1.10 @@ -1447,52 +1577,12 @@ $103.00 assets:euros  -File: hledger.info, Node: -X Market value in specified commodity, Next: Market prices, Prev: -V Value, Up: Valuation - -2.17.3 -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'.) - - -File: hledger.info, Node: Market prices, Next: --value Flexible valuation, Prev: -X Market value in specified commodity, Up: Valuation - -2.17.4 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 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 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. - - -File: hledger.info, Node: --value Flexible valuation, Next: Effect of --value on reports, Prev: Market prices, Up: Valuation +File: hledger.info, Node: --value Flexible valuation, Next: More valuation examples, Prev: Simple valuation examples, Up: Valuation -2.17.5 -value: Flexible valuation +2.17.9 -value: Flexible valuation --------------------------------- -_(experimental, added 201905)_ - - '-B', '-V' and '-X' are special cases of the more general '--value' +'-B', '-V' and '-X' are special cases of the more general '--value' option: --value=TYPE[,COMM] TYPE is cost, then, end, now or YYYY-MM-DD. @@ -1504,51 +1594,43 @@ - default valuation commodity (or COMM) using current market prices - default valuation commodity (or COMM) using market prices at some date - The TYPE part basically selects either "cost", or "market value" plus -a valuation date: + The TYPE part selects cost or value and valuation date: '--value=cost' Convert amounts to cost, using the prices recorded in transactions. '--value=then' - Convert amounts to their value in a default valuation commodity, + Convert amounts to their value in the default valuation commodity, using market prices on each posting's date. This is currently supported only by the print and register commands. '--value=end' - Convert amounts to their value in a default valuation commodity, + Convert amounts to their value in the default valuation commodity, using market prices on the last day of the report period (or if unspecified, the journal's end date); or in multiperiod reports, market prices on the last day of each subperiod. '--value=now' - Convert amounts to their value in default valuation commodity using - current market prices (as of when report is generated). + Convert amounts to their value in the default valuation commodity + using current market prices (as of when report is generated). '--value=YYYY-MM-DD' - Convert amounts to their value in default valuation commodity using - market prices on this date. - - 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, this will usually do what -you want. + Convert amounts to their value in the default valuation commodity + using market prices on this date. To select a different valuation commodity, add the optional ',COMM' part: a comma, then the target commodity's symbol. Eg: *'--value=now,EUR'*. hledger will do its best to convert amounts to -this commodity, using: +this commodity, deducing market prices as described above. - * declared prices (from source commodity to valuation commodity) - * reverse prices (declared prices from valuation to source commodity, - inverted) - * indirect prices (prices calculated from the shortest chain of - declared or reverse prices from source to valuation commodity) + +File: hledger.info, Node: More valuation examples, Next: Effect of valuation on reports, Prev: --value Flexible valuation, Up: Valuation - in that order. +2.17.10 More valuation examples +------------------------------- - Here are some examples showing the effect of '--value' as seen with +Here are some examples showing the effect of '--value', as seen with 'print': P 2000-01-01 A 1 B @@ -1657,16 +1739,16 @@ b -0.50A  -File: hledger.info, Node: Effect of --value on reports, Prev: --value Flexible valuation, Up: Valuation +File: hledger.info, Node: Effect of valuation on reports, Prev: More valuation examples, Up: Valuation -2.17.6 Effect of -value on reports ----------------------------------- +2.17.11 Effect of valuation on reports +-------------------------------------- -Here is a reference for how '--value' currently affects each part of -hledger's reports. It's work in progress, but may be useful for -troubleshooting or reporting bugs. See also the definitions and notes -below. If you find problems, please report them, ideally with a -reproducible example. Related: #329, #1083. +Here is a reference for how valuation is supposed to affect each part of +hledger's reports (and a glossary). (It's wide, you'll have to scroll +sideways.) It may be useful when troubleshooting. If you find +problems, please report them, ideally with a reproducible example. +Related: #329, #1083. Report '-B', '-V', '-X' '--value=then' '--value=end' '--value=DATE', type '--value=cost' '--value=now' @@ -1739,7 +1821,7 @@ totals totals totals column totals - *Additional notes* + *Glossary:* _cost_ @@ -3776,187 +3858,197 @@  Tag Table: Node: Top68 -Node: COMMON TASKS2315 -Ref: #common-tasks2427 -Node: Getting help2834 -Ref: #getting-help2966 -Node: Constructing command lines3519 -Ref: #constructing-command-lines3711 -Node: Starting a journal file4408 -Ref: #starting-a-journal-file4606 -Node: Setting opening balances5794 -Ref: #setting-opening-balances5990 -Node: Recording transactions9131 -Ref: #recording-transactions9311 -Node: Reconciling9867 -Ref: #reconciling10010 -Node: Reporting12267 -Ref: #reporting12407 -Node: Migrating to a new file16406 -Ref: #migrating-to-a-new-file16554 -Node: OPTIONS16853 -Ref: #options16960 -Node: General options17330 -Ref: #general-options17455 -Node: Command options20225 -Ref: #command-options20376 -Node: Command arguments20774 -Ref: #command-arguments20921 -Node: Queries21801 -Ref: #queries21956 -Node: Special characters in arguments and queries25918 -Ref: #special-characters-in-arguments-and-queries26146 -Node: More escaping26597 -Ref: #more-escaping26759 -Node: Even more escaping27055 -Ref: #even-more-escaping27249 -Node: Less escaping27920 -Ref: #less-escaping28082 -Node: Unicode characters28327 -Ref: #unicode-characters28509 -Node: Input files29921 -Ref: #input-files30064 -Node: Output destination31993 -Ref: #output-destination32145 -Node: Output format32570 -Ref: #output-format32720 -Node: Regular expressions34302 -Ref: #regular-expressions34459 -Node: Smart dates36195 -Ref: #smart-dates36346 -Node: Report start & end date37707 -Ref: #report-start-end-date37879 -Node: Report intervals39376 -Ref: #report-intervals39541 -Node: Period expressions39931 -Ref: #period-expressions40091 -Node: Depth limiting44227 -Ref: #depth-limiting44371 -Node: Pivoting44703 -Ref: #pivoting44826 -Node: Valuation46502 -Ref: #valuation46604 -Node: -B Cost47524 -Ref: #b-cost47628 -Node: -V Value47800 -Ref: #v-value47953 -Node: -X Market value in specified commodity49226 -Ref: #x-market-value-in-specified-commodity49445 -Node: Market prices49623 -Ref: #market-prices49808 -Node: --value Flexible valuation50733 -Ref: #value-flexible-valuation50934 -Node: Effect of --value on reports55439 -Ref: #effect-of---value-on-reports55620 -Node: COMMANDS61166 -Ref: #commands61274 -Node: accounts62358 -Ref: #accounts62456 -Node: activity63155 -Ref: #activity63265 -Node: add63648 -Ref: #add63747 -Node: balance66486 -Ref: #balance66597 -Node: Classic balance report68055 -Ref: #classic-balance-report68228 -Node: Customising the classic balance report69597 -Ref: #customising-the-classic-balance-report69825 -Node: Colour support71901 -Ref: #colour-support72068 -Node: Flat mode72241 -Ref: #flat-mode72389 -Node: Depth limited balance reports72802 -Ref: #depth-limited-balance-reports72987 -Node: Percentages73443 -Ref: #percentages73609 -Node: Multicolumn balance report74746 -Ref: #multicolumn-balance-report74926 -Node: Budget report80188 -Ref: #budget-report80331 -Node: Nested budgets85597 -Ref: #nested-budgets85709 -Ref: #output-format-189190 -Node: balancesheet89387 -Ref: #balancesheet89523 -Node: balancesheetequity90989 -Ref: #balancesheetequity91138 -Node: cashflow91861 -Ref: #cashflow91989 -Node: check-dates93168 -Ref: #check-dates93295 -Node: check-dupes93574 -Ref: #check-dupes93698 -Node: close93991 -Ref: #close94105 -Node: close usage95627 -Ref: #close-usage95720 -Node: commodities98533 -Ref: #commodities98660 -Node: descriptions98742 -Ref: #descriptions98870 -Node: diff99051 -Ref: #diff99157 -Node: files100204 -Ref: #files100304 -Node: help100451 -Ref: #help100551 -Node: import101632 -Ref: #import101746 -Node: Importing balance assignments102639 -Ref: #importing-balance-assignments102787 -Node: incomestatement103436 -Ref: #incomestatement103569 -Node: notes105056 -Ref: #notes105169 -Node: payees105295 -Ref: #payees105401 -Node: prices105559 -Ref: #prices105665 -Node: print106006 -Ref: #print106116 -Node: print-unique110902 -Ref: #print-unique111028 -Node: register111313 -Ref: #register111440 -Node: Custom register output115612 -Ref: #custom-register-output115741 -Node: register-match117078 -Ref: #register-match117212 -Node: rewrite117563 -Ref: #rewrite117678 -Node: Re-write rules in a file119533 -Ref: #re-write-rules-in-a-file119667 -Node: Diff output format120877 -Ref: #diff-output-format121046 -Node: rewrite vs print --auto122138 -Ref: #rewrite-vs.-print---auto122317 -Node: roi122873 -Ref: #roi122971 -Node: stats123983 -Ref: #stats124082 -Node: tags124870 -Ref: #tags124968 -Node: test125262 -Ref: #test125370 -Node: Add-on commands126117 -Ref: #add-on-commands126234 -Node: ui127577 -Ref: #ui127665 -Node: web127719 -Ref: #web127822 -Node: iadd127938 -Ref: #iadd128049 -Node: interest128131 -Ref: #interest128238 -Node: ENVIRONMENT128478 -Ref: #environment128590 -Node: FILES129419 -Ref: #files-1129522 -Node: LIMITATIONS129735 -Ref: #limitations129854 -Node: TROUBLESHOOTING130596 -Ref: #troubleshooting130709 +Node: COMMON TASKS2319 +Ref: #common-tasks2431 +Node: Getting help2838 +Ref: #getting-help2970 +Node: Constructing command lines3523 +Ref: #constructing-command-lines3715 +Node: Starting a journal file4412 +Ref: #starting-a-journal-file4610 +Node: Setting opening balances5798 +Ref: #setting-opening-balances5994 +Node: Recording transactions9135 +Ref: #recording-transactions9315 +Node: Reconciling9871 +Ref: #reconciling10014 +Node: Reporting12271 +Ref: #reporting12411 +Node: Migrating to a new file16410 +Ref: #migrating-to-a-new-file16558 +Node: OPTIONS16857 +Ref: #options16964 +Node: General options17334 +Ref: #general-options17459 +Node: Command options20413 +Ref: #command-options20564 +Node: Command arguments20962 +Ref: #command-arguments21109 +Node: Queries21989 +Ref: #queries22144 +Node: Special characters in arguments and queries26106 +Ref: #special-characters-in-arguments-and-queries26334 +Node: More escaping26785 +Ref: #more-escaping26947 +Node: Even more escaping27243 +Ref: #even-more-escaping27437 +Node: Less escaping28108 +Ref: #less-escaping28270 +Node: Unicode characters28515 +Ref: #unicode-characters28697 +Node: Input files30109 +Ref: #input-files30252 +Node: Output destination32181 +Ref: #output-destination32333 +Node: Output format32758 +Ref: #output-format32908 +Node: Regular expressions34490 +Ref: #regular-expressions34647 +Node: Smart dates36383 +Ref: #smart-dates36534 +Node: Report start & end date37895 +Ref: #report-start-end-date38067 +Node: Report intervals39564 +Ref: #report-intervals39729 +Node: Period expressions40119 +Ref: #period-expressions40279 +Node: Depth limiting44415 +Ref: #depth-limiting44559 +Node: Pivoting44891 +Ref: #pivoting45014 +Node: Valuation46690 +Ref: #valuation46792 +Node: -B Cost47481 +Ref: #b-cost47585 +Node: -V Value47718 +Ref: #v-value47864 +Node: -X Value in specified commodity48059 +Ref: #x-value-in-specified-commodity48258 +Node: Valuation date48407 +Ref: #valuation-date48575 +Node: Market prices48985 +Ref: #market-prices49165 +Node: --infer-value market prices from transactions49942 +Ref: #infer-value-market-prices-from-transactions50191 +Node: Valuation commodity51473 +Ref: #valuation-commodity51682 +Node: Simple valuation examples52908 +Ref: #simple-valuation-examples53110 +Node: --value Flexible valuation53769 +Ref: #value-flexible-valuation53977 +Node: More valuation examples55924 +Ref: #more-valuation-examples56133 +Node: Effect of valuation on reports58138 +Ref: #effect-of-valuation-on-reports58326 +Node: COMMANDS63847 +Ref: #commands63955 +Node: accounts65039 +Ref: #accounts65137 +Node: activity65836 +Ref: #activity65946 +Node: add66329 +Ref: #add66428 +Node: balance69167 +Ref: #balance69278 +Node: Classic balance report70736 +Ref: #classic-balance-report70909 +Node: Customising the classic balance report72278 +Ref: #customising-the-classic-balance-report72506 +Node: Colour support74582 +Ref: #colour-support74749 +Node: Flat mode74922 +Ref: #flat-mode75070 +Node: Depth limited balance reports75483 +Ref: #depth-limited-balance-reports75668 +Node: Percentages76124 +Ref: #percentages76290 +Node: Multicolumn balance report77427 +Ref: #multicolumn-balance-report77607 +Node: Budget report82869 +Ref: #budget-report83012 +Node: Nested budgets88278 +Ref: #nested-budgets88390 +Ref: #output-format-191871 +Node: balancesheet92068 +Ref: #balancesheet92204 +Node: balancesheetequity93670 +Ref: #balancesheetequity93819 +Node: cashflow94542 +Ref: #cashflow94670 +Node: check-dates95849 +Ref: #check-dates95976 +Node: check-dupes96255 +Ref: #check-dupes96379 +Node: close96672 +Ref: #close96786 +Node: close usage98308 +Ref: #close-usage98401 +Node: commodities101214 +Ref: #commodities101341 +Node: descriptions101423 +Ref: #descriptions101551 +Node: diff101732 +Ref: #diff101838 +Node: files102885 +Ref: #files102985 +Node: help103132 +Ref: #help103232 +Node: import104313 +Ref: #import104427 +Node: Importing balance assignments105320 +Ref: #importing-balance-assignments105468 +Node: incomestatement106117 +Ref: #incomestatement106250 +Node: notes107737 +Ref: #notes107850 +Node: payees107976 +Ref: #payees108082 +Node: prices108240 +Ref: #prices108346 +Node: print108687 +Ref: #print108797 +Node: print-unique113583 +Ref: #print-unique113709 +Node: register113994 +Ref: #register114121 +Node: Custom register output118293 +Ref: #custom-register-output118422 +Node: register-match119759 +Ref: #register-match119893 +Node: rewrite120244 +Ref: #rewrite120359 +Node: Re-write rules in a file122214 +Ref: #re-write-rules-in-a-file122348 +Node: Diff output format123558 +Ref: #diff-output-format123727 +Node: rewrite vs print --auto124819 +Ref: #rewrite-vs.-print---auto124998 +Node: roi125554 +Ref: #roi125652 +Node: stats126664 +Ref: #stats126763 +Node: tags127551 +Ref: #tags127649 +Node: test127943 +Ref: #test128051 +Node: Add-on commands128798 +Ref: #add-on-commands128915 +Node: ui130258 +Ref: #ui130346 +Node: web130400 +Ref: #web130503 +Node: iadd130619 +Ref: #iadd130730 +Node: interest130812 +Ref: #interest130919 +Node: ENVIRONMENT131159 +Ref: #environment131271 +Node: FILES132100 +Ref: #files-1132203 +Node: LIMITATIONS132416 +Ref: #limitations132535 +Node: TROUBLESHOOTING133277 +Ref: #troubleshooting133390  End Tag Table diff --git a/hledger.txt b/hledger.txt --- a/hledger.txt +++ b/hledger.txt @@ -515,13 +515,22 @@ hledger-ui/hledger-web) -B --cost - convert amounts to their cost at transaction time (using the - transaction price, if any) + convert amounts to their cost/selling amount at transaction time - -V --value - convert amounts to their market value on the report end date - (using the most recent applicable market price, if any) + -V --market + convert amounts to their market value in default valuation com- + modities + -X --exchange=COMM + convert amounts to their market value in commodity COMM + + --value + convert amounts to cost or market value, more flexibly than + -B/-V/-X + + --infer-value + with -V/-X/--value, also infer market prices from transactions + --auto apply automated posting rules to modify transactions. --forecast @@ -934,7 +943,6 @@ 2004/10/1, 2004-01-01, exact date, several separators allowed. Year 2004.9.1 is 4+ digits, month is 1-12, day is 1-31 2004 start of year - 2004/10 start of month 10/1 month and day in current year 21 day in current month @@ -1067,6 +1075,8 @@ -p "weekly from 2009/1/1 starts on 2008/12/29, closest preceding Mon- to 2009/4/1" day + + -p "monthly in starts on 2018/11/01 2008/11/25" -p "quarterly from starts on 2009/04/01, ends on 2009/06/30, @@ -1179,45 +1189,128 @@ -2 EUR 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/commod- - ity at a specified date (using market prices inferred from your trans- - actions, or declared with P directives). + Instead of reporting amounts in their original commodity, hledger can + convert them to cost/sale amount (using the conversion rate recorded in + the transaction), or to market value (using some market price on a cer- + tain date). This is controlled by the --value=TYPE[,COMMODITY] option, + but we also provide the simpler -B/-V/-X flags, and usually one of + those is all you need. - We call this "valuation", and it is controlled by the --value=VALUA- - TIONTYPE[,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: Cost + The -B/--cost flag converts amounts to their cost or sale amount at + transaction time, if they have a transaction price specified. - o -B to convert to cost/sale amount, or + -V: Value + The -V/--market flag converts amounts to market value in their default + valuation commodity, using the market prices in effect on the valuation + date(s), if any. More on these in a minute. - o -V to convert to market value in your base currency. Or occasion- - ally, + -X: Value in specified commodity + The -X/--exchange=COMM option is like -V, except you tell it which cur- + rency you want to convert to, and it tries to convert everything to + that. - o -X COMMODITY to convert to market value in some other currency. + Valuation date + Since market prices can change from day to day, market value reports + have a valuation date (or more than one), which determines which market + prices will be used. - -B: Cost - The -B/--cost flag converts amounts to their cost or sale amount at - transaction time, if they have a transaction price specified. (It is - equivalent to --value=cost.) + For single period reports, if an explicit report end date is specified, + that will be used as the valuation date; otherwise the valuation date + is "today". - -V: Value - The -V/--market flag converts reported amounts to market value in their - default valuation commodity, using the market prices in effect on a de- - fault valuation date. (More on these below.) + For multiperiod reports, each column/period is valued on the last day + of the period. - The default valuation commodity is the one referenced in the latest ap- - plicable market price dated on or before the valuation date. Typically - your P declarations or currency exchange transactions reference a sin- - gle base currency, and -V will pick that. + Market prices + (experimental) - The default valuation date is today for single period reports (equiva- - lent to --value=now), or the last day of each subperiod for multiperiod - reports (equivalent to --value=end). + 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 : - An example: + 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 direc- + tive, or (if the --infer-value flag is used) inferred from transac- + tion prices. + 2. A reverse market price: the inverse of a declared or inferred market + price from B to A. + + 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. + + Amounts for which no applicable market price can be found, are not con- + verted. + + --infer-value: market prices from transactions + (experimental) + + Normally, market value in hledger is fully controlled by, and requires, + P directives 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 as additional market + prices (as Ledger does) ? We could produce value reports without need- + ing 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: value reports can sometimes be affected in confus- + ing/undesired ways by your journal entries. If this happens to you, + read all of this Valuation section carefully, and try adding --debug or + --debug=2 to troubleshoot. + + --infer-value can infer market prices from: + + o multicommodity transactions with explicit prices (@/@@) + + o multicommodity transactions with implicit prices (no @, two commodi- + ties, unbalanced). (With these, the order of postings matters. + hledger print -x can be useful for troubleshooting.) + + o but not, currently, from "more correct" multicommodity transactions + (no @, multiple commodities, balanced). + + Valuation commodity + (experimental) + + When you specify a valuation commodity (-X COMM or --value TYPE,COMM): + hledger will convert all amounts to COMM, wherever it can find a suit- + able market price (including by reversing or chaining prices). + + 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: + + 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. + + This means: + + o If you have P directives, they determine which commodities -V will + convert, and to what. + + o If you have no P directives, and use the --infer-value flag, transac- + tion prices determine it. + + Amounts for which no valuation commodity can be found are not con- + verted. + + Simple valuation examples + Here are some quick examples of -V: + ; one euro is worth this many dollars from nov 1 P 2016/11/01 EUR $1.10 @@ -1239,42 +1332,13 @@ $ hledger -f t.j bal -N euros -V -e 2016/11/4 $110.00 assets:euros - What are they worth after 2016/12/21 ? (no report end date specified, + What are they worth after 2016/12/21 ? (no report end date specified, defaults to today) $ hledger -f t.j bal -N euros -V $103.00 assets:euros - -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.) - - 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 specifying the ex- - change 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 used in the latest transaction where A is con- - verted 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 - (experimental, added 201905) - -B, -V and -X are special cases of the more general --value option: --value=TYPE[,COMM] TYPE is cost, then, end, now or YYYY-MM-DD. @@ -1286,52 +1350,39 @@ - default valuation commodity (or COMM) using current market prices - default valuation commodity (or COMM) using market prices at some date - The TYPE part basically selects either "cost", or "market value" plus a - valuation date: + The TYPE part selects cost or value and valuation date: --value=cost - Convert amounts to cost, using the prices recorded in transac- + Convert amounts to cost, using the prices recorded in transac- tions. --value=then - Convert amounts to their value in a default valuation commodity, - using market prices on each posting's date. This is currently - supported only by the print and register commands. + Convert amounts to their value in the default valuation commod- + ity, using market prices on each posting's date. This is cur- + rently supported only by the print and register commands. --value=end - Convert amounts to their value in a default valuation commodity, - using market prices on the last day of the report period (or if - unspecified, the journal's end date); or in multiperiod reports, - market prices on the last day of each subperiod. + Convert amounts to their value in the default valuation commod- + ity, using market prices on the last day of the report period + (or if unspecified, the journal's end date); or in multiperiod + reports, market prices on the last day of each subperiod. --value=now - Convert amounts to their value in default valuation commodity - using current market prices (as of when report is generated). + Convert amounts to their value in the default valuation commod- + ity using current market prices (as of when report is gener- + ated). --value=YYYY-MM-DD - Convert amounts to their value in default valuation commodity - using market prices on this date. - - The default valuation commodity is the commodity mentioned in the most - recent applicable market price declaration. When all your price decla- - rations lead to a single home currency, this will usually do what you - want. + Convert amounts to their value in the default valuation commod- + ity using market prices on this date. To select a different valuation commodity, add the optional ,COMM part: - a comma, then the target commodity's symbol. Eg: --value=now,EUR. - hledger will do its best to convert amounts to this commodity, using: - - o declared prices (from source commodity to valuation commodity) - - o reverse prices (declared prices from valuation to source commodity, - inverted) - - o indirect prices (prices calculated from the shortest chain of de- - clared or reverse prices from source to valuation commodity) - - in that order. + a comma, then the target commodity's symbol. Eg: --value=now,EUR. + hledger will do its best to convert amounts to this commodity, deducing + market prices as described above. - Here are some examples showing the effect of --value as seen with + More valuation examples + Here are some examples showing the effect of --value, as seen with print: P 2000-01-01 A 1 B @@ -1438,12 +1489,12 @@ a 0.50A b -0.50A - Effect of --value on reports - Here is a reference for how --value currently affects each part of - hledger's reports. It's work in progress, but may be useful for trou- - bleshooting or reporting bugs. See also the definitions and notes be- - low. If you find problems, please report them, ideally with a repro- - ducible example. Related: #329, #1083. + Effect of valuation on reports + Here is a reference for how valuation is supposed to affect each part + of hledger's reports (and a glossary). (It's wide, you'll have to + scroll sideways.) It may be useful when troubleshooting. If you find + problems, please report them, ideally with a reproducible example. Re- + lated: #329, #1083. Report type -B, -V, -X --value=then --value=end --value=DATE, --value=cost --value=now @@ -1492,9 +1543,6 @@ (with report postings be- fore report fore report report start interval and fore report start start -H) start - - - budget like bal- like bal- not supported like bal- like balances amounts with ances ances ances --budget @@ -1514,7 +1562,7 @@ totals totals totals tals - Additional notes + Glossary: cost calculated using price(s) recorded in the transaction(s). @@ -3231,4 +3279,4 @@ -hledger 1.18 June 2020 hledger(1) +hledger 1.18.1 June 2020 hledger(1)