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

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

@ -152,12 +152,21 @@ the data.
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.
@ -501,24 +510,24 @@ 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: KEYS5182
Ref: #keys5277
Node: SCREENS9553
Ref: #screens9658
Node: Accounts screen9748
Ref: #accounts-screen9876
Node: Register screen12092
Ref: #register-screen12247
Node: Transaction screen14244
Ref: #transaction-screen14402
Node: Error screen15272
Ref: #error-screen15394
Node: ENVIRONMENT15638
Ref: #environment15752
Node: FILES16559
Ref: #files16658
Node: BUGS16871
Ref: #bugs16948

End Tag Table

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

@ -135,12 +135,21 @@ OPTIONS
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.

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

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

@ -176,12 +176,21 @@ before options, as shown in the synopsis above.
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.
@ -566,20 +575,20 @@ 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: PERMISSIONS8379
Ref: #permissions8518
Node: EDITING UPLOADING DOWNLOADING9730
Ref: #editing-uploading-downloading9911
Node: RELOADING10745
Ref: #reloading10879
Node: JSON API11312
Ref: #json-api11426
Node: ENVIRONMENT16907
Ref: #environment17023
Node: FILES17756
Ref: #files17856
Node: BUGS18069
Ref: #bugs18147

End Tag Table

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

@ -156,12 +156,21 @@ OPTIONS
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.

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)
.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.
@ -1671,47 +1678,143 @@ $ hledger balance --pivot member acct:.
.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).
Instead of reporting amounts in their original commodity, hledger can
convert them to:
.IP \[bu] 2
cost (or sale amount), using the conversion rate recorded as part of the
transaction (transaction price).
.IP \[bu] 2
value, using the market prices in effect on certain date(s).
.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.
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.
But we also provide simpler, Ledger-compatible
\f[C]-B\f[R]/\f[C]-V\f[R]/\f[C]-X\f[R] flags, and usually one of these
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 things 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\f[R] option is like \f[C]-V\f[R] except the
desired valuation currency is specified explicitly.
.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]).
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
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
.nf
\f[C]
@ -1755,39 +1858,8 @@ $ hledger -f t.j bal -N euros -V
$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 +1876,38 @@ more general \f[C]--value\f[R] option:
\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)
hledger will do its best to convert amounts to this commodity, deducing
market prices as described above.
.SS More valuation examples
.PP
in that order.
.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 +2055,12 @@ $ hledger print -X A
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 +2311,7 @@ T}@T{
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).

625
hledger/hledger.info
View File

