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

doc,tests: Document new --value=then functionality and add tests.

Browse Source
This commit is contained in:
Stephen Morgan 2021-01-06 21:11:01 +11:00 committed by Simon Michael
parent 55e8ecf9e3
commit 0ef413bc25
2 changed files with 56 additions and 48 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
hledger/hledger.m4.md
View File

@ -903,9 +903,7 @@ The TYPE part selects cost or value and valuation date:
`--value=then` `--value=then`
: Convert amounts to their value in the [default valuation commodity](#valuation-commodity), : Convert amounts to their value in the [default valuation commodity](#valuation-commodity),
using market prices on each posting's date. This is currently using market prices on each posting's date.
supported only by the [print](#print) and [register](#register)
commands.
`--value=end` `--value=end`
: Convert amounts to their value in the default valuation commodity, using market prices : Convert amounts to their value in the default valuation commodity, using market prices
@ -1059,30 +1057,30 @@ Related:
[#1083](https://github.com/simonmichael/hledger/issues/1083). [#1083](https://github.com/simonmichael/hledger/issues/1083).
| Report type | `-B`, `--value=cost` | `-V`, `-X` | `--value=then` | `--value=end` | `--value=DATE`, `--value=now` | | Report type | `-B`, `--value=cost` | `-V`, `-X` | `--value=then` | `--value=end` | `--value=DATE`, `--value=now` |
|-----------------------------------------------------|------------------------------------------------------------------|-------------------------------------------------------------------|-------------------------------------------------------|-------------------------------------------------------------------|-----------------------------------------| |-----------------------------------------------------|------------------------------------------------------------------|-------------------------------------------------------------------|------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|-----------------------------------------|
| **print** | | | | | | | **print** | | | | | |
| posting amounts | cost | value at report end or today | value at posting date | value at report or journal end | value at DATE/today | | posting amounts | cost | value at report end or today | value at posting date | value at report or journal end | value at DATE/today |
| balance assertions/assignments | unchanged | unchanged | unchanged | unchanged | unchanged | | balance assertions/assignments | unchanged | unchanged | unchanged | unchanged | unchanged |
| <br> | | | | | | | <br> | | | | | |
| **register** | | | | | | | **register** | | | | | |
| starting balance (-H) | cost | value at day before report or journal start | not supported | value at day before report or journal start | value at DATE/today | | starting balance (-H) | cost | value at day before report or journal start | valued at day each historical posting was made | value at day before report or journal start | value at DATE/today |
| posting amounts | cost | value at report end or today | value at posting date | value at report or journal end | value at DATE/today | | posting amounts | cost | value at report end or today | value at posting date | value at report or journal end | value at DATE/today |
| summary posting amounts with report interval | summarised cost | value at period ends | sum of postings in interval, valued at interval start | value at period ends | value at DATE/today | | summary posting amounts with report interval | summarised cost | value at period ends | sum of postings in interval, valued at interval start | value at period ends | value at DATE/today |
| running total/average | sum/average of displayed values | sum/average of displayed values | sum/average of displayed values | sum/average of displayed values | sum/average of displayed values | | running total/average | sum/average of displayed values | sum/average of displayed values | sum/average of displayed values | sum/average of displayed values | sum/average of displayed values |
| <br> | | | | | | | <br> | | | | | |
| **balance (bs, bse, cf, is)** | | | | | | | **balance (bs, bse, cf, is)** | | | | | |
| balance changes | sums of costs | value at report end or today of sums of postings | not supported | value at report or journal end of sums of postings | value at DATE/today of sums of postings | | balance changes | sums of costs | value at report end or today of sums of postings | value at posting date | value at report or journal end of sums of postings | value at DATE/today of sums of postings |
| budget amounts (--budget) | like balance changes | like balance changes | not supported | like balances | like balance changes | | budget amounts (--budget) | like balance changes | like balance changes | like balance changes | like balances | like balance changes |
| grand total | sum of displayed values | sum of displayed values | not supported | sum of displayed values | sum of displayed values | | grand total | sum of displayed values | sum of displayed values | sum of displayed valued | sum of displayed values | sum of displayed values |
| <br> | | | | | | | <br> | | | | | |
| **balance (bs, bse, cf, is) with report interval** | | | | | | | **balance (bs, bse, cf, is) with report interval** | | | | | |
| starting balances (-H) | sums of costs of postings before report start | value at report start of sums of all postings before report start | not supported | value at report start of sums of all postings before report start | sums of postings before report start | | starting balances (-H) | sums of costs of postings before report start | value at report start of sums of all postings before report start | sums of values of postings before report start at respective posting dates | value at report start of sums of all postings before report start | sums of postings before report start |
| balance changes (bal, is, bs --change, cf --change) | sums of costs of postings in period | same as --value=end | not supported | balance change in each period, valued at period ends | value at DATE/today of sums of postings | | balance changes (bal, is, bs --change, cf --change) | sums of costs of postings in period | same as --value=end | sums of values of postings in period at respective posting dates | balance change in each period, valued at period ends | value at DATE/today of sums of postings |
| end balances (bal -H, is --H, bs, cf) | sums of costs of postings from before report start to period end | same as --value=end | not supported | period end balances, valued at period ends | value at DATE/today of sums of postings | | end balances (bal -H, is --H, bs, cf) | sums of costs of postings from before report start to period end | same as --value=end | sums of values of postings from before period start to period end at respective posting dates | period end balances, valued at period ends | value at DATE/today of sums of postings |
| budget amounts (--budget) | like balance changes/end balances | like balance changes/end balances | not supported | like balances | like balance changes/end balances | | budget amounts (--budget) | like balance changes/end balances | like balance changes/end balances | like balance changes/end balances | like balances | like balance changes/end balances |
| row totals, row averages (-T, -A) | sums, averages of displayed values | sums, averages of displayed values | not supported | sums, averages of displayed values | sums, averages of displayed values | | row totals, row averages (-T, -A) | sums, averages of displayed values | sums, averages of displayed values | sums, averages of displayed values | sums, averages of displayed values | sums, averages of displayed values |
| column totals | sums of displayed values | sums of displayed values | not supported | sums of displayed values | sums of displayed values | | column totals | sums of displayed values | sums of displayed values | sums of displayed values | sums of displayed values | sums of displayed values |
| grand total, grand average | sum, average of column totals | sum, average of column totals | not supported | sum, average of column totals | sum, average of column totals | | grand total, grand average | sum, average of column totals | sum, average of column totals | sum, average of column totals | sum, average of column totals | sum, average of column totals |
| <br> | | | | | | | <br> | | | | | |
`--cumulative` is omitted to save space, it works like `-H` but with a zero starting balance. `--cumulative` is omitted to save space, it works like `-H` but with a zero starting balance.

46
hledger/test/journal/valuation.test
View File

@ -376,7 +376,17 @@ Balance changes in 2000-01-01..2000-04-30, valued at cost:
---++-------------------------------------- ---++--------------------------------------
|| 6 B 7 B 8 B 0 21 B 5 B || 6 B 7 B 8 B 0 21 B 5 B
# 35. multicolumn balance report showing changes in period-end values # 35. multicolumn balance report valued at posting date
$ hledger -f- bal -M --value=then
Balance changes in 2000-01-01..2000-04-30, valued at posting date:
|| Jan Feb Mar Apr
===++====================
a || 1 B 2 B 3 B 0
---++--------------------
|| 1 B 2 B 3 B 0
# 36. multicolumn balance report showing changes in period-end values
$ hledger -f- bal -M --value=end $ hledger -f- bal -M --value=end
Period-end value changes in 2000-01-01..2000-04-30: Period-end value changes in 2000-01-01..2000-04-30:
@ -386,7 +396,7 @@ Period-end value changes in 2000-01-01..2000-04-30:
---++--------------------- ---++---------------------
|| 5 B -1 B 5 B 3 B || 5 B -1 B 5 B 3 B
# 36. multicolumn balance report showing changes in period-end values with -T or -A # 37. multicolumn balance report showing changes in period-end values with -T or -A
$ hledger -f- bal -MTA --value=end $ hledger -f- bal -MTA --value=end
Period-end value changes in 2000-01-01..2000-04-30: Period-end value changes in 2000-01-01..2000-04-30:
@ -396,7 +406,7 @@ Period-end value changes in 2000-01-01..2000-04-30:
---++--------------------------------------- ---++---------------------------------------
|| 5 B -1 B 5 B 3 B 12 B 3 B || 5 B -1 B 5 B 3 B 12 B 3 B
# 37. multicolumn balance report valued at other date # 38. multicolumn balance report valued at other date
$ hledger -f- bal -MTA --value=2000-01-15 $ hledger -f- bal -MTA --value=2000-01-15
Balance changes in 2000-01-01..2000-04-30, valued at 2000-01-15: Balance changes in 2000-01-01..2000-04-30, valued at 2000-01-15:
@ -406,7 +416,7 @@ Balance changes in 2000-01-01..2000-04-30, valued at 2000-01-15:
---++-------------------------------------- ---++--------------------------------------
|| 5 B 5 B 5 B 0 15 B 4 B || 5 B 5 B 5 B 0 15 B 4 B
# 38. multicolumn balance report valued today (with today >= 2000-04-01) # 39. multicolumn balance report valued today (with today >= 2000-04-01)
$ hledger -f- bal -M --value=now $ hledger -f- bal -M --value=now
Balance changes in 2000-01-01..2000-04-30, current value: Balance changes in 2000-01-01..2000-04-30, current value:
@ -416,7 +426,7 @@ Balance changes in 2000-01-01..2000-04-30, current value:
---++-------------------- ---++--------------------
|| 4 B 4 B 4 B 0 || 4 B 4 B 4 B 0
# 39. multicolumn balance report showing changes in period-end values (same as --value=end) # 40. multicolumn balance report showing changes in period-end values (same as --value=end)
$ hledger -f- bal -M -V $ hledger -f- bal -M -V
Period-end value changes in 2000-01-01..2000-04-30: Period-end value changes in 2000-01-01..2000-04-30:
@ -428,7 +438,7 @@ Period-end value changes in 2000-01-01..2000-04-30:
# balance, periodic, with -H (starting balance and accumulating across periods) # balance, periodic, with -H (starting balance and accumulating across periods)
# 40. multicolumn balance report with -H, valued at cost. # 41. multicolumn balance report with -H, valued at cost.
# The starting balance on 2000/01/01 is 6 B (cost of the first 2 A). # The starting balance on 2000/01/01 is 6 B (cost of the first 2 A).
# February adds 1 A costing 7 B, making 13 B. # February adds 1 A costing 7 B, making 13 B.
# March adds 1 A costing 8 B, making 21 B. # March adds 1 A costing 8 B, making 21 B.
@ -441,7 +451,7 @@ Ending balances (historical) in 2000-02-01..2000-04-30, valued at cost:
---++------------------------------------ ---++------------------------------------
|| 13 B 21 B 21 B || 13 B 21 B 21 B
# 41. multicolumn balance report with -H valued at period end. # 42. multicolumn balance report with -H valued at period end.
# The starting balance is 1 A. # The starting balance is 1 A.
# February adds 1 A making 2 A, which is valued at 2000/02/29 as 4 B. # February adds 1 A making 2 A, which is valued at 2000/02/29 as 4 B.
# March adds 1 A making 3 A, which is valued at 2000/03/31 as 9 B. # March adds 1 A making 3 A, which is valued at 2000/03/31 as 9 B.
@ -455,7 +465,7 @@ Ending balances (historical) in 2000-02-01..2000-04-30, valued at period ends:
---++--------------------------------------------- ---++---------------------------------------------
|| 4 B 9 B 12 B 8 B || 4 B 9 B 12 B 8 B
# 42. multicolumn balance report with -H valued at other date. # 43. multicolumn balance report with -H valued at other date.
# The starting balance is 5 B (1 A valued at 2000/1/15). # The starting balance is 5 B (1 A valued at 2000/1/15).
$ hledger -f- bal -M -H -b 200002 --value=2000-01-15 $ hledger -f- bal -M -H -b 200002 --value=2000-01-15
Ending balances (historical) in 2000-02-01..2000-04-30, valued at 2000-01-15: Ending balances (historical) in 2000-02-01..2000-04-30, valued at 2000-01-15:
@ -466,7 +476,7 @@ Ending balances (historical) in 2000-02-01..2000-04-30, valued at 2000-01-15:
---++------------------------------------ ---++------------------------------------
|| 10 B 15 B 15 B || 10 B 15 B 15 B
# 43. multicolumn balance report with -H, valuing each period's carried-over balances at cost. # 44. multicolumn balance report with -H, valuing each period's carried-over balances at cost.
< <
P 2000/01/01 A 1 B P 2000/01/01 A 1 B
P 2000/01/15 A 5 B P 2000/01/15 A 5 B
@ -486,7 +496,7 @@ Ending balances (historical) in 2000Q1, valued at cost:
---++------------------------------------ ---++------------------------------------
|| 6 B 6 B 6 B || 6 B 6 B 6 B
# 44. multicolumn balance report with -H, valuing each period's carried-over balances at period end. # 45. multicolumn balance report with -H, valuing each period's carried-over balances at period end.
# Unrelated, also -H always disables -T. # Unrelated, also -H always disables -T.
$ hledger -f- bal -META -H -p200001-200004 --value=e $ hledger -f- bal -META -H -p200001-200004 --value=e
Ending balances (historical) in 2000Q1, valued at period ends: Ending balances (historical) in 2000Q1, valued at period ends:
@ -497,7 +507,7 @@ Ending balances (historical) in 2000Q1, valued at period ends:
---++--------------------------------------------- ---++---------------------------------------------
|| 5 B 2 B 3 B 3 B || 5 B 2 B 3 B 3 B
# 45. multicolumn balance report with -H, valuing each period's carried-over balances at other date. # 46. multicolumn balance report with -H, valuing each period's carried-over balances at other date.
$ hledger -f- bal -ME -H -p200001-200004 --value=2000-01-15 $ hledger -f- bal -ME -H -p200001-200004 --value=2000-01-15
Ending balances (historical) in 2000Q1, valued at 2000-01-15: Ending balances (historical) in 2000Q1, valued at 2000-01-15:
@ -529,7 +539,7 @@ P 2000/04/01 A 4 B
2000/03/01 2000/03/01
(a) 1 A @ 8 B (a) 1 A @ 8 B
# 46. budget report, unvalued (for reference). # 47. budget report, unvalued (for reference).
$ hledger -f- bal -M --budget $ hledger -f- bal -M --budget
Budget performance in 2000-01-01..2000-04-30: Budget performance in 2000-01-01..2000-04-30:
@ -539,7 +549,7 @@ Budget performance in 2000-01-01..2000-04-30:
---++--------------------------------------------------------------------- ---++---------------------------------------------------------------------
|| 1 A [50% of 2 A] 1 A [50% of 2 A] 1 A [50% of 2 A] 0 [0% of 2 A] || 1 A [50% of 2 A] 1 A [50% of 2 A] 1 A [50% of 2 A] 0 [0% of 2 A]
# 47. budget report, valued at cost. # 48. budget report, valued at cost.
$ hledger -f- bal -MTA --budget --value=c $ hledger -f- bal -MTA --budget --value=c
Budget performance in 2000-01-01..2000-04-30, valued at cost: Budget performance in 2000-01-01..2000-04-30, valued at cost:
@ -549,7 +559,7 @@ Budget performance in 2000-01-01..2000-04-30, valued at cost:
---++--------------------------------------------------------------------------------------------------------------- ---++---------------------------------------------------------------------------------------------------------------
|| 6 B [300% of 2 B] 7 B [350% of 2 B] 8 B [400% of 2 B] 0 [0% of 2 B] 21 B [262% of 8 B] 5 B [262% of 2 B] || 6 B [300% of 2 B] 7 B [350% of 2 B] 8 B [400% of 2 B] 0 [0% of 2 B] 21 B [262% of 8 B] 5 B [262% of 2 B]
# 48. budget report, showing changes in period-end values. # 49. budget report, showing changes in period-end values.
$ hledger -f- bal -MTA --budget --value=e $ hledger -f- bal -MTA --budget --value=e
Budget performance in 2000-01-01..2000-04-30, valued at period ends: Budget performance in 2000-01-01..2000-04-30, valued at period ends:
@ -559,7 +569,7 @@ Budget performance in 2000-01-01..2000-04-30, valued at period ends:
---++------------------------------------------------------------------------------------------------------------------- ---++-------------------------------------------------------------------------------------------------------------------
|| 5 B [50% of 10 B] -1 B [50% of -2 B] 5 B [50% of 10 B] 3 B [21% of 14 B] 12 B [38% of 32 B] 3 B [38% of 8 B] || 5 B [50% of 10 B] -1 B [50% of -2 B] 5 B [50% of 10 B] 3 B [21% of 14 B] 12 B [38% of 32 B] 3 B [38% of 8 B]
# 49. budget report, valued at other date. # 50. budget report, valued at other date.
$ hledger -f- bal -MTA --budget --value=2000-01-15 $ hledger -f- bal -MTA --budget --value=2000-01-15
Budget performance in 2000-01-01..2000-04-30, valued at 2000-01-15: Budget performance in 2000-01-01..2000-04-30, valued at 2000-01-15:
@ -569,7 +579,7 @@ Budget performance in 2000-01-01..2000-04-30, valued at 2000-01-15:
---++---------------------------------------------------------------------------------------------------------------- ---++----------------------------------------------------------------------------------------------------------------
|| 5 B [50% of 10 B] 5 B [50% of 10 B] 5 B [50% of 10 B] 0 [0% of 10 B] 15 B [38% of 40 B] 4 B [38% of 10 B] || 5 B [50% of 10 B] 5 B [50% of 10 B] 5 B [50% of 10 B] 0 [0% of 10 B] 15 B [38% of 40 B] 4 B [38% of 10 B]
# 50. --value=then with --historical. The starting total is valued individually for each posting at its posting time. # 51. --value=then with --historical. The starting total is valued individually for each posting at its posting time.
< <
P 2020-01-01 A 1 B P 2020-01-01 A 1 B
P 2020-02-01 A 2 B P 2020-02-01 A 2 B
@ -593,7 +603,7 @@ $ hledger -f- reg --value=then -b 2020-03 -H
2020-04-01 (a) 4 B 10 B 2020-04-01 (a) 4 B 10 B
>=0 >=0
# 51. --value=then with a report interval. How are the summary amounts valued ? # 52. --value=then with a report interval. How are the summary amounts valued ?
# Currently each interval's unvalued sum is valued on its first day. # Currently each interval's unvalued sum is valued on its first day.
< <
P 2020-01-01 A 1 B P 2020-01-01 A 1 B
@ -618,7 +628,7 @@ $ hledger -f- reg --value=then -Q
2020Q2 a 4 B 7 B 2020Q2 a 4 B 7 B
>=0 >=0
# 52. print --value should affect all postings, including when there's an implicit transaction price # 53. print --value should affect all postings, including when there's an implicit transaction price
< <
P 2020-01-01 A 1 C P 2020-01-01 A 1 C
P 2020-01-01 B 1 C P 2020-01-01 B 1 C