slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

;regen manuals

Browse Source
This commit is contained in:
Simon Michael 2020-06-19 14:36:58 -07:00
parent ec1a8c7296
commit fae1cc262e
9 changed files with 1130 additions and 874 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
hledger-ui/hledger-ui.1
View File

@ -139,12 +139,19 @@ show items with zero amount, normally hidden (and vice-versa in
hledger-ui/hledger-web) hledger-ui/hledger-web)
.TP .TP
\f[B]\f[CB]-B --cost\f[B]\f[R] \f[B]\f[CB]-B --cost\f[B]\f[R]
convert amounts to their cost at transaction time (using the transaction convert amounts to their cost/selling amount at transaction time
price, if any)
.TP .TP
\f[B]\f[CB]-V --value\f[B]\f[R] \f[B]\f[CB]-V --market\f[B]\f[R]
convert amounts to their market value on the report end date (using the convert amounts to their market value in default valuation commodities
most recent applicable market price, if any) .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 .TP
\f[B]\f[CB]--auto\f[B]\f[R] \f[B]\f[CB]--auto\f[B]\f[R]
apply automated posting rules to modify transactions. apply automated posting rules to modify transactions.

55
hledger-ui/hledger-ui.info
View File

@ -152,12 +152,21 @@ the data.
hledger-ui/hledger-web) hledger-ui/hledger-web)
'-B --cost' '-B --cost'
convert amounts to their cost at transaction time (using the convert amounts to their cost/selling amount at transaction time
transaction price, if any) '-V --market'
'-V --value'
convert amounts to their market value on the report end date (using convert amounts to their market value in default valuation
the most recent applicable market price, if any) 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' '--auto'
apply automated posting rules to modify transactions. apply automated posting rules to modify transactions.
@ -501,24 +510,24 @@ Tag Table:
Node: Top71 Node: Top71
Node: OPTIONS1470 Node: OPTIONS1470
Ref: #options1567 Ref: #options1567
Node: KEYS4998 Node: KEYS5182
Ref: #keys5093 Ref: #keys5277
Node: SCREENS9369 Node: SCREENS9553
Ref: #screens9474 Ref: #screens9658
Node: Accounts screen9564 Node: Accounts screen9748
Ref: #accounts-screen9692 Ref: #accounts-screen9876
Node: Register screen11908 Node: Register screen12092
Ref: #register-screen12063 Ref: #register-screen12247
Node: Transaction screen14060 Node: Transaction screen14244
Ref: #transaction-screen14218 Ref: #transaction-screen14402
Node: Error screen15088 Node: Error screen15272
Ref: #error-screen15210 Ref: #error-screen15394
Node: ENVIRONMENT15454 Node: ENVIRONMENT15638
Ref: #environment15568 Ref: #environment15752
Node: FILES16375 Node: FILES16559
Ref: #files16474 Ref: #files16658
Node: BUGS16687 Node: BUGS16871
Ref: #bugs16764 Ref: #bugs16948
 
End Tag Table End Tag Table

19
hledger-ui/hledger-ui.txt
View File

@ -135,12 +135,21 @@ OPTIONS
hledger-ui/hledger-web) hledger-ui/hledger-web)
-B --cost -B --cost
convert amounts to their cost at transaction time (using the convert amounts to their cost/selling amount at transaction time
transaction price, if any)
-V --value -V --market
convert amounts to their market value on the report end date convert amounts to their market value in default valuation com-
(using the most recent applicable market price, if any) 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. --auto apply automated posting rules to modify transactions.

17
hledger-web/hledger-web.1
View File

@ -165,12 +165,19 @@ show items with zero amount, normally hidden (and vice-versa in
hledger-ui/hledger-web) hledger-ui/hledger-web)
.TP .TP
\f[B]\f[CB]-B --cost\f[B]\f[R] \f[B]\f[CB]-B --cost\f[B]\f[R]
convert amounts to their cost at transaction time (using the transaction convert amounts to their cost/selling amount at transaction time
price, if any)
.TP .TP
\f[B]\f[CB]-V --value\f[B]\f[R] \f[B]\f[CB]-V --market\f[B]\f[R]
convert amounts to their market value on the report end date (using the convert amounts to their market value in default valuation commodities
most recent applicable market price, if any) .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 .TP
\f[B]\f[CB]--auto\f[B]\f[R] \f[B]\f[CB]--auto\f[B]\f[R]
apply automated posting rules to modify transactions. apply automated posting rules to modify transactions.

47
hledger-web/hledger-web.info
View File

