feat(logging): introduce log levels info and debug

Adds debug logging for refreshing stateful segments.

CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Changed
+
+- `whale-line-log` is now either `nil`, `0`, or `1`. The numbers
+  represent log levels.
+
 ## [v0.8.1]
 
 ### Added

test/whale-line-test.el

@@ -575,10 +575,13 @@
 
     (bydi ((:spy whale-line-a--action)
            (:spy whale-line-b--action)
-           (:spy whale-line-c--action))
+           (:spy whale-line-c--action)
+           whale-line-debug)
 
       (whale-line--refresh-stateful-segments)
 
+      (bydi-was-called whale-line-debug)
+
       (bydi-was-called whale-line-a--action)
       (bydi-was-not-called whale-line-b--action)
       (bydi-was-called whale-line-c--action))))
@@ -715,7 +718,7 @@
          "Set up test segment."
          (unless (memq 'test whale-line-segments)
            (cl-return-from whale-line-test--setup))
-         (whale-line--log "Setting up test (%s)" (whale-line--prop 'test :type))
+         (whale-line-log "Setting up `test' (%s)" (whale-line--prop 'test :type))
          (add-hook 'first-hook #'whale-line-test--action)
          (add-hook 'second-hook #'whale-line-test--action)
          (advice-add 'one :after #'whale-line-test--action)
@@ -728,7 +731,7 @@
          "Tear down test segment."
          (unless (memq 'test whale-line-segments)
            (cl-return-from whale-line-test--teardown))
-         (whale-line--log "Tearing down test (%s)" (whale-line--prop 'test :type))
+         (whale-line-log "Tearing down `test' (%s)" (whale-line--prop 'test :type))
          (remove-hook 'first-hook #'whale-line-test--action)
          (remove-hook 'second-hook #'whale-line-test--action)
          (advice-remove 'one #'whale-line-test--action)
@@ -747,15 +750,15 @@
         (unless
             (memq 'test whale-line-segments)
           (cl-return-from whale-line-test--setup))
-        (whale-line--log "Would set up test (%s)" (whale-line--prop 'test :type)))
+        (whale-line-log "Segment `test' (%s) requires no setup" (whale-line--prop 'test :type)))
       (add-hook 'whale-line-setup-hook #'whale-line-test--setup)
       (cl-defun whale-line-test--teardown
           (&rest _)
         "Tear down test segment."
         (unless
             (memq 'test whale-line-segments)
           (cl-return-from whale-line-test--teardown))
-        (whale-line--log "Would tear down test (%s)" (whale-line--prop 'test :type)))
+        (whale-line-log "Segment `test' (%s) requires no teardown" (whale-line--prop 'test :type)))
       (add-hook 'whale-line-teardown-hook #'whale-line-test--teardown))))
 
 (ert-deftest whale-line--setup--early-return ()
@@ -772,7 +775,7 @@
          "Set up test segment."
          (unless (and (not whale-line--rebuilding) (whale-line-test--verify))
            (cl-return-from whale-line-test--setup))
-         (whale-line--log "Setting up test (%s)" (whale-line--prop 'test :type))
+         (whale-line-log "Setting up `test' (%s)" (whale-line--prop 'test :type))
          (add-hook 'first-hook #'whale-line-test--action)
          (add-hook 'second-hook #'whale-line-test--action)
          (advice-add 'one :after #'whale-line-test--action)
@@ -785,7 +788,7 @@
          "Tear down test segment."
          (unless (and (not whale-line--rebuilding) (whale-line-test--verify))
            (cl-return-from whale-line-test--teardown))
-         (whale-line--log "Tearing down test (%s)" (whale-line--prop 'test :type))
+         (whale-line-log "Tearing down `test' (%s)" (whale-line--prop 'test :type))
          (remove-hook 'first-hook #'whale-line-test--action)
          (remove-hook 'second-hook #'whale-line-test--action)
          (advice-remove 'one #'whale-line-test--action)
@@ -805,7 +808,7 @@
          "Set up test segment."
          (unless (memq 'test whale-line-segments)
            (cl-return-from whale-line-test--setup))
-         (whale-line--log "Setting up test (%s)" (whale-line--prop 'test :type))
+         (whale-line-log "Setting up `test' (%s)" (whale-line--prop 'test :type))
          (funcall 'one))
 
        (add-hook 'whale-line-setup-hook #'whale-line-test--setup)
@@ -814,7 +817,7 @@
          "Tear down test segment."
          (unless (memq 'test whale-line-segments)
            (cl-return-from whale-line-test--teardown))
-         (whale-line--log "Tearing down test (%s)" (whale-line--prop 'test :type))
+         (whale-line-log "Tearing down `test' (%s)" (whale-line--prop 'test :type))
          (funcall 'two))
        (add-hook 'whale-line-teardown-hook #'whale-line-test--teardown)))))
 
@@ -844,19 +847,19 @@
 
       (bydi-was-called-with run-hooks 'whale-line-teardown-hook))))
 
-(ert-deftest whale-line--log--formats ()
+(ert-deftest whale-line-log--formats ()
   (let ((whale-line-log nil))
 
-    (whale-line--log "This is a %s" "test")
+    (whale-line-log "This is a %s" "test")
 
-    (should-not (get-buffer whale-line--log-buffer-name))
+    (should-not (get-buffer whale-line-log--buffer-name))
 
-    (setq whale-line-log t)
+    (setq whale-line-log 0)
 
-    (whale-line--log "This is the %s message" "first")
-    (whale-line--log "This %s the %s message" "will be" "second")
+    (whale-line-log "This is the %s message" "first")
+    (whale-line-debug "This %s the %s message" "will be" "second")
 
-    (with-current-buffer (get-buffer whale-line--log-buffer-name)
+    (with-current-buffer (get-buffer whale-line-log--buffer-name)
       (should (string= (buffer-string)
                        "This is the first message\nThis will be the second message\n")))))
 
@@ -865,24 +868,24 @@
         (whale-line--last-build nil))
 
     (shut-up
-      (bydi (whale-line--log)
+      (bydi (whale-line-log)
 
         (ert-with-message-capture messages
 
           (whale-line--handle-build-difference)
 
-          (bydi-was-not-called whale-line--log)
+          (bydi-was-not-called whale-line-log)
 
           (whale-line--handle-build-difference)
 
-          (bydi-was-not-called whale-line--log)
+          (bydi-was-not-called whale-line-log)
 
           (setq whale-line-segments '(two four))
 
           (whale-line--handle-build-difference)
 
-          (bydi-was-called-nth-with whale-line--log '("Added segment(s) %s since last build" (four)) 0)
-          (bydi-was-called-nth-with whale-line--log '("Removed segment(s) %s since last build" (one three)) 1))))))
+          (bydi-was-called-nth-with whale-line-log '("Added segment(s) %s since last build" (four)) 0)
+          (bydi-was-called-nth-with whale-line-log '("Removed segment(s) %s since last build" (one three)) 1))))))
 
 (ert-deftest whale-line--normalize-list ()
   (should (equal (whale-line--normalize-list '(test))
@@ -947,15 +950,16 @@
     (bydi-was-called whale-line--trigger-augments)))
 
 (ert-deftest whale-line--pop-to-logs ()
-  (bydi (pop-to-buffer)
-    (whale-line--log "Make sure it exists")
+  (let ((whale-line-log 0))
+    (bydi (pop-to-buffer)
+      (whale-line-log "Make sure it exists")
 
-    (whale-line-pop-to-logs)
-    (bydi-was-called pop-to-buffer)
+      (whale-line-pop-to-logs)
+      (bydi-was-called pop-to-buffer)
 
-    (kill-buffer whale-line--log-buffer-name)
+      (kill-buffer whale-line-log--buffer-name)
 
-    (should-error (whale-line-pop-to-logs))))
+      (should-error (whale-line-pop-to-logs)))))
 
 ;;; whale-line-test.el ends here
 

whale-line.el

@@ -68,9 +68,14 @@ constraints."
                  (const ignore)))
 
 (defcustom whale-line-log nil
-  "Whether to log."
+  "Log level (or whether to log at all).
+
+This is either nil meaning on logs, or integers 1 or 0 for info
+and debug logging respectively."
   :group 'whale-line
-  :type 'boolean)
+  :type '(choice (const :tag "No logging" nil)
+                 (const :tag "Info logging" 1)
+                 (const :tag "Debug logging" 0)))
 
 ;;; -- Variables
 
@@ -273,15 +278,15 @@ This uses `string-pixel-width' for Emacs 29+, otherwise
           (removed (cl-set-difference whale-line--last-build whale-line-segments)))
 
       (when added
-        (whale-line--log "Added segment(s) %s since last build" added)
+        (whale-line-log "Added segment(s) %s since last build" added)
 
         (let ((whale-line--rebuilding t)
               (whale-line-segments added))
 
           (run-hooks 'whale-line-setup-hook)))
 
       (when removed
-        (whale-line--log "Removed segment(s) %s since last build" removed)
+        (whale-line-log "Removed segment(s) %s since last build" removed)
 
         (let ((whale-line--rebuilding t)
               (whale-line-segments removed))
@@ -314,6 +319,8 @@ This uses `string-pixel-width' for Emacs 29+, otherwise
 Sets up augments. If ARG is t tears them down instead."
   (let ((whale-line-segments (whale-line--segments-by-type 'augment)))
 
+    (whale-line-debug "Running %ss for augments" (if arg "teardown" "setup"))
+
     (if arg
         (run-hooks 'whale-line-teardown-hook)
       (run-hooks 'whale-line-setup-hook))))
@@ -416,9 +423,9 @@ return early."
                                               `(funcall ',setup)
                                             `(funcall ,setup))))))
 
-                  (log (if setups `(whale-line--log ,(format "Setting up %s (%%s)" name)
+                  (log (if setups `(whale-line-log ,(format "Setting up `%s' (%%s)" name)
                                                     (whale-line--prop ',name :type))
-                         `(whale-line--log ,(format "Would set up %s (%%s)" name)
+                         `(whale-line-log ,(format "Segment `%s' (%%s) requires no setup" name)
                                            (whale-line--prop ',name :type)))))
 
              (if setups
@@ -447,9 +454,9 @@ return early."
                                    (if (symbolp teardown)
                                        `(funcall ',teardown)
                                      `(funcall ,teardown))))))
-                  (log (if teardowns `(whale-line--log ,(format "Tearing down %s (%%s)" name)
+                  (log (if teardowns `(whale-line-log ,(format "Tearing down `%s' (%%s)" name)
                                                        (whale-line--prop ',name :type))
-                         `(whale-line--log ,(format "Would tear down %s (%%s)" name)
+                         `(whale-line-log ,(format "Segment `%s' (%%s) requires no teardown" name)
                                            (whale-line--prop ',name :type)))))
              (if teardowns
                  `(,log ,@teardowns)
@@ -886,6 +893,8 @@ This will call the respective segment's action."
   (let* ((interner (lambda (it) (intern-soft (format "whale-line-%s--action" it))))
          (actions (mapcar interner (whale-line--segments-by-type 'stateful))))
 
+    (whale-line-debug "Refreshing stateful segments (%s)" (format-time-string "%H:%M:%S"))
+
     (mapc #'funcall actions)))
 
 ;;; -- Helpers
@@ -904,23 +913,34 @@ This will call the respective segment's action."
 
 ;;; -- Logging
 
-(defvar whale-line--log-buffer-name " *whale-line*")
+(defvar whale-line-log--buffer-name " *whale-line*")
 
-(defun whale-line--log (fmt &rest args)
+(defun whale-line-log--write (fmt &rest args)
   "Format FMT with ARGS."
-  (when whale-line-log
-    (let ((buffer (get-buffer whale-line--log-buffer-name))
-          (inhibit-read-only t))
-
-      (unless buffer
-        (setq buffer (get-buffer-create whale-line--log-buffer-name))
-        (with-current-buffer buffer
-          (view-mode)))
+  (let ((buffer (get-buffer whale-line-log--buffer-name))
+        (inhibit-read-only t))
 
+    (unless buffer
+      (setq buffer (get-buffer-create whale-line-log--buffer-name))
       (with-current-buffer buffer
-        (goto-char (point-max))
-        (insert (apply #'format fmt args))
-        (insert "\n")))))
+        (view-mode)))
+
+    (with-current-buffer buffer
+      (goto-char (point-max))
+      (insert (apply #'format fmt args))
+      (insert "\n"))))
+
+(defun whale-line-log (fmt &rest args)
+  "Format FMT with ARGS."
+  (when (and (numberp whale-line-log)
+             (>= 1 whale-line-log))
+    (apply #'whale-line-log--write (append (list fmt) args))))
+
+(defun whale-line-debug (fmt &rest args)
+  "Format debug message FMT with ARGS."
+  (when (and (numberp whale-line-log)
+             (>= 0 whale-line-log))
+    (apply #'whale-line-log--write (append (list fmt) args))))
 
 ;;; -- Setup
 
@@ -1013,12 +1033,12 @@ Sets up augments (again). If ARG is t, tears them down instead."
   "Switch to the log buffer."
   (interactive)
 
-  (let ((buffer (get-buffer whale-line--log-buffer-name)))
+  (let ((buffer (get-buffer whale-line-log--buffer-name)))
 
     (unless buffer
-      (user-error "You need to set `harpoon-log' to t first"))
+      (user-error "You need to set `harpoon-log' to 0 or 1 first"))
 
-    (pop-to-buffer (get-buffer whale-line--log-buffer-name))))
+    (pop-to-buffer (get-buffer whale-line-log--buffer-name))))
 
 ;;;###autoload
 (define-minor-mode whale-line-mode