Decoded time accessors

Decoded time accessors

[Lars Ingebrigtsen]

A while back we added accessors to the return value from
`file-attributes' (i.e., `file-attribute-size' etc), and I think that
was a readability win.

I think we should do the same for the return value for `decode-time',
but do it as settable values instead:

---

decode-time is a built-in function in ‘C source code’.

(decode-time &optional TIME ZONE)

  Probably introduced at or before Emacs version 19.29.
  This function does not change global state, including the match data.

Decode a time value as (SEC MINUTE HOUR DAY MONTH YEAR DOW DST UTCOFF).

---

So you could do something like

(let ((decoded (decode-time (parse-time-string ...))))
  (setf (decoded-time-year decoded) 1975)
  (apply #'encode-time decoded))

or whatever.  I hate reading code that says (elt decoded 5) and then
have to look up the doc string and then count to be able to tell what
it's doing...

Does this sound like a good idea?  And if so, what should the name of
these accessors be?  `decoded-time-' is clear, but perhaps a mouthful...

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: Decoded time accessors

[Paul Eggert]

Lars Ingebrigtsen wrote:
> I hate reading code that says (elt decoded 5) and then
> have to look up the doc string and then count to be able to tell what
> it's doing

I dislike that too. Luckily, it doesn't happen too often for me. I try to avoid 
it by using format-time-string instead of decode-time.

What do Common Lisp hackers do? Common Lisp has a similar function 
decode-universal-time, so they must have a similar problem.

Where in the source code would you put the accessors?

Re: Decoded time accessors

[Lars Ingebrigtsen]

Paul Eggert <eggert@cs.ucla.edu> writes:

> Lars Ingebrigtsen wrote:
>> I hate reading code that says (elt decoded 5) and then
>> have to look up the doc string and then count to be able to tell what
>> it's doing
>
> I dislike that too. Luckily, it doesn't happen too often for me. I try
> to avoid it by using format-time-string instead of decode-time.

Yup, but when writing code to manipulate times, it's often easier to
work on the decoded time instead of manipulating the other time forms.
(For instance, getting "next day at the same time" is much easier in
decoded time, because that can be 23, 24 or 25 hours depending on
DST...)

> What do Common Lisp hackers do? Common Lisp has a similar function
> decode-universal-time, so they must have a similar problem.

Yup.  I can only speak for myself, and we ended up with similar things
to what I'm proposing, only...  more organically grown over the years.
:-)

> Where in the source code would you put the accessors?

I was looking around in the tree, and I haven't really found a good
place to put them...  parse-time.el isn't basic enough, and the really
base time functions are in C.  So...  perhaps simple.el?  Or a new file,
decoded-time.el? 

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: Decoded time accessors

[Alan Mackenzie]

Hello, Lars.

On Sun, Jul 07, 2019 at 21:33:19 +0200, Lars Ingebrigtsen wrote:
> A while back we added accessors to the return value from
> `file-attributes' (i.e., `file-attribute-size' etc), and I think that
> was a readability win.

I disagree strongly.  It may be a "readability" win, but comes at great
cost.

My limited experience of this is that people don't bother to write the
necessary doc strings, or don't bother to write them properly, so one is
left guessing at the precise semantics.  For example the doc string for
`file-attribute-size' is poor, whereas the doc string for
`file-attribute' is better, though still not perfect.  To understand the
former, one must read _both_ doc strings.  This is not a win.