@ -176,12 +176,21 @@ before options, as shown in the synopsis above.
hledger-ui/hledger-web) hledger-ui/hledger-web)
'-B --cost' '-B --cost'
convert amounts to their cost at transaction time (using the convert amounts to their cost/selling amount at transaction time
transaction price, if any) '-V --market'
'-V --value'
convert amounts to their market value on the report end date (using convert amounts to their market value in default valuation
the most recent applicable market price, if any) 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' '--auto'
apply automated posting rules to modify transactions. apply automated posting rules to modify transactions.
@ -566,20 +575,20 @@ Tag Table:
Node: Top72 Node: Top72
Node: OPTIONS1746 Node: OPTIONS1746
Ref: #options1851 Ref: #options1851
Node: PERMISSIONS8195 Node: PERMISSIONS8379
Ref: #permissions8334 Ref: #permissions8518
Node: EDITING UPLOADING DOWNLOADING9546 Node: EDITING UPLOADING DOWNLOADING9730
Ref: #editing-uploading-downloading9727 Ref: #editing-uploading-downloading9911
Node: RELOADING10561 Node: RELOADING10745
Ref: #reloading10695 Ref: #reloading10879
Node: JSON API11128 Node: JSON API11312
Ref: #json-api11242 Ref: #json-api11426
Node: ENVIRONMENT16723 Node: ENVIRONMENT16907
Ref: #environment16839 Ref: #environment17023
Node: FILES17572 Node: FILES17756
Ref: #files17672 Ref: #files17856
Node: BUGS17885 Node: BUGS18069
Ref: #bugs17963 Ref: #bugs18147
 
End Tag Table End Tag Table

19
hledger-web/hledger-web.txt
View File

@ -156,12 +156,21 @@ OPTIONS
hledger-ui/hledger-web) hledger-ui/hledger-web)
-B --cost -B --cost
convert amounts to their cost at transaction time (using the convert amounts to their cost/selling amount at transaction time
transaction price, if any)
-V --value -V --market
convert amounts to their market value on the report end date convert amounts to their market value in default valuation com-
(using the most recent applicable market price, if any) 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. --auto apply automated posting rules to modify transactions.

249
hledger/hledger.1
View File

