natural language dates (last, first, etc)

[Per Uger]

I'm getting into hledger, and trying to set up periodic transactions.  I like the flexibility of the date constructions.  However, I wonder what is the best way to build a periodic transaction on the last weekday of a month (e.g., a paycheck).  I see reference to "weekday" in the manual, but know how to go from there.

I can individual month transactions for 28/30/31 day, but not guaranteed to be a weekday.  

Any thoughts?

[Simon Michael]

I could be wrong, but I’d guess we can’t express that right now..

Would someone like to review our smart date constructs and identify such “holes” ? The current syntax is flexible, but more evolved than systematic. 

--
You received this message because you are subscribed to the Google Groups "hledger" group.
To unsubscribe from this group and stop receiving emails from it, send an email to hledger+u...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Robert Nielsen]

I would be willing to review the smart date constructs. However, because of my schedule I may not finish for a couple of weeks. Is that still useful to you?

Rob

[Simon Michael]

Sure!

[Robert Nielsen]

Following up on this, I compared hledger’s options for scheduling transactions with two commercial programs that schedule events: MS Outlook and Calendar (for the Mac). Why compare hledger to Outlook and Calendar, when the latter two are not specific to finances? For one, they are used for scheduling recurring events, and that is the function we are looking at in hledger, even if the hledger “event” is a financial transaction. In addition, Outlook and Calendar are widely used, and presumably a lot of thought has gone into their design. Finally, I have access to these programs and can test what they do and don’t do. In other words, it’s one thing to read about a program; it is another to be able to do hands on testing.

Also, it’s very possible that I have missed some ways one or more of the programs works, so corrections are welcomed!

I have organized the comparison starting with a summary, and then examining in more detail five basic options for scheduling: daily, weekly, monthly, quarterly and yearly.

Summary
There is considerable overlap between hledger and the two commercial programs. However, there are some differences.

Some of the things that hledger doesn’t have are:

• A distinction between weekend days and the rest of the workweek (note, depending on the locale, one country’s weekend day may be another country’s workday)
• An option for “last” as in the last Monday of a month

On the other hand, hledger has some things that the commercial programs don’t:

• An explicit way to schedule quarterly events
• An option to extend 1st, 2nd, 3rd, 4th, and 5th indefinitely (there must be an upper limit, but I didn’t come across one in my testing)

And there are even different definitions between hledger and the commercial programs for what might appear at first glance to be the same thing. For example, all programs have the concept of 1st, 2nd, 3rd, and 4th (as in 4th Monday). However, there are differences in the definition.

Daily and Weekly
First, all three programs seem to handle daily and weekly scheduling largely the same. Daily events can be scheduled every X number of days. Weekly events can be scheduled on a specific day of the week (e.g., every Monday). Events can also be scheduled every Xth day of the week, such as every second Tuesday. That is, the event would take place every other week on a Tuesday.

Monthly
In terms of similarities, the 3 programs allow for the option to schedule

• Every X month(s)
• Every 1st, 2nd, 3rd, and 4th Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, and Saturday
• A date, such as the 23rd of a month

As to differences, the two commercial programs allow the following, which the current version of hledger doesn’t have:

• An option for “last,” as in the last Tuesday of the month
• Options to select “weekday” or “weekend day” as in the 3rd weekday of the month or the last weekday of the month

Note that hledger does have “weekday” option; however, “weekday” in the commercial programs means the part of the week traditional or normative for working (Monday to Friday in many places, but this depends on the locale—see https://en.wikipedia.org/wiki/Workweek_and_weekend for more information on this topic). Note, though, that in hledger, weekday means any of the seven days of the week.

Both hledger and Calendar offer an option for the 5th Monday, Tuesday, Wednesday, etc. of the month (e.g., “5th Monday of July”). However, with Calendar, if you set up something for the 5th Monday of every month, Calendar will schedule something only if there is a 5th Monday. In contrast, hledger will schedule something every 5th Monday, no matter where it falls in a month.

In addition, hledger differs from the other two programs in that it allows for 6th, 7th, 8th, etc. Monday, Tuesday, Wednesday, etc. of the month. While at first glance this sounds impossible (i.e., there is no “7th Monday of a month”), hledger calculates the nth Monday, Tuesday, etc. beginning from whatever period is specified or understood. For example, the 11th Monday of 2018 is March 12, 2018. Similarly, the 11th Monday of January (of 2018) is exactly the same date (March 12, 2018) as hledger counts 11 Mondays beginning with the first Monday in January until it arrives at March 12.

Quarterly
While hledger supports quarterly intervals, neither Outlook nor Calendar explicitly have this option (though it would be possible to define something that repeated quarterly).

Yearly
All three programs can work with yearly intervals, but Calendar adds the option to specify every N years.

When specifying a yearly interval, Calendar and Outlook require a month and a day to be specified. (Calendar additionally gives the option to specify multiple months, so you can have something yearly that happens in specific months, for example: January, February, and September.) Along with the month, a specific day is required, the same as with a monthly interval, which I will summarize for the two commercial programs:

• Every 1st, 2nd, 3rd, and 4th Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, and Saturday
• An option for “last,” as in the last Tuesday of the month
• Options to select “weekday” or “weekend day” as in the 3rd weekday of the month or the last weekday of the month
• A date, such as the 23rd of a month

When specifying a yearly interval for hledger, you also specify a month and a day (which are implied if no month or day is stated). As stated above in the discussion for monthly intervals, hledger has the following options for days:

• Every 1st, 2nd, 3rd, etc. Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, and Saturday
• A date, such as the 23rd of a month

[Simon Michael]

Thanks for the interesting review Robert. This is very helpful.

> every second Tuesday. That is, the event would take place every other week on a Tuesday.

Would you remind me, how do you write that with current hledger ?

I looked for a suitable issue and found https://github.com/simonmichael/hledger/issues/650 , and linked this thread there.

Ideas for the backlog:
- add ISO8601 to this comparative review
- develop more thorough and clearer docs; in particular, a list or table giving examples for all of the cases we're discussing
- pursue those other todos noted on the issue in september

[Robert Nielsen]

The answer is that there is no way to explicitly specify something like every 2nd Tuesday in hledger. That was my misreading of the documentation and my not thinking to test that feature.

However, there is a workaround for the current version of hledger for anyone who needs this behavior. To set a periodic transaction for every two weeks, you would set the days to "every 14 days" and start the period on whatever Tuesday you needed, as in:

~ every 14 days from 2019/1/1 to 2019/4/1 ; 2019/1/1 is a Tuesday
expenses:test $1
assetts:checking

Similarly, if you need every 2nd Wednesday, you would write:

~ every 14 days from 2019/1/2 to 2019/4/1 ; 2019/1/2 is a Wednesday
expenses:test $1
assetts:checking

And as a last example, if you needed every 3rd Friday, the following will do the trick:

~ every 21 days from 2019/1/4 to 2019/4/1 ; 2019/1/4 is a Friday
expenses:test $1
assetts:checking

If you see anything else that looks like it would benefit from some more testing ;-) please let me know, and I will be glad to do so!

Rob

[Simon Michael]

Ah, yes. We can express "every second tuesday" but not yet "every second tuesday of the month".

[Robert Nielsen]

hledger actually handles quite well the idea of the second Tuesday of each month, as in:

~ every 2nd Tuesday from 2019/1/4 to 2019/4/1

expenses:test $1
assetts:checking

No improvements needed there, as far as I can see!

Rob

[Simon Michael]

Oh, right you are.