Cleanup old helpful buffers0.5

Define helpful-max-buffers as a compromise between 'keep everything'
and 'cleanup immediately', allowing users to decide how many helpful
buffers they want to keep around.

Fixes #66

2 files changed, 46 insertions, 2 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f2ef499..6f30d42 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,11 @@ highlights which aliases are obsolete.
 Improved helpful performance for primitives when Emacs source code is
 loaded.
 
+Helpful will now only keep the last 5 buffers, to avoid cluttering
+your buffer list. You can customise this behaviour with
+`helpful-max-buffers`: set it to 1 to cleanup all previous buffers, or
+set it to `nil` never cleanup buffers.
+
 ## recentf bug
 
 Helpful had an issue where it would call find-file with propertized
diff --git a/helpful.el b/helpful.el
index b6438b4..aecb3df 100644
--- a/helpful.el
+++ b/helpful.el
@@ -6,7 +6,7 @@
 ;; URL: https://github.com/Wilfred/helpful
 ;; Keywords: help, lisp
 ;; Version: 0.5
-;; Package-Requires: ((emacs "25.1") (dash "2.12.0") (s "1.11.0") (elisp-refs "1.2") (shut-up "0.3"))
+;; Package-Requires: ((emacs "25.1") (dash "2.12.0") (dash-functional "1.2.0") (s "1.11.0") (elisp-refs "1.2") (shut-up "0.3"))
 
 ;; This program is free software; you can redistribute it and/or modify
 ;; it under the terms of the GNU General Public License as published by
@@ -45,6 +45,7 @@
 (require 'elisp-refs)
 (require 'help)
 (require 'dash)
+(require 'dash-functional)
 (require 's)
 (require 'shut-up)
 (require 'find-func)
@@ -52,6 +53,7 @@
 (require 'info-look)
 (require 'edebug)
 (require 'trace)
+(require 'ring)
 
 (defvar-local helpful--sym nil)
 (defvar-local helpful--callable-p nil)
@@ -59,6 +61,23 @@
   "We store a reference to the buffer we were called from, so we can
 show the value of buffer-local variables.")
 
+(defgroup helpful nil
+  "A rich help system with contextual information.")
+
+(defcustom helpful-max-buffers
+  5
+  "Helpful will kill the oldest helpful buffer if there are
+more than this many.
+
+To disable cleanup entirely, set this variable to nil. See also
+`helpful-kill-buffers' for a one-off cleanup."
+  :group 'help
+  :type '(choice (const nil) number)
+  :group 'helpful)
+
+(defvar helpful--buffers (make-ring helpful-max-buffers)
+  "Buffers created by helpful.")
+
 (defun helpful--kind-name (symbol callable-p)
   "Describe what kind of symbol this is."
   (cond
@@ -68,6 +87,12 @@ show the value of buffer-local variables.")
    ((functionp symbol) "function")
    ((special-form-p symbol) "special form")))
 
+(defun helpful--ring-remove-if (ring predicate)
+  "Remove items from RING where PREDICATE returns non-nil."
+  (dolist (i (number-sequence (1- (ring-length ring)) 0 -1))
+    (when (funcall predicate (ring-ref ring i))
+      (ring-remove ring i))))
+
 (defun helpful--buffer (symbol callable-p)
   "Return a buffer to show help for SYMBOL in."
   (let ((current-buffer (current-buffer))
@@ -75,11 +100,23 @@ show the value of buffer-local variables.")
               (format "*helpful %s: %s*"
                       (helpful--kind-name symbol callable-p)
                       symbol))))
+    ;; Initialise the buffer with the symbol and associated data.
     (with-current-buffer buf
       (helpful-mode)
       (setq helpful--sym symbol)
       (setq helpful--callable-p callable-p)
       (setq helpful--associated-buffer current-buffer))
+
+    ;; We keep track of buffers that we've created.
+    (ring-insert+extend helpful--buffers buf t)
+
+    ;; Clear out any buffers that the user has explicitly killed.
+    (helpful--ring-remove-if helpful--buffers (-not #'buffer-live-p))
+
+    (unless (null helpful-max-buffers)
+      ;; If we have too many buffers, kill the oldest buffers.
+      (while (> (ring-length helpful--buffers) helpful-max-buffers)
+        (kill-buffer (ring-remove helpful--buffers))))
     buf))
 
 (defun helpful--heading (text)
@@ -1359,7 +1396,9 @@ See also `helpful-callable' and `helpful-variable'."
   (helpful--forward-button -1))
 
 (defun helpful-kill-buffers ()
-  "Kill all `helpful-mode' buffers."
+  "Kill all `helpful-mode' buffers.
+
+See also `helpful-max-buffers'."
   (interactive)
   (dolist (buffer (buffer-list))
     (when (eq (buffer-local-value 'major-mode buffer) 'helpful-mode)