@ -610,12 +610,21 @@ by most hledger commands, run 'hledger -h'.
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,32 @@ File: hledger.info, Node: Valuation, Prev: Pivoting, Up: OPTIONS
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).
Instead of reporting amounts in their original commodity, hledger can
convert them to:
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:
* cost (or sale amount), using the conversion rate recorded as part
of the transaction (transaction price).
* '-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.
* value, using the market prices in effect on certain date(s).
We call this "valuation", and it is controlled in full by the
'--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:
* -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,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
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 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.
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' 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
P 2016/11/01 € $1.10
@ -1447,51 +1580,11 @@ $ hledger -f t.j bal -N euros -V
$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
----------------------------------------------
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
2.17.9 -value: Flexible valuation
---------------------------------
_(experimental, added 201905)_
'-B', '-V' and '-X' are special cases of the more general '--value'
option:
@ -1504,51 +1597,43 @@ option:
- 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 +1742,16 @@ $ hledger print -X A
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 +1824,7 @@ total/averageof column of column supported of column of
totals totals totals column
totals
*Additional notes*
*Glossary:*
_cost_
@ -3798,165 +3883,175 @@ 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: Command options20409
Ref: #command-options20560
Node: Command arguments20958
Ref: #command-arguments21105
Node: Queries21985
Ref: #queries22140
Node: Special characters in arguments and queries26102
Ref: #special-characters-in-arguments-and-queries26330
Node: More escaping26781
Ref: #more-escaping26943
Node: Even more escaping27239
Ref: #even-more-escaping27433
Node: Less escaping28104
Ref: #less-escaping28266
Node: Unicode characters28511
Ref: #unicode-characters28693
Node: Input files30105
Ref: #input-files30248
Node: Output destination32177
Ref: #output-destination32329
Node: Output format32754
Ref: #output-format32904
Node: Regular expressions34486
Ref: #regular-expressions34643
Node: Smart dates36379
Ref: #smart-dates36530
Node: Report start & end date37891
Ref: #report-start-end-date38063
Node: Report intervals39560
Ref: #report-intervals39725
Node: Period expressions40115
Ref: #period-expressions40275
Node: Depth limiting44411
Ref: #depth-limiting44555
Node: Pivoting44887
Ref: #pivoting45010
Node: Valuation46686
Ref: #valuation46788
Node: -B Cost47588
Ref: #b-cost47692
Node: -V Value47825
Ref: #v-value47971
Node: -X Value in specified commodity48173
Ref: #x-value-in-specified-commodity48372
Node: Valuation date48476
Ref: #valuation-date48644
Node: Market prices48888
Ref: #market-prices49068
Node: --infer-value market prices from transactions49845
Ref: #infer-value-market-prices-from-transactions50094
Node: Valuation commodity51385
Ref: #valuation-commodity51594
Node: Simple valuation examples52919
Ref: #simple-valuation-examples53121
Node: --value Flexible valuation53780
Ref: #value-flexible-valuation53988
Node: More valuation examples55935
Ref: #more-valuation-examples56144
Node: Effect of valuation on reports58149
Ref: #effect-of-valuation-on-reports58337
Node: COMMANDS63858
Ref: #commands63966
Node: accounts65050
Ref: #accounts65148
Node: activity65847
Ref: #activity65957
Node: add66340
Ref: #add66439
Node: balance69178
Ref: #balance69289
Node: Classic balance report70747
Ref: #classic-balance-report70920
Node: Customising the classic balance report72289
Ref: #customising-the-classic-balance-report72517
Node: Colour support74593
Ref: #colour-support74760
Node: Flat mode74933
Ref: #flat-mode75081
Node: Depth limited balance reports75494
Ref: #depth-limited-balance-reports75679
Node: Percentages76135
Ref: #percentages76301
Node: Multicolumn balance report77438
Ref: #multicolumn-balance-report77618
Node: Budget report82880
Ref: #budget-report83023
Node: Nested budgets88289
Ref: #nested-budgets88401
Ref: #output-format-191882
Node: balancesheet92079
Ref: #balancesheet92215
Node: balancesheetequity93681
Ref: #balancesheetequity93830
Node: cashflow94553
Ref: #cashflow94681
Node: check-dates95860
Ref: #check-dates95987
Node: check-dupes96266
Ref: #check-dupes96390
Node: close96683
Ref: #close96797
Node: close usage98319
Ref: #close-usage98412
Node: commodities101225
Ref: #commodities101352
Node: descriptions101434
Ref: #descriptions101562
Node: diff101743
Ref: #diff101849
Node: files102896
Ref: #files102996
Node: help103143
Ref: #help103243
Node: import104324
Ref: #import104438
Node: Importing balance assignments105331
Ref: #importing-balance-assignments105479
Node: incomestatement106128
Ref: #incomestatement106261
Node: notes107748
Ref: #notes107861
Node: payees107987
Ref: #payees108093
Node: prices108251
Ref: #prices108357
Node: print108698
Ref: #print108808
Node: print-unique113594
Ref: #print-unique113720
Node: register114005
Ref: #register114132
Node: Custom register output118304
Ref: #custom-register-output118433
Node: register-match119770
Ref: #register-match119904
Node: rewrite120255
Ref: #rewrite120370
Node: Re-write rules in a file122225
Ref: #re-write-rules-in-a-file122359
Node: Diff output format123569
Ref: #diff-output-format123738
Node: rewrite vs print --auto124830
Ref: #rewrite-vs.-print---auto125009
Node: roi125565
Ref: #roi125663
Node: stats126675
Ref: #stats126774
Node: tags127562
Ref: #tags127660
Node: test127954
Ref: #test128062
Node: Add-on commands128809
Ref: #add-on-commands128926
Node: ui130269
Ref: #ui130357
Node: web130411
Ref: #web130514
Node: iadd130630
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

258
hledger/hledger.txt
View File

@ -515,12 +515,21 @@ OPTIONS
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.
@ -934,7 +943,6 @@ OPTIONS
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 @@ OPTIONS
-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,44 +1189,130 @@ OPTIONS
-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:
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:
o cost (or sale amount), using the conversion rate recorded as part of
the transaction (transaction price).
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-
ally,
o -X COMMODITY to convert to market value in some other currency.
We call this "valuation", and it is controlled in full by the
--value=VALUATIONTYPE[,COMMODITY] option. But we also provide simpler,
Ledger-compatible -B/-V/-X flags, and usually one of these is all you
need:
-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.)
transaction time, if they have a transaction price specified.
-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.)
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 things in a minute.
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.
-X: Value in specified commodity
The -X/--exchange option is like -V except the desired valuation cur-
rency is specified explicitly.
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).
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".
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
P 2016/11/01 EUR $1.10
@ -1245,36 +1341,7 @@ OPTIONS
$ 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 +1353,39 @@ OPTIONS
- 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-
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:
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)
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
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 +1492,12 @@ OPTIONS
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 +1546,6 @@ OPTIONS
(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
@ -1506,6 +1557,9 @@ OPTIONS
ages (with played val- played val- played val- values
report in- ues ues ues
terval)
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
ues ues ues
@ -1514,7 +1568,7 @@ OPTIONS
totals totals totals tals
Additional notes
Glossary:
cost calculated using price(s) recorded in the transaction(s).