@ -617,12 +617,19 @@ show items with zero amount, normally hidden (and vice-versa in
hledger-ui/hledger-web) hledger-ui/hledger-web)
.TP .TP
\f[B]\f[CB]-B --cost\f[B]\f[R] \f[B]\f[CB]-B --cost\f[B]\f[R]
convert amounts to their cost at transaction time (using the transaction convert amounts to their cost/selling amount at transaction time
price, if any)
.TP .TP
\f[B]\f[CB]-V --value\f[B]\f[R] \f[B]\f[CB]-V --market\f[B]\f[R]
convert amounts to their market value on the report end date (using the convert amounts to their market value in default valuation commodities
most recent applicable market price, if any) .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 .TP
\f[B]\f[CB]--auto\f[B]\f[R] \f[B]\f[CB]--auto\f[B]\f[R]
apply automated posting rules to modify transactions. apply automated posting rules to modify transactions.
@ -1671,47 +1678,143 @@ $ hledger balance --pivot member acct:.
.fi .fi
.SS Valuation .SS Valuation
.PP .PP
hledger can show cost reports, where amounts are converted to their cost Instead of reporting amounts in their original commodity, hledger can
or sale amount at transaction time; or value reports, where amounts are convert them to:
converted to their market value in another currency/commodity at a .IP \[bu] 2
specified date (using market prices inferred from your transactions, or cost (or sale amount), using the conversion rate recorded as part of the
declared with P directives). transaction (transaction price).
.IP \[bu] 2
value, using the market prices in effect on certain date(s).
.PP .PP
We call this \[dq]valuation\[dq], and it is controlled by the We call this \[dq]valuation\[dq], and it is controlled in full by the
\f[C]--value=VALUATIONTYPE[,COMMODITY]\f[R] option. \f[C]--value=VALUATIONTYPE[,COMMODITY]\f[R] option.
It can get a little involved, so we cover all the details below. But we also provide simpler, Ledger-compatible
But most of the time, all you need to do is use these simpler flags \f[C]-B\f[R]/\f[C]-V\f[R]/\f[C]-X\f[R] flags, and usually one of these
instead: is all you need:
.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.
.SS -B: Cost .SS -B: Cost
.PP .PP
The \f[C]-B/--cost\f[R] flag converts amounts to their cost or sale 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. amount at transaction time, if they have a transaction price specified.
(It is equivalent to \f[C]--value=cost\f[R].)
.SS -V: Value .SS -V: Value
.PP .PP
The \f[C]-V/--market\f[R] flag converts reported amounts to market value The \f[C]-V/--market\f[R] flag converts amounts to market value in their
in their \f[I]default valuation commodity\f[R], using the market prices default \f[I]valuation commodity\f[R], using the market prices in effect
in effect on a \f[I]default valuation date\f[R]. on the \f[I]valuation date(s)\f[R], if any.
(More on these below.) More on these things in a minute.
.SS -X: Value in specified commodity
.PP .PP
The default valuation commodity is the one referenced in the latest The \f[C]-X/--exchange\f[R] option is like \f[C]-V\f[R] except the
applicable market price dated on or before the valuation date. desired valuation currency is specified explicitly.
Typically your P declarations or currency exchange transactions .SS Valuation date
reference a single base currency, and -V will pick that.
.PP .PP
The default valuation date is today for single period reports For single period reports, if an explicit report end date is specified,
(equivalent to \f[C]--value=now\f[R]), or the last day of each subperiod that will be used as the valuation date; otherwise the valuation date is
for multiperiod reports (equivalent to \f[C]--value=end\f[R]). \[dq]today\[dq].
.PP .PP
An example: 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 to this: value reports can be affected in
confusing/undesired ways by your journal entries.
If this happens to you, read all of this Valuation section carefully,
and try adding \f[C]--debug\f[R] or \f[C]--debug=2\f[R] to troubleshoot
the reason.
.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
Amounts for which no valuation commodity can be found are not converted.
.PP
This means:
.IP \[bu] 2
If you have any P directives, they alone determine which commodities
\f[C]-V\f[R] will convert, and to what.
.IP \[bu] 2
If you have no P directives, and you add the \f[C]--infer-value\f[R]
flag, transaction prices determine what \f[C]-V\f[R] converts.
.IP \[bu] 2
\f[C]-X\f[R] tries harder to convert everything to just one commodity.
.SS Simple valuation examples
.PP
Here are some quick examples of \f[C]-V\f[R]:
.IP .IP
.nf .nf
\f[C] \f[C]
@ -1755,39 +1858,8 @@ $ hledger -f t.j bal -N euros -V
$103.00 assets:euros $103.00 assets:euros
\f[R] \f[R]
.fi .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 .SS --value: Flexible valuation
.PP .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 \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: more general \f[C]--value\f[R] option:
.IP .IP
@ -1804,52 +1876,38 @@ more general \f[C]--value\f[R] option:
\f[R] \f[R]
.fi .fi
.PP .PP
The TYPE part basically selects either \[dq]cost\[dq], or \[dq]market The TYPE part selects cost or value and valuation date:
value\[dq] plus a valuation date:
.TP .TP
\f[B]\f[CB]--value=cost\f[B]\f[R] \f[B]\f[CB]--value=cost\f[B]\f[R]
Convert amounts to cost, using the prices recorded in transactions. Convert amounts to cost, using the prices recorded in transactions.
.TP .TP
\f[B]\f[CB]--value=then\f[B]\f[R] \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. market prices on each posting\[aq]s date.
This is currently supported only by the print and register commands. This is currently supported only by the print and register commands.
.TP .TP
\f[B]\f[CB]--value=end\f[B]\f[R] \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, 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 journal\[aq]s end date); or in multiperiod reports, market prices on
the last day of each subperiod. the last day of each subperiod.
.TP .TP
\f[B]\f[CB]--value=now\f[B]\f[R] \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). current market prices (as of when report is generated).
.TP .TP
\f[B]\f[CB]--value=YYYY-MM-DD\f[B]\f[R] \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. market prices on this date.
.PP .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 To select a different valuation commodity, add the optional
\f[C],COMM\f[R] part: a comma, then the target commodity\[aq]s symbol. \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]. Eg: \f[B]\f[CB]--value=now,EUR\f[B]\f[R].
hledger will do its best to convert amounts to this commodity, using: hledger will do its best to convert amounts to this commodity, deducing
.IP \[bu] 2 market prices as described above.
declared prices (from source commodity to valuation commodity) .SS More valuation examples
.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 .PP
in that order. Here are some examples showing the effect of \f[C]--value\f[R], as seen
.PP
Here are some examples showing the effect of \f[C]--value\f[R] as seen
with \f[C]print\f[R]: with \f[C]print\f[R]:
.IP .IP
.nf .nf
@ -1997,13 +2055,12 @@ $ hledger print -X A
b -0.50A b -0.50A
\f[R] \f[R]
.fi .fi
.SS Effect of --value on reports .SS Effect of valuation on reports
.PP .PP
Here is a reference for how \f[C]--value\f[R] currently affects each Here is a reference for how valuation is supposed to affect each part of
part of hledger\[aq]s reports. hledger\[aq]s reports (and a glossary).
It\[aq]s work in progress, but may be useful for troubleshooting or (It\[aq]s wide, you\[aq]ll have to scroll sideways.) It may be useful
reporting bugs. when troubleshooting.
See also the definitions and notes below.
If you find problems, please report them, ideally with a reproducible If you find problems, please report them, ideally with a reproducible
example. example.
Related: #329, #1083. Related: #329, #1083.
@ -2254,7 +2311,7 @@ T}@T{
T} T}
.TE .TE
.PP .PP
\f[B]Additional notes\f[R] \f[B]Glossary:\f[R]
.TP .TP
\f[I]cost\f[R] \f[I]cost\f[R]
calculated using price(s) recorded in the transaction(s). calculated using price(s) recorded in the transaction(s).

625
hledger/hledger.info
View File

