Change: org-agenda-ng -> org-ql-agenda

README.org

@@ -1,73 +1,28 @@
-* org-agenda-ng / org-ql
+* 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=.
+~org-ql~ is a lispy query language for Org files.  It allows you to find Org entries matching certain criteria and perform actions on them, such as collecting their parsed representation with ~org-element~ (the default action).  Some examples:
-
-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"
+  ;; Return a list of Org entry elements in the file "~/org/main.org" which have the SOMEDAY
-    (and (or (date = today)
+  ;; to-do keyword, are tagged "Emacs", and have priority B or higher.
-             (deadline <=)
-             (scheduled <= today))
-         (not (done))))
-#+END_SRC
-
-[[screenshot.png]]
-
-Here are some other examples:
-
-#+BEGIN_SRC elisp
-  ;; Show an agenda-like view of items in "~/org/main.org" with TODO and SOMEDAY keywords which are
-  ;; tagged "computer" or "Emacs" and in the category "main":
-  (org-agenda-ng "~/org/main.org"
-    (and (todo "TODO" "SOMEDAY")
-         (tags "computer" "Emacs")
-         (category "main")))
-
-  ;; Show an agenda-like view of all habits in all agenda files:
-  (org-agenda-ng
-    (habit))
-
-  ;; Show an agenda-like view similar to a "traditional" Org agenda:
-  (org-agenda-ng
-    (or (habit)
-        (date = today)
-        (deadline <=)
-        (scheduled <= today)
-        (and (todo "DONE" "CANCELLED")
-             (closed = today))))
-#+END_SRC
-
-More examples are available in [[examples.org]].
-
-** org-ql
-
-Another way to look at it is like a "query language" for Org buffers.  For example:
-
-#+BEGIN_SRC elisp
-  ;; Return a list of Org entry elements which have the SOMEDAY keyword, are tagged "Emacs", and have
-  ;; priority B or higher:
   (org-ql "~/org/main.org"
     (and (todo "SOMEDAY")
          (tags "Emacs")
-         (priority >= "B"))) ;; => ((headline (:raw-value "org-board" :begin 1220270 :end 1220403 ...)) ...)
+         (priority >= "B"))) ;=> ((headline (:raw-value "org-board" :begin 1220270 :end 1220403 ...)) ...)
 
-  ;; Find non-done items which contain the term "Emacs" and have priority "B" or higher, and
+  ;; Return a list of bills coming due, searching all Org Agenda files, sorted by deadline.  Deadlines
-  ;; return a list of heading positions:
+  ;; are compared with configured Org warning days, which is implied by the plain `<=' in the
-  (org-ql org-agenda-files
+  ;; `deadline' matcher.
+  (org-ql (org-agenda-files)
     (and (not (done))
-         (regexp "Emacs")
+         (tags "bills")
-         (priority >= "B"))
+         (deadline <=))
-    :action-fn (lambda (element)
+    :sort deadline)
-                 (org-element-property :begin element)))  ;; => (44154 46469 56008 63965 100008 ...)
 
-  ;; Or you can use mapcar around it to get the same result (API is WIP):
+  ;; Set the tag "Emacs" on every entry in the inbox file that mentions "Emacs".
-  (mapcar (lambda (element)
+  (org-ql "~/org/inbox.org"
-            (org-element-property :begin element))
+    (regexp "Emacs")
-          (org-ql org-agenda-files
+    :action (org-toggle-tag "Emacs" 'on))
-            (and (not (done))
-                 (tags "Emacs")
-                 (priority >= "B"))))  ;; => (44154 46469 56008 63965 100008 ...)
 
   ;; If you kept a database of music in an Org file, you might run a query like this to find tracks
   ;; composed by Chopin that do not have their key recorded in the database:
@@ -77,20 +32,68 @@ Another way to look at it is like a "query language" for Org buffers.  For examp
          (not (property "key"))))
 #+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.
+** org-ql-agenda
 
-Results may also be sorted by a user-defined sorting function, or by some built-in sorters: =date=, =deadline=, =scheduled=, =priority= (which assume that the =action-fn= is the default, =org-element-headline-parser)=.  For example:
+Also included is ~org-ql-agenda~, which uses ~org-ql~ queries to select entries and present them in an Agenda-like view.  It's compatible with [[https://github.com/alphapapa/org-super-agenda][org-super-agenda]], which provides grouping.  For example:
 
 #+BEGIN_SRC elisp
