hledger 1.18 → 1.18.1

raw patch · 30 files changed

+1925/−1457 lines, 30 filesdep ~hledger-libPVP: major bump suggested

API removals or changes: PVP suggests a major version bump

Dependency ranges changed: hledger-lib

API changes (from Hackage documentation)

Files

• CHANGES.md +17/−3
• Hledger/Cli/CliOptions.hs +2/−1
• Hledger/Cli/Commands/Print.hs +3/−1
• Hledger/Cli/CompoundBalanceCommand.hs +2/−2
• Hledger/Cli/Main.hs +1/−1
• embeddedfiles/hledger-ui.1 +13/−6
• embeddedfiles/hledger-ui.info +36/−27
• embeddedfiles/hledger-ui.txt +15/−6
• embeddedfiles/hledger-web.1 +14/−7
• embeddedfiles/hledger-web.info +33/−24
• embeddedfiles/hledger-web.txt +16/−7
• embeddedfiles/hledger.1 +152/−99
• embeddedfiles/hledger.info +384/−292
• embeddedfiles/hledger.txt +156/−108
• embeddedfiles/hledger_csv.5 +2/−2
• embeddedfiles/hledger_csv.info +71/−71
• embeddedfiles/hledger_csv.txt +2/−2
• embeddedfiles/hledger_journal.5 +12/−7
• embeddedfiles/hledger_journal.info +131/−126
• embeddedfiles/hledger_journal.txt +154/−149
• embeddedfiles/hledger_timeclock.5 +1/−1
• embeddedfiles/hledger_timeclock.info +2/−2
• embeddedfiles/hledger_timeclock.txt +1/−1
• embeddedfiles/hledger_timedot.5 +1/−1
• embeddedfiles/hledger_timedot.info +2/−2
• embeddedfiles/hledger_timedot.txt +1/−1
• hledger.1 +152/−99
• hledger.cabal +9/−9
• hledger.info +384/−292
• hledger.txt +156/−108

@@ -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.

@@ -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"

@@ -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

@@ -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

@@ -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

@@ -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.

@@ -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 

@@ -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)

@@ -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

@@ -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 

@@ -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)

@@ -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).

@@ -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 

@@ -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)

@@ -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

@@ -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 

@@ -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)

@@ -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

@@ -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 

@@ -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)

@@ -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"   

@@ -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 

@@ -78,4 +78,4 @@   -hledger 1.18                       June 2020              hledger_timeclock(5)+hledger 1.18.1                     June 2020              hledger_timeclock(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"   

@@ -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 

@@ -161,4 +161,4 @@   -hledger 1.18                       June 2020                hledger_timedot(5)+hledger 1.18.1                     June 2020                hledger_timedot(5)

@@ -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).

@@ -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

@@ -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 

@@ -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)