Documentation: if|table, priority of search patterns about hledger HOT 12 OPEN

Is that something you would like to help with ?

I gave if tables a serious try recently but I found them difficult to understand and not very widely useful. I'd be more inclined to remove them, personally.

from hledger.

Is that something you would like to help with ?

Not really. It is just a request to improve documentation. I agree that if|tables are not easy to work with and could be confusing.
This example is nice use of if table, it is not so much confusing and explains how to use them (else rule, priority of rules).

Other way to define "else" rule, it has to be the first entry in the table (it has the lowest priority and matches any record):

# date has to be defined, it is mandatory field...
# The default value, it will be overwritten with values from the table.
date  9999-99-99

# The first rule defines default value (else value), the rule matches any record and
# it defines that month has 31 days.
# Following rules can change that
if|date
%ym .|%ym/31
%ym -02|%ym/28
%ym -04|%ym/30
%ym -06|%ym/30
%ym -09|%ym/30
%ym -11|%ym/30
%ym 2016-02|%ym/29
%ym 2020-02|%ym/29
%ym 2024-02|%ym/29
%ym 2028-02|%ym/29
%ym 2032-02|%ym/29

from hledger.

from hledger.

I don't use iftables, but

We want to translate that information in the way that payment is done in the last day of the month, like 2020-04 -> 2024-04-30. This is not straight forward task, months have different number of days, between 28 and 31 and February can have 28 or 29 days.

This is similar to one of the motivations for adding rewrite rules -- I wanted to warp the credit card repayment postings to the start of the billing period, so I regex-match the year-month bit, and hard-code a different day.

However this only works for my card where the start of the billing period is in the same month as the statement. I have one credit card where this holds and one where it doesn't.

To address the other, I was thinking we might need some kind of date manipulation support in rewrite rules. Although I wouldn't like to implement them!

In the meantime, I have an ugly series of 12 if statements which match the month portion like this

if
%type DD
& %description HALIFAX
& %date ../02/(....)
    comment2 date:\1-01-14
    account2 liabilities:clarity

The reason I mention this, I had hoped to try and tackle it with if tables but found that they don't help this problem at all.

from hledger.

I think this feature needs someone to champion it and do the work of making it more usable, otherwise it's for the chop sooner or later.

I think I wrote it originally and I use it extensively, and I would be very sad to see it go. @simonmichael , what kind of work (besides documentation) do you envision it needing?

Semantically, an "if table" of N rows behaves exactly the same as would N "if" statements, one per table row - it just occupies about 4x less lines (and significantly fewer characters, and removes the repetition, and ...), so I would argue that it is not significantly more confusing than N if statements

Edit: I have 2200 lines worth of "if tables" and while it is not hard to write a generator that would convert them into if statements to be included in the csv rules file, I would rather avoid doing this if possible

from hledger.

Actually, looking at the documentation, I would argue that the behavior is documented (emphasis in the below is mine):

An if table like the above is interpreted as follows:
try all of the matchers;
whenever a matcher succeeds, assign all of the values on that line to the corresponding hledger fields;
later lines can overrider earlier ones.
It is equivalent to this sequence of if blocks:

if MATCHERA
  HLEDGERFIELD1 VALUE1
  HLEDGERFIELD2 VALUE2
  ...

if MATCHERB
  HLEDGERFIELD1 VALUE1
  HLEDGERFIELD2 VALUE2
  ...

if MATCHERC
  HLEDGERFIELD1 VALUE1
  HLEDGERFIELD2 VALUE2
  ...

from hledger.

Ahaha, hello @adept. I didn't remember. There you are. Sorry to threaten your feature. :)

You're the first person I've found relying on it. Could you help us understand how/for what you use it ?

In my experience (multiple tries) it is extremely non-intuitive for "normal people" at present. The work needed is at least handling UX/doc requests like this one. Also I haven't found a good use case of my own where it helped, yet. It needs more examples/motivation.

I had vague ideas of how variations of it could be useful to more people. But I'll wait to hear what you tell us.

from hledger.

Ahaha, hello @adept. I didn't remember. There you are. Sorry to threaten your feature. :)

No worries, I knew you would not shoot to kill without warning :)

My primary use-case is this: for CSV import rules, I usually have account1 fixed in the rules file, and then based on the CSV line, I assign account2, and potentially a comment. Over time, you accumulate lots of rules that look roughly the same:

if SOMETHING
  account2    is:this
  comment    is this

Another way to present them would be:

if|account2|comment
SOMETHING|is:this:account|with this comment
SOMETHING ELSE|is:this:other:account|
AND THIS|is:yet:another:account|with a comment

This is way more compact, and it is also dead easy to add new rules -- maybe even in automated fashion: https://github.com/adept/full-fledged-hledger/wiki/Sorting-unknowns

from hledger.

Sorry, forgot one more thing. I have lots of csv files and a build system to convert them to journals. Tabular machine-readable nature of the (majority of) the rules means that I could easily check which rules affect which input files. Then, when rules change, i can rebuild just the affected journals: https://github.com/adept/full-fledged-hledger/wiki/Speeding-up

from hledger.

I miss a possibility to disable a row in if|table, like to comment it. And I miss comments to explain why some row is in if|table; this can improve readability of rules.

Something like this:

if|date
;%ym .|%ym/31  ; this matches every raw
.|%ym/31  ; this matches every raw too
%ym -02|%ym/28
; this is just a comment
%ym -04|%ym/30
;%ym -05|%ym/31  ; this rule is not needed, was disabled for test and once verified, it will be removed
%ym -06|%ym/30

from hledger.

Comment lines in the table body seem sensible, I made a PR for this.

Comments inside field assignments feel more controversial (plus, I don't immediately see how to implement them AND allow user to use ";" or "#" in, say, "comment" field assignments in the table), so I haven't done them.

from hledger.

I am using if tables. Anyone who is using https://github.com/adept/full-fledged-hledger is using if tables. My HLedger setup is based on adept's full fledge ledger.

from hledger.