Re: Making decoded-times and calendar dates compatible?

[Richard Lawrence <rwl@recursewithless.net>]

Hi Richard and all,

Richard Stallman <rms@gnu.org> writes:

> I tried reading the code of calendar.el to see what data structures it
> uses, but I could not find documentation for that.  (The file is
> enormous.)
>
> Can you tell me where to find that documentation?  Perhaps
> wuotq a few lines so I can search for them.

The only documentation I'm aware of (besides the Calendar/Diary section
in the Emacs manual, which doesn't deal with the programming interface)
is in the docstrings of the library. The docstrings of the functions

calendar-extract-year
calendar-extract-month
calendar-extract-day

are where the (MONTH DAY YEAR) format is mentioned. I *believe* these
functions are used pretty consistently as accessors in the calendar
code, so in theory changing the representation would only require
changing these functions, but honestly I have no idea at this point how
much of a pain it would be.

This is the "standard", Gregorian format for calendar dates, but it is
not the only format that the calendar works with. Internally it also
uses an "absolute" format which is an integer number of days since
December 31, 1BC (see e.g. `calendar-absolute-from-gregorian'), and
converts between different calendar scales by converting to and from the
absolute format (see e.g. `calendar-iso-from-absolute').

Similarly, the only documentation I'm aware of for the decoded-time
format is in the docstrings of the functions `decode-time' and
`parse-time-string', and in the symbol documentation for `decoded-time',
which is declared as a cl-struct with :type list in simple.el. According
to a comment there, the point of this declaration is to provide
accessors for the various slots in the list, e.g. `decoded-time-month'.

>   > If we changed them to use a format like, say,
>   >   (YEAR MONTH DAY)
>   > and 
>   >   (YEAR MONTH DAY DOW HOUR MINUTE SECOND DST TZ)
>   > respectively, changing the relevant accessors, then calendar arithmetic
>   > functions could also work effortlessly with [the date part of] decoded
>   > times,
>
> In principle it sounds like a good idea, but I think that the
> incompatibility might be a big pain to fix.  Doesn't some user code
> have to operate on those formats?

It could very well be a big pain to fix. I'm not sure how much user code
has to work with these formats. I know I've written some code to work
with them once or twice.

Personally, I think it's reasonable to change the underlying format as
long as the documented accessors (calendar-extract-*, decoded-time-*)
continue to work as expected. User code which uses these functions will
then continue to work. User code which instead makes assumptions about
the underlying format is not respecting an abstraction boundary, and
it's reasonable to break this code. But I realize that my personal view
may be more liberal than the general view of the Emacs community on this
point; that's fine (and I'm surely grateful for it in other cases!).

> I wonder also if calendar.el was designed to be compatible with
> something in Unix that existed before GNU Emacs.  But I wasn't the
> one who wrote it, so I wouldn't know.

I don't know either.

> One possible way to make the incompatible change less of a pain to
> cope with would be to use a list like
>
>   (calendar YEAR MONTH DAY)
>
> in caledar.el.  The presence of the synbol `calendar' would say "this
> date uses the new format", thus avoiding ambiguity of the datum.
> There would still need to be a lot of change, but at least it would be
> easier to be sure you found all the places that had to be changed.

If we were going to do that, it might make sense to just declare
calendar dates as cl-structs, since this provides the tag automatically,
and comes along with some other benefits.

Best,
Richard