Readers

[psionic-k]

Some code I just wrote needed understand these input formats:

;; (champagne nil "12:00am") ; will use tomorrow if necessary
;; (champagne nil "12:00") ; ⚠️ read as military time, tomorrow if necessary
;; (champagne nil 60) ; one minute from now
;; (champagne nil "2 hours 10 minutes") ; two hours and 10 minutes from now

To do this attempting to re-use bits from around Emacs, I had to rob run-at-time and lean on diary-lib other bits. Given how common applications using time are, my expectation was a more unified set of tools. The results:

https://github.com/positron-solutions/champagne/blob/master/lisp/champagne.el#L199-L246

The other path I looked at was org-read-date. org-read-date is powerful, but is not IMO designed for programmers. Mainly, it requires let-binding org-popup-calendar-for-date-prompt and org-read-date-prefer-future instead accepting proper arguments like other readers. Its output is a timestamp.

1. Should we put readers in ts?
2. If so, what supported input formats will cover the ROI sweet spot?
3. What does the preferred outcome look like in terms of implementation?

The timer-duration-words style parsing approach looks like a near match for using ts-apply and ts-adjust downstream, returning a time that is adjusted either relatively or absolutely. For arguments:

• The choice of ts-apply versus ts-adjust would depend on whether a recognized format is time-like or duration-like.
• Formats like HH:MM are ambiguously both times and durations. An argument should control preference for HH:MM or MM:SS etc.
• Fill preferences
• Future preference

That's enough for now. org-read-date demonstrates how complex things can get if a nearly complete cover is attempted.

[alphapapa]

my expectation was a more unified set of tools.

Your first lesson... :) Haha, seriously though, I'm glad you're taking an interest in the subject, because a better API is certainly needed. My own attempts at using Org's code proved complicated, as you also found.

Here are some thoughts:

Should we put readers in ts?

I don't object, in principle. I would prefer that Emacs have such functions itself someday, but maybe we can be at least a testing/proving ground for an implementation. (With that in mind, I'd probably ask that any code contributions come from an author who's signed the FSF Copyright Assignment, so it could be upstreamed into Emacs someday.)

If so, what supported input formats will cover the ROI sweet spot?

shrug As many as seem reasonable? As many as we can find? Something like that.

I think we'd want to handle both relative and absolute ones, of course.

Ideally we should probably also have a way to plug in words and abbreviations from other languages, because it's probably common for users to use both English and another language when working with times and dates and other people.

What does the preferred outcome look like in terms of implementation?

I'd guess that we should provide a library in a separate file, like ts-read, and perhaps not even use any other functions from ts, so as to make it easier to upstream (and avoid any parts of ts which may be a bit outdated since Emacs's time-related changes in 28-29). Probably there should be a single public function, like ts-read, which should have an interactive form as well (and that part could be delegated to a separate, private function), and it should return an Emacs native timestamp value. I'd guess that we should minimize the number of arguments as much as possible, and keep the function's scope limited to reading a string value and returning a timestamp value. If downstream code only cared about the time and not the date, for example, there are other functions that can be used to do that later.

What do you think?

Thanks.