From 01b75599a500d6276a962b47744166abb25d846c Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Tue, 28 Apr 2026 19:13:05 -0500 Subject: refactor: switch gloss-fetch result to uniform plist shape MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The previous shape (:ok DEFS) | (:empty :no-defs (...) :failed (...)) was malformed as a plist. The :empty tag at position 0 shifted the plist alignment. plist-get on :no-defs or :failed returned nil. Tests had to use (plist-get (cdr result) ...) as a workaround. The new shape is a uniform plist with all three keys always present: (:defs DEFS :no-defs (SYM ...) :failed (SYM ...)). Consumers branch on whether :defs is non-empty. There is no tag. plist-get works uniformly across success and empty cases. Updated gloss-fetch.el (rollup function and docstrings), 7 test files, and the design doc (docs/design/gloss.org ยง Error Handling). Tested by `make test`. 65 tests pass in 0.36 seconds. --- gloss-fetch.el | 36 ++++++++++++++++++++---------------- 1 file changed, 20 insertions(+), 16 deletions(-) (limited to 'gloss-fetch.el') diff --git a/gloss-fetch.el b/gloss-fetch.el index a5aa84d..d48e4db 100644 --- a/gloss-fetch.el +++ b/gloss-fetch.el @@ -13,8 +13,8 @@ ;; ;; Public API: ;; `gloss-fetch-definitions' TERM -;; -> (:ok DEFS) ; any source returned >=1 def -;; | (:empty :no-defs (SYM ...) :failed (SYM ...)) +;; -> (:defs DEFS :no-defs (SYM ...) :failed (SYM ...)) +;; ; uniform plist; success = DEFS non-empty. ;; ;; Each definition is a plist: ;; (:source SYM :text "Reference to ...") @@ -254,32 +254,36 @@ in `gloss-fetch--sources' are silently skipped." (nreverse results))) (defun gloss-fetch--rollup (per-source) - "Roll up PER-SOURCE results into the user-facing response shape. -Returns (:ok DEFS) when any source returned :ok with non-empty :defs. -Otherwise returns (:empty :no-defs (...) :failed (...))." - (let (ok-defs no-defs failed) + "Roll up PER-SOURCE results into the user-facing response plist. +Always returns (:defs DEFS :no-defs (SYM ...) :failed (SYM ...)) with +all three keys present. DEFS is a (possibly empty) list of definition +plists. :no-defs lists sources that were reached but returned no +definitions. :failed lists sources that could not be reached. +Consumers branch on whether DEFS is non-empty." + (let (defs no-defs failed) (dolist (entry per-source) (let ((sym (plist-get entry :source)) (status (plist-get entry :status))) (cond ((and (eq status :ok) (plist-get entry :defs)) - (setq ok-defs (append ok-defs (plist-get entry :defs)))) + (setq defs (append defs (plist-get entry :defs)))) ((eq status :no-defs) (push sym no-defs)) ((memq status '(:unreachable :server-error :rate-limited)) (push sym failed))))) - (if ok-defs - (list :ok ok-defs) - (list :empty - :no-defs (nreverse no-defs) - :failed (nreverse failed))))) + (list :defs defs + :no-defs (nreverse no-defs) + :failed (nreverse failed)))) (defun gloss-fetch-definitions (term) "Fetch candidate definitions for TERM from each source in `gloss-fetch-sources'. -Returns (:ok DEFS) when any source returns at least one definition, -otherwise (:empty :no-defs (SYM ...) :failed (SYM ...)). Signals -`user-error' the first time it runs in a session without libxml, and -on every subsequent call in that session." +Returns a plist with three keys, all always present: + :defs โ€” list of definition plists, possibly empty. + :no-defs โ€” list of sources reached but returning no definitions. + :failed โ€” list of sources that could not be reached. +Consumers branch on whether `(plist-get result :defs)' is non-empty. +Signals `user-error' the first time it runs in a session without libxml, +and on every subsequent call in that session." (gloss-fetch--ensure-libxml) (gloss-fetch--rollup (gloss-fetch--collect term))) -- cgit v1.2.3