@ -610,12 +610,21 @@ by most hledger commands, run 'hledger -h'.
hledger-ui/hledger-web) hledger-ui/hledger-web)
'-B --cost' '-B --cost'
convert amounts to their cost at transaction time (using the convert amounts to their cost/selling amount at transaction time
transaction price, if any) '-V --market'
'-V --value'
convert amounts to their market value on the report end date (using convert amounts to their market value in default valuation
the most recent applicable market price, if any) 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' '--auto'
apply automated posting rules to modify transactions. apply automated posting rules to modify transactions.
@ -1363,30 +1372,32 @@ File: hledger.info, Node: Valuation, Prev: Pivoting, Up: OPTIONS
2.17 Valuation 2.17 Valuation
============== ==============
hledger can show cost reports, where amounts are converted to their cost Instead of reporting amounts in their original commodity, hledger can
or sale amount at transaction time; or value reports, where amounts are convert them to:
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 * cost (or sale amount), using the conversion rate recorded as part
'--value=VALUATIONTYPE[,COMMODITY]' option. It can get a little of the transaction (transaction price).
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 * value, using the market prices in effect on certain date(s).
* '-V' to convert to market value in your base currency. Or
occasionally, We call this "valuation", and it is controlled in full by the
* '-X COMMODITY' to convert to market value in some other currency. '--value=VALUATIONTYPE[,COMMODITY]' option. But we also provide
simpler, Ledger-compatible '-B'/'-V'/'-X' flags, and usually one of
these is all you need:
* Menu: * Menu:
* -B Cost:: * -B Cost::
* -V Value:: * -V Value::
* -X Market value in specified commodity:: * -X Value in specified commodity::
* Valuation date::
* Market prices:: * Market prices::
* --infer-value market prices from transactions::
* Valuation commodity::
* Simple valuation examples::
* --value Flexible valuation:: * --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 File: hledger.info, Node: -B Cost, Next: -V Value, Up: Valuation
@ -1395,29 +1406,151 @@ File: hledger.info, Node: -B Cost, Next: -V Value, Up: Valuation
--------------- ---------------
The '-B/--cost' flag converts amounts to their cost or sale amount at The '-B/--cost' flag converts amounts to their cost or sale amount at
transaction time, if they have a transaction price specified. (It is transaction time, if they have a transaction price specified.
equivalent to '--value=cost'.)
 
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 2.17.2 -V: Value
---------------- ----------------
The '-V/--market' flag converts reported amounts to market value in The '-V/--market' flag converts amounts to market value in their default
their _default valuation commodity_, using the market prices in effect _valuation commodity_, using the market prices in effect on the
on a _default valuation date_. (More on these below.) _valuation date(s)_, if any. More on these things in a minute.
The default valuation commodity is the one referenced in the latest 
applicable market price dated on or before the valuation date. File: hledger.info, Node: -X Value in specified commodity, Next: Valuation date, Prev: -V Value, Up: Valuation
Typically your P declarations or currency exchange transactions
reference a single base currency, and -V will pick that.
The default valuation date is today for single period reports 2.17.3 -X: Value in specified commodity
(equivalent to '--value=now'), or the last day of each subperiod for ---------------------------------------
multiperiod reports (equivalent to '--value=end').
An example: The '-X/--exchange' option is like '-V' except the desired valuation
currency is specified explicitly.

File: hledger.info, Node: Valuation date, Next: Market prices, Prev: -X Value in specified commodity, Up: Valuation
2.17.4 Valuation date
---------------------
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 to this: value reports can be affected in
confusing/undesired ways by your journal entries. If this happens to
you, read all of this Valuation section carefully, and try adding
'--debug' or '--debug=2' to troubleshoot the reason.
'--infer-value' can infer market prices from:
* multicommodity transactions with explicit prices ('@'/'@@')
* multicommodity transactions with implicit prices (no '@', two
commodities, unbalanced). (With these, the order of postings
matters. 'hledger print -x' can be useful for troubleshooting.)
* but not, currently, from "more correct" 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.
Amounts for which no valuation commodity can be found are not
converted.
This means:
* If you have any P directives, they alone determine which
commodities '-V' will convert, and to what.
* If you have no P directives, and you add the '--infer-value' flag,
transaction prices determine what '-V' converts.
* '-X' tries harder to convert everything to just one commodity.

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 ; one euro is worth this many dollars from nov 1
P 2016/11/01 € $1.10 P 2016/11/01 € $1.10
@ -1447,51 +1580,11 @@ $ hledger -f t.j bal -N euros -V
$103.00 assets:euros $103.00 assets:euros
 
