Handle bucket directive (default account to balance postings against)

[jneubrand]

Resolves #989.

I'm not super happy about this—however, it clearly needs some context from the parser and I want to avoid changing Transaction.

[simonmichael]

Thanks for the PR @jneubrand !

I must tell you I'm if anything less fond of this directive than I was last year. I'm not sure it brings enough benefit to justify the cost (yet another "complicated" hledger feature, strange name, obfuscation of journals..). On the other hand, it would be one more piece of Ledger syntax we can parse easily.

Can you motivate it a bit for me ? Is this something you find valuable and use a lot ?

I've sent a poll to the mail list also, to get more input.

The Ledger manual says: Defines the default account to use for balancing transactions. Normally, each transaction has at least two postings, which must balance to zero. Ledger allows you to leave one posting with no amount and automatically balance the transaction in the posting. The bucket allows you to fill in all postings and automatically generate an additional posting to the bucket account balancing the transaction. If any transaction is unbalanced, it will automatically be balanced against the bucket account. Does this describe your implementation too ? I guess an extra posting is added, only to transactions which can't be balanced otherwise ?

What will be the scope of this directive ? (cf https://hledger.org/journal.html#directives)

I'd like to see how this interacts with balance assertions and balance assignments.

[jneubrand]

I use this in practically all my journals. I keep them organized as [year]/[category].ledger. Within each category file I have sections per payment method, and finally within those, all transactions are chronological. This means that the vast majorities of transactions take two lines, which makes it very easy to scan the journal visually.

I've tested this impl on my journals, and it has the same results as ledger does.

That being said, the functionality isn't exactly the same: counter to what its documentation implies, ledger throws a hissy fit on this:

bucket A
2020-01-01 X
    B    $5
    C    $5

This is an unbalanced transaction, but ledger does not balance it with account A (instead erroring). This PR's implementation handles the transaction as if     A (optionally with $-10) were appended.

We could match this behavior by also predicating the additional posting on length postings == 1.

---

Wrt. scope: end bucket does not exist in ledger, though I'd be happy to add it, if you'd like.

Children inherit the parent's bucket in ledger, this doesn't. It seems like that'd be a relatively simple newJournalWithParseStateFrom change.

---

I have no idea about balance assertions/assignments. I have a weird setup for checking balances, and assignments aren't relevant either, so I don't use those features. I could compare this with ledger's test cases from the repo, though.

[simonmichael]

I use this in practically all my journals. I keep them organized as [year]/[category].ledger. Within each category file I have sections per payment method,

I guess this means you have multiple bucket directives, affecting different parts of a file ?

This is an unbalanced transaction, but ledger does not balance it with account A (instead erroring). This PR's implementation handles the transaction as if     A (optionally with $-10) were appended.

Sounds good.

Wrt. scope: end bucket does not exist in ledger, though I'd be happy to add it, if you'd like.

Children inherit the parent's bucket in ledger, this doesn't. It seems like that'd be a relatively simple newJournalWithParseStateFrom change.

I'm guessing right now then, the scope is "from the bucket directive to the next bucket directive or end of current file, but not affecting children".

Yes it would probably need to affect children (until end of file). This would make it one of the "following inline/included entries until end of current file or end directive" directives. Is that the most useful scope for this directive to have, or would something else (cf last column of the directives table) be preferable ? What scope does it have in Ledger ?

I have no idea about balance assertions/assignments.

Some exploration of these will be needed for sure, as they complicate transaction balancing a lot.

[simonmichael]

If added, we would have (as in Ledger): account, bucket, apply account/end apply account.

With an eye on long-term clarity/learnability, what would you think of supporting an alternate spelling for this: balancing-account.. and adding parent-account as an alias for apply account.. so we could teach new users: account, balancing-account, parent-account/end parent-account. Worthwhile ?

[jneubrand]

I guess this means you have multiple bucket directives, affecting different parts of a file ?

Yep.

Yes it would probably need to affect children (until end of file). This would make it one of the "following inline/included entries until end of current file or end directive" directives. Is that the most useful scope for this directive to have, or would something else (cf last column of the directives table) be preferable ? What scope does it have in Ledger ?

I agree with that scope, and:

• that is what ledger does, except the end directive is missing.
• this PR would conform to that scope after two changes: newJournalWithParseStateFrom & the end counterpart.

With an eye on long-term clarity/learnability, what would you think of supporting an alternate spelling for this:

I think that's a very good idea (and hopefully it would propagate to ledger), but would like you to consider enforcing “apply” for both instead of neither: apply parent-account / apply balancing-account. In a sense, these are both “applied” to transactions instead of stated as a fact (“this account exists”.)

[simonmichael]

Sorry for the inactivity on this. I'm not super fond of the apply keyword myself and wanted to get rid of it for simplicity. I think all other directives are a single word.

[jneubrand]

Hey Simon! A lot of time has passed and I still use these changes locally (I realize the PR's current state isn't ready to be merged w/r/t documentation & more, but maybe it's useful to someone else…).

Just wondering whether you're still interested in considering these changes. If so, I'd be glad to spend some more time on this.

[simonmichael]

Hi @jneubrand thanks for checking. I'm not interested in this feature myself and when I polled the mail list in 2020 the response was two against. If you can raise a small crowd in favour of this, I'd rethink.