Add: org-ql-search

Also move screenshot into subdir.

README.org

@@ -1,3 +1,5 @@
+
+
 * org-ql
 
 ~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:
@@ -32,6 +34,12 @@
          (not (property "key"))))
 #+END_SRC
 
+** org-ql-search
+
+The command =org-ql-search= prompts for a query, a list of buffers or files, and how to group and sort results.  Without prefix, it searches the current buffer instead of prompting.  Then it presents the results in an agenda-like view.
+
+[[images/org-ql-search.gif]]
+
 ** org-ql-agenda
 
 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:
@@ -61,7 +69,7 @@ Also included is ~org-ql-agenda~, which uses ~org-ql~ queries to select entries
 
 Which presents this buffer:
 
-[[screenshot.png]]
+[[images/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.)
 

org-ql-agenda.el

@@ -111,6 +111,61 @@ is used, rather than binding it locally."
          :narrow ,narrow
          :super-groups ',super-groups))))
 
+;;;; Commands
+
+;; TODO: This is called `org-ql-search' but it's in org-ql-agenda.el because
+;; it uses `org-ql-agenda--agenda'.  Maybe this could be better organized.
+
+;;;###autoload
+(defun org-ql-search (query &optional buffers-files narrow group sort)
+  "Read QUERY and search with `org-ql'.
+Interactively, prompt for these variables:
+
+BUFFERS-FILES: A list of buffers and/or files to search, or an
+expression which evaluates to such a list.
+
+GROUP: An `org-super-agenda' auto-grouping selector.  See
+variable `org-super-agenda-auto-selector-keywords'.
+
+NARROW: Don't widen buffers before searching.  Buffers are
+widened by default.  With prefix, leave narrowed.
+
+SORT: One or a list of `org-ql' sorting functions, like `date' or
+`priority'."
+  (interactive (progn
+                 (when (and current-prefix-arg
+                            (not (derived-mode-p 'org-mode)))
+                   (user-error "Not an Org buffer: %s" (buffer-name)))
+                 (list (read-minibuffer "Query: ")
+                       (--if-let (read-from-minibuffer "Buffers/Files (blank for current buffer): ")
+                           ;; TODO: Add glob matching?  Buffer mode matching?
+                           (pcase it
+                             ("" (current-buffer))
+                             ((rx bos "(") (-flatten (eval (read it))))
+                             (_ (s-split (rx (1+ space)) it)))
+                         (current-buffer))
+                       (eq current-prefix-arg '(4))
+                       (pcase (completing-read "Group by: "
+                                               (cons "Don't group"
+                                                     (cl-loop for type in org-super-agenda-auto-selector-keywords
+                                                              collect (substring (symbol-name type) 6))))
+                         ("Don't group" nil)
+                         (property (list (list (intern (concat ":auto-" property))))))
+                       (pcase (completing-read "Sort by: "
+                                               (list "Don't sort"
+                                                     "date"
+                                                     "deadline"
+                                                     "priority"
+                                                     "scheduled"
+                                                     "todo"))
+                         ("Don't sort" nil)
+                         (sort (intern sort))))))
+  (org-ql-agenda--agenda buffers-files
+    query
+    :narrow narrow
+    :sort sort
+    :super-groups group))
+
 ;;;; Functions
 
 ;; TODO: Move the action-fn down into --filter-buffer, so users can avoid calling the