* Decoded time accessors @ 2019-07-07 19:33 Lars Ingebrigtsen 2019-07-07 19:52 ` Paul Eggert ` (2 more replies) 0 siblings, 3 replies; 10+ messages in thread From: Lars Ingebrigtsen @ 2019-07-07 19:33 UTC (permalink / raw) To: emacs-devel 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 ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: Decoded time accessors 2019-07-07 19:33 Decoded time accessors Lars Ingebrigtsen @ 2019-07-07 19:52 ` Paul Eggert 2019-07-07 20:09 ` Lars Ingebrigtsen 2019-07-07 21:43 ` Alan Mackenzie 2019-07-29 12:29 ` Decoded time accessors Lars Ingebrigtsen 2 siblings, 1 reply; 10+ messages in thread From: Paul Eggert @ 2019-07-07 19:52 UTC (permalink / raw) To: Lars Ingebrigtsen; +Cc: emacs-devel 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? ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: Decoded time accessors 2019-07-07 19:52 ` Paul Eggert @ 2019-07-07 20:09 ` Lars Ingebrigtsen 0 siblings, 0 replies; 10+ messages in thread From: Lars Ingebrigtsen @ 2019-07-07 20:09 UTC (permalink / raw) To: Paul Eggert; +Cc: emacs-devel 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 ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: Decoded time accessors 2019-07-07 19:33 Decoded time accessors Lars Ingebrigtsen 2019-07-07 19:52 ` Paul Eggert @ 2019-07-07 21:43 ` Alan Mackenzie 2019-07-07 22:20 ` Lars Ingebrigtsen ` (3 more replies) 2019-07-29 12:29 ` Decoded time accessors Lars Ingebrigtsen 2 siblings, 4 replies; 10+ messages in thread From: Alan Mackenzie @ 2019-07-07 21:43 UTC (permalink / raw) To: Lars Ingebrigtsen; +Cc: emacs-devel 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). ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: Decoded time accessors 2019-07-07 21:43 ` Alan Mackenzie @ 2019-07-07 22:20 ` Lars Ingebrigtsen 2019-07-07 22:25 ` Clément Pit-Claudel ` (2 subsequent siblings) 3 siblings, 0 replies; 10+ messages in thread From: Lars Ingebrigtsen @ 2019-07-07 22:20 UTC (permalink / raw) To: Alan Mackenzie; +Cc: emacs-devel 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 ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: Decoded time accessors 2019-07-07 21:43 ` Alan Mackenzie 2019-07-07 22:20 ` Lars Ingebrigtsen @ 2019-07-07 22:25 ` Clément Pit-Claudel 2019-07-08 14:41 ` Eli Zaretskii 2019-07-09 0:12 ` Accessor functions vs nth (WAS: Decoded time accessors) Noam Postavsky 3 siblings, 0 replies; 10+ messages in thread From: Clément Pit-Claudel @ 2019-07-07 22:25 UTC (permalink / raw) To: emacs-devel 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. ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: Decoded time accessors 2019-07-07 21:43 ` Alan Mackenzie 2019-07-07 22:20 ` Lars Ingebrigtsen 2019-07-07 22:25 ` Clément Pit-Claudel @ 2019-07-08 14:41 ` Eli Zaretskii 2019-07-09 0:12 ` Accessor functions vs nth (WAS: Decoded time accessors) Noam Postavsky 3 siblings, 0 replies; 10+ messages in thread From: Eli Zaretskii @ 2019-07-08 14:41 UTC (permalink / raw) To: Alan Mackenzie; +Cc: larsi, emacs-devel > 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. ^ permalink raw reply [flat|nested] 10+ messages in thread
* Accessor functions vs nth (WAS: Decoded time accessors) 2019-07-07 21:43 ` Alan Mackenzie ` (2 preceding siblings ...) 2019-07-08 14:41 ` Eli Zaretskii @ 2019-07-09 0:12 ` Noam Postavsky 2019-07-10 10:02 ` João Távora 3 siblings, 1 reply; 10+ messages in thread From: Noam Postavsky @ 2019-07-09 0:12 UTC (permalink / raw) To: Alan Mackenzie; +Cc: Lars Ingebrigtsen, Emacs developers 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 ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: Accessor functions vs nth (WAS: Decoded time accessors) 2019-07-09 0:12 ` Accessor functions vs nth (WAS: Decoded time accessors) Noam Postavsky @ 2019-07-10 10:02 ` João Távora 0 siblings, 0 replies; 10+ messages in thread From: João Távora @ 2019-07-10 10:02 UTC (permalink / raw) To: Noam Postavsky; +Cc: Alan Mackenzie, Lars Ingebrigtsen, Emacs developers [-- 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 --] ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: Decoded time accessors 2019-07-07 19:33 Decoded time accessors Lars Ingebrigtsen 2019-07-07 19:52 ` Paul Eggert 2019-07-07 21:43 ` Alan Mackenzie @ 2019-07-29 12:29 ` Lars Ingebrigtsen 2 siblings, 0 replies; 10+ messages in thread From: Lars Ingebrigtsen @ 2019-07-29 12:29 UTC (permalink / raw) To: emacs-devel 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 ^ permalink raw reply [flat|nested] 10+ messages in thread
end of thread, other threads:[~2019-07-29 12:29 UTC | newest] Thread overview: 10+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2019-07-07 19:33 Decoded time accessors Lars Ingebrigtsen 2019-07-07 19:52 ` Paul Eggert 2019-07-07 20:09 ` Lars Ingebrigtsen 2019-07-07 21:43 ` Alan Mackenzie 2019-07-07 22:20 ` Lars Ingebrigtsen 2019-07-07 22:25 ` Clément Pit-Claudel 2019-07-08 14:41 ` Eli Zaretskii 2019-07-09 0:12 ` Accessor functions vs nth (WAS: Decoded time accessors) Noam Postavsky 2019-07-10 10:02 ` João Távora 2019-07-29 12:29 ` Decoded time accessors Lars Ingebrigtsen
Code repositories for project(s) associated with this external index https://git.savannah.gnu.org/cgit/emacs.git https://git.savannah.gnu.org/cgit/emacs/org-mode.git This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.