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

;doc: update --value docs (#329)

Browse Source
This commit is contained in:
Simon Michael 2019-05-23 12:59:52 -07:00
parent e5cb082fb5
commit 2325ff4e08
1 changed files with 56 additions and 59 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

115
hledger/hledger_options.m4.md
View File

@ -450,7 +450,7 @@ if they have a [transaction price](/journal.html#transaction-prices) specified.
## Market value ## Market value
The `-V/--value` flag converts reported amounts to their market value in another commodity. The `-V/--market` flag converts reported amounts to their market value in another commodity.
It uses the commodity referenced in the latest [market price](journal.html#market-prices) (P directive) It uses the commodity referenced in the latest [market price](journal.html#market-prices) (P directive)
dated on or before the valuation date. The default valuation date is today. dated on or before the valuation date. The default valuation date is today.
For example: For example:
@ -483,41 +483,40 @@ $ hledger -f t.j bal -N euros -V
$103.00 assets:euros $103.00 assets:euros
``` ```
A note for Ledger users: Ledger's -V also infers market prices from journal entries, Ledger users: Ledger's -V also infers market prices from journal entries,
but we don't do that. hledger's -V uses only market prices declared explicitly, with P directives. but we don't do that. hledger's -V uses only market prices declared explicitly, with P directives.
(Mnemonic: -B/--cost uses transaction prices, -V/--value uses market prices.) (Mnemonic: -B/--cost uses transaction prices, -V/--market uses market prices.)
### Valuation date ### More control over valuation
*(experimental, added 201904)* *(experimental, added 201905)*
You can select valuation dates other than today, with the `--value-at` option. (This implies `-V`): You can control valuation more precisely with the `--value` option.
--value-at=VALUEDATE as of which date should market values be calculated ? --value=TYPE which type of valuation should be done ? cost|end|now|YYYY-MM-DD
transaction|period|now|YYYY-MM-DD (default: now)
The argument must be one of the keywords shown, or their first letter, or a custom date. The argument is one of the keywords shown, or their first letter, or a custom date.
The precise effect of the keywords is command-specific, but here is their general meaning: The precise effect of the keywords is command-specific, but here is their general meaning:
`--value-at=transaction` (or `t`) `--value=cost` (or `c`)
: Use the prices as of each transaction date (more precisely, each [posting's date](/journal.html#posting-dates)). : Convert amounts to cost, using the prices recorded in transactions.
Balance reports will show the sum of amount values. `-B`/`--cost` does this.
`--value-at=period` (or `p`) `--value=end` (or `e`)
: Use the prices as of the last day of the report period (or each subperiod in a multiperiod report). : Convert amounts to their value in default valuation commodity using market prices
on the last day of the report period (or of each subperiod in a multiperiod report).
When no report period is specified, uses the journal's last transaction date. When no report period is specified, uses the journal's last transaction date.
Balance reports will show the period-end value of summed amounts.
`--value-at=now` (or `n`) `--value=now` (or `n`)
: Use the prices as of today's date when the report is generated. This is the default. : Convert amounts to their value in default valuation commodity using current market prices
Balance reports will show the current value of summed amounts. (as of when report is generated). `-V`/`--market` does this.
`--value-at=YYYY-MM-DD` `--value=YYYY-MM-DD`
: Use the prices as of the given date (8 digits with `-` or `/` or `.` separators). : Convert amounts to their value in default valuation commodity using market prices
Eg `--value-at=2019-04-25`. on the given date (which must be 8 digits with `-` or `/` or `.` separators).
Balance reports will show the value on the given date of summed amounts. Eg `--value=2019-04-25`.
Here are the effects of `--value-at` as seen with `print`: Here are the effects of `--value` as seen with `print`:
```journal ```journal
P 2000-01-01 A 1 B P 2000-01-01 A 1 B
@ -526,32 +525,32 @@ P 2000-03-01 A 3 B
P 2000-04-01 A 4 B P 2000-04-01 A 4 B
2000-01-01 2000-01-01
(a) 1 A (a) 1 A @ 5 B
2000-02-01 2000-02-01
(a) 1 A (a) 1 A @ 6 B
2000-03-01 2000-03-01
(a) 1 A (a) 1 A @ 7 B
``` ```
Show the value as of each transaction (posting) date: Show the cost of each posting:
```shell ```shell
$ hledger -f- print --value-at=transaction $ hledger -f- print --value=cost
2000/01/01 2000/01/01
(a) 1 B (a) 5 B
2000/02/01 2000/02/01
(a) 2 B (a) 6 B
2000/03/01 2000/03/01
(a) 3 B (a) 7 B
``` ```
Show the value as of the last day of the report period (2000-02-29): Show the value as of the last day of the report period (2000-02-29):
```shell ```shell
$ hledger -f- print --value-at=period date:2000/01-2000/03 $ hledger -f- print --value=end date:2000/01-2000/03
2000-01-01 2000-01-01
(a) 2 B (a) 2 B
@ -562,7 +561,7 @@ $ hledger -f- print --value-at=period date:2000/01-2000/03
With no report period specified, that shows the value as of the last day of the journal (2000-03-01): With no report period specified, that shows the value as of the last day of the journal (2000-03-01):
```shell ```shell
$ hledger -f- print --value-at=period $ hledger -f- print --value=end
2000/01/01 2000/01/01
(a) 3 B (a) 3 B
@ -576,7 +575,7 @@ $ hledger -f- print --value-at=period
Show the current value (the 2000-04-01 price is still in effect today): Show the current value (the 2000-04-01 price is still in effect today):
```shell ```shell
$ hledger -f- print --value-at=now $ hledger -f- print --value=now
2000-01-01 2000-01-01
(a) 4 B (a) 4 B
@ -590,7 +589,7 @@ $ hledger -f- print --value-at=now
Show the value on 2000/01/15: Show the value on 2000/01/15:
```shell ```shell
$ hledger -f- print --value-at=2000-01-15 $ hledger -f- print --value=2000-01-15
2000/01/01 2000/01/01
(a) 1 B (a) 1 B
@ -602,30 +601,30 @@ $ hledger -f- print --value-at=2000-01-15
``` ```
### Effect of --value-at on reports ### Effect of --value on reports
Below is how `--value-at` affects each of hledger's reports, currently. Below is how `--value` affects each of hledger's reports, currently.
You're not expected to remember all this, but when troubleshooting a report, look here. You're not expected to remember all this, but when troubleshooting a report, look here.
If you find problems - useless reports, misbehaving reports, or error If you find problems - useless reports, misbehaving reports, or error
messages being printed - please report them (with reproducible examples) eg at messages being printed - please report them (with reproducible examples) eg at
[#329](https://github.com/simonmichael/hledger/issues/329). [#329](https://github.com/simonmichael/hledger/issues/329).
| Report type | `--value-at` `transaction`  | `--value-at` `period`  | `--value-at` `DATE`/`now`  | | Report type | `--value` `cost`  | `--value` `end`  | `--value` `DATE`/`now`  |
|----------------------------------|-----------------------------------------------------------|--------------------------------------------------------------|-------------------------------------------------| |----------------------------------|-------------------------------------|---------------------------------------------------------------------|--------------------------------------------------|
| <br>**print** | | | | | <br>**print** | | | |
| posting amounts | value at posting date | value at report end | value at DATE | | posting amounts | cost, as recorded in transaction | market value at report end | market value at DATE |
| balance assertions/assignments | show unvalued | show unvalued | show unvalued | | balance assertions/assignments | show unvalued | show unvalued | show unvalued |
| <br>**register** | | | | | <br>**register** | | | |
| starting balance with -H | value at day before report start | value at day before report start | value at DATE | | starting balance with -H | cost of starting balance | market value at day before report start | market value at DATE |
| posting amounts | value at posting date | value at report end | value at DATE | | posting amounts | cost | market value at report end | market value at DATE |
| posting amounts, multiperiod | value each posting at posting date then summarise | value each summary posting at period end | value each summary posting at DATE | | posting amounts, multiperiod | summarised cost | market value each summary posting at period end | market value each summary posting at DATE |
| running total/average | sum/average of the displayed values | sum/average of the displayed values | sum/average of the displayed values | | running total/average | sum/average of the displayed values | sum/average of the displayed values | sum/average of the displayed values |
| <br>**balance (bs, cf, is..)** | | | | | <br>**balance (bs, cf, is..)** | | | |
| starting balances with -H | sum of values of previous postings at their posting dates | value at day before report start of sum of previous postings | value at DATE of sum of previous postings | | starting balances with -H | costs of starting balances | market value at day before report start of sum of previous postings | market value at DATE of sum of previous postings |
| balances, simple balance report | sum of values of each posting at posting date | value at period end of sum of postings | value at DATE of sum of postings | | balances, simple balance report | summed costs | market value at period end of sum of postings | market value at DATE of sum of postings |
| balances, multiperiod report | sum of values of each posting at posting date | value at period end of sum of postings | value at DATE of sum of postings | | balances, multiperiod report | summed costs | market value at period end of sum of postings | market value at DATE of sum of postings |
| budget amounts with --budget | budget-setting periodic txns are valued at posting date | budget-setting periodic txns are valued at period end | budget-setting periodic txns are valued at DATE | | budget amounts with --budget | costs of budget amounts | budget-setting periodic txns are valued at period end | budget-setting periodic txns are valued at DATE |
| column/row/grand totals/averages | sum/average of the displayed values | value at period end of sum/average of postings | value at DATE of sum/average of postings | | column/row/grand totals/averages | sum/average of the displayed values | market value at period end of sum/average of postings | market value at DATE of sum/average of postings |
### Some useful value reports ### Some useful value reports
@ -633,14 +632,12 @@ Here are some probably useful reports - please send suggestions if you find out
| Command: | Description of report: | Could answer: | | Command: | Description of report: | Could answer: |
|------------------------------|----------------------------------------------------|--------------------------------------------------| |------------------------------|----------------------------------------------------|--------------------------------------------------|
| `hledger bs -M --value-at=p` | Monthly historical value of assets/liabilities | How are my investments performing ? | | `hledger bs -M --value=p` | Monthly historical value of assets/liabilities | How are my investments performing ? |
| `hledger is -M --value-at=t` | Monthly contemporaneous value of revenues/expenses | How much foreign currency have I been spending ? | | `hledger is -M --value=t` | Monthly contemporaneous value of revenues/expenses | How much foreign currency have I been spending ? |
## Combining -B, -V, --value
## Combining -B and -V The rightmost of these flags wins.
Using -B/--cost together with -V/--value or --value-at is allowed, but probably not useful.
(Let us know if you find a use for it.)
## Output destination ## Output destination