From 0ef413bc25ec1b339968cb128811b4305042bee3 Mon Sep 17 00:00:00 2001 From: Stephen Morgan Date: Wed, 6 Jan 2021 21:11:01 +1100 Subject: [PATCH] doc,tests: Document new --value=then functionality and add tests. --- hledger/hledger.m4.md | 58 ++++++++++++++--------------- hledger/test/journal/valuation.test | 46 ++++++++++++++--------- 2 files changed, 56 insertions(+), 48 deletions(-) diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md index 465eee466..e0c9fb646 100644 --- a/hledger/hledger.m4.md +++ b/hledger/hledger.m4.md @@ -902,10 +902,8 @@ The TYPE part selects cost or value and valuation date: : Convert amounts to cost, using the prices recorded in transactions. `--value=then` -: Convert amounts to their value in the [default valuation commodity](#valuation-commodity), - using market prices on each posting's date. This is currently - supported only by the [print](#print) and [register](#register) - commands. +: Convert amounts to their value in the [default valuation commodity](#valuation-commodity), + using market prices on each posting's date. `--value=end` : Convert amounts to their value in the default valuation commodity, using market prices @@ -1058,32 +1056,32 @@ Related: [#329](https://github.com/simonmichael/hledger/issues/329), [#1083](https://github.com/simonmichael/hledger/issues/1083). -| Report type | `-B`, `--value=cost` | `-V`, `-X` | `--value=then` | `--value=end` | `--value=DATE`, `--value=now` | -|-----------------------------------------------------|------------------------------------------------------------------|-------------------------------------------------------------------|-------------------------------------------------------|-------------------------------------------------------------------|-----------------------------------------| -| **print** | | | | | | -| 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 | -|
| | | | | | -| **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 | -| 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 | -| 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 | -|
| | | | | | -| **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 | -| budget amounts (--budget) | like balance changes | like balance changes | not supported | 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 | -|
| | | | | | -| **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 | -| 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 | -| 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 | -| budget amounts (--budget) | like balance changes/end balances | like balance changes/end balances | not supported | 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 | -| column totals | sums of displayed values | sums of displayed values | not supported | 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 | -|
| | | | | | +| Report type | `-B`, `--value=cost` | `-V`, `-X` | `--value=then` | `--value=end` | `--value=DATE`, `--value=now` | +|-----------------------------------------------------|------------------------------------------------------------------|-------------------------------------------------------------------|------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|-----------------------------------------| +| **print** | | | | | | +| 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 | +|
| | | | | | +| **register** | | | | | | +| 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 | +| 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 | +|
| | | | | | +| **balance (bs, bse, cf, is)** | | | | | | +| 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 | like balance changes | like balances | like balance changes | +| grand total | sum of displayed values | sum of displayed values | sum of displayed valued | sum of displayed values | sum of displayed values | +|
| | | | | | +| **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 | 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 | 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 | 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 | 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 | 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 | 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 | sum, average of column totals | sum, average of column totals | sum, average of column totals | +|
| | | | | | `--cumulative` is omitted to save space, it works like `-H` but with a zero starting balance. diff --git a/hledger/test/journal/valuation.test b/hledger/test/journal/valuation.test index fc9ee8a8a..5128926fe 100644 --- a/hledger/test/journal/valuation.test +++ b/hledger/test/journal/valuation.test @@ -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 -# 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 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 -# 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 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 -# 37. multicolumn balance report valued at other date +# 38. multicolumn balance report valued at other date $ hledger -f- bal -MTA --value=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 -# 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 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 -# 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 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) -# 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). # February adds 1 A costing 7 B, making 13 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 -# 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. # 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. @@ -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 -# 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). $ 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: @@ -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 -# 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/15 A 5 B @@ -486,7 +496,7 @@ Ending balances (historical) in 2000Q1, valued at cost: ---++------------------------------------ || 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. $ hledger -f- bal -META -H -p200001-200004 --value=e 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 -# 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 Ending balances (historical) in 2000Q1, valued at 2000-01-15: @@ -529,7 +539,7 @@ P 2000/04/01 A 4 B 2000/03/01 (a) 1 A @ 8 B -# 46. budget report, unvalued (for reference). +# 47. budget report, unvalued (for reference). $ hledger -f- bal -M --budget 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] -# 47. budget report, valued at cost. +# 48. budget report, valued at cost. $ hledger -f- bal -MTA --budget --value=c 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] -# 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 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] -# 49. budget report, valued at other date. +# 50. budget report, valued at other date. $ hledger -f- bal -MTA --budget --value=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] -# 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-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 >=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. < P 2020-01-01 A 1 B @@ -618,7 +628,7 @@ $ hledger -f- reg --value=then -Q 2020Q2 a 4 B 7 B >=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 B 1 C