From a52d421fd703d9d84348adefbc3daceb844cd910 Mon Sep 17 00:00:00 2001
From: Adam Porter <adam@alphapapa.net>
Date: Sun, 25 Aug 2019 20:11:24 -0500
Subject: [PATCH] Add: random sorter

---
 README.org |  3 ++-
 org-ql.el  | 12 +++++++-----
 2 files changed, 9 insertions(+), 6 deletions(-)

diff --git a/README.org b/README.org
index 3cbc1e9..9b11864 100644
--- a/README.org
+++ b/README.org
@@ -356,7 +356,7 @@ Return items matching ~QUERY~ in ~BUFFERS-OR-FILES~.
 
 If ~NARROW~ is non-nil, buffers are not widened (the default is to widen and search the entire buffer).
 
-~SORT~ is either nil, in which case items are not sorted; or one or a list of defined ~org-ql~ sorting methods (~date~, ~deadline~, ~scheduled~, ~todo~, or ~priority~); or a user-defined comparator function that accepts two items as arguments and returns nil or non-nil.
+~SORT~ is either nil, in which case items are not sorted; or one or a list of defined ~org-ql~ sorting methods (~date~, ~deadline~, ~scheduled~, ~todo~, ~priority~, or ~random~); or a user-defined comparator function that accepts two items as arguments and returns nil or non-nil.
 
 Examples:
 
@@ -459,6 +459,7 @@ Expands into a call to ~org-ql-select~ with the same arguments.  For convenience
 +  Customization group ~org-ql~.
 +  Command ~org-ql-view~, which displays views saved to variable ~org-ql-views~, which can be saved from ~org-ql-search~ buffers with command ~org-ql-search-save~, which is bound to =C-x C-s= in view buffers.
 +  Variable ~org-ql-view-map~, active in view buffers displayed by ~org-ql-search~, ~org-ql-agenda~, and ~org-ql-view~.
++  =random= sort method.
 
 *Changed*
 +  Function ~org-ql-query~ renamed to ~org-ql-select~.  ~org-ql-query~ now refers to a new function.
diff --git a/org-ql.el b/org-ql.el
index 59215f7..34a0aeb 100644
--- a/org-ql.el
+++ b/org-ql.el
@@ -163,9 +163,9 @@ widen and search the entire buffer).
 
 SORT is either nil, in which case items are not sorted; or one or
 a list of defined `org-ql' sorting methods (`date', `deadline',
-`scheduled', `todo', or `priority'); or a user-defined comparator
-function that accepts two items as arguments and returns nil or
-non-nil."
+`scheduled', `todo', `priority', or `random'); or a user-defined
+comparator function that accepts two items as arguments and
+returns nil or non-nil."
   (declare (indent defun))
   (-let* ((buffers (->> (cl-typecase buffers-or-files
                           (null (list (current-buffer)))
@@ -217,9 +217,9 @@ non-nil."
     ;; Sort items
     (pcase sort
       (`nil items)
-      ((or 'date 'deadline 'scheduled 'todo 'priority
+      ((or 'date 'deadline 'scheduled 'todo 'priority 'random
            (guard (cl-loop for elem in sort
-                           always (memq elem '(date deadline scheduled todo priority)))))
+                           always (memq elem '(date deadline scheduled todo priority 'random)))))
        ;; Default sorting functions
        (org-ql--sort-by items (-list sort)))
       ;; Sort by user-given comparator.
@@ -938,6 +938,8 @@ PREDICATES is a list of one or more sorting methods, including:
                         (apply-partially #'org-ql--date-type< (intern (concat ":" (symbol-name symbol)))))
                        ('date #'org-ql--date<)
                        ('priority #'org-ql--priority<)
+                       ('random (lambda (&rest _ignore)
+                                  (= 0 (random 2))))
                        ;; NOTE: 'todo is handled below
                        ;; FIXME: Add more?
                        (_ (user-error "Invalid sorting predicate: %s" symbol))))