Re: [O] ANN: org-ql agenda block support

[Adam Porter]

Samuel Wales <address@hidden> writes:

> the idea was that we can resurrect the timeline view, for all agenda
> files instead of only one, merely by a use of a text search custom
> agenda view.  timestamps go where categories currently go.  sorted by
> that ts.
>
> if an entry has more than one ts (active bare, inactive bare including
> on header, or planning -- other stuff requires org support), then it
> will get more than one agenda line.
>
> so this requires modifying that list that is there for the user to
> modify tasks before displaying them.
>
> can any of this stuff do that?
>
> i keep wanting this feature: do a text search and have all matching
> org-agenda-files outline entries show, with more than one agenda line
> if more than one ts in entry, sorted by that ts.
>
> so for example you search for "melatonin" (or even "." meaning all
> entries, such as for an agenda restriction) and then you get to see
> the most recent thing you did for melatonin or in that restriction at
> the top.  and everything else you did below.  (assuming reverse sort.)
>
> i can post more accurate and precise details if needed, but i wanted
> to know if you think your work can support this.

I don't recall using the timeline view much, so I'm not very familiar
with it.  From your description, it's certainly possible to do that with
a bit of code.  Basically, it would work like this:

1.  Run an org-ql query to find entries which have the type of timestamp
you're looking for, with or without any date/time bounds, and with or
without any additional query parameters.  So the query could be as
simple as, e.g. (ts) or (ts-active), or it could be something like:

    (and "melatonin" (ts :from -60))

Which would select all entries mentioning "melatonin" which have any
kind of timestamp within the last 60 days.

2.  The :action argument to org-ql would be a function which returns a
list containing the necessary heading information (e.g. heading text,
marker, etc.) and all timestamps found in the entry.  Something like:

    (lambda ()
      (list (point-marker) (org-get-heading)
            (cl-loop with limit = (org-entry-end-position)
                     while (re-search-forward org-ts-regexp-both
                                              limit t)
                     collect (match-string 0))))

3.  The results of the query would be a list of lists returned by the
:action function.  Then, you can do whatever you like with that.  It
wouldn't take much code to insert entries into a buffer with each
heading on a line and its timestamps on following lines.

...

Here's a quick prototype.  Note that the timestamps aren't propertized,
so to jump to an entry, you must use the heading; and I didn't bother to
format the timestamps like Org does; and the "date" sorting actually
sorts by the planning line at the moment, rather than other timestamps;
but things like that can easily be polished.

Note that despite my mangling it, Gnus is probably going to wrap these
lines, making the code very ugly, and I can't quickly find how to stop
that, so you might want to use e.g. lispy to reformat it.

(cl-defun org-ql-timeline (buffers-files query)
  (let ((results
         (org-ql-select buffers-files
           query :action
           (lambda ()
             (let* ((heading-string
                     (->> (org-element-headline-parser
                           (line-end-position))
                          org-ql--add-markers
                          org-ql-agenda--format-element))
                    (timestamps
                     (cl-loop with limit = (org-entry-end-position)
                              while (re-search-forward org-ts-regexp-both
                                                       limit t)
                              collect (ts-parse-org (match-string 0))))
                    (timestamp-strings
                     (->> timestamps
                          (-sort #'ts<)
                          (--map (concat "    " (ts-format it))))))
               (s-join "\n" (cons heading-string timestamp-strings))))
           :sort '(date))))
    (org-ql-agenda--agenda nil nil :strings results)))

Use it like this:

  (org-ql-timeline (org-agenda-files)
                   '(and "Emacs" (ts)))

That produces a view like this:

  WAITING [#C] org-link-match struct and functions  344d ago     :current:Emacs:
    2018-09-13 05:54:00 -0500
    2018-09-20 00:00:00 -0500
  NEXT Emacs timers and frames  348d ago                         :current:Emacs:
    2018-06-11 08:41:00 -0500
    2018-06-14 20:34:00 -0500
    2018-09-16 00:00:00 -0500
  WAITING [#B] Emacs ~-defun~ macro idea  4d ago                 :current:Emacs:
    2018-07-10 17:20:00 -0500
    2019-08-26 00:00:00 -0500

So, a timeline view isn't currently implemented, but as you can see,
it can easily be done using org-ql.  Thanks for mentioning this; I'll
probably add it in a future version.

> also, does it support all the usual variables for leaders and faces and so on?

I'm not sure exactly what you mean.  Formatting of entries is not
currently done exactly as in the Org Agenda, with customizable format
strings, etc.  It does apply faces for deadline, scheduled, overdue
deadline, etc., and as you can see in the example above, it does insert
a form of relative dates, similarly to the Agenda.  It also adds most
text properties that the Agenda does, which allows some Agenda Mode
commands to work in the Org QL Search results buffer.  Making the
formatter more customizable is something on the to-do list, maybe for
version 0.3.

> it all sounds promising.
>
> more speed and beautiful sexps!  what more could we ask for?  :)

That's the idea!  :)