* org-agenda-ng / org-ql

This is rudimentary, experimental, proof-of-concept alternative code for generating Org agendas.  It doesn't support nearly as many features as =org-agenda.el= does, but it might be useful in some way.  It uses some existing code from =org-agenda.el= and tries to be compatible with parts of it, like =org-agenda-finalize-entries= and =org-agenda-finalize=.

Here's an example of generating a kind of agenda view for today (note that the grouping is provided by [[https://github.com/alphapapa/org-super-agenda][org-super-agenda]], not this code:

#+BEGIN_SRC elisp
  (org-agenda-ng "~/src/emacs/org-super-agenda/test/test.org"
    (and (or (date '= today)
             (deadline '<=)
             (scheduled '<= today))
         (not (done))))
#+END_SRC

[[screenshot.png]]

Here are some other examples:

#+BEGIN_SRC elisp
  (org-agenda-ng org-agenda-files
    (and (todo "TODO" "SOMEDAY")
         (tags "computer" "Emacs")
         (category "main")))

  (org-agenda-ng org-agenda-files
    (habit))

  (org-agenda-ng "~/org/main.org"
    (or (habit)
        (deadline '<=)
        (scheduled '<= today)
        (and (todo "DONE" "CANCELLED")
             (closed '= today))))

  (org-agenda-ng "~/org/main.org"
    (or (habit)
        (and (or (date '= today)
                 (deadline '<=)
                 (scheduled '<= today))
             (not (done)))
        (and (todo "DONE" "CANCELLED")
             (closed '= today))))

  (org-agenda-ng "~/org/main.org"
    (or (habit)
        (and (or (date '= today)
                 (deadline '<=)
                 (scheduled '<= today))
             (not (done)))
        (and (todo "DONE" "CANCELLED")
             (closed '= today))))
  (org-agenda-ng "~/org/main.org"
    (or (habit)
        (and (or (date '= today)
                 (deadline '<=)
                 (scheduled '<= today))
             (not (done)))
        (and (todo "DONE" "CANCELLED")
             (closed '= today))))
#+END_SRC

** org-ql

Another way to look at it is like a "query language" for Org buffers.  For example:

#+BEGIN_SRC elisp
  (org-ql org-agenda-files
    (and (todo "SOMEDAY")
         (tags "Emacs")
         (priority >= "B"))) ;; => ((headline (:raw-value "org-board" :begin 1220270 :end 1220403 ...)) ...)

  (org-ql "~/org/main.org"
    (and (or (tags "Emacs")
             (priority >= "B"))
         (not (done)))) ;; => (((headline (:raw-value "Now" :begin 3832 :end 3843 ...))) ...)

  (org-ql "~/org/main.org"
    (and (or (tags "Emacs")
             (priority >= "B"))
         (done))
    :action-fn (lambda (element)
                 (org-element-property :begin element)))  ;; => (44154 46469 56008 63965 100008 ...)

  (mapcar (lambda (element)
            (org-element-property :begin element))
          (org-ql "~/org/main.org"
            (and (or (tags "Emacs")
                     (priority >= "B"))
                 (done))))  ;; => (44154 46469 56008 63965 100008 ...)
#+END_SRC

Instead of opening an agenda-like buffer with matching entries, =org-ql= can take a function as an argument that is called at each matching entry to return a result, and finally it returns a list of the results.  For example, you could return a list of positions within the buffer, or a list of headings, or headings with entry contents, etc.  By default, the matching element is returned, which is the result of calling =org-element-headline-parser= at that entry.