From 274751f48aebdb77340c419206a1611ef08dbf46 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sun, 27 Apr 2025 09:05:25 -1000 Subject: [PATCH] ;doc: balance assertions and multiple files: clarify again, add tests --- hledger/hledger.m4.md | 20 ++++++-------------- hledger/test/journal/assertions.test | 9 +++++++++ hledger/test/journal/assertions1.j | 4 ++++ hledger/test/journal/assertions11.j | 10 ++++++++++ hledger/test/journal/assertions2.j | 4 ++++ hledger/test/journal/assertions21.j | 7 +++++++ hledger/test/journal/assertions22.j | 4 ++++ hledger/test/journal/assertions31.j | 4 ++++ 8 files changed, 48 insertions(+), 14 deletions(-) create mode 100644 hledger/test/journal/assertions1.j create mode 100644 hledger/test/journal/assertions11.j create mode 100644 hledger/test/journal/assertions2.j create mode 100644 hledger/test/journal/assertions21.j create mode 100644 hledger/test/journal/assertions22.j create mode 100644 hledger/test/journal/assertions31.j diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md index c26f388e6..e103b024d 100644 --- a/hledger/hledger.m4.md +++ b/hledger/hledger.m4.md @@ -1679,25 +1679,17 @@ The exception is when you reorder multiple postings on the same day, to the same ### Assertions and multiple files If an account has transactions appearing in multiple files, balance assertions can still work - -but *only if those files are in a parent-child relationship, using [include directives](#include-directive)*. +but *only if those files are part of a hierarchy made by [include directives](#include-directive)*. -If the same files are siblings, the assertions will not work. -For example if you specify them with two `-f` options on the command line, -the assertions in one will not see the balances from the other. +If the same files are specified with two `-f` options on the command line, +the assertions in the second will not see the balances from the first. -But also, if a parent file includes the two subfiles with two side-by-side `include` directives, this too will fail (I think I have that right). -Assertions in one subfile will not see the balances from the other. - -To work around this, arrange your files in parent child relationships with `include`. -Eg make one subfile include the other (it doesn't matter which way round). - -Or, you could concatenate the files temporarily, and process them like one big file. Eg:\ -`hledger print -I | hledger -f- CMD` +To work around this, arrange your files in a hierarchy with `include`. +Or, you could concatenate the files temporarily, and process them like one big file. Why does it work this way ? It might be related to hledger's goal of stable predictable reports. -File hierarchy is considered "permanent" - it's part of your data. -Whereas the order of sibling files (on the command line at least) is transient - it can change from one command to the next. +File hierarchy is considered "permanent", part of your data, while the order of command line options/arguments is not. We don't want transient changes to be able to change the meaning of the data. Eg it would be frustrating if tomorrow all your balance assertions broke because you wrote command line arguments in a different order. (Discussion welcome.) diff --git a/hledger/test/journal/assertions.test b/hledger/test/journal/assertions.test index 66a164498..41d4a6664 100755 --- a/hledger/test/journal/assertions.test +++ b/hledger/test/journal/assertions.test @@ -493,3 +493,12 @@ $ hledger -f - check -I -s $ hledger -f - check assertions -I >2 /Balance assertion failed/ >=1 + +# ** 32. Assertions don't see balances from previous sibling -f files +$ hledger check assertions -f assertions1.j -f assertions2.j +>2 /assertion failed/ +>= 1 + +# ** 33. Assertions do see balances from parents and previous siblings/children in an include hierarchy +$ hledger check assertions -f assertions11.j + diff --git a/hledger/test/journal/assertions1.j b/hledger/test/journal/assertions1.j new file mode 100644 index 000000000..54a0c2eb1 --- /dev/null +++ b/hledger/test/journal/assertions1.j @@ -0,0 +1,4 @@ +; assertions1.j + +2025-01-01 + (a) 1 = 1 diff --git a/hledger/test/journal/assertions11.j b/hledger/test/journal/assertions11.j new file mode 100644 index 000000000..a81c1db09 --- /dev/null +++ b/hledger/test/journal/assertions11.j @@ -0,0 +1,10 @@ +; assertions11.j + +2025-01-11 + (a) 11 = 11 ; first assertion + +include assertions21.j +include assertions22.j + +2025-03-11 + (a) 100 = 185 ; sees balance from previous children diff --git a/hledger/test/journal/assertions2.j b/hledger/test/journal/assertions2.j new file mode 100644 index 000000000..8986cbfaf --- /dev/null +++ b/hledger/test/journal/assertions2.j @@ -0,0 +1,4 @@ +; assertions2.j + +2025-01-02 + (a) 1 = 2 ; won't see balance from previous sibling -f file diff --git a/hledger/test/journal/assertions21.j b/hledger/test/journal/assertions21.j new file mode 100644 index 000000000..a414f78e7 --- /dev/null +++ b/hledger/test/journal/assertions21.j @@ -0,0 +1,7 @@ +; assertions21.j + +2025-01-21 + (a) 21 = 32 ; sees balance from parent + +include assertions31.j + diff --git a/hledger/test/journal/assertions22.j b/hledger/test/journal/assertions22.j new file mode 100644 index 000000000..4a94ec996 --- /dev/null +++ b/hledger/test/journal/assertions22.j @@ -0,0 +1,4 @@ +; assertions22.j + +2025-02-22 * + (a) 22 = 85 ; sees balance from parent and previous siblings/children included by parent diff --git a/hledger/test/journal/assertions31.j b/hledger/test/journal/assertions31.j new file mode 100644 index 000000000..95ff3fbc5 --- /dev/null +++ b/hledger/test/journal/assertions31.j @@ -0,0 +1,4 @@ +; assertions31.j + +2025-01-31 + (a) 31 = 63 ; sees balance from parent and grandparent