diff options
| -rw-r--r-- | sx-auth.el | 4 | ||||
| -rw-r--r-- | sx-cache.el | 10 | ||||
| -rw-r--r-- | sx-encoding.el | 16 | ||||
| -rw-r--r-- | sx-favorites.el | 5 | ||||
| -rw-r--r-- | sx-filter.el | 2 | ||||
| -rw-r--r-- | sx-method.el | 5 | ||||
| -rw-r--r-- | sx-networks.el | 6 | ||||
| -rw-r--r-- | sx-question-list.el | 26 | ||||
| -rw-r--r-- | sx-question-mode.el | 46 | ||||
| -rw-r--r-- | sx-question.el | 15 | ||||
| -rw-r--r-- | sx-request.el | 16 | ||||
| -rw-r--r-- | sx-site.el | 4 | ||||
| -rw-r--r-- | sx-time.el | 2 | ||||
| -rw-r--r-- | sx.el | 21 |
14 files changed, 54 insertions, 124 deletions
@@ -19,8 +19,6 @@ ;;; Commentary: -;; - ;;; Code: (require 'sx) @@ -36,14 +34,12 @@ (defvar sx-auth-access-token nil "Your access token. - This is needed to use your account to write questions, make comments, and read your inbox. Do not alter this unless you know what you are doing!") (defun sx-auth-authenticate () "Authenticate this application. - Authentication is required to read your personal data (such as notifications) and to write with the API (asking and answering questions). diff --git a/sx-cache.el b/sx-cache.el index 049e171..9f152e2 100644 --- a/sx-cache.el +++ b/sx-cache.el @@ -47,7 +47,6 @@ (defun sx-cache-get (cache &optional form) "Return the data within CACHE. - If CACHE does not exist, use `sx-cache-set' to set CACHE to the result of evaluating FORM. @@ -64,8 +63,7 @@ CACHE is resolved to a file name by `sx-cache-get-file-name'." (sx-cache-set cache (eval form))))) (defun sx-cache-set (cache data) - "Set the content of CACHE to DATA and save changes permanently. - + "Set the content of CACHE to DATA and save. DATA will be written as returned by `prin1'. CACHE is resolved to a file name by `sx-cache-get-file-name'." @@ -86,10 +84,8 @@ re-initialize the cache." (defun sx-cache-invalidate-all (&optional save-auth) "Invalidate all caches using `sx-cache--invalidate'. - -Afterwards reinitialize caches using `sx-initialize'. - -If SAVE-AUTH is non-nil, do not clear AUTH cache." +Afterwards reinitialize caches using `sx-initialize'. If +SAVE-AUTH is non-nil, do not clear AUTH cache." (let ((caches (let ((default-directory sx-cache-directory)) (file-expand-wildcards "*.el")))) (when save-auth diff --git a/sx-encoding.el b/sx-encoding.el index 8af020e..f683615 100644 --- a/sx-encoding.el +++ b/sx-encoding.el @@ -61,7 +61,6 @@ upsilon "υ" uuml "ü" Uuml "Ü" weierp "℘" Xi "Ξ" xi "ξ" yacute "ý" Yacute "Ý" yen "¥" yuml "ÿ" Yuml "Ÿ" Zeta "Ζ" zeta "ζ" zwj "" zwnj "") "Plist of HTML entities and their respective glyphs. - See `sx-encoding-decode-entities'." :type '(repeat (choice symbol string)) :group 'sx) @@ -89,7 +88,6 @@ Return the decoded string." (defun sx-encoding-normalize-line-endings (string) "Normalize the line endings for 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 @@ -98,7 +96,6 @@ conversion." (defun sx-encoding-clean-content (string) "Clean STRING for display. - Applies `sx-encoding-normalize-line-endings' and `sx-encoding-decode-entities' (in that order) to prepare STRING for sane display." @@ -135,8 +132,7 @@ some cases." (t data)))) (defun sx-encoding-gzipped-p (data) - "Checks for magic bytes in DATA. - + "Check for magic bytes in DATA. Check if the first two bytes of a string in DATA match the magic numbers identifying the gzip file format. @@ -145,15 +141,15 @@ See URL `http://www.gzip.org/zlib/rfc-gzip.html'." (equal (substring (string-as-unibyte data) 0 2) (unibyte-string 31 139))) -(defun sx-encoding-gzipped-buffer-p (filename) - "Check if the BUFFER is gzip-compressed. - +(defun sx-encoding-gzipped-buffer-p (buffer) + "Check if BUFFER is gzip-compressed. See `sx-encoding-gzipped-p'." - (sx-encoding-gzip-check-magic (buffer-string))) + (with-current-buffer buffer + (sx-encoding-gzip-check-magic + (buffer-string)))) (defun sx-encoding-gzipped-file-p (file) "Check if the FILE is gzip-compressed. - See `sx-encoding-gzipped-p'." (let ((first-two-bytes (with-temp-buffer (set-buffer-multibyte nil) diff --git a/sx-favorites.el b/sx-favorites.el index 3aa96dd..71079fb 100644 --- a/sx-favorites.el +++ b/sx-favorites.el @@ -19,8 +19,6 @@ ;;; Commentary: -;; - ;;; Code: (require 'sx-method) @@ -39,13 +37,11 @@ (defvar sx-favorites--user-favorite-list nil "Alist of questions favorited by the user. - Each element has the form (SITE FAVORITE-LIST). And each element in FAVORITE-LIST is the numerical QUESTION_ID.") (defun sx-favorites--initialize () "Ensure question-favorites cache is available. - Added as hook to initialization." (or (setq sx-favorites--user-favorite-list (sx-cache-get 'question-favorites)) @@ -62,7 +58,6 @@ Added as hook to initialization." (defun sx-favorites--update-site-favorites (site) "Update list of starred QUESTION_IDs for SITE. - Writes list to cache QUESTION-FAVORITES." (let* ((favs (sx-favorites--retrieve-favorites site)) (site-cell (assoc site diff --git a/sx-filter.el b/sx-filter.el index 5c878c5..38084b9 100644 --- a/sx-filter.el +++ b/sx-filter.el @@ -34,7 +34,6 @@ (defvar sx--filter-alist (sx-cache-get 'filter) "An alist of known filters. See `sx-filter-compile'. - Structure: (((INCLUDE EXCLUDE BASE ) . \"compiled filter \") @@ -47,7 +46,6 @@ Structure: ;;; @TODO allow BASE to be a precompiled filter name (defun sx-filter-compile (&optional include exclude base) "Compile INCLUDE and EXCLUDE into a filter derived from BASE. - INCLUDE and EXCLUDE must both be lists; BASE should be a string. Returns the compiled filter as a string." diff --git a/sx-method.el b/sx-method.el index 2d8f9d2..8909a2b 100644 --- a/sx-method.el +++ b/sx-method.el @@ -34,6 +34,7 @@ (defun sx-method-call (method &optional keyword-arguments filter need-auth use-post) "Call METHOD with KEYWORD-ARGUMENTS using FILTER. +This is a high-level wrapper for `sx-request-make'. If NEED-AUTH is non-nil, an auth-token is required. If 'WARN, warn the user `(user-error ...)' if they do not have an AUTH @@ -42,9 +43,7 @@ token set. If USE-POST is non-nil, use `POST' rather than `GET' for passing arguments. -Return the response content as a complex alist. - -See `sx-request-make' and `sx-filter-get-var'." +Return the response content as a complex alist." (sx-request-make method (cons (cons 'filter (sx-filter-get-var filter)) keyword-arguments) diff --git a/sx-networks.el b/sx-networks.el index 755d62c..6820e11 100644 --- a/sx-networks.el +++ b/sx-networks.el @@ -19,8 +19,6 @@ ;;; Commentary: -;; - ;;; Code: (require 'sx-method) @@ -54,7 +52,6 @@ (defun sx-network--get-associated () "Retrieve cached information for network user. - If cache is not available, retrieve current data." (or (and (setq sx-network--user-information (sx-cache-get 'network-user) sx-network--user-sites @@ -63,7 +60,6 @@ If cache is not available, retrieve current data." (defun sx-network--update () "Update user information. - Sets cache and then uses `sx-network--get-associated' to update the variables." (sx-cache-set 'network-user @@ -75,7 +71,6 @@ the variables." (defun sx-network--initialize () "Ensure network-user cache is available. - Added as hook to initialization." ;; Cache was not retrieved, retrieve it. (sx-network--get-associated)) @@ -83,7 +78,6 @@ Added as hook to initialization." (defun sx-network--map-site-url-to-site-api () "Convert `me/associations' to a set of `api_site_parameter's. - `me/associations' does not return `api_site_parameter' so cannot be directly used to retrieve content per site. This creates a list of sites the user is active on." diff --git a/sx-question-list.el b/sx-question-list.el index cad67a1..9e94536 100644 --- a/sx-question-list.el +++ b/sx-question-list.el @@ -161,7 +161,7 @@ Non-interactively, DATA is a question alist." (tabulated-list-get-id) (user-error "Not in `sx-question-list-mode'")))) (sx-question--mark-read data) - (sx-question-list-next 1) + (sx-question-list-next 1) (when (called-interactively-p 'any) (sx-question-list-refresh 'redisplay 'noupdate))) @@ -211,13 +211,11 @@ Non-interactively, DATA is a question alist." (defvar sx-question-list--current-dataset nil "The logical data behind the displayed list of questions. - This dataset contains even questions that are hidden by the user, and thus not displayed in the 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." @@ -248,14 +246,13 @@ 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\"." +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 (question-data) "Convert `json-read' QUESTION-DATA into tabulated-list format. - See `sx-question-list-refresh'." (sx-assoc-let question-data (let ((favorite (if (member .question_id @@ -293,16 +290,14 @@ See `sx-question-list-refresh'." (propertize " " 'display "\n"))))))) (defun sx-question-list-view-previous (n) - "Move to the previous question and display it. - + "Move cursor up N questions up and display this question. 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) - "Move to the next question and display it. - + "Move cursor down N questions and display this question. Displayed in `sx-question-mode--window', replacing any question that may currently be there." (interactive "p") @@ -310,22 +305,19 @@ that may currently be there." (sx-question-list-display-question)) (defun sx-question-list-next (n) - "Move to the next entry. - + "Move cursor down N questions. 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 cursor up N questions. 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. - When DATA is nil, display question under point. When FOCUS is non-nil (the default when called interactively), also focus the relevant window." @@ -364,8 +356,7 @@ relevant window." (defun sx-question-list-switch-site (site) "Switch the current site to SITE and display its questions. - -Uses `ido-completing-read' if `ido-mode' is active. Retrieves +Uses `ido-completing-read' if variable `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'." @@ -383,7 +374,6 @@ completions from `sx-site-get-api-tokens'. Sets (defun list-questions (no-update) "Display a list of StackExchange questions. - NO-UPDATE is passed to `sx-question-list-refresh'." (interactive "P") (sx-initialize) diff --git a/sx-question-mode.el b/sx-question-mode.el index 37d50f9..f8a0d1e 100644 --- a/sx-question-mode.el +++ b/sx-question-mode.el @@ -51,7 +51,6 @@ (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." @@ -65,9 +64,7 @@ Returns the question buffer." (defun sx-question-mode--display-buffer (window) "Display and return the buffer used for displaying a question. - 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) @@ -88,7 +85,7 @@ If WINDOW is given, use that to display the buffer." ;;;; Faces and Variables (defvar sx-question-mode--overlays nil - "") + "Question mode overlays.") (make-variable-buffer-local 'sx-question-mode--overlays) (defface sx-question-mode-header @@ -150,14 +147,12 @@ If WINDOW is given, use that to display the buffer." '((((background dark)) :background "#090909") (((background light)) :background "#f4f4f4")) "Face used on the question body in the question buffer. - This shouldn't have a foreground, or this will interfere with font-locking." :group 'sx-question-mode-faces) (defcustom sx-question-mode-last-edit-format " (edited %s ago by %s)" "Format used to describe last edit date in the header. - First \"%s\" is replaced with the date and the second \"%s\" with the editor's name." :type 'string @@ -181,7 +176,6 @@ the editor's name." (defcustom sx-question-mode-comments-format "%s: %s\n" "Format used to display comments. - First \"%s\" is replaced with user name. Second \"%s\" is replaced with the comment." :type 'string @@ -197,7 +191,6 @@ replaced with the comment." ;;;; Functions (defun sx-question-mode--print-question (question) "Print a buffer describing QUESTION. - QUESTION must be a data structure returned by `json-read'." (setq sx-question-mode--data question) ;; Clear the overlays @@ -213,21 +206,20 @@ QUESTION must be a data structure returned by `json-read'." (defvar sx-question-mode--section-help-echo (format - (propertize "%s to hide/display content" 'face 'minibuffer-prompt) - (propertize "RET" 'face 'font-lock-function-name-face)) - "") + (propertize "%s to hide/display content" 'face 'minibuffer-prompt) + (propertize "RET" 'face 'font-lock-function-name-face)) + "Help echoed in the minibuffer when point is on a section.") (defvar sx-question-mode--title-properties `(face sx-question-mode-title action sx-question-mode-hide-show-section help-echo ,sx-question-mode--section-help-echo button t - follow-link t) - "") + follow-link t) + "Title properties.") (defun sx-question-mode--print-section (data) "Print a section corresponding to DATA. - DATA can represent a question or an answer." ;; This makes `data' accessible through ;; `(get-text-property (point) 'sx-question-mode--data-here)' @@ -303,7 +295,6 @@ DATA can represent a question or an answer." (defun sx-question-mode--print-comment (comment-data) "Print the comment described by alist COMMENT-DATA. - The comment is indented, filled, and then printed according to `sx-question-mode-comments-format'." (sx-assoc-let comment-data @@ -321,8 +312,7 @@ The comment is indented, filled, and then printed according to 3))))) (defmacro sx-question-mode--wrap-in-overlay (properties &rest body) - "Execute BODY and wrap any inserted text in an overlay. - + "Start a scope with overlay PROPERTIES and execute BODY. Overlay is pushed on `sx-question-mode--overlays' and given PROPERTIES. @@ -339,8 +329,7 @@ Return the result of BODY." result)) (defmacro sx-question-mode--wrap-in-text-property (properties &rest body) - "Execute BODY and add PROPERTIES to any inserted text. - + "Start a scope with PROPERTIES and execute BODY. Return the result of BODY." (declare (indent 1) (debug t)) @@ -351,7 +340,6 @@ Return the result of BODY." (defun sx-question-mode--insert-header (&rest args) "Insert propertized ARGS. - ARGS is a list of repeating values -- `header', `value', and `face'. `header' is given `sx-question-mode-header' as a face, where `value' is given `face' as its face. @@ -430,14 +418,13 @@ Syntax: (defun sx-question-mode--propertize-link (text url) "Return a link propertized version of string TEXT. - URL is used as 'help-echo and 'url properties." (propertize text ;; Mouse-over 'help-echo (format (propertize "URL: %s, %s to visit" 'face 'minibuffer-prompt) - (propertize url 'face 'default) + (propertize url 'face 'default) (propertize "RET" 'face 'font-lock-function-name-face)) ;; In case we need it. 'url url @@ -460,7 +447,6 @@ URL is used as 'help-echo and 'url properties." (defun sx-question-mode-find-reference (id &optional fallback-id) "Find url identified by reference ID in current buffer. - If ID is nil, use FALLBACK-ID instead." (save-excursion (save-match-data @@ -489,7 +475,6 @@ If ID is nil, use FALLBACK-ID instead." ;; for comments). (defcustom sx-question-mode-recenter-line 1 "Screen line to which we recenter after moving between sections. - This is used as an argument to `recenter', only used if the end of section is outside the window. @@ -500,7 +485,6 @@ If nil, no recentering is performed." (defun sx-question-mode-next-section (&optional n) "Move down to next section (question or answer) of this buffer. - Prefix argument N moves N sections down or up." (interactive "p") (let ((count (if n (abs n) 1))) @@ -523,14 +507,12 @@ Prefix argument N moves N sections down or up." (defun sx-question-mode-previous-section (&optional n) "Move down to previous section (question or answer) of this buffer. - -Prefix argument N moves N sections up or down." +Prefix argument moves N sections up or down." (interactive "p") (sx-question-mode-next-section (- (or n 1)))) (defun sx-question-mode--goto-property-change (prop &optional direction) - "Move forward until the value of text-property sx-question-mode--PROP changes. - + "Move forward to the next change of text-property sx-question-mode--PROP. Return the new value of PROP at point. If DIRECTION is negative, move backwards instead." @@ -545,9 +527,9 @@ If DIRECTION is negative, move backwards instead." (goto-char (funcall func (point) prop nil limit)) (get-text-property (point) prop))) -;;; Optional argument is for `push-button'. (defun sx-question-mode-hide-show-section (&optional _) - "Hide or show section under point." + "Hide or show section under point. +Optional argument _ is for `push-button'." (interactive) (let ((ov (car (or (sx-question-mode--section-overlays-at (point)) (sx-question-mode--section-overlays-at @@ -567,7 +549,6 @@ If DIRECTION is negative, move backwards instead." ;;; Major-mode (define-derived-mode sx-question-mode markdown-mode "Question" "Major mode to display and navigate a question and its answers. - Letters do not insert themselves; instead, they are commands. \\<sx-question-mode> @@ -616,7 +597,6 @@ Letters do not insert themselves; instead, they are commands. (defun sx-question-mode-refresh () "Refresh currently displayed question. - Queries the API for any changes to the question or its answers or comments, and redisplays it." (interactive) diff --git a/sx-question.el b/sx-question.el index cccf525..f6b7beb 100644 --- a/sx-question.el +++ b/sx-question.el @@ -43,12 +43,11 @@ answer.body_markdown answer.comments) (user.profile_image shallow_user.profile_image)) - "The filter applied with `sx-question-get-questions' and - `sx-question-get-question'.") + "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. @@ -64,7 +63,6 @@ property. (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" question-id) @@ -79,7 +77,7 @@ If QUESTION-ID doesn't exist on SITE, raise an error." ;;; Question Properties ;;;; Read/unread -(defvar sx-question--user-read-list nil +(defvar sx-question--user-read-list nil "Alist of questions read by the user. Each element has the form @@ -92,7 +90,6 @@ where each element in QUESTION-LIST has the form (defun sx-question--ensure-read-list (site) "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 @@ -100,7 +97,6 @@ If no cache exists for it, initialize one with SITE." (defun sx-question--read-p (question) "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) @@ -111,7 +107,6 @@ See `sx-question--user-read-list'." (defun sx-question--mark-read (question) "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) @@ -136,7 +131,7 @@ See `sx-question--user-read-list'." ;;;; Hidden -(defvar sx-question--user-hidden-list nil +(defvar sx-question--user-hidden-list nil "Alist of questions hidden by the user. Each element has the form diff --git a/sx-request.el b/sx-request.el index c49a62d..906785b 100644 --- a/sx-request.el +++ b/sx-request.el @@ -20,7 +20,7 @@ ;;; Commentary: ;; API requests are handled on three separate tiers: -;; +;; ;; `sx-method-call': ;; ;; This is the function that should be used most often, since it @@ -39,7 +39,7 @@ ;; The whole solution is built upon `url-retrieve-synchronously' ;; for making the request and `json-read-from-string' for parsing ;; it into a properly symbolic data structure. -;; +;; ;; When at all possible, use `sx-method-call'. There are specialized ;; cases for the use of `sx-request-make' outside of sx-method.el, but ;; these must be well-documented inline with the code. @@ -70,7 +70,6 @@ (defcustom sx-request-unzip-program "gunzip" "Program used to unzip the response if it is compressed. - This program must accept compressed data on standard input." :group 'sx-request :type 'string) @@ -78,13 +77,11 @@ This program must accept compressed data on standard input." (defvar sx-request-remaining-api-requests nil "The number of API requests remaining. - Set by `sx-request-make'.") (defcustom sx-request-remaining-api-requests-message-threshold 50 "Lower bound for printed warnings of API usage limits. - After `sx-request-remaining-api-requests' drops below this number, `sx-request-make' will begin printing out the number of requests left every time it finishes a call." @@ -97,10 +94,12 @@ number of requests left every time it finishes a call." (defun sx-request-make (method &optional args need-auth use-post) "Make a request to the API, executing METHOD with ARGS. - You should almost certainly be using `sx-method-call' instead of this function. +If NEED-AUTH is non-nil, authentication will be provided. If +USE-POST is non-nil, the request will use POST instead of GET. + Returns cleaned response content. See (`sx-encoding-clean-content-deep'). @@ -176,12 +175,13 @@ the main content of the response is returned." (defun sx-request--build-keyword-arguments (alist &optional kv-sep need-auth) "Format ALIST as a key-value list joined with KV-SEP. - If authentication is needed, include it also or error if it is not available. +If NEED-AUTH is non-nil, authentication is required. + Build a \"key=value&key=value&...\"-style string with the elements -of ALIST. If any value in the alist is `nil', that pair will not +of ALIST. If any value in the alist is nil, that pair will not be included in the return. If you wish to pass a notion of false, use the symbol `false'. Each element is processed with `sx--thing-as-string'." @@ -42,9 +42,10 @@ related_site.relation) nil none) - "") + "Filter for browsing sites.") (defun sx-site--get-site-list () + "Return all sites with `sx-site-browse-filter'." (sx-cache-get 'site-list '(sx-method-call @@ -54,7 +55,6 @@ (defcustom sx-site-favorites nil "List of favorite sites. - Each entry is a string corresponding to a single site's api_site_parameter." :group 'sx-site) @@ -51,14 +51,12 @@ (defcustom sx-time-date-format-year "%H:%M %e %b %Y" "Format used for dates on a past year. - See also `sx-time-date-format'." :type 'string :group 'sx-time) (defcustom sx-time-date-format "%H:%M - %d %b" "Format used for dates on this year. - See also `sx-time-date-format-year'." :type 'string :group 'sx-time) @@ -49,7 +49,7 @@ (defmacro sx-sorted-insert-skip-first (newelt list &optional predicate) "Inserted NEWELT into LIST sorted by PREDICATE. -This is designed for the (site id id ...) lists. So the first car +This is designed for the (site id id ...) lists. So the first car is intentionally skipped." `(let ((tail ,list) (x ,newelt)) @@ -61,7 +61,8 @@ is intentionally skipped." (setcdr tail (cons x (cdr tail))))) (defun sx-message (format-string &rest args) - "Display a message." + "Display FORMAT-STRING as a message with ARGS. +See `format'." (message "[stack] %s" (apply #'format format-string args))) (defun sx-message-help-echo () @@ -71,7 +72,6 @@ is intentionally skipped." (defun sx--thing-as-string (thing &optional sequence-sep) "Return a string representation of THING. - If THING is already a string, just return it. Optional argument SEQUENCE-SEP is the separator applied between @@ -98,7 +98,7 @@ For example: (prop4 . t)) '(prop1 (prop3 test2))) -would yeild +would yield ((prop1 . value1) (prop3 @@ -132,8 +132,7 @@ would yeild ;;; Interpreting request data (defun sx--deep-dot-search (data) "Find symbols somewhere inside DATA which start with a `.'. - -Returns a list where each element is a cons cell. The car is the +Returns a list where each element is a cons cell. The car is the symbol, the cdr is the symbol without the `.'." (cond ((symbolp data) @@ -148,9 +147,8 @@ symbol, the cdr is the symbol without the `.'." (remove nil (mapcar #'sx--deep-dot-search data)))))) (defmacro sx-assoc-let (alist &rest body) - "Execute BODY with dotted symbols let-bound to their values in ALIST. - -Dotted symbol is any symbol starting with a `.'. Only those + "Use dotted symbols let-bound to their values in ALIST and execute BODY. +Dotted symbol is any symbol starting with a `.'. Only those present in BODY are letbound, which leads to optimal performance. For instance, the following code @@ -172,20 +170,17 @@ is equivalent to (defcustom sx-init-hook nil "Hook run when stack-mode initializes. - Run after `sx-init--internal-hook'." :group 'sx :type 'hook) (defvar sx-init--internal-hook nil "Hook run when stack-mode initializes. - This is used internally to set initial values for variables such as filters.") (defun sx--< (property x y &optional predicate) "Non-nil if PROPERTY attribute of alist X is less than that of Y. - With optional argument PREDICATE, use it instead of `<'." (funcall (or predicate #'<) (cdr (assoc property x)) @@ -193,7 +188,6 @@ With optional argument PREDICATE, use it instead of `<'." (defmacro sx-init-variable (variable value &optional setter) "Set VARIABLE to VALUE using SETTER. - SETTER should be a function of two arguments. If SETTER is nil, `set' is used." (eval @@ -209,7 +203,6 @@ If it has, holds the time at which initialization happened.") (defun sx-initialize (&optional force) "Run initialization hooks if they haven't been run yet. - These are `sx-init--internal-hook' and `sx-init-hook'. If FORCE is non-nil, run them even if they've already been run." |