> I think we should do the same for the return value for `decode-time',
> but do it as settable values instead:

I disagree.  All these "readability hacks" greatly increase the number
of functions a hacker must cope with, and greatly increase their
complexity (they require cl-... macros, many of which are poorly
documented).

We've coped now with (nth 8 state) (for the starting position of a
string or comment) for decades now without any problems.  The sort of
"readability hack" proposed, as it is steadily proliferated, makes the
entry barrier for new Elisp programmers steadily higher.  To use it is
one extra thing which has to be learned, or looked up.

Are all these accessors going to find their way into the index of the
Elisp manual?  Well, yes, they need to.  But this will bloat that index
uncontrollably.

Personally, I find it rather un-lispy, more like C++.
(decoded-time-year result) looks like a (complicated) function call,
which you need to look up to find out what it does.  How is one, at a
glance, to tell whether that form is just an accessor, or a true
function call?  On the other hand (nth 5 result) is chrystal clear,
except to the rawest of beginners.

The other day, I came across new interfaces involving mark-data.  Rather
than return a simple 3-element list, they construct a (basically
undocumented) 3 element type, with accessors.  Why?  Because the fancy
cl- macro is there, therefore should be used?  Because the short
expression (nth 1 result) is too easy, and needs to be made more
complicated?  Because the typical hacker has too few function names to
exercise her imagination on?  Who knows?

This sort of complication needs to be kept in check.  But thanks, Lars,
for actually having the consideration to ask here first.


> ---

> decode-time is a built-in function in ‘C source code’.

> (decode-time &optional TIME ZONE)

>   Probably introduced at or before Emacs version 19.29.
>   This function does not change global state, including the match data.

> Decode a time value as (SEC MINUTE HOUR DAY MONTH YEAR DOW DST UTCOFF).

> ---

> So you could do something like

> (let ((decoded (decode-time (parse-time-string ...))))
>   (setf (decoded-time-year decoded) 1975)
>   (apply #'encode-time decoded))

> or whatever.  I hate reading code that says (elt decoded 5) and then
> have to look up the doc string and then count to be able to tell what
> it's doing...

That's what comments are for.  I will hate it even more having to look
up the doc string several times, once to find out what a function does,
and once for each accessor name I've got to use; then having somehow to
memorize that long accessor name between doc string and the source code
I'm writing.  (My memory isn't good enough to note all these names on
one sweep of the doc string.)

> Does this sound like a good idea?  And if so, what should the name of
> these accessors be?  `decoded-time-' is clear, but perhaps a mouthful...

Exactly!  (decoded-time-year result) will not be better than (nth 5
result).  Both really require comments:

    (decoded-time-year result) ; An accessor function.
vs.
    (nth 5 result) ; The year.

> -- 
> (domestic pets only, the antidote for overdose, milk.)
>    bloggy blog: http://lars.ingebrigtsen.no

-- 
Alan Mackenzie (Nuremberg, Germany).

Re: Decoded time accessors

[Lars Ingebrigtsen]

Alan Mackenzie <acm@muc.de> writes:

> My limited experience of this is that people don't bother to write the
> necessary doc strings, or don't bother to write them properly, so one is
> left guessing at the precise semantics.  For example the doc string for
> `file-attribute-size' is poor, whereas the doc string for
> `file-attribute' is better, though still not perfect.  To understand the
> former, one must read _both_ doc strings.  This is not a win.

If you see code with

(if (> (file-attribute-size (file-attributes "some/file")) 1000)
    ...)

then I think the meaning of that would be pretty obvious to everybody?

The doc string could be more verbose, but I think it describes the
semantics pretty clearly?

----

file-attribute-size is a compiled Lisp function in ‘files.el’.

(file-attribute-size ATTRIBUTES)

  Probably introduced at or before Emacs version 26.1.

The integer size (in bytes) in ATTRIBUTES returned by ‘file-attributes’.


-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: Decoded time accessors

[Clément Pit-Claudel]

On 2019-07-07 17:43, Alan Mackenzie wrote:
> We've coped now with (nth 8 state) (for the starting position of a
> string or comment) for decades now without any problems.  The sort of
> "readability hack" proposed, as it is steadily proliferated, makes the
> entry barrier for new Elisp programmers steadily higher.  To use it is
> one extra thing which has to be learned, or looked up.

FWIW, I disagree; I find that these accessor functions actually help.  And I think I count as fairly new, since I've been writing ELisp for just 5 years. 

The nice part about these accessor functions is that I only have to look them up once (and often not even once, since the name gives a precise enough idea of what they do).  But after 5 years, I still can't remember what each part of syntax-ppss means (and I end up defining my own aliases in each new package).

Besides, if I want detailed documentation, having to click on one more link to get to the docstring of file-attributes really isn't much of a problem, as far as I'm concerned.  And if a piece of code does (nth 3 attrs), how am I supposed to know that I have to look at the documentation of file-attributes to know what is in attrs?  If attrs is an argument of the current function I need to read the docstring, and if there isn't one or it doesn't say then I have to find the callers.  That's a lot harder than if the code used an accessor function on attrs.

Clément.

Re: Decoded time accessors

[Eli Zaretskii]

