Helpers for agenda custom commands

README.org

@@ -56,7 +56,16 @@ Example configuration:
 ** Commands/functions
 - =org-roam-ql-search (SOURCE-OR-QUERY &optional TITLE SORT-FN)= :: This is an *interactive* command that creates a ~org-roam-ql~ buffer with the nodes of the corresponding [[#valid-values-for-source-or-query][ ~SOURCE-OR-QUERY~ ]] ([[#valid-values-for-source-or-query] with ~TITLE~. An ~org-roam-ql~ buffer is functionally similar to the ~org-roam-buffer~, but allows displaying any list of nodes ([[#screen-shots][see screen-shots above]]). When called interactively, it will prompt for the ~SOURCE-OR-QUERY~ and ~TITLE~. Note that when entering queries interactively either in ~org-roam-ql-search~ or in the transient, you can get completion-at-point with ~tab~. ~SORT-FN~ is used for sorting the results. It can be a string name of a registered sort function or a predicate function that can be used to sort the nodes (should take two nodes as input and return a non-nil value if the first node should be before the second). By default the following sort function are registered: ~file-mtime~, ~file-atime~, ~deadline~, ~scheduled~, ~point~, ~level~, ~file-title~, ~file~ and ~title~. Each corresponds to the respective slot of an org-roam-node. It is possible to register new sort functions with ~org-roam-ql-register-sort-fn~. These registered functions will also appear as options for completion in the transient.
 - =org-roam-ql-nodes (SOURCE-OR-QUERY)= :: Given a [[#valid-values-for-source-or-query][ ~SOURCE-OR-QUERY~ ]] , return a list of nodes.
-
+- ~org-roam-ql-agenda-block (QUERY)~ :: Meant to be used in ~org-agenda-custom-commands~ as a user-defined function. Insert items from processing ~QUERY~ (which is a [[#valid-values-for-source-or-query][ ~SOURCE-OR-QUERY~ ]]) into current buffer. QUERY is the `match' item in the custom command form. Currently this doesn't respect agenda restrict. Example:
+ #+begin_src emacs-lisp
+ (setq org-agenda-custom-commands
+ ("cr" "Node a" org-roam-ql-agenda-block '(title "Node a")))
+ #+end_src
+- ~org-roam-ql-nodes-files (SOURCE-OR-QUERY)~ :: Given a [[#valid-values-for-source-or-query][ ~SOURCE-OR-QUERY~ ]] , returns a list of files of the nodes. Can be used in ~org-agenda-custom-commands~. Example:
+ #+begin_src emacs-lisp
+ (setq org-agenda-custom-commands
+ ("cr" "todo nodes" todo "TODO" ((org-agenda-files (org-roam-ql-nodes-files '(title "Node"))))))
+ #+end_src
 ** Valid values for ~SOURCE-OR-QUERY~
 - A list of ~org-roam-nodes~ :: This should self explanatory.
 - A list of parameters that can be passed to ~org-roam-db-query~ :: It should be a list of the form ~(QUERY ARG1 ARG2...)~. The result of calling ~org-roam-db-query~ with these parameters should return a list of records where the first element is the ID of a corresponding node. For example:

org-roam-ql.el

@@ -950,14 +950,55 @@ If there are entries that do not have an ID, it will signal an error"
  (message "Query results is empty"))
  (user-error "Dynamic block needs to specify :query and :columns"))))
 
-;; Useful helper functions
+;; ;; *****************************************************************************
+;; ;; org agenda custom command
+;; ;; *****************************************************************************
+(defun org-roam-ql-agenda-block (query)
+ "Insert items for QUERY into current buffer.
+See `org-roam-ql-nodes' for more information on QUERY. Intended to be
+used as a user-defined function in `org-agenda-custom-commands'.
+QUERY is the `match' item in the custom command form. Currently this
+doesn't respect agenda restrict."
+ ;; Copying alot from org-ql-search-block
+ (let (narrow-p old-beg old-end strings)
+ (when-let* ((from (pcase org-agenda-restrict
+ ('nil (org-agenda-files nil 'ifmode))
+ (_ (prog1 org-agenda-restrict
+ (with-current-buffer org-agenda-restrict
+ ;; Narrow the buffer; remember to widen it later.
+ (setf old-beg (point-min) old-end (point-max)
+ narrow-p t)
+ (narrow-to-region org-agenda-restrict-begin org-agenda-restrict-end))))))
+ (nodes (org-roam-ql-nodes query)))
+ (when narrow-p
+ ;; Restore buffer's previous restrictions.
+ (with-current-buffer from
+ (narrow-to-region old-beg old-end)))
+ (org-agenda-prepare)
+ (org-agenda--insert-overriding-header (org-roam-ql--get-formatted-title nil query))
+ ;; But we do call `org-agenda-finalize-entries', which allows `org-super-agenda' to work.
+ (dolist-with-progress-reporter (node nodes)
+ (format "Processing %s nodes" (length nodes))
+ (push (org-roam-ql-view--format-node node) strings))
+ (insert (org-agenda-finalize-entries strings) "\n"))))
+
+(defun org-roam-ql-nodes-files (source-or-query)
+ "Retuns a list of files of the corresponding SOURCE-OR-QUERY.
+See `org-roam-ql-nodes' for more information on SOURCE-OR-QUERY."
+ (em (-map #'org-roam-node-file (org-roam-ql-nodes source-or-query))))
+
+;; ;; *****************************************************************************
+;; Helper functions
+;; *****************************************************************************
 (defun org-roam-ql-insert-node-title ()
  "Select a node and insert only its title.
 Can be used in the minibuffer or when writting querries."
  (interactive)
  (insert (format "\"%s\"" (org-roam-node-title (org-roam-node-read nil nil nil t)))))
 
-;; setup of org-roam-ql
+;; *****************************************************************************
+;; Setup of org-roam-ql
+;; *****************************************************************************
 (dolist (predicate
  '((file "Compare to `file' of a node" org-roam-node-file . org-roam-ql--predicate-s-match)
  (file-title "Compare to `file-title' of a node" org-roam-node-file-title . org-roam-ql--predicate-s-match)