diff options
| -rw-r--r-- | sx-encoding.el | 12 | ||||
| -rw-r--r-- | sx-filter.el | 9 | ||||
| -rw-r--r-- | sx-method.el | 7 | ||||
| -rw-r--r-- | sx-question-list.el | 66 | ||||
| -rw-r--r-- | sx-question-mode.el | 9 |
5 files changed, 67 insertions, 36 deletions
diff --git a/sx-encoding.el b/sx-encoding.el index 91d2765..8af020e 100644 --- a/sx-encoding.el +++ b/sx-encoding.el @@ -60,7 +60,9 @@ ucirc "û" Ucirc "Û" ugrave "ù" Ugrave "Ù" uml "¨" upsih "ϒ" Upsilon "Υ" upsilon "υ" uuml "ü" Uuml "Ü" weierp "℘" Xi "Ξ" xi "ξ" yacute "ý" Yacute "Ý" yen "¥" yuml "ÿ" Yuml "Ÿ" Zeta "Ζ" zeta "ζ" zwj "" zwnj "") - "Plist of HTML entities and their respective glyphs." + "Plist of HTML entities and their respective glyphs. + +See `sx-encoding-decode-entities'." :type '(repeat (choice symbol string)) :group 'sx) @@ -72,9 +74,6 @@ list does not contain the entity, it is assumed to be a number and converted to a string (with `char-to-string'). Return the decoded string." - ;; @TODO Why are we limiting ourselves to two digits, here? - ;; "Ɛ" is perfectly valid, corresponding to "Ɛ". (Note that - ;; "Ɛ" is not in our plist.) (let* ((plist sx-encoding-html-entities-plist) (get-function (lambda (s) @@ -84,6 +83,7 @@ Return the decoded string." ;; Handle things like ' (char-to-string (string-to-number + ;; Skip the `#' (substring ss 1)))))))) (replace-regexp-in-string "&[^; ]*;" get-function string))) @@ -92,8 +92,8 @@ Return the decoded string." The API returns strings that use Windows-style line endings. These are largely useless in an Emacs environment. Windows uses -\"\\r\\n\", Unix uses just \"\\n\". Deleting \"\\r\" is -sufficient for conversion." +\"\\r\\n\", Unix uses just \"\\n\". Deleting \"\\r\" is sufficient for +conversion." (delete ?\r string)) (defun sx-encoding-clean-content (string) diff --git a/sx-filter.el b/sx-filter.el index 1fb2861..1241614 100644 --- a/sx-filter.el +++ b/sx-filter.el @@ -71,10 +71,11 @@ Returns the compiled filter as a string." (defun sx-filter-get (&optional include exclude base) "Return the string representation of the given filter. -If the filter data exist together in `sx--filter-alist', that -value will be returned. Otherwise, compile INCLUDE, EXCLUDE, and -BASE into a filter with `sx-filter-compile' and push the -association onto `sx--filter-alist'." +If the filter data exist in `sx--filter-alist', that value will +be returned. Otherwise, compile INCLUDE, EXCLUDE, and BASE into +a filter with `sx-filter-compile' and push the association onto +`sx--filter-alist'. Re-cache the alise with `sx-cache-set' and +return the compiled filter." (or (cdr (assoc (list include exclude base) sx--filter-alist)) (let ((filter (sx-filter-compile include exclude base))) (when filter diff --git a/sx-method.el b/sx-method.el index 8838134..bd91e38 100644 --- a/sx-method.el +++ b/sx-method.el @@ -19,6 +19,11 @@ ;;; Commentary: +;;; This file is effectively a common-use wrapper for +;;; `sx-request-make'. It provides higher-level handling such as +;;; (authentication, filters, ...) that `sx-request-make' doesn't need +;;; to handle. + ;;; Code: (require 'json) (require 'url) @@ -30,7 +35,7 @@ (method &optional keyword-arguments filter) "Call METHOD with KEYWORD-ARGUMENTS using FILTER. -Return the entire response as a complex alist. +Return the response content as a complex alist. See `sx-request-make' and `sx-filter-get-var'." (sx-request-make diff --git a/sx-question-list.el b/sx-question-list.el index b220097..26b7c2f 100644 --- a/sx-question-list.el +++ b/sx-question-list.el @@ -135,7 +135,7 @@ Letters do not insert themselves; instead, they are commands. ([?\r] sx-question-list-display-question))) (defvar sx-question-list--current-page "Latest" - ;; Other values (once we implement them) are "Top Voted", + ;; @TODO Other values (once we implement them) are "Top Voted", ;; "Unanswered", etc. "Variable describing current page being viewed.") @@ -179,10 +179,11 @@ Letters do not insert themselves; instead, they are commands. "Site being displayed in the *question-list* buffer.") (defvar sx-question-list--current-dataset nil - "") + "The logical data behind the displayed list of questions.") (defun sx-question-list-refresh (&optional redisplay no-update) "Update the list of questions. + If REDISPLAY is non-nil (or if interactive), also call `tabulated-list-print'. If the prefix argument NO-UPDATE is nil, query StackExchange for a new list before redisplaying." @@ -212,29 +213,33 @@ a new list before redisplaying." (defcustom sx-question-list-ago-string " ago" "String appended to descriptions of the time since something happened. + Used in the questions list to indicate a question was updated \"4d ago\"." :type 'string :group 'sx-question-list) -(defun sx-question-list--print-info (data) - "Convert `json-read' DATA into tabulated-list format." - (sx-assoc-let data +(defun sx-question-list--print-info (question-data) + "Format QUESTION-DATA for display in the list. + +See `sx-question-list-refresh'." + (sx-assoc-let question-data (list - data + question-data (vector (list (int-to-string .score) 'face (if .upvoted 'sx-question-list-score-upvoted 'sx-question-list-score)) (list (int-to-string .answer_count) - 'face (if (sx-question--accepted-answer-id data) + 'face (if (sx-question--accepted-answer-id question-data) 'sx-question-list-answers-accepted 'sx-question-list-answers)) (concat (propertize .title - 'face (if (sx-question--read-p data) + 'face (if (sx-question--read-p question-data) 'sx-question-list-read-question - ;; Increment `sx-question-list--unread-count' for the mode-line. + ;; Increment `sx-question-list--unread-count' for the + ;; mode-line. (cl-incf sx-question-list--unread-count) 'sx-question-list-unread-question)) (propertize " " 'display "\n ") @@ -247,32 +252,42 @@ Used in the questions list to indicate a question was updated \"4d ago\"." (propertize " " 'display "\n")))))) (defun sx-question-list-view-previous (n) - "Hide this question, move to previous one, display it." + "Move to the previous question and display it. + +Displayed in `sx-question-mode--window', replacing any question +that may currently be there." (interactive "p") (sx-question-list-view-next (- n))) (defun sx-question-list-view-next (n) - "Hide this question, move to next one, display it." + "Move to the next question and display it. + +Displayed in `sx-question-mode--window', replacing any question +that may currently be there." (interactive "p") (sx-question-list-next n) (sx-question-list-display-question)) (defun sx-question-list-next (n) - "Move to the next entry." + "Move to the next entry. + +This does not update `sx-question-mode--window'." (interactive "p") (forward-line n)) (defun sx-question-list-previous (n) - "Move to the previous entry." + "Move to the previous entry. + +This does not update `sx-question-mode--window'." (interactive "p") (sx-question-list-next (- n))) (defun sx-question-list-display-question (&optional data focus) "Display question given by DATA. -If called interactively (or with DATA being nil), display -question under point. -Also when called interactively (or when FOCUS is non-nil), also -focus the relevant window." + +When DATA is nil, display question under point. When FOCUS is +non-nil (the default when called interactively), also focus the +relevant window." (interactive '(nil t)) (unless data (setq data (tabulated-list-get-id))) (unless data (error "No question here!")) @@ -299,7 +314,7 @@ focus the relevant window." (set-window-parameter sx-question-mode--window 'quit-restore - ;; See https://www.gnu.org/software/emacs/manual/html_node/elisp/Window-Parameters.html#Window-Parameters + ;; See (info "(elisp) Window Parameters") `(window window ,(selected-window) ,sx-question-mode--buffer)) (when focus (if sx-question-mode--window @@ -307,7 +322,12 @@ focus the relevant window." (switch-to-buffer sx-question-mode--buffer)))) (defun sx-question-list-switch-site (site) - "Switch the current site to SITE and display its questions" + "Switch the current site to SITE and display its questions. + +Uses `ido-completing-read' if `ido-mode' is active. Retrieves +completions from `sx-site-get-api-tokens'. Sets +`sx-question-list--current-site' and then +`sx-question-list-refresh' with `redisplay'." (interactive (list (funcall (if ido-mode #'ido-completing-read #'completing-read) "Switch to site: " (sx-site-get-api-tokens) @@ -320,8 +340,10 @@ focus the relevant window." (defvar sx-question-list--buffer nil "Buffer where the list of questions is displayed.") -(defun list-questions (no-update) - "Display a list of StackExchange questions." +(defun sx-list-questions (no-update) + "Display a list of StackExchange questions. + +NO-UPDATE is passed to `sx-question-list-refresh'." (interactive "P") (unless (buffer-live-p sx-question-list--buffer) (setq sx-question-list--buffer @@ -331,7 +353,7 @@ focus the relevant window." (sx-question-list-refresh 'redisplay no-update)) (switch-to-buffer sx-question-list--buffer)) -(defalias 'sx-list-questions #'list-questions) +(defalias 'list-questions #'sx-list-questions) (provide 'sx-question-list) ;;; sx-question-list.el ends here diff --git a/sx-question-mode.el b/sx-question-mode.el index 32cd112..e436b40 100644 --- a/sx-question-mode.el +++ b/sx-question-mode.el @@ -19,8 +19,6 @@ ;;; Commentary: -;; - ;;; Code: (require 'markdown-mode) @@ -53,7 +51,9 @@ (defun sx-question-mode--display (data &optional window) "Display question given by DATA on WINDOW. + If WINDOW is nil, use selected one. + Returns the question buffer." (let ((inhibit-read-only t)) (with-current-buffer @@ -65,7 +65,9 @@ Returns the question buffer." (defun sx-question-mode--display-buffer (window) "Display and return the buffer used for displaying a question. -Create the buffer if necessary. + +Create `sx-question-mode--buffer' if necessary. + If WINDOW is given, use that to display the buffer." ;; Create the buffer if necessary. (unless (buffer-live-p sx-question-mode--buffer) @@ -84,6 +86,7 @@ If WINDOW is given, use that to display the buffer." ;;; Printing a question's content ;;;; Faces and Variables + (defvar sx-question-mode--overlays nil "") (make-variable-buffer-local 'sx-question-mode--overlays) |