ts argument for the current week? about org-ql

[alphapapa]

Hi,

Please see the documentation for the timestamp-based predicates:

The following predicates, in addition to the keyword arguments, can also take a single argument, a number, which looks backward or forward a number of days. The number can be negative to invert the direction.

[FTWynn]

I see that, but I'm still a bit confused.

I suppose I would've expected a keyword like current_week that only gets items corresponding to the given calendar week (W40, etc in the agenda view).

[alphapapa]

The only keyword at the moment is today.

You can, of course, use specific dates corresponding to the range you want. You can find an example of a helper function here: https://github.com/alphapapa/ts.el Search the readme for does a timestamp fall within the previous calendar week?

[forrestchang]

@FTWynn You can check my config.

https://github.com/forrestchang/.doom.d/blob/master/modules/private/my-org/config.el#L166

(defun current-week-range ()
  "Return timestamps (BEG . END) spanning current calendar week."
  (let* (;; Bind `now' to the current timestamp to ensure all calculations
         ;; begin from the same timestamp.  (In the unlikely event that
         ;; the execution of this code spanned from one day into the next,
         ;; that would cause a wrong result.)
         (now (ts-now))
         ;; We start by calculating the offsets for the beginning and
         ;; ending timestamps using the current day of the week.  Note
         ;; that the `ts-dow' slot uses the "%w" format specifier, which
         ;; counts from Sunday to Saturday as a number from 0 to 6.
         (adjust-beg-day (- 1 (ts-dow now)))
         (adjust-end-day (- 7 (ts-dow now)))
         ;; Make beginning/end timestamps based on `now', with adjusted
         ;; day and hour/minute/second values.  These functions return
         ;; new timestamps, so `now' is unchanged.
         (beg (thread-last now
                ;; `ts-adjust' makes relative adjustments to timestamps.
                (ts-adjust 'day adjust-beg-day)
                ;; `ts-apply' applies absolute values to timestamps.
                (ts-apply :hour 0 :minute 0 :second 0)))
         (end (thread-last now
                (ts-adjust 'day adjust-end-day)
                (ts-apply :hour 23 :minute 59 :second 59))))
    (cons beg end)))

  ;; Weekly Review
  (defun custom-ql-weekly-review ()
    (interactive)
    (let* ((ts-default-format "%Y-%m-%d")
           (beg (ts-format (car (current-week-range))))
           (end (ts-format (cdr (current-week-range)))))
      (org-ql-search (org-agenda-files)
        `(and (todo "TODO" "STARTED" "BLOCKED" "DONE")
              (tags "PROJ")
              (or (deadline :from ,beg :to ,end)
                  (closed :from ,beg :to ,end)))
        :title "Weekly Review"
        :super-groups '((:name "STARTED"
                               :todo "STARTED")
                        (:name "TODO"
                               :todo "TODO")
                        (:name "BLOCKED"
                               :todo "BLOCKED")
                        (:name "DONE"
                               :todo "DONE"))
        )))

[mskorzhinskiy]

Just in case if someone find its useful, I've extended this snippet for my use to be able to go back as many weeks in the past as I want:

;; Past week intraspection
(defun past-week-range (num)
  "Return timestamps (BEG . END) spanning the previous*NUM calendar week."
  (let* (;; Bind `now' to the current timestamp to ensure all calculations
         ;; begin from the same timestamp.  (In the unlikely event that
         ;; the execution of this code spanned from one day into the next,
         ;; that would cause a wrong result.)
         (now (ts-now))
         ;; We start by calculating the offsets for the beginning and
         ;; ending timestamps using the current day of the week.  Note
         ;; that the `ts-dow' slot uses the "%w" format specifier, which
         ;; counts from Sunday to Saturday as a number from 0 to 6.
         (adjust-beg-day (- (+ (* num 7) (ts-dow now))))
         (adjust-end-day (- (- (* num 7) (- 6 (ts-dow now)))))
         ;; Make beginning/end timestamps based on `now', with adjusted
         ;; day and hour/minute/second values.  These functions return
         ;; new timestamps, so `now' is unchanged.
         (beg (thread-last now
                ;; `ts-adjust' makes relative adjustments to timestamps.
                (ts-adjust 'day adjust-beg-day)
                ;; `ts-apply' applies absolute values to timestamps.
                (ts-apply :hour 0 :minute 0 :second 0)))
         (end (thread-last now
                (ts-adjust 'day adjust-end-day)
                (ts-apply :hour 23 :minute 59 :second 59))))
    (cons beg end)))

;; Weekly Review
(defun org-user/week-intraspection ()
  (interactive)
  (let* ((week-num (read-number "How many weeks in past? " 1))
         (ts-default-format "%Y-%m-%d")
         (wbeg (ts-format (car (past-week-range week-num))))
         (wend (ts-format (cdr (past-week-range week-num)))))
    (org-ql-search (org-agenda-files)
      `(and (done)
            (closed :from ,wbeg :to ,wend))
      :title "Weekly Review"
      :super-groups (quote ((:auto-ts t))))))

I believe org-ql users would benefit a lot having 'thisweek', 'thismonth' and 'thisyear' duration tags. So one can actually write something like:
(closed :duration thisweek) or (closed :duration thisweek-1) or (ts-active :duration thismonth+1). What do you think about it, @alphapapa? Will you accept a patch about this?

[alphapapa]

Something like that could be useful, yes. It would need a clear and unambiguous API. For example, does thisweek mean "from the previous Sunday at 00:00 local time until the next Saturday at 23:59 local time," or "from 168 hours ago until the present"? And what about users whose calendar week starts on Monday (I've already been asked about this by another user)?

Because of that ambiguity, I'd generally be in favor of something more flexible and less ambiguous, even if it were a bit more verbose. e.g. (closed :from "last Sunday 00:00" :to "Saturday 23:59").

Another possibility might be something like (closed :from (week-start) :to (week-end)), i.e. functions which could also accept an optional argument, something like (closed :from (week-start -1) :to (week-end 2)), which would span a 4-week period, and possibly account for locale calendar first-day-of-week issues.

If the documentation were clear enough, something like this might also work:

• (closed :during week) for this calendar week
• (closed :during (week -1)) for the previous calendar week

If you want to submit PRs, I'm open to them, but please construct them carefully. For example, adding a :during keyword argument to certain predicates should be done separately, and the argument to it should be a cons, which can be expanded into the :from and :to arguments in the query pre-processing. It should be carefully documented and noted in the changelog.

Then, assuming that week, month, year-type arguments are added, they will need special handling to work as both bare symbols (like (closed :during week)) and functions (like (closed :during (week -1))). It will require code in the query pre-processing function and careful documentation.

Finally, any new arguments and functions like that need to have tests as well.

The "paperwork" sometimes produces more lines in the diff than the actual code, but it's necessary for the quality of the project. And if a PR submitter doesn't submit those parts, I end up having to do them myself, which isn't as much fun as writing code. ;)

[panmengguan]

Is there now a general way to retrieve current week, month, or year for org-ql ts arguments?