-  ;; Return TODO items sorted by deadline, then priority.  These built-in sorters assume that items
+  (org-ql-agenda "~/src/emacs/org-super-agenda/test/test.org"
-  ;; are Org elements returned by `org-element-headline-parser' (the default action function).
+    (and (or (date = today)
-  (org-ql "~/org/main.org"
+             (deadline <=)
-    (todo)
+             (scheduled <= today))
-    :sort (deadline priority))
+         (not (done))))
-
-  ;; Return TODO items sorted by user-defined sorting function.
-  (org-ql "~/org/main.org"
-    (todo)
-    :sort #'custom-sort-fn)
 #+END_SRC
 
+Which presents this buffer:
+
+[[screenshot.png]]
+
+*Note:* The view buffer is currently put in ~org-agenda-mode~, which means that /some/ Org Agenda commands work, such as jumping to entries and changing item priorities (without necessarily updating the view).  This feature is experimental and not guaranteed to work correctly with all commands.  (It works to the extent it does because the appropriate text properties are placed on each item, imitating an Agenda buffer.)
+
+Here are some other examples:
+
+#+BEGIN_SRC elisp
+  ;; Show an agenda-like view of items in "~/org/main.org" with TODO and SOMEDAY keywords which are
+  ;; tagged "computer" or "Emacs" and in the category "main":
+  (org-ql-agenda "~/org/main.org"
+    (and (todo "TODO" "SOMEDAY")
+         (tags "computer" "Emacs")
+         (category "main")))
+
+  ;; Show an agenda-like view of all habits in all agenda files:
+  (org-ql-agenda
+    (habit))
+
+  ;; Show an agenda-like view similar to a "traditional" Org agenda.
+  (org-ql-agenda
+    (or (habit)
+        (date = today)
+        (deadline <=)
+        (scheduled <= today)
+        (and (todo "DONE" "CANCELLED")
+             (closed = today))))
+#+END_SRC
+
+** Comparison with Org Agenda searches
+
+Of course, queries like these can already be written with Org Agenda searches, but the syntax can be complex.  For example, this query would be difficult to write in a standard Org Agenda search, because it matches against a to-do keyword /and/ a plain-text search.  As described in the [[https://orgmode.org/worg/org-tutorials/advanced-searching.html#combining-metadata-and-full-text-queries][advanced searching tutorial]], it would require using ~org-search-view~ with a query with specific regular expression syntax, like this:
+
+#+BEGIN_EXAMPLE
+  +lisp +{^\*+\s-+TO-READ\s-}
+#+END_EXAMPLE
+
+But with ~org-ql-agenda~, you would write:
+
+#+BEGIN_SRC elisp
+  (org-ql-agenda
+    (and (regexp "lisp")
+         (todo "TO-READ")))
+#+END_SRC
+
+** More examples
+
+More examples are available in [[examples.org]].
+
+** License
+
+GPLv3

examples.org

@@ -1,20 +1,17 @@
-
-
 * Examples
 
-** Showing TO-READ entries containing the word "lisp"
+** Listing bills coming due
 
-This query would be difficult to write in a standard Org Agenda search, because it matches against a to-do keyword /and/ a plain-text search.  As described in the [[https://orgmode.org/worg/org-tutorials/advanced-searching.html#combining-metadata-and-full-text-queries][advanced searching tutorial]], it would require using ~org-search-view~ with a query with specific regular expression syntax, like this:
+This uses the example in the readme file, but maps across the elements returned by ~org-ql~ to present a simple list of titles and deadlines.
-
-#+BEGIN_EXAMPLE
-  +lisp +{^\*+\s-+TO-READ\s-}
-#+END_EXAMPLE
-
-But with =org-ql= or =org-agenda-ng=, you would write:
 
 #+BEGIN_SRC elisp
-  (org-agenda-ng
+  (--map (list (org-element-property :raw-value it)
-    (and (regexp "lisp")
+               (org-timestamp-format (org-element-property :deadline it) "%c"))
-         (todo "TO-READ")))
+         (org-ql (org-agenda-files)
+           (and (not (done))
+                (tags "bills")
+                (deadline <=))
+           :sort deadline))
+  ;;=> (("Electric bill" "Thu 23 Aug 2018 12:00:00 AM CDT")
+  ;;    ("Rent" "Sat 01 Sep 2018 08:00:00 PM CDT"))
 #+END_SRC
-

notes.org

@@ -2,10 +2,6 @@
 
 * Tasks
 
-** TODO Move/rename repo to =org-ql=
-
-Since =org-sidebar= uses it, it probably makes more sense for =org-ql= to be the primary focus of the repo.  But it also uses =org-agenda-ng--format-element=, so =org-agenda-ng= probably should be part of that package, too.
-
 ** TODO Document matchers/selectors/predicates
 
 And maybe pick a single name for them...

org-ql-agenda.el

@@ -39,14 +39,14 @@
 
 ;;;; Variables
 
-(defvar org-agenda-ng-buffer-name "*Org Agenda NG*"
+(defvar org-ql-agenda-buffer-name "*Org Agenda NG*"
-  "Name of default `org-agenda-ng' buffer.")
+  "Name of default `org-ql-agenda' buffer.")
 
 ;;;; Macros
 
 ;; FIXME: DRY these two macros.
 
