Highlight the current argument in eldoc

When point is inside a call, eldoc now wraps the matching parameter
in eldoc-highlight-function-argument. Multi-arity arglists pick
whichever arity fits the current arg count; variadic arities
highlight the rest param once you're past the fixed slots.

Kept language-agnostic via two seams: neat-eldoc-arg-index-function
computes the position (default uses forward-sexp, works for any
Lisp-flavored major mode) and neat-eldoc-arglist-formatter formats
the display string (default parses [a b & rest] shapes). Servers
that report arglists in some other syntax swap the formatter; major
modes where argument boundaries aren't sexps swap the index function.

Destructuring forms containing maps still fall back to the raw
arglist; the read-from-string trick can't handle them without a
bigger parser, and that's not worth the LOC today.

Author: bbatsov

CHANGELOG.md

@@ -24,6 +24,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - REPL: input history persistence. New `neat-repl-history-file` defaults to `~/.emacs.d/neat-repl-history`; history is loaded on REPL start and saved on buffer kill. Set to nil to disable.
 - REPL: namespace-aware prompt. The prompt is now derived from `neat-repl-prompt-format` (default `"%s> "`) and updates in response to the server's `ns` field, so `user> ` becomes `myapp.core> ` after `(in-ns 'myapp.core)`. `neat-repl-default-ns` controls what appears before the server has reported one.
 - REPL: completion-at-point and eldoc are now also active in the REPL buffer, not just in source buffers running `neat-mode`. Same backends, same caveats (server must implement `completions` / `lookup`).
+- Eldoc highlights the current argument in the displayed arglist. When point sits inside a call like `(map f |coll)`, the param matching the cursor position is wrapped in `eldoc-highlight-function-argument`. Multi-arity arglists pick whichever arity fits the current arg count; variadic arities highlight the rest param once you're past the fixed slots. Two seams keep this language-agnostic: `neat-eldoc-arg-index-function` (defaults to a `forward-sexp`-based walk) and `neat-eldoc-arglist-formatter` (defaults to a Clojure-shape `[a b & rest]` parser). Destructuring forms containing maps fall back to the unhighlighted arglist.
 
 ### Changed
 

neat.el

@@ -228,17 +228,6 @@ Asks the server for completions of the symbol at point via the
             (when cands
               (list start end cands :exclusive 'no))))))))
 
-(defun neat--eldoc-format (info)
-  "Pick the displayable string from a `lookup' INFO dict, or return nil."
-  (let* ((arglists (neat-bencode-get info "arglists-str"))
-         (doc (neat-bencode-get info "doc"))
-         (first-doc-line (and doc (car (split-string doc "\n")))))
-    (cond
-     ((and arglists first-doc-line)
-      (format "%s: %s" arglists first-doc-line))
-     (arglists arglists)
-     (first-doc-line first-doc-line))))
-
 (defun neat--eldoc-thing-at-point ()
   "Return the symbol eldoc should look up around point, or nil.
 Prefers the symbol at point; if there isn't one (point is in
@@ -253,6 +242,119 @@ results in nested calls: from `(str (sub |))' you get `sub'."
           (down-list)
           (thing-at-point 'symbol t)))))
 
+(defun neat--current-arg-index ()
+  "Return the 0-indexed arg position at point in the enclosing call.
+nil if there's no enclosing call (top-level point).  Drives the
+arg-highlight in `neat-eldoc-format-lispy-arglist'.  Uses
+`forward-sexp', so it follows the buffer's syntax table and works
+for any Lisp-flavored major mode."
+  (save-excursion
+    (let ((origin (point)))
+      (when (ignore-errors (backward-up-list) t)
+        (forward-char 1)
+        (when (ignore-errors (forward-sexp 1) t)   ; past the head
+          (let ((idx 0))
+            (while (let ((before (point)))
+                     (and (ignore-errors (forward-sexp 1) t)
+                          (> (point) before)
+                          (<= (point) origin)))
+              (cl-incf idx))
+            idx))))))
+
+(defun neat--lispy-parse-arglist (arglist-str)
+  "Parse a Clojure/Lisp-shape ARGLIST-STR into a list of arities.
+Each arity is a list of param tokens (strings); `&' is kept as its
+own token.  Returns nil if parsing fails (e.g. destructuring forms
+containing maps), in which case the caller should fall back to the
+raw string."
+  (ignore-errors
+    (let* ((s (replace-regexp-in-string "\\[" "(" arglist-str))
+           (s (replace-regexp-in-string "\\]" ")" s))
+           (form (car (read-from-string s))))
+      (cond
+       ;; `[]' -> nil; treat as a single empty arity.
+       ((null form) '(()))
+       ;; `([] [x] ...)' -> every element is a list (nil counts).
+       ((cl-every #'listp form)
+        (mapcar (lambda (a) (mapcar #'symbol-name a)) form))
+       ;; `[f coll]' -> flat list of symbols.
+       ((consp form)
+        (list (mapcar #'symbol-name form)))))))
+
+(defun neat--pick-arity (arities arg-index)
+  "Return the arity in ARITIES that best matches ARG-INDEX, or nil."
+  (cl-find-if
+   (lambda (arity)
+     (let ((amp (cl-position "&" arity :test #'equal)))
+       (if amp
+           (>= arg-index amp)
+         (< arg-index (length arity)))))
+   arities))
+
+(defun neat--render-arity (arity highlight-pos)
+  "Render ARITY as `[a b c]', wrapping the param at HIGHLIGHT-POS in a face.
+HIGHLIGHT-POS of -1 disables highlighting."
+  (let ((i 0))
+    (concat "["
+            (mapconcat
+             (lambda (p)
+               (prog1
+                   (if (= i highlight-pos)
+                       (propertize p 'face
+                                   'eldoc-highlight-function-argument)
+                     p)
+                 (cl-incf i)))
+             arity " ")
+            "]")))
+
+(defun neat--lispy-highlight-arglist (arglist-str arg-index)
+  "Return ARGLIST-STR with the param at ARG-INDEX highlighted.
+Falls back to the original string when parsing fails or no arity
+fits ARG-INDEX (e.g. user has typed more args than any arity takes)."
+  (or (when (and arglist-str arg-index)
+        (let ((arities (neat--lispy-parse-arglist arglist-str)))
+          (when arities
+            (let ((chosen (neat--pick-arity arities arg-index)))
+              (when chosen
+                (let* ((amp (cl-position "&" chosen :test #'equal))
+                       (hi (cond
+                            ((and amp (>= arg-index amp)) (1+ amp))
+                            (t (min arg-index (1- (length chosen))))))
+                       (parts (mapcar
+                               (lambda (a)
+                                 (neat--render-arity
+                                  a (if (eq a chosen) hi -1)))
+                               arities)))
+                  (if (= (length arities) 1)
+                      (car parts)
+                    (concat "(" (mapconcat #'identity parts " ") ")"))))))))
+      arglist-str))
+
+(defun neat-eldoc-format-lispy-arglist (info arg-index)
+  "Default `neat-eldoc-arglist-formatter'.
+Formats INFO's `arglists-str' and `doc' for eldoc display, with the
+param at ARG-INDEX highlighted when given."
+  (let* ((arglist (neat-bencode-get info "arglists-str"))
+         (styled (neat--lispy-highlight-arglist arglist arg-index))
+         (doc (neat-bencode-get info "doc"))
+         (first-doc-line (and doc (car (split-string doc "\n")))))
+    (cond
+     ((and styled first-doc-line) (format "%s: %s" styled first-doc-line))
+     (styled styled)
+     (first-doc-line first-doc-line))))
+
+(defvar neat-eldoc-arg-index-function #'neat--current-arg-index
+  "Function returning the 0-indexed arg position at point, or nil.
+Called with no arguments.  Default works for any Lisp-flavored
+major mode via `forward-sexp'; replace for languages where argument
+boundaries aren't sexps (e.g. Python commas).")
+
+(defvar neat-eldoc-arglist-formatter #'neat-eldoc-format-lispy-arglist
+  "Function (INFO ARG-INDEX) -> string, or nil for no display.
+Produces the eldoc display string from a `lookup' INFO dict.  The
+default understands Clojure/Lisp-shape arglists `[a b & rest]';
+override for servers that report arglists in a different syntax.")
+
 (defun neat-eldoc-function (callback &rest _ignored)
   "Eldoc backend driven by the `lookup' op.
 
@@ -262,13 +364,15 @@ never blocks waiting on a lookup.  When the user has moved point
 by the time the response arrives, eldoc may briefly show stale
 output -- acceptable trade-off for not blocking the editor."
   (let ((conn (neat-active-connection))
-        (sym (neat--eldoc-thing-at-point)))
+        (sym (neat--eldoc-thing-at-point))
+        (arg-index (funcall neat-eldoc-arg-index-function)))
     (when (and conn sym (neat-connection-live-p conn))
       (neat-lookup
        conn sym nil
        (lambda (resp)
          (when-let* ((info (neat-bencode-get resp "info"))
-                     (str (neat--eldoc-format info)))
+                     (str (funcall neat-eldoc-arglist-formatter
+                                   info arg-index)))
            (funcall callback str :thing sym))))
       ;; Tell eldoc we'll call the callback asynchronously.
       t)))

test/neat-test.el

@@ -41,5 +41,84 @@ POS is a 1-indexed buffer position."
   (it "returns nil at top-level whitespace"
     (expect (neat-test--thing-at "  " 2) :to-be nil)))
 
+(defun neat-test--arg-index-at (text pos)
+  "Insert TEXT, jump to POS, return `neat--current-arg-index'."
+  (with-temp-buffer
+    (insert text)
+    (goto-char pos)
+    (neat--current-arg-index)))
+
+(describe "neat--current-arg-index"
+  (it "is 0 when point is on the first arg"
+    ;; "(foo a b)" -> point at `a'.
+    (expect (neat-test--arg-index-at "(foo a b)" 6) :to-equal 0))
+
+  (it "is 1 when point is on the second arg"
+    ;; "(foo a b)" -> point at `b'.
+    (expect (neat-test--arg-index-at "(foo a b)" 8) :to-equal 1))
+
+  (it "is 0 in the whitespace right after the head"
+    ;; "(foo  a)" -> point in the second space.
+    (expect (neat-test--arg-index-at "(foo  a)" 6) :to-equal 0))
+
+  (it "counts past completed args when in trailing whitespace"
+    ;; "(foo a b )" -> point between `b' and `)'.
+    (expect (neat-test--arg-index-at "(foo a b )" 10) :to-equal 2))
+
+  (it "returns nil at the top level"
+    (expect (neat-test--arg-index-at "(foo a)" 1) :to-be nil)))
+
+(describe "neat--lispy-parse-arglist"
+  (it "parses a single-arity arglist"
+    (expect (neat--lispy-parse-arglist "[f coll]")
+            :to-equal '(("f" "coll"))))
+
+  (it "parses a variadic single-arity arglist"
+    (expect (neat--lispy-parse-arglist "[x & rest]")
+            :to-equal '(("x" "&" "rest"))))
+
+  (it "parses a multi-arity arglist"
+    (expect (neat--lispy-parse-arglist "([] [x] [x & ys])")
+            :to-equal '(() ("x") ("x" "&" "ys"))))
+
+  (it "returns nil for an unparseable arglist (destructuring with maps)"
+    (expect (neat--lispy-parse-arglist "[{:keys [a b]} coll]")
+            :to-be nil)))
+
+(describe "neat--pick-arity"
+  (it "picks the fixed arity matching ARG-INDEX"
+    (expect (neat--pick-arity '(("x") ("x" "y")) 1)
+            :to-equal '("x" "y")))
+
+  (it "picks the variadic arity for out-of-range ARG-INDEX"
+    (expect (neat--pick-arity '(("x") ("x" "&" "ys")) 4)
+            :to-equal '("x" "&" "ys")))
+
+  (it "returns nil when no arity fits"
+    (expect (neat--pick-arity '(("x")) 5) :to-be nil)))
+
+(describe "neat--lispy-highlight-arglist"
+  (it "highlights the correct param in a single arity"
+    (let ((out (neat--lispy-highlight-arglist "[f coll]" 1)))
+      (expect (substring-no-properties out) :to-equal "[f coll]")
+      (expect (get-text-property (+ (length "[f ") (- (length "coll") 1))
+                                 'face out)
+              :to-equal 'eldoc-highlight-function-argument)))
+
+  (it "highlights the rest param when past the variadic marker"
+    (let ((out (neat--lispy-highlight-arglist "[x & rest]" 3)))
+      (expect (substring-no-properties out) :to-equal "[x & rest]")
+      ;; The `rest' token should carry the highlight face.
+      (expect (get-text-property (+ (length "[x & ") 0) 'face out)
+              :to-equal 'eldoc-highlight-function-argument)))
+
+  (it "falls back to the raw string when parsing fails"
+    (expect (neat--lispy-highlight-arglist "[{:keys [a]} c]" 0)
+            :to-equal "[{:keys [a]} c]"))
+
+  (it "falls back to the raw string when ARG-INDEX is nil"
+    (expect (neat--lispy-highlight-arglist "[a b]" nil)
+            :to-equal "[a b]")))
+
 (provide 'neat-test)
 ;;; neat-test.el ends here