File: hledger.info, Node: -X Market value in specified commodity, Next: Market prices, Prev: -V Value, Up: Valuation File: hledger.info, Node: --value Flexible valuation, Next: More valuation examples, Prev: Simple valuation examples, Up: Valuation
2.17.3 -X: Market value in specified commodity 2.17.9 -value: Flexible valuation
----------------------------------------------
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
2.17.5 -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: option:
@ -1504,51 +1597,43 @@ option:
- default valuation commodity (or COMM) using current market prices - default valuation commodity (or COMM) using current market prices
- default valuation commodity (or COMM) using market prices at some date - default valuation commodity (or COMM) using market prices at some date
The TYPE part basically selects either "cost", or "market value" plus The TYPE part selects cost or value and valuation date:
a valuation date:
'--value=cost' '--value=cost'
Convert amounts to cost, using the prices recorded in transactions. Convert amounts to cost, using the prices recorded in transactions.
'--value=then' '--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 using market prices on each posting's date. This is currently
supported only by the print and register commands. supported only by the print and register commands.
'--value=end' '--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 using market prices on the last day of the report period (or if
unspecified, the journal's end date); or in multiperiod reports, unspecified, the journal's end date); or in multiperiod reports,
market prices on the last day of each subperiod. market prices on the last day of each subperiod.
'--value=now' '--value=now'
Convert amounts to their value in default valuation commodity using Convert amounts to their value in the default valuation commodity
current market prices (as of when report is generated). using current market prices (as of when report is generated).
'--value=YYYY-MM-DD' '--value=YYYY-MM-DD'
Convert amounts to their value in default valuation commodity using Convert amounts to their value in the default valuation commodity
market prices on this date. 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.
To select a different valuation commodity, add the optional ',COMM' To select a different valuation commodity, add the optional ',COMM'
part: a comma, then the target commodity's symbol. Eg: part: a comma, then the target commodity's symbol. Eg:
*'--value=now,EUR'*. hledger will do its best to convert amounts to *'--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, File: hledger.info, Node: More valuation examples, Next: Effect of valuation on reports, Prev: --value Flexible valuation, Up: Valuation
inverted)
* indirect prices (prices calculated from the shortest chain of
declared or reverse prices from source to valuation commodity)
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': 'print':
P 2000-01-01 A 1 B P 2000-01-01 A 1 B
@ -1657,16 +1742,16 @@ $ hledger print -X A
b -0.50A 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 Here is a reference for how valuation is supposed to affect each part of
hledger's reports. It's work in progress, but may be useful for hledger's reports (and a glossary). (It's wide, you'll have to scroll
troubleshooting or reporting bugs. See also the definitions and notes sideways.) It may be useful when troubleshooting. If you find
below. If you find problems, please report them, ideally with a problems, please report them, ideally with a reproducible example.
reproducible example. Related: #329, #1083. Related: #329, #1083.
Report '-B', '-V', '-X' '--value=then' '--value=end' '--value=DATE', Report '-B', '-V', '-X' '--value=then' '--value=end' '--value=DATE',
type '--value=cost' '--value=now' type '--value=cost' '--value=now'
@ -1739,7 +1824,7 @@ total/averageof column of column supported of column of
totals totals totals column totals totals totals column
totals totals
*Additional notes* *Glossary:*
_cost_ _cost_
@ -3798,165 +3883,175 @@ Node: OPTIONS16853
Ref: #options16960 Ref: #options16960
Node: General options17330 Node: General options17330
Ref: #general-options17455 Ref: #general-options17455
Node: Command options20225 Node: Command options20409
Ref: #command-options20376 Ref: #command-options20560
Node: Command arguments20774 Node: Command arguments20958
Ref: #command-arguments20921 Ref: #command-arguments21105
Node: Queries21801 Node: Queries21985
Ref: #queries21956 Ref: #queries22140
Node: Special characters in arguments and queries25918 Node: Special characters in arguments and queries26102
Ref: #special-characters-in-arguments-and-queries26146 Ref: #special-characters-in-arguments-and-queries26330
Node: More escaping26597 Node: More escaping26781
Ref: #more-escaping26759 Ref: #more-escaping26943
Node: Even more escaping27055 Node: Even more escaping27239
Ref: #even-more-escaping27249 Ref: #even-more-escaping27433
Node: Less escaping27920 Node: Less escaping28104
Ref: #less-escaping28082 Ref: #less-escaping28266
Node: Unicode characters28327 Node: Unicode characters28511
Ref: #unicode-characters28509 Ref: #unicode-characters28693
Node: Input files29921 Node: Input files30105
Ref: #input-files30064 Ref: #input-files30248
Node: Output destination31993 Node: Output destination32177
Ref: #output-destination32145 Ref: #output-destination32329
Node: Output format32570 Node: Output format32754
Ref: #output-format32720 Ref: #output-format32904
Node: Regular expressions34302 Node: Regular expressions34486
Ref: #regular-expressions34459 Ref: #regular-expressions34643
Node: Smart dates36195 Node: Smart dates36379
Ref: #smart-dates36346 Ref: #smart-dates36530
Node: Report start & end date37707 Node: Report start & end date37891
Ref: #report-start-end-date37879 Ref: #report-start-end-date38063
Node: Report intervals39376 Node: Report intervals39560
Ref: #report-intervals39541 Ref: #report-intervals39725
Node: Period expressions39931 Node: Period expressions40115
Ref: #period-expressions40091 Ref: #period-expressions40275
Node: Depth limiting44227 Node: Depth limiting44411
Ref: #depth-limiting44371 Ref: #depth-limiting44555
Node: Pivoting44703 Node: Pivoting44887
Ref: #pivoting44826 Ref: #pivoting45010
Node: Valuation46502 Node: Valuation46686
Ref: #valuation46604 Ref: #valuation46788
Node: -B Cost47524 Node: -B Cost47588
Ref: #b-cost47628 Ref: #b-cost47692
Node: -V Value47800 Node: -V Value47825
Ref: #v-value47953 Ref: #v-value47971
Node: -X Market value in specified commodity49226 Node: -X Value in specified commodity48173
Ref: #x-market-value-in-specified-commodity49445 Ref: #x-value-in-specified-commodity48372
Node: Market prices49623 Node: Valuation date48476
Ref: #market-prices49808 Ref: #valuation-date48644
Node: --value Flexible valuation50733 Node: Market prices48888
Ref: #value-flexible-valuation50934 Ref: #market-prices49068
Node: Effect of --value on reports55439 Node: --infer-value market prices from transactions49845
Ref: #effect-of---value-on-reports55620 Ref: #infer-value-market-prices-from-transactions50094
Node: COMMANDS61166 Node: Valuation commodity51385
Ref: #commands61274 Ref: #valuation-commodity51594
Node: accounts62358 Node: Simple valuation examples52919
Ref: #accounts62456 Ref: #simple-valuation-examples53121
Node: activity63155 Node: --value Flexible valuation53780
Ref: #activity63265 Ref: #value-flexible-valuation53988
Node: add63648 Node: More valuation examples55935
Ref: #add63747 Ref: #more-valuation-examples56144
Node: balance66486 Node: Effect of valuation on reports58149
Ref: #balance66597 Ref: #effect-of-valuation-on-reports58337
Node: Classic balance report68055 Node: COMMANDS63858
Ref: #classic-balance-report68228 Ref: #commands63966
Node: Customising the classic balance report69597 Node: accounts65050
Ref: #customising-the-classic-balance-report69825 Ref: #accounts65148
Node: Colour support71901 Node: activity65847
Ref: #colour-support72068 Ref: #activity65957
Node: Flat mode72241 Node: add66340
Ref: #flat-mode72389 Ref: #add66439
Node: Depth limited balance reports72802 Node: balance69178
Ref: #depth-limited-balance-reports72987 Ref: #balance69289
Node: Percentages73443 Node: Classic balance report70747
Ref: #percentages73609 Ref: #classic-balance-report70920
Node: Multicolumn balance report74746 Node: Customising the classic balance report72289
Ref: #multicolumn-balance-report74926 Ref: #customising-the-classic-balance-report72517
Node: Budget report80188 Node: Colour support74593
Ref: #budget-report80331 Ref: #colour-support74760
Node: Nested budgets85597 Node: Flat mode74933
Ref: #nested-budgets85709 Ref: #flat-mode75081
Ref: #output-format-189190 Node: Depth limited balance reports75494
Node: balancesheet89387 Ref: #depth-limited-balance-reports75679
Ref: #balancesheet89523 Node: Percentages76135
Node: balancesheetequity90989 Ref: #percentages76301
Ref: #balancesheetequity91138 Node: Multicolumn balance report77438
Node: cashflow91861 Ref: #multicolumn-balance-report77618
Ref: #cashflow91989 Node: Budget report82880
Node: check-dates93168 Ref: #budget-report83023
Ref: #check-dates93295 Node: Nested budgets88289
Node: check-dupes93574 Ref: #nested-budgets88401
Ref: #check-dupes93698 Ref: #output-format-191882
Node: close93991 Node: balancesheet92079
Ref: #close94105 Ref: #balancesheet92215
Node: close usage95627 Node: balancesheetequity93681
Ref: #close-usage95720 Ref: #balancesheetequity93830
Node: commodities98533 Node: cashflow94553
Ref: #commodities98660 Ref: #cashflow94681
Node: descriptions98742 Node: check-dates95860
Ref: #descriptions98870 Ref: #check-dates95987
Node: diff99051 Node: check-dupes96266
Ref: #diff99157 Ref: #check-dupes96390
Node: files100204 Node: close96683
Ref: #files100304 Ref: #close96797
Node: help100451 Node: close usage98319
Ref: #help100551 Ref: #close-usage98412
Node: import101632 Node: commodities101225
Ref: #import101746 Ref: #commodities101352
Node: Importing balance assignments102639 Node: descriptions101434
Ref: #importing-balance-assignments102787 Ref: #descriptions101562
Node: incomestatement103436 Node: diff101743
Ref: #incomestatement103569 Ref: #diff101849
Node: notes105056 Node: files102896
Ref: #notes105169 Ref: #files102996
Node: payees105295 Node: help103143
Ref: #payees105401 Ref: #help103243
Node: prices105559 Node: import104324
Ref: #prices105665 Ref: #import104438
Node: print106006 Node: Importing balance assignments105331
Ref: #print106116 Ref: #importing-balance-assignments105479
Node: print-unique110902 Node: incomestatement106128
Ref: #print-unique111028 Ref: #incomestatement106261
Node: register111313 Node: notes107748
Ref: #register111440 Ref: #notes107861
Node: Custom register output115612 Node: payees107987
Ref: #custom-register-output115741 Ref: #payees108093
Node: register-match117078 Node: prices108251
Ref: #register-match117212 Ref: #prices108357
Node: rewrite117563 Node: print108698
Ref: #rewrite117678 Ref: #print108808
Node: Re-write rules in a file119533 Node: print-unique113594
Ref: #re-write-rules-in-a-file119667 Ref: #print-unique113720
Node: Diff output format120877 Node: register114005
Ref: #diff-output-format121046 Ref: #register114132
Node: rewrite vs print --auto122138 Node: Custom register output118304
Ref: #rewrite-vs.-print---auto122317 Ref: #custom-register-output118433
Node: roi122873 Node: register-match119770
Ref: #roi122971 Ref: #register-match119904
Node: stats123983 Node: rewrite120255
Ref: #stats124082 Ref: #rewrite120370
Node: tags124870 Node: Re-write rules in a file122225
Ref: #tags124968 Ref: #re-write-rules-in-a-file122359
Node: test125262 Node: Diff output format123569
Ref: #test125370 Ref: #diff-output-format123738
Node: Add-on commands126117 Node: rewrite vs print --auto124830
Ref: #add-on-commands126234 Ref: #rewrite-vs.-print---auto125009
Node: ui127577 Node: roi125565
Ref: #ui127665 Ref: #roi125663
Node: web127719 Node: stats126675
Ref: #web127822 Ref: #stats126774
Node: iadd127938 Node: tags127562
Ref: #iadd128049 Ref: #tags127660
Node: interest128131 Node: test127954
Ref: #interest128238 Ref: #test128062
Node: ENVIRONMENT128478 Node: Add-on commands128809
Ref: #environment128590 Ref: #add-on-commands128926
Node: FILES129419 Node: ui130269
Ref: #files-1129522 Ref: #ui130357
Node: LIMITATIONS129735 Node: web130411
Ref: #limitations129854 Ref: #web130514
Node: TROUBLESHOOTING130596 Node: iadd130630
Ref: #troubleshooting130709 Ref: #iadd130741
Node: interest130823
Ref: #interest130930
Node: ENVIRONMENT131170
Ref: #environment131282
Node: FILES132111
Ref: #files-1132214
Node: LIMITATIONS132427
Ref: #limitations132546
Node: TROUBLESHOOTING133288
Ref: #troubleshooting133401
 