-(cl-defmacro org-agenda-ng (&rest args)
+(cl-defmacro org-ql-agenda (&rest args)
   "Display an agenda-like buffer of entries in FILES that match QUERY.
 
 FILES-OR-QUERY is a sexp that is evaluated to get the list of
@@ -89,7 +89,7 @@ agenda in, rather than the default."
          ;; Only query
          (setq query arg-pred)))
       ;; Call --agenda
-      `(org-agenda-ng--agenda ,files
+      `(org-ql-agenda--agenda ,files
          ;; TODO: Probably better to just use eval on org-ql rather than reimplementing parts of it here.
          ',query
          :sort ',sort
@@ -100,7 +100,7 @@ agenda in, rather than the default."
 ;; TODO: Move the action-fn down into --filter-buffer, so users can avoid calling the
 ;; headline-parser when they don't need it.
 
-(cl-defun org-agenda-ng--agenda (buffers-files query &key sort buffer)
+(cl-defun org-ql-agenda--agenda (buffers-files query &key sort buffer)
   "FIXME: Docstring"
   (declare (indent defun))
   ;; I think it's reasonable to use `eval' here.
@@ -108,28 +108,28 @@ agenda in, rather than the default."
                                 ,query
                                 :sort ,sort
                                 :markers t))
-                       (mapcar #'org-agenda-ng--format-element it)
+                       (mapcar #'org-ql-agenda--format-element it)
                        (cond ((bound-and-true-p org-super-agenda-mode) (org-super-agenda--group-items it))
                              (t it))
                        (s-join "\n" it)))
          (inhibit-read-only t))
-    (with-current-buffer (org-agenda-ng--buffer buffer)
+    (with-current-buffer (org-ql-agenda--buffer buffer)
       (erase-buffer)
       (insert entries)
       (pop-to-buffer (current-buffer))
       (org-agenda-finalize)
       (goto-char (point-min)))))
 
