org-ql/README.org

• org-agenda-ng / org-ql
  • org-ql

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 org-super-agenda, not this code:

  (org-agenda-ng "~/src/emacs/org-super-agenda/test/test.org"
    (and (or (date :date '= (org-today))
             (date :deadline '<= (+ org-deadline-warning-days (org-today)))
             (date :scheduled '<= (org-today)))
         (not (apply #'todo org-done-keywords-for-agenda))))

Here are some other examples:

  (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)
        (date :deadline '<= (org-today))
        (date :scheduled '<= (org-today))
        (and (todo "DONE" "CANCELLED")
             (date :closed '= (org-today)))))

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

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

org-ql

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

  (org-ql org-agenda-files
    (and (todo "SOMEDAY")
         (tags "Emacs")
         (priority >= "B")))

  (org-ql "~/org/main.org"
    (and (or (tags "Emacs")
             (priority >= "B"))
         (not (done))))

  (org-ql "~/org/main.org"
    (and (or (tags "Emacs")
             (priority >= "B"))
         (done)))

Instead of opening an agenda-like buffer with matching entries, org-ql could take a function as an argument that would be called at each matching entry to return a result, and finally it would return 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.