End Tag Table End Tag Table

258
hledger/hledger.txt
View File

@ -515,12 +515,21 @@ OPTIONS
hledger-ui/hledger-web) hledger-ui/hledger-web)
-B --cost -B --cost
convert amounts to their cost at transaction time (using the convert amounts to their cost/selling amount at transaction time
transaction price, if any)
-V --value -V --market
convert amounts to their market value on the report end date convert amounts to their market value in default valuation com-
(using the most recent applicable market price, if any) 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. --auto apply automated posting rules to modify transactions.
@ -934,7 +943,6 @@ OPTIONS
2004/10/1, 2004-01-01, exact date, several separators allowed. Year 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.9.1 is 4+ digits, month is 1-12, day is 1-31
2004 start of year 2004 start of year
2004/10 start of month 2004/10 start of month
10/1 month and day in current year 10/1 month and day in current year
21 day in current month 21 day in current month
@ -1067,6 +1075,8 @@ OPTIONS
-p "weekly from 2009/1/1 starts on 2008/12/29, closest preceding Mon- -p "weekly from 2009/1/1 starts on 2008/12/29, closest preceding Mon-
to 2009/4/1" day to 2009/4/1" day
-p "monthly in starts on 2018/11/01 -p "monthly in starts on 2018/11/01
2008/11/25" 2008/11/25"
-p "quarterly from starts on 2009/04/01, ends on 2009/06/30, -p "quarterly from starts on 2009/04/01, ends on 2009/06/30,
@ -1179,44 +1189,130 @@ OPTIONS
-2 EUR -2 EUR
Valuation Valuation
hledger can show cost reports, where amounts are converted to their Instead of reporting amounts in their original commodity, hledger can
cost or sale amount at transaction time; or value reports, where convert them to:
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).
We call this "valuation", and it is controlled by the --value=VALUA- o cost (or sale amount), using the conversion rate recorded as part of
TIONTYPE[,COMMODITY] option. It can get a little involved, so we cover the transaction (transaction price).
all the details below. But most of the time, all you need to do is use
these simpler flags instead:
o -B to convert to cost/sale amount, or o value, using the market prices in effect on certain date(s).
o -V to convert to market value in your base currency. Or occasion- We call this "valuation", and it is controlled in full by the
ally, --value=VALUATIONTYPE[,COMMODITY] option. But we also provide simpler,
Ledger-compatible -B/-V/-X flags, and usually one of these is all you
o -X COMMODITY to convert to market value in some other currency. need:
-B: Cost -B: Cost
The -B/--cost flag converts amounts to their cost or sale amount at The -B/--cost flag converts amounts to their cost or sale amount at
transaction time, if they have a transaction price specified. (It is transaction time, if they have a transaction price specified.
equivalent to --value=cost.)
-V: Value -V: Value
The -V/--market flag converts reported amounts to market value in their The -V/--market flag converts amounts to market value in their default
default valuation commodity, using the market prices in effect on a de- valuation commodity, using the market prices in effect on the valuation
fault valuation date. (More on these below.) date(s), if any. More on these things in a minute.
The default valuation commodity is the one referenced in the latest ap- -X: Value in specified commodity
plicable market price dated on or before the valuation date. Typically The -X/--exchange option is like -V except the desired valuation cur-
your P declarations or currency exchange transactions reference a sin- rency is specified explicitly.
gle base currency, and -V will pick that.
The default valuation date is today for single period reports (equiva- Valuation date
lent to --value=now), or the last day of each subperiod for multiperiod For single period reports, if an explicit report end date is specified,
reports (equivalent to --value=end). that will be used as the valuation date; otherwise the valuation date
is "today".
An example: For multiperiod reports, each column/period is valued on the last day
of the period.
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 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 to this: value reports can 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 the reason.
--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.
Amounts for which no valuation commodity can be found are not con-
verted.
This means:
o If you have any P directives, they alone determine which commodities
-V will convert, and to what.
o If you have no P directives, and you add the --infer-value flag,
transaction prices determine what -V converts.
o -X tries harder to convert everything to just one commodity.
Simple valuation examples
Here are some quick examples of -V:
; one euro is worth this many dollars from nov 1 ; one euro is worth this many dollars from nov 1
P 2016/11/01 EUR $1.10 P 2016/11/01 EUR $1.10
@ -1245,36 +1341,7 @@ OPTIONS
$ hledger -f t.j bal -N euros -V $ hledger -f t.j bal -N euros -V
$103.00 assets:euros $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 --value: Flexible valuation
(experimental, added 201905)
-B, -V and -X are special cases of the more general --value option: -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. --value=TYPE[,COMM] TYPE is cost, then, end, now or YYYY-MM-DD.
@ -1286,52 +1353,39 @@ OPTIONS
- default valuation commodity (or COMM) using current market prices - default valuation commodity (or COMM) using current market prices
- default valuation commodity (or COMM) using market prices at some date - default valuation commodity (or COMM) using market prices at some date
The TYPE part basically selects either "cost", or "market value" plus a The TYPE part selects cost or value and valuation date:
valuation date:
--value=cost --value=cost
Convert amounts to cost, using the prices recorded in transac- Convert amounts to cost, using the prices recorded in transac-
tions. tions.
--value=then --value=then
Convert amounts to their value in a default valuation commodity, Convert amounts to their value in the default valuation commod-
using market prices on each posting's date. This is currently ity, using market prices on each posting's date. This is cur-
supported only by the print and register commands. rently supported only by the print and register commands.
--value=end --value=end
Convert amounts to their value in a default valuation commodity, Convert amounts to their value in the default valuation commod-
using market prices on the last day of the report period (or if ity, using market prices on the last day of the report period
unspecified, the journal's end date); or in multiperiod reports, (or if unspecified, the journal's end date); or in multiperiod
market prices on the last day of each subperiod. reports, market prices on the last day of each subperiod.
--value=now --value=now
Convert amounts to their value in default valuation commodity Convert amounts to their value in the default valuation commod-
using current market prices (as of when report is generated). ity using current market prices (as of when report is gener-
ated).
--value=YYYY-MM-DD --value=YYYY-MM-DD
Convert amounts to their value in default valuation commodity Convert amounts to their value in the default valuation commod-
using market prices on this date. ity 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.
To select a different valuation commodity, add the optional ,COMM part: To select a different valuation commodity, add the optional ,COMM part:
a comma, then the target commodity's symbol. Eg: --value=now,EUR. a comma, then the target commodity's symbol. Eg: --value=now,EUR.
hledger will do its best to convert amounts to this commodity, using: hledger will do its best to convert amounts to this commodity, deducing
market prices as described above.
o declared prices (from source commodity to valuation commodity) More valuation examples
Here are some examples showing the effect of --value, as seen with
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.
Here are some examples showing the effect of --value as seen with
print: print:
P 2000-01-01 A 1 B P 2000-01-01 A 1 B
@ -1438,12 +1492,12 @@ OPTIONS
a 0.50A a 0.50A
b -0.50A b -0.50A
Effect of --value on reports Effect of valuation on reports
Here is a reference for how --value currently affects each part of Here is a reference for how valuation is supposed to affect each part
hledger's reports. It's work in progress, but may be useful for trou- of hledger's reports (and a glossary). (It's wide, you'll have to
bleshooting or reporting bugs. See also the definitions and notes be- scroll sideways.) It may be useful when troubleshooting. If you find
low. If you find problems, please report them, ideally with a repro- problems, please report them, ideally with a reproducible example. Re-
ducible example. Related: #329, #1083. lated: #329, #1083.
Report type -B, -V, -X --value=then --value=end --value=DATE, Report type -B, -V, -X --value=then --value=end --value=DATE,
--value=cost --value=now --value=cost --value=now
@ -1492,9 +1546,6 @@ OPTIONS
(with report postings be- fore report fore report report start (with report postings be- fore report fore report report start
interval and fore report start start interval and fore report start start
-H) start -H) start
budget like bal- like bal- not supported like bal- like balances budget like bal- like bal- not supported like bal- like balances
amounts with ances ances ances amounts with ances ances ances
--budget --budget
@ -1506,6 +1557,9 @@ OPTIONS
ages (with played val- played val- played val- values ages (with played val- played val- played val- values
report in- ues ues ues report in- ues ues ues
terval) terval)
column to- sums of dis- sums of dis- not supported sums of dis- sums of dis- column to- sums of dis- sums of dis- not supported sums of dis- sums of dis-
tals played val- played val- played val- played values tals played val- played val- played val- played values
ues ues ues ues ues ues
@ -1514,7 +1568,7 @@ OPTIONS
totals totals totals tals totals totals totals tals
Additional notes Glossary:
cost calculated using price(s) recorded in the transaction(s). cost calculated using price(s) recorded in the transaction(s).