-(defun org-agenda-ng--buffer (&optional name)
+(defun org-ql-agenda--buffer (&optional name)
   "Return Agenda NG buffer, creating it if necessary.
 If NAME is non-nil, return buffer by that name instead of using
 default buffer."
-  (with-current-buffer (get-buffer-create (or name org-agenda-ng-buffer-name))
+  (with-current-buffer (get-buffer-create (or name org-ql-agenda-buffer-name))
     (unless (eq major-mode 'org-agenda-mode)
       (org-agenda-mode))
     (current-buffer)))
 
-(defun org-agenda-ng--format-relative-date (difference)
+(defun org-ql-agenda--format-relative-date (difference)
   "Return relative date string for DIFFERENCE.
 DIFFERENCE should be an integer number of days, positive for
 dates in the past, and negative for dates in the future."
@@ -141,7 +141,7 @@ dates in the past, and negative for dates in the future."
 
 ;;;; Faces/properties
 
-(defun org-agenda-ng--add-markers (element)
+(defun org-ql-agenda--add-markers (element)
   "Return ELEMENT with marker properties added."
   (let* ((marker (org-agenda-new-marker (org-element-property :begin element)))
          (properties (--> (cadr element)
@@ -150,7 +150,7 @@ dates in the past, and negative for dates in the future."
     (setf (cadr element) properties)
     element))
 
-(defun org-agenda-ng--format-element (element)
+(defun org-ql-agenda--format-element (element)
   ;; This essentially needs to do what `org-agenda-format-item' does,
   ;; which is a lot.  We are a long way from that, but it's a start.
   "Return ELEMENT as a string with its text-properties set according to its property list.
@@ -175,12 +175,12 @@ Its property list should be the second item in the list, as returned by `org-ele
          ;; --add-deadline-face), and doing it in this form that gets the title hides it even more.
          ;; Adding the relative due date property should probably be done explicitly and separately
          ;; (which would also make it easier to do it independently of faces, etc).
-         (title (--> (org-agenda-ng--add-faces element)
+         (title (--> (org-ql-agenda--add-faces element)
                      (org-element-property :raw-value it)
                      (org-link-display-format it)
                      ))
          (todo-keyword (-some--> (org-element-property :todo-keyword element)
-                                 (org-agenda-ng--add-todo-face it)))
+                                 (org-ql-agenda--add-todo-face it)))
          ;; FIXME: Figure out whether I should use `org-agenda-use-tag-inheritance' or `org-use-tag-inheritance', etc.
          (tag-list (if org-use-tag-inheritance
                        (if-let ((marker (or (org-element-property :org-hd-marker element)
@@ -202,7 +202,7 @@ Its property list should be the second item in the list, as returned by `org-ele
          (priority-string (-some->> (org-element-property :priority element)
                                     (char-to-string)
                                     (format "[#%s]")
-                                    (org-agenda-ng--add-priority-face)))
+                                    (org-ql-agenda--add-priority-face)))
          (habit-property (org-with-point-at (org-element-property :begin element)
                            (when (org-is-habit-p)
                              (org-habit-parse-todo))))
@@ -220,18 +220,18 @@ Its property list should be the second item in the list, as returned by `org-ele
            'tags tag-list
            'org-habit-p habit-property))))
 
-(defun org-agenda-ng--add-faces (element)
+(defun org-ql-agenda--add-faces (element)
   (->> element
-       (org-agenda-ng--add-scheduled-face)
+       (org-ql-agenda--add-scheduled-face)
-       (org-agenda-ng--add-deadline-face)))
+       (org-ql-agenda--add-deadline-face)))
 
-(defun org-agenda-ng--add-priority-face (string)
+(defun org-ql-agenda--add-priority-face (string)
   "Return STRING with priority face added."
   (when (string-match "\\(\\[#\\(.\\)\\]\\)" string)
     (let ((face (org-get-priority-face (string-to-char (match-string 2 string)))))
       (org-add-props string nil 'face face 'font-lock-fontified t))))
 
-(defun org-agenda-ng--add-scheduled-face (element)
+(defun org-ql-agenda--add-scheduled-face (element)
   "Add faces to ELEMENT's title for its scheduled status."
   ;; NOTE: Also adding prefix
   (if-let ((scheduled-date (org-element-property :scheduled element)))
@@ -252,7 +252,7 @@ Its property list should be the second item in the list, as returned by `org-ele
              (scheduled-day-number (org-time-string-to-absolute
                                     (org-element-timestamp-interpreter scheduled-date 'ignore)))
              (difference-days (- today-day-number scheduled-day-number))
-             (relative-due-date (org-add-props (org-agenda-ng--format-relative-date difference-days) nil
+             (relative-due-date (org-add-props (org-ql-agenda--format-relative-date difference-days) nil
                                   'help-echo (org-element-property :raw-value scheduled-date)))
              (repeat-day-number (cond (sexp-p (org-time-string-to-absolute scheduled-date))
                                       ((< today-day-number scheduled-day-number) scheduled-day-number)
@@ -297,7 +297,7 @@ Its property list should be the second item in the list, as returned by `org-ele
     ;; Not scheduled
     element))
 
-(defun org-agenda-ng--add-deadline-face (element)
+(defun org-ql-agenda--add-deadline-face (element)
   "Add faces to ELEMENT's title for its deadline status.
 Also store relative due date as string in `:relative-due-date'
 property."
@@ -306,7 +306,7 @@ property."
              (deadline-day-number (org-time-string-to-absolute
                                    (org-element-timestamp-interpreter deadline-date 'ignore)))
              (difference-days (- today-day-number deadline-day-number))
-             (relative-due-date (org-add-props (org-agenda-ng--format-relative-date difference-days) nil
+             (relative-due-date (org-add-props (org-ql-agenda--format-relative-date difference-days) nil
                                   'help-echo (org-element-property :raw-value deadline-date)))
              (todo-keyword (org-element-property :todo-keyword element))
              (done-p (member todo-keyword org-done-keywords))
@@ -327,12 +327,12 @@ property."
     ;; No deadline
     element))
 
-(defun org-agenda-ng--add-todo-face (keyword)
+(defun org-ql-agenda--add-todo-face (keyword)
   (when-let ((face (org-get-todo-face keyword)))
     (org-add-props keyword nil 'face face)))
 
 ;;;; Footer
 
-(provide 'org-agenda-ng)
+(provide 'org-ql-agenda)
 
-;;; org-agenda-ng.el ends here
+;;; org-ql-agenda.el ends here