Merge branch 'master' into invalidate-cache

Conflicts:
	sx-cache.el - RESOLVED

1 files changed, 86 insertions, 21 deletions

diff --git a/sx-question.el b/sx-question.el
index 6ef9484..f6b7beb 100644
--- a/sx-question.el
+++ b/sx-question.el
@@ -19,8 +19,6 @@
 
 ;;; Commentary:
 
-;;
-
 
 ;;; Code:
 
@@ -44,10 +42,17 @@
      answer.owner
      answer.body_markdown
      answer.comments)
-    (user.profile_image shallow_user.profile_image)))
+    (user.profile_image shallow_user.profile_image))
+  "The filter applied when retrieving question data.
+See `sx-question-get-questions' and `sx-question-get-question'.")
 
 (defun sx-question-get-questions (site &optional page)
-  "Get the page PAGE of questions from SITE."
+  "Get SITE questions.  Return page PAGE (the first if nil).
+Return a list of question.  Each question is an alist of
+properties returned by the API with an added (site SITE)
+property.
+
+`sx-method-call' is used with `sx-question-browse-filter'."
   (mapcar
    (lambda (question) (cons (cons 'site site) question))
    (sx-method-call
@@ -56,32 +61,43 @@
       (page . ,page))
     sx-question-browse-filter)))
 
-(defun sx-question-get-question (site id)
-  "Get the question ID from SITE."
+(defun sx-question-get-question (site question-id)
+  "Query SITE for a QUESTION-ID and return it.
+If QUESTION-ID doesn't exist on SITE, raise an error."
   (let ((res (sx-method-call
-              (format "questions/%s" id)
+              (format "questions/%s" question-id)
               `((site . ,site))
               sx-question-browse-filter)))
     (if (vectorp res)
         (elt res 0)
-      (error "Couldn't find question %S in %S" id site))))
+      (error "Couldn't find question %S in %S"
+             question-id site))))
 
 
 ;;; Question Properties
-(defvar sx-question--user-read-list nil 
+
+;;;; Read/unread
+(defvar sx-question--user-read-list nil
   "Alist of questions read by the user.
-Each element has the form (SITE . QUESTION-LIST).
-And each element in QUESTION-LIST has the form (QUESTION_ID . LAST-VIEWED-DATE).")
+
+Each element has the form
+
+    (SITE . QUESTION-LIST)
+
+where each element in QUESTION-LIST has the form
+
+    (QUESTION_ID . LAST-VIEWED-DATE).")
 
 (defun sx-question--ensure-read-list (site)
-  "Ensure the `sx-question--user-read-list' has been read from cache.
+  "Ensure `sx-question--user-read-list' has been read from cache.
 If no cache exists for it, initialize one with SITE."
   (unless sx-question--user-read-list
     (setq sx-question--user-read-list
-          (sx-cache-get 'read-questions `(list ,site)))))
+          (sx-cache-get 'read-questions `'((,site))))))
 
 (defun sx-question--read-p (question)
-  "Non-nil if QUESTION has been read since last updated."
+  "Non-nil if QUESTION has been read since last updated.
+See `sx-question--user-read-list'."
   (sx-assoc-let question
     (sx-question--ensure-read-list .site)
     (let ((ql (cdr (assoc .site sx-question--user-read-list))))
@@ -90,7 +106,8 @@ If no cache exists for it, initialize one with SITE."
                .last_activity_date)))))
 
 (defun sx-question--mark-read (question)
-  "Mark QUESTION as being read, until it is updated again."
+  "Mark QUESTION as being read until it is updated again.
+See `sx-question--user-read-list'."
   (sx-assoc-let question
     (sx-question--ensure-read-list .site)
     (let ((site-cell (assoc .site sx-question--user-read-list))
@@ -104,21 +121,69 @@ If no cache exists for it, initialize one with SITE."
        ((setq cell (assoc .question_id site-cell))
         (setcdr cell .last_activity_date))
        ;; Question wasn't present.
-       (t 
-        (setcdr site-cell (cons q-cell (cdr site-cell)))))))
-  ;; This causes a small lag on `j' and `k' as the list gets large.
-  ;; Should we do this on a timer?
+       (t
+        (sx-sorted-insert-skip-first
+         q-cell site-cell (lambda (x y) (> (car x) (car y))))))))
   ;; Save the results.
+  ;; @TODO This causes a small lag on `j' and `k' as the list gets
+  ;; large.  Should we do this on a timer?
   (sx-cache-set 'read-questions sx-question--user-read-list))
 
+
+;;;; Hidden
+(defvar sx-question--user-hidden-list nil
+  "Alist of questions hidden by the user.
+
+Each element has the form
+
+  (SITE QUESTION_ID QUESTION_ID ...)")
+
+(defun sx-question--ensure-hidden-list (site)
+  "Ensure the `sx-question--user-hidden-list' has been read from cache.
+
+If no cache exists for it, initialize one with SITE."
+  (unless sx-question--user-hidden-list
+    (setq sx-question--user-hidden-list
+          (sx-cache-get 'hidden-questions `'((,site))))))
+
+(defun sx-question--hidden-p (question)
+  "Non-nil if QUESTION has been hidden."
+  (sx-assoc-let question
+    (sx-question--ensure-hidden-list .site)
+    (let ((ql (cdr (assoc .site sx-question--user-hidden-list))))
+      (and ql (memq .question_id ql)))))
+
+(defun sx-question--mark-hidden (question)
+  "Mark QUESTION as being hidden."
+  (sx-assoc-let question
+    (sx-question--ensure-hidden-list .site)
+    (let ((site-cell (assoc .site sx-question--user-hidden-list))
+          cell)
+      ;; If question already hidden, do nothing.
+      (unless (memq .question_id site-cell)
+        ;; First question from this site.
+        (if (null site-cell)
+            (push (list .site .question_id) sx-question--user-hidden-list)
+          ;; Question wasn't present.
+          ;; Add it in, but make sure it's sorted (just in case we need
+          ;; it later).
+          (sx-sorted-insert-skip-first .question_id site-cell >))
+        ;; This causes a small lag on `j' and `k' as the list gets large.
+        ;; Should we do this on a timer?
+        ;; Save the results.
+        (sx-cache-set 'hidden-questions sx-question--user-hidden-list)))))
+
+
+;;;; Other data
+
 (defun sx-question--accepted-answer-id (question)
-  "Return accepted answer in QUESTION, or nil if none."
+  "Return accepted answer in QUESTION or nil if none exists."
   (sx-assoc-let question
     (and (integerp .accepted_answer_id)
          .accepted_answer_id)))
 
 (defun sx-question--tag-format (tag)
-  "Formats TAG for display"
+  "Formats TAG for display."
   (concat "[" tag "]"))
 
 (provide 'sx-question)