> Date: Sun, 7 Jul 2019 21:43:26 +0000
> From: Alan Mackenzie <acm@muc.de>
> Cc: emacs-devel@gnu.org
> 
> My limited experience of this is that people don't bother to write the
> necessary doc strings, or don't bother to write them properly, so one is
> left guessing at the precise semantics.  For example the doc string for
> `file-attribute-size' is poor, whereas the doc string for
> `file-attribute' is better, though still not perfect.  To understand the
> former, one must read _both_ doc strings.  This is not a win.

Can you tell more about your example?  AFAICT, file-attribute-size
just repeats what file-attributes says about its 7th element, nothing
more, nothing less.  What is missing from the doc string of the former
that requires you to read the latter?

> I disagree.  All these "readability hacks" greatly increase the number
> of functions a hacker must cope with

I think "must" hear is inaccurate, because you can still reference the
original list by element numbers.  Only those who want it will use the
accessors.

Accessor functions vs nth (WAS: Decoded time accessors)

[Noam Postavsky]

On Sun, 7 Jul 2019 at 17:43, Alan Mackenzie <acm@muc.de> wrote:

> I disagree.  All these "readability hacks" greatly increase the number
> of functions a hacker must cope with, and greatly increase their
> complexity (they require cl-... macros, many of which are poorly
> documented).
>
> We've coped now with (nth 8 state) (for the starting position of a
> string or comment) for decades now without any problems.  The sort of
> "readability hack" proposed, as it is steadily proliferated, makes the
> entry barrier for new Elisp programmers steadily higher.  To use it is
> one extra thing which has to be learned, or looked up.

> This sort of complication needs to be kept in check.  But thanks, Lars,
> for actually having the consideration to ask here first.

Huh. I'm constantly annoyed at the (nth 8 state) thing, because I can
never remember which number is which. In fact, I had meant to propose
some accessors in Bug#32504. It didn't actually occur to me that this
might be at all controversial, the only reason that bug sat for a
while is that I got busy with other things.

https://debbugs.gnu.org/32504#51

Re: Accessor functions vs nth (WAS: Decoded time accessors)

[João Távora]

[-- Attachment #1: Type: text/plain, Size: 1073 bytes --]

On Tue, Jul 9, 2019 at 1:12 AM Noam Postavsky <npostavs@gmail.com> wrote:

> > This sort of complication needs to be kept in check.  But thanks, Lars,
> > for actually having the consideration to ask here first.
>
> Huh. I'm constantly annoyed at the (nth 8 state) thing, because I can
> never remember which number is which. In fact, I had meant to propose
> some accessors in Bug#32504. It didn't actually occur to me that this
> might be at all controversial, the only reason that bug sat for a
> while is that I got busy with other things.
>
> https://debbugs.gnu.org/32504#51
>
> I don't see any reason for it to be controversial, either.  If some people
like the terseness (and what I believe is the unneeded obfuscation) of (nth
8 x)
they can still use it. I'd rather have (in-string-or-comment-p s).  The
syntax-ppss
situation is particularly painful because the doc is actually in
parse-partial-sexp. So you're using syntax-ppss but have to remember to
find the doc in that other function (unless you like clicking a link each
time)

João

[-- Attachment #2: Type: text/html, Size: 1528 bytes --]

Re: Decoded time accessors

[Lars Ingebrigtsen]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> A while back we added accessors to the return value from
> `file-attributes' (i.e., `file-attribute-size' etc), and I think that
> was a readability win.
>
> I think we should do the same for the return value for `decode-time',
> but do it as settable values instead:

I proposed some weeks back, and there was one person that didn't like
the idea, while the others who spoke up were either for it or neutral.

I found myself writing a proper ISO 8601 library starting just after
that (to solve a problem with parsing citations in bibtex, which a user
had reported), and while doing that, I found these accessors to be
really handy, so I added them.

While writing the ISO 8601 parsing library (did you know that
"P1Y2M10DT2H30M/2008W32T153000-01" is a valid duration?  ISO 8601
contains multitudes), I also found myself in need of writing functions
to do math on decoded time structures.  This all happened on the
scratch/iso8601 branch.

I've now mashed the work there into two commits -- one for the decoded
time stuff, and one for the ISO 8601 work itself.

The new stuff is documented and NEWS'd, but the documentation probably
needs copy-editing.  And some concept index entries, perhaps...

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no