[PATCH 0/2] org-clock: Simplify `untilnow' range logic

[PATCH 0/2] org-clock: Simplify `untilnow' range logic

[Kyle Meyer]

Hello,

For the clock table `untilnow' behavior, we set the starting point to
a really old date, but that falls outside the YYYY-MM-DD that
org-parse-time-string was designed to handle.  I've reworked
org-clock-special-range to use nil to represent the starting bound for
`untilnow' and updated org-parse-time-string to mention the YYYY-MM-DD
assumption.

Please let me know if you have any objections.  Otherwise, I'll apply
the following commits to maint in a few days.

  org-clock: Simplify `untilnow' range logic
  org-parse-time-string: Describe time stamp matching behavior

 lisp/org-clock.el | 9 ++++-----
 lisp/org-macs.el  | 4 +++-
 2 files changed, 7 insertions(+), 6 deletions(-)

-- 
2.20.0

[PATCH 1/2] org-clock: Simplify `untilnow' range logic

[Kyle Meyer]

* lisp/org-clock.el (org-clock-special-range): Use nil to represent
`untilnow'.

For `untilnow', org-clock-special-range sets the start to
"<-50001-11-30 Tue 00:00>", but org-parse-time-string actually assumes
a YYYY-MM-DD format and parses the year as 0001.  By chance, this is
still a really old date, so no one noticed.  However, with the port of
Emacs's fde99c729c (Port recent org-clock fix to POSIX time_t,
2018-03-28), test-org-clock/clocktable/ranges would fail if the system
supports the oldest date tried, "<-67715-09-22 Tue 17:51>".

But this "encode-time -> format-time-string -> org-parse-time-string"
dance is unnecessary.  All the current callers of
org-clock-special-range in Org's codebase (1) explicitly check if the
starting time is nil, (2) don't use the starting time, or (3) pass it
directly to org-clock-sum, which handles nil values.  And
org-clock-sum executes the same codepath when nil is passed instead of
"really old date".
---
 lisp/org-clock.el | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/lisp/org-clock.el b/lisp/org-clock.el
index 494423e4e..2c24b04fb 100644
--- a/lisp/org-clock.el
+++ b/lisp/org-clock.el
@@ -2126,7 +2126,8 @@ (defun org-clock-special-range (key &optional time as-strings wstart mstart)
 the beginning of the range and one for its end, like the ones
 returned by `current-time' or `encode-time' and a string used to
 display information.  If AS-STRINGS is non-nil, the returned
-times will be formatted strings.
+times will be formatted strings.  Note that the first element is
+always nil when KEY is `untilnow'.
 
 If WSTART is non-nil, use this number to specify the starting day
 of a week (monday is 1).  If MSTART is non-nil, use this number
@@ -2243,9 +2244,7 @@ (defun org-clock-special-range (key &optional time as-strings wstart mstart)
     ;; Format start and end times according to AS-STRINGS.
     (let* ((start (pcase key
 		    (`interactive (org-read-date nil t nil "Range start? "))
-                    ;; In theory, all clocks started after the dawn of
-                    ;; humanity.
-		    (`untilnow (encode-time 0 0 0 0 0 -50000))
+		    (`untilnow nil)
 		    (_ (encode-time 0 m h d month y))))
 	   (end (pcase key
 		  (`interactive (org-read-date nil t nil "Range end? "))
@@ -2269,7 +2268,7 @@ (defun org-clock-special-range (key &optional time as-strings wstart mstart)
 	      (`untilnow "now"))))
       (if (not as-strings) (list start end text)
 	(let ((f (cdr org-time-stamp-formats)))
-	  (list (format-time-string f start)
+	  (list (and start (format-time-string f start))
 		(format-time-string f end)
 		text))))))
 
-- 
2.20.0

[PATCH 2/2] org-parse-time-string: Describe time stamp matching behavior

[Kyle Meyer]

* lisp/org-macs.el (org-parse-time-string): Document matching of
YYYY-MM-DD substring.

org-clock-special-range used to pass in <-50001-11-30 Tue 00:00> with
the expectation that the year would be parsed as -50001, not 0001.
Mention this YYYY-MM-DD format assumption in the docstring to help
avoid such cases.
---
 lisp/org-macs.el | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/lisp/org-macs.el b/lisp/org-macs.el
index 6da69c75d..9a65360ff 100644
--- a/lisp/org-macs.el
+++ b/lisp/org-macs.el
@@ -1112,7 +1112,9 @@ (defun org-parse-time-string (s &optional nodefault)
 If time is not given, defaults to 0:00.  However, with optional
 NODEFAULT, hour and minute fields are nil if not given.
 
-Throw an error if S in not a valid Org time string.
+Throw an error if S does not contain a valid Org time string.
+Note that the first match for YYYY-MM-DD will be used (e.g.,
+\"-52000-02-03\" will be taken as \"2000-02-03\").
 
 This should be a lot faster than the `parse-time-string'."
   (unless (string-match org-ts-regexp0 s)
-- 
2.20.0