[nongnu] elpa/cider 186b497656: [Fix #3200] Improve browse-ns interface with filters and groupings (#3217)

[ELPA Syncer]

branch: elpa/cider
commit 186b4976565a18fcb00e1685a44a87a8559eadcc
Author: Zachary Romero <zacromero@posteo.net>
Commit: GitHub <noreply@github.com>

    [Fix #3200] Improve browse-ns interface with filters and groupings (#3217)
    
    Major re-work of the browse-ns interface, as well as fixing
    misc bug.
    
    - cider-browse-ns--thing-at-point didn't distinguish a ns without '.'
    - Added helper nrepl-dict-filter to filter entries in a nrepl-dict
    - added grouping feature and corresponding keybindings
    - added filtering features and corresponding keybindings
    - added new local vars to aid in re-displaying buffer
---
 CHANGELOG.md                                    |   1 +
 cider-browse-ns.el                              | 391 +++++++++++++++++++++---
 cider-client.el                                 |   9 +
 cider-debug.el                                  |  21 +-
 doc/modules/ROOT/assets/images/ns_browser.png   | Bin 292793 -> 217749 bytes
 doc/modules/ROOT/pages/usage/misc_features.adoc |  26 ++
 nrepl-dict.el                                   |  12 +
 test/cider-browse-ns-tests.el                   |   7 +-
 8 files changed, 416 insertions(+), 51 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5da369b039..5291ffb405 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,7 @@
 ## Changes
 
 * Upgrade injected `cider-nrepl` to 
[0.28.5](https://github.com/clojure-emacs/cider-nrepl/releases/tag/v0.28.5).
+* [#3200](https://github.com/clojure-emacs/cider/issues/3200): Improve 
cider-browse-ns interface to allow selective hiding of var types as well as 
grouping options.  Include private vars in result list.
 
 ## 1.4.1 (2022-05-25)
 
diff --git a/cider-browse-ns.el b/cider-browse-ns.el
index 8c864cc87c..76e5c05600 100644
--- a/cider-browse-ns.el
+++ b/cider-browse-ns.el
@@ -42,12 +42,41 @@
 
 (require 'subr-x)
 (require 'easymenu)
+(require 'button)
+(require 'cl-lib)
 (require 'thingatpt)
 
+
+(defgroup cider-browse-ns nil
+  "Display contents of namespaces for CIDER."
+  :prefix "cider-browse-ns-"
+  :group 'cider)
+
+(defface cider-browse-ns-extra-info-face
+  '((t (:inherit shadow)))
+  "Face for displaying extra info of namespace vars."
+  :package-version '(cider . "1.4.0"))
+
+(defcustom cider-browse-ns-default-filters nil
+  "List of default hide filters to apply to browse-ns buffer.
+
+Available options include `private', `test', `macro', `function', and
+`var'."
+  :type 'list
+  :package-version '(cider . "1.4.0"))
+
 (defconst cider-browse-ns-buffer "*cider-ns-browser*")
 
 (defvar-local cider-browse-ns-current-ns nil)
 
+(defvar-local cider-browse-ns-filters nil)
+(defvar-local cider-browse-ns-show-all nil)
+(defvar-local cider-browse-ns-group-by nil)
+(defvar-local cider-browse-ns-items nil)
+(defvar-local cider-browse-ns-title nil)
+(defvar-local cider-browse-ns-group-by nil)
+
+
 ;; Mode Definition
 
 (defvar cider-browse-ns-mode-map
@@ -59,6 +88,18 @@
     (define-key map "^" #'cider-browse-ns-all)
     (define-key map "n" #'next-line)
     (define-key map "p" #'previous-line)
+
+    (define-key map "a" #'cider-browse-ns-toggle-all)
+
+    (define-key map (kbd "h p") #'cider-browse-ns-toggle-hide-private)
+    (define-key map (kbd "h t") #'cider-browse-ns-toggle-hide-test)
+    (define-key map (kbd "h m") #'cider-browse-ns-toggle-hide-macro)
+    (define-key map (kbd "h f") #'cider-browse-ns-toggle-hide-function)
+    (define-key map (kbd "h v") #'cider-browse-ns-toggle-hide-var)
+
+    (define-key map (kbd "g t") #'cider-browse-ns-group-by-type)
+    (define-key map (kbd "g v") #'cider-browse-ns-group-by-visibility)
+
     (easy-menu-define cider-browse-ns-mode-menu map
       "Menu for CIDER's namespace browser"
       '("Namespace Browser"
@@ -106,22 +147,256 @@ VAR-META is used to decide a font-lock face."
                 'mouse-face 'highlight
                 'keymap cider-browse-ns-mouse-map)))
 
-(defun cider-browse-ns--list (buffer title items &optional ns noerase)
-  "Reset contents of BUFFER.
-Display TITLE at the top and ITEMS are indented underneath.
-If NS is non-nil, it is added to each item as the
-`cider-browse-ns-current-ns' text property.  If NOERASE is non-nil, the
-contents of the buffer are not reset before inserting TITLE and ITEMS."
+(defun cider-browse-ns--ns-list (buffer title nss)
+  "List the namespaces NSS in BUFFER.
+
+Buffer is rendered with TITLE at the top and lists ITEMS filtered according
+to user settings."
+  (let ((dict (nrepl-dict)))
+    (dolist (ns nss)
+      (nrepl-dict-put dict ns (nrepl-dict "ns" "true")))
+    (cider-browse-ns--list buffer title dict nil)))
+
+(defun cider-browse-ns--list (buffer title items ns)
+  "Initialize rendering of browse-ns BUFFER.
+
+Initialize the buffer's TITLE, namespace NS, and the nrepl-dict ITEMS to be
+displayed."
   (with-current-buffer buffer
     (cider-browse-ns-mode)
-    (let ((inhibit-read-only t))
-      (unless noerase (erase-buffer))
-      (goto-char (point-max))
-      (insert (cider-propertize title 'ns) "\n")
-      (dolist (item items)
-        (insert (propertize (concat "  " item "\n")
-                            'cider-browse-ns-current-ns ns)))
-      (goto-char (point-min)))))
+    (setq-local cider-browse-ns-items items)
+    (setq-local cider-browse-ns-title title)
+    (setq-local cider-browse-ns-filters cider-browse-ns-default-filters)
+    (setq-local cider-browse-ns-current-ns ns))
+  (cider-browse-ns--render-buffer))
+
+(defun cider-browse-ns--meta-macro-p (var-meta)
+  "Return non-nil if VAR-META is the metadata of a macro."
+  (and (nrepl-dict-contains var-meta "arglists")
+       (string= (nrepl-dict-get var-meta "macro") "true")))
+
+(defun cider-browse-ns--meta-test-p (var-meta)
+  "Return non-nil if VAR-META is the metadata of a test."
+  (nrepl-dict-contains var-meta "test"))
+
+(defun cider-browse-ns--meta-function-p (var-meta)
+  "Return non-nil if VAR-META is the metadata of a function."
+  (and (nrepl-dict-contains var-meta "arglists")
+       (not (cider-browse-ns--meta-macro-p var-meta))))
+
+(defun cider-browse-ns--meta-private-p (var-meta)
+  "Return non-nil if VAR-META indicates a private element."
+  (string= (nrepl-dict-get var-meta "private") "true"))
+
+(defun cider-browse-ns--meta-var-p (var-meta)
+  "Return non-nil if VAR-META indicates a var."
+  (not (or (cider-browse-ns--meta-test-p var-meta)
+           (cider-browse-ns--meta-macro-p var-meta)
+           (cider-browse-ns--meta-function-p var-meta))))
+
+(defun cider-browse-ns--item-filter (_ var-meta)
+  "Return non-nil if item containing VAR-META should be listed in buffer."
+  (let ((function-filter-p (memq 'function cider-browse-ns-filters))
+        (var-filter-p (memq 'var cider-browse-ns-filters))
+        (private-filter-p (memq 'private cider-browse-ns-filters))
+        (test-filter-p (memq 'test cider-browse-ns-filters))
+        (macro-filter-p (memq 'macro cider-browse-ns-filters)))
+    ;; check if item should be displayed
+    (let* ((macro-p (cider-browse-ns--meta-macro-p var-meta))
+           (function-p (cider-browse-ns--meta-function-p var-meta))
+           (private-p (cider-browse-ns--meta-private-p var-meta))
+           (test-p (cider-browse-ns--meta-test-p var-meta))
+           (var-p (cider-browse-ns--meta-var-p var-meta)))
+      (or cider-browse-ns-show-all
+          (not (or (and macro-p macro-filter-p)
+                   (and function-p function-filter-p)
+                   (and test-p test-filter-p)
+                   (and var-p var-filter-p)
+                   (and private-p private-filter-p)))))))
+
+(defun cider-browse-ns--propertized-item (key items)
+  "Return propertized line of item KEY in nrepl-dict ITEMS."
+  (let* ((var-meta (nrepl-dict-get items key))
+         (face (cider-browse-ns--text-face (nrepl-dict-get items key)))
+         (private-p (string= (nrepl-dict-get var-meta "private") "true"))
+         (test-p (nrepl-dict-contains var-meta "test"))
+         (ns-p (nrepl-dict-contains var-meta "ns")))
+    (concat
+     (propertize key
+                 'font-lock-face face
+                 'ns ns-p)
+     " "
+     (cond
+      (test-p (propertize "(test) " 'face 'cider-browse-ns-extra-info-face))
+      (private-p (propertize "(-) " 'face 'cider-browse-ns-extra-info-face))
+      (t "")))))
+
+(defun cider-browse-ns--display-list (keys items max-length &optional label)
+  "Render the items of KEYS as condained in the nrepl-dict ITEMS.
+
+Pad the row to be MAX-LENGTH+1.  If LABEL is non-nil, add a header to the
+list of items."
+  (when keys
+    (when label
+      (insert "  " label ":\n"))
+    (dolist (key keys)
+      (let* ((doc (nrepl-dict-get-in items (list key "doc")))
+             (doc (when doc (read doc)))
+             (first-doc-line (cider-browse-ns--first-doc-line doc))
+             (item-line (cider-browse-ns--propertized-item key items)))
+        (insert "  ")
+        (insert item-line)
+        (when cider-browse-ns-current-ns
+          (insert (make-string (+ (- max-length (string-width item-line)) 1) 
?·))
+          (insert " " (propertize first-doc-line 'font-lock-face 
'font-lock-doc-face)))
+        (insert "\n")))
+    (insert "\n")))
+
+(defun cider-browse-ns--column-width (items)
+  "Determine the display width of displayed ITEMS."
+  (let* ((propertized-lines
+          (seq-map (lambda (key)
+                     (cider-browse-ns--propertized-item key items))
+                   (nrepl-dict-keys items))))
+    (if propertized-lines
+        (apply #'max (seq-map (lambda (entry) (string-width entry))
+                              propertized-lines))
+      0)))
+
+(defun cider-browse-ns--render-items (items)
+  "Render the nrepl-dict ITEMS to the browse-ns buffer."
+  (let* ((max-length (cider-browse-ns--column-width items)))
+    (cl-labels
+        ((keys-from-pred
+          (pred items)
+          (nrepl-dict-keys (nrepl-dict-filter (lambda (_ var-meta)
+                                                (funcall pred var-meta))
+                                              items))))
+      (cond
+       ((eql cider-browse-ns-group-by 'type)
+        (let* ((func-keys (keys-from-pred #'cider-browse-ns--meta-function-p 
items))
+               (macro-keys (keys-from-pred #'cider-browse-ns--meta-macro-p 
items))
+               (var-keys (keys-from-pred #'cider-browse-ns--meta-var-p items))
+               (test-keys (keys-from-pred #'cider-browse-ns--meta-test-p 
items)))
+          (cider-browse-ns--display-list func-keys items max-length 
"Functions")
+          (cider-browse-ns--display-list macro-keys items max-length "Macros")
+          (cider-browse-ns--display-list var-keys items max-length "Vars")
+          (cider-browse-ns--display-list test-keys items max-length "Tests")))
+       ((eql cider-browse-ns-group-by 'visibility)
+        (let* ((public-keys
+                (keys-from-pred
+                 (lambda (var-meta)
+                   (not (cider-browse-ns--meta-private-p var-meta)))
+                 items))
+               (private-keys (keys-from-pred #'cider-browse-ns--meta-private-p 
items)))
+          (cider-browse-ns--display-list public-keys items max-length "Public")
+          (cider-browse-ns--display-list private-keys items max-length 
"Private")))
+       (t
+        (cider-browse-ns--display-list
+         (nrepl-dict-keys items) items max-length))))))
+
+(defun cider-browse-ns--filter (flag)
+  "Toggle the filter indicated by FLAG and re-render the buffer."
+  (setq cider-browse-ns-filters
+        (if (memq flag cider-browse-ns-filters)
+            (remq flag cider-browse-ns-filters)
+          (cons flag cider-browse-ns-filters)))
+  (cider-browse-ns--render-buffer))
+
+(defun cider-browse-ns--button-filter (button)
+  "Handle filter action for BUTTON."
+  (let ((flag (button-get button 'filter)))
+    (cider-browse-ns--filter flag)))
+
+(defun cider-browse-ns--group (flag)
+  "Set the group-by option to FLAG and re-renderthe buffer."
+  (setq cider-browse-ns-group-by
+        (if (eql flag cider-browse-ns-group-by) nil flag))
+  (cider-browse-ns--render-buffer))
+
+(defun cider-browse-ns--button-group (button)
+  "Handle grouping action for BUTTON."
+  (let ((flag (button-get button 'group-by)))
+    (cider-browse-ns--group flag)))
+
+(defun cider-browse-ns--toggle-all (_button)
+  "Toggle the display-all visibility setting."
+  (setq cider-browse-ns-show-all (not cider-browse-ns-show-all))
+  (cider-browse-ns--render-buffer))
+
+(defun cider-browse-ns--render-header (&optional filtered-items-ct)
+  "Render the section at the top of the buffer displaying visibility controls.
+
+If FILTERED-ITEMS-CT is non-nil, then display a message of how many items
+are being filtered."
+  ;; Display Show line
+  (insert "  Show: ")
+  (insert-text-button "All"
+                      'follow-link t
+                      'action #'cider-browse-ns--toggle-all
+                      ;; 'help-echo (cider-stacktrace-tooltip)
+                      'face (if cider-browse-ns-show-all
+                                'cider-stacktrace-filter-active-face
+                              nil))
+  (insert "\n")
+  ;; Display Filters
+  (let ((filters '(("Private" private)
+                   ("Test" test)
+                   ("Macro" macro)
+                   ("Function" function)
+                   ("Var" var))))
+    (insert "  Hide: ")
+    (dolist (filter filters)
+      (seq-let (title key) filter
+        (let ((is-active (memq key cider-browse-ns-filters)))
+          (insert-text-button title
+                              'filter key
+                              'follow-link t
+                              'action #'cider-browse-ns--button-filter
+                              ;; 'help-echo (cider-stacktrace-tooltip)
+                              'face (if (and is-active (not 
cider-browse-ns-show-all))
+                                        'cider-stacktrace-filter-active-face
+                                      nil))
+          (insert " "))))
+    (when filtered-items-ct
+      (insert (format "(%d items filtered)" filtered-items-ct))))
+  (insert "\n")
+  ;; Groupings
+  (insert "  Group-by: ")
+  (let ((groupings '(("Type" type)
+                     ("Visibility" visibility))))
+    (dolist (grouping groupings)
+      (seq-let (title key) grouping
+        (let ((is-active (eql key cider-browse-ns-group-by)))
+          (insert-text-button title
+                              'group-by key
+                              'follow-link t
+                              'action #'cider-browse-ns--button-group
+                              ;; 'help-echo ()
+                              'face (if is-active
+                                        'cider-stacktrace-filter-active-face
+                                      nil)))
+        (insert " "))))
+  (insert "\n\n"))
+
+(defun cider-browse-ns--render-buffer (&optional buffer)
+  "Render the sections of the browse-ns buffer.
+
+Render occurs in BUFFER if non-nil.  This function is the main entrypoint
+for redisplaying the buffer when filters change."
+  (with-current-buffer (or buffer (current-buffer))
+    (let* ((inhibit-read-only t)
+           (point (point))
+           (filtered-items (nrepl-dict-filter #'cider-browse-ns--item-filter
+                                              cider-browse-ns-items))
+           (filtered-item-ct (- (length (nrepl-dict-keys 
cider-browse-ns-items))
+                                (length (nrepl-dict-keys filtered-items)))))
+      (erase-buffer)
+      (insert (propertize (cider-propertize cider-browse-ns-title 'ns) 'ns t) 
"\n")
+      (when cider-browse-ns-current-ns
+        (cider-browse-ns--render-header filtered-item-ct))
+      (cider-browse-ns--render-items filtered-items)
+      (goto-char point))))
 
 (defun cider-browse-ns--first-doc-line (doc)
   "Return the first line of the given DOC string.
@@ -137,19 +412,19 @@ string is returned."
          (t (concat first-line "..."))))
     "Not documented."))
 
-(defun cider-browse-ns--items (namespace)
-  "Return the items to show in the namespace browser of the given NAMESPACE.
-Each item consists of a ns-var and the first line of its docstring."
-  (let* ((ns-vars-with-meta (cider-sync-request:ns-vars-with-meta namespace))
-         (propertized-ns-vars (nrepl-dict-map #'cider-browse-ns--properties 
ns-vars-with-meta)))
-    (mapcar (lambda (ns-var)
-              (let* ((doc (nrepl-dict-get-in ns-vars-with-meta (list ns-var 
"doc")))
-                     ;; to avoid (read nil)
-                     ;; it prompts the user for a Lisp expression
-                     (doc (when doc (read doc)))
-                     (first-doc-line (cider-browse-ns--first-doc-line doc)))
-                (concat ns-var " " (propertize first-doc-line 'font-lock-face 
'font-lock-doc-face))))
-            propertized-ns-vars)))
+(defun cider-browse-ns--combined-vars-with-meta (namespace)
+  "Return the combined public and private vars in NAMESPACE.
+
+Private vars have the additional metadata \"private\": \"true\" in their
+var-meta map."
+  (let ((items (cider-sync-request:ns-vars-with-meta namespace))
+        (private-items (cider-sync-request:private-ns-vars-with-meta 
namespace)))
+    (when private-items
+      (dolist (key (nrepl-dict-keys private-items))
+        (let ((var-meta (nrepl-dict-put (nrepl-dict-get private-items key)
+                                        "private" "true")))
+          (setq items (nrepl-dict-put items key var-meta)))))
+    items))
 
 ;; Interactive Functions
 
@@ -160,8 +435,8 @@ Each item consists of a ns-var and the first line of its 
docstring."
   (with-current-buffer (cider-popup-buffer cider-browse-ns-buffer 'select nil 
'ancillary)
     (cider-browse-ns--list (current-buffer)
                            namespace
-                           (cider-browse-ns--items namespace))
-    (setq-local cider-browse-ns-current-ns namespace)))
+                           (cider-browse-ns--combined-vars-with-meta namespace)
+                           namespace)))
 
 ;;;###autoload
 (defun cider-browse-ns-all ()
@@ -169,24 +444,66 @@ Each item consists of a ns-var and the first line of its 
docstring."
   (interactive)
   (with-current-buffer (cider-popup-buffer cider-browse-ns-buffer 'select nil 
'ancillary)
     (let ((names (cider-sync-request:ns-list)))
-      (cider-browse-ns--list (current-buffer)
-                             "All loaded namespaces"
-                             (mapcar (lambda (name)
-                                       (cider-browse-ns--properties name nil))
-                                     names))
-      (setq-local cider-browse-ns-current-ns nil))))
+      (cider-browse-ns--ns-list
+       (current-buffer)
+       "All loaded namespaces"
+       (mapcar (lambda (name)
+                 (cider-browse-ns--properties name nil))
+               names)))))
 
 (defun cider-browse-ns--thing-at-point ()
   "Get the thing at point.
 Return a list of the type ('ns or 'var) and the value."
-  (let ((line (car (split-string (string-trim (thing-at-point 'line)) " "))))
-    (if (string-match "\\." line)
+  (let ((ns-p (get-text-property (point) 'ns))
+        (line (car (split-string (string-trim (thing-at-point 'line)) " "))))
+    (if (or ns-p (string-match "\\." line))
         `(ns ,line)
       `(var ,(format "%s/%s"
                      (or (get-text-property (point) 
'cider-browse-ns-current-ns)
                          cider-browse-ns-current-ns)
                      line)))))
 
+(defun cider-browse-ns-toggle-all ()
+  "Toggle showing all of the items in the browse-ns buffer."
+  (interactive)
+  (cider-browse-ns--toggle-all nil))
+
+(defun cider-browse-ns-toggle-hide-private ()
+  "Toggle visibility of private items displayed in browse-ns buffer."
+  (interactive)
+  (cider-browse-ns--filter 'private))
+
+(defun cider-browse-ns-toggle-hide-test ()
+  "Toggle visibility of test items displayed in browse-ns buffer."
+  (interactive)
+  (cider-browse-ns--filter 'test))
+
+(defun cider-browse-ns-toggle-hide-macro ()
+  "Toggle visibility of macro items displayed in browse-ns buffer."
+  (interactive)
+  (cider-browse-ns--filter 'macro))
+
+(defun cider-browse-ns-toggle-hide-function ()
+  "Toggle visibility of function items displayed in browse-ns buffer."
+  (interactive)
+  (cider-browse-ns--filter 'function))
+
+(defun cider-browse-ns-toggle-hide-var ()
+  "Toggle visibility of var items displayed in browse-ns buffer."
+  (interactive)
+  (cider-browse-ns--filter 'var))
+
+(defun cider-browse-ns-group-by-type ()
+  "Toggle visibility of var items displayed in browse-ns buffer."
+  (interactive)
+  (cider-browse-ns--group 'type))
+
+(defun cider-browse-ns-group-by-visibility ()
+  "Toggle visibility of var items displayed in browse-ns buffer."
+  (interactive)
+  (cider-browse-ns--group 'visibility))
+
+
 (declare-function cider-doc-lookup "cider-doc")
 
 (defun cider-browse-ns-doc-at-point ()
diff --git a/cider-client.el b/cider-client.el
index a8c159955f..d4b8832896 100644
--- a/cider-client.el
+++ b/cider-client.el
@@ -743,6 +743,15 @@ returned."
                 (cider-nrepl-send-sync-request)
                 (nrepl-dict-get "ns-vars-with-meta")))
 
+(defun cider-sync-request:private-ns-vars-with-meta (ns)
+  "Get a map of the vars in NS to its metadata information."
+  (thread-first `("op" "ns-vars-with-meta"
+                  "ns" ,ns
+                  "var-query" ,(nrepl-dict "private?" "t"
+                                           "include-meta-key" '("private")))
+                (cider-nrepl-send-sync-request)
+                (nrepl-dict-get "ns-vars-with-meta")))
+
 (defun cider-sync-request:ns-load-all ()
   "Load all project namespaces."
   (thread-first '("op" "ns-load-all")
diff --git a/cider-debug.el b/cider-debug.el
index cc6b1bc3b1..e846d71e85 100644
--- a/cider-debug.el
+++ b/cider-debug.el
@@ -103,6 +103,8 @@ configure `cider-debug-prompt' instead."
 
 
 ;;; Implementation
+(declare-function cider-browse-ns--combined-vars-with-meta "cider-browse-ns")
+
 (defun cider-browse-instrumented-defs ()
   "List all instrumented definitions."
   (interactive)
@@ -110,22 +112,15 @@ configure `cider-debug-prompt' instead."
                                (nrepl-dict-get "list"))))
       (with-current-buffer (cider-popup-buffer cider-browse-ns-buffer t)
         (let ((inhibit-read-only t))
-          (erase-buffer)
           (dolist (list all)
             (let* ((ns (car list))
-                   (ns-vars-with-meta (cider-sync-request:ns-vars-with-meta 
ns))
-                   ;; seq of metadata maps of the instrumented vars
-                   (instrumented-meta (mapcar (apply-partially 
#'nrepl-dict-get ns-vars-with-meta)
-                                              (cdr list))))
+                   (ns-vars-with-meta 
(cider-browse-ns--combined-vars-with-meta ns))
+                   (instrumented-meta (nrepl-dict-filter (lambda (k _)
+                                                           (member k list))
+                                                         ns-vars-with-meta)))
               (cider-browse-ns--list (current-buffer) ns
-                                     (seq-mapn #'cider-browse-ns--properties
-                                               (cdr list)
-                                               instrumented-meta)
-
-                                     ns 'noerase)
-              (goto-char (point-max))
-              (insert "\n"))))
-        (goto-char (point-min)))
+                                     instrumented-meta
+                                     ns)))))
     (message "No currently instrumented definitions")))
 
 (defun cider--debug-response-handler (response)
diff --git a/doc/modules/ROOT/assets/images/ns_browser.png 
b/doc/modules/ROOT/assets/images/ns_browser.png
index bd8d7438d2..2c5ac4c7c5 100644
Binary files a/doc/modules/ROOT/assets/images/ns_browser.png and 
b/doc/modules/ROOT/assets/images/ns_browser.png differ
diff --git a/doc/modules/ROOT/pages/usage/misc_features.adoc 
b/doc/modules/ROOT/pages/usage/misc_features.adoc
index 1f8ddd4b00..607b2952cf 100644
--- a/doc/modules/ROOT/pages/usage/misc_features.adoc
+++ b/doc/modules/ROOT/pages/usage/misc_features.adoc
@@ -224,6 +224,11 @@ image::ns_browser.png[Namespace Browser]
 You can also browse all available namespaces with kbd:[M-x]
 `cider-browse-ns-all`.
 
+The UI contains buttons in the header which allow you to control how
+the buffer is displayed (see below for keybindings).  You may also
+configure the `cider-browse-ns-default-filters` variable to a list of
+the element types you want to be hidden by default.
+
 There are a bunch of useful keybindings that are defined in browser buffers.
 
 |===
@@ -244,6 +249,27 @@ There are a bunch of useful keybindings that are defined 
in browser buffers.
 | kbd:[n]
 | Go to next line.
 
+| kbd:[h p]
+| Toggle visibility of private items.
+
+| kbd:[h t]
+| Toggle visibility of tests.
+
+| kbd:[h m]
+| Toggle visibility of macros.
+
+| kbd:[h f]
+| Toggle visibility of functions.
+
+| kbd:[h v]
+| Toggle visibility of vars.
+
+| kbd:[g t]
+| Group items by type (function, macro, var, etc.).
+
+| kbd:[g v]
+| Group items by visibility (public vs. private).
+
 | kbd:[p]
 | Go to previous line.
 |===
diff --git a/nrepl-dict.el b/nrepl-dict.el
index 2d82c2ea8c..8db5a772ed 100644
--- a/nrepl-dict.el
+++ b/nrepl-dict.el
@@ -128,6 +128,18 @@ also always return a sequence (since the result will be 
flattened)."
   (when dict
     (apply #'append (nrepl-dict-map function dict))))
 
+(defun nrepl-dict-filter (function dict)
+  "For all key-values of DICT, return new dict where FUNCTION returns non-nil.
+
+FUNCTION should be a function taking two arguments, key and value."
+  (let ((new-map (nrepl-dict))
+        (keys (nrepl-dict-keys dict)))
+    (dolist (key keys)
+      (let ((val (nrepl-dict-get dict key)))
+        (when (funcall function key val)
+          (nrepl-dict-put new-map key val))))
+    new-map))
+
 
 ;;; More specific functions
 (defun nrepl--cons (car list-or-dict)
diff --git a/test/cider-browse-ns-tests.el b/test/cider-browse-ns-tests.el
index 13775a2ab1..854df69258 100644
--- a/test/cider-browse-ns-tests.el
+++ b/test/cider-browse-ns-tests.el
@@ -50,6 +50,7 @@
             '(dict "blank?"
                    (dict "arglists" "fn arg list"
                          "doc" "\"True if s is nil, empty, or contains only 
whitespace.\"")))
+    (spy-on 'cider-sync-request:private-ns-vars-with-meta :and-return-value 
'(dict))
 
     (with-temp-buffer
       (setq cider-browse-ns-buffer (buffer-name (current-buffer)))
@@ -59,7 +60,11 @@
       (search-forward "blank")
       (expect (get-text-property (point) 'font-lock-face) :to-equal 
'font-lock-function-name-face)
       (search-forward "True")
-      (expect (get-text-property (point) 'font-lock-face) :to-equal 
'font-lock-doc-face))))
+      (expect (get-text-property (point) 'font-lock-face) :to-equal 
'font-lock-doc-face)
+      ;; filter out the functions and ensure that blank? doesn't show up
+      (cider-browse-ns-toggle-hide-function)
+      (goto-char (point-min))
+      (expect (not (search-forward "blank" nil t))))))
 
 (describe "cider-browse-ns--first-doc-line"
   (it "returns Not documented if the doc string is missing"