Make different parts of the output configurable by setting user functions

This naming convention denotes “private” functions; however, if we want to introduce more
customization, we should make these available and documented well.

README.md

@@ -10,6 +10,27 @@ You can set the file to be written by customizing `org-clock-waybar-filename`; i
 `$XDG_CACHE_HOME/waybar-current-task.json` (`$XDG_CACHE_HOME` defaults to `$HOME/.cache` on XDG
 compatible systems, like Linux.)
 
+### Quelpa
+
+If you only have [`quelpa`](https://github.com/quelpa/quelpa) installed:
+
+```elisp
+(quelpa
+ '(org-clock-waybar
+   :fetcher git
+   :url "https://gitea.polonkai.eu/gergely/org-clock-waybar.git"))
+```
+
+or, if you have [`quelpa-use-package`](https://github.com/quelpa/quelpa-use-package) installed,
+too:
+
+```elisp
+(quelpa-use-package org-clock-waybar
+  :quelpa (org-clock-waybar
+           :fetcher git
+           :url "https://gitea.polonkai.eu/gergely/org-clock-waybar.git"))
+```
+
 ## Waybar configuration
 
 To add the current task to Waybar, add this snippet to your config:

org-clock-waybar.el

@@ -1,4 +1,5 @@
-;;; org-clock-waybar --- Summary
+;;; ...  -*- lexical-binding: t -*-
+;;; org-clock-waybar.el --- Summary
 
 ;; Copyright (C) 2021 Gergely Polonkai
 
@@ -38,7 +39,7 @@
 
 ;;; Code:
 
-(require 'xdg)
+(require 'xdg nil t)
 (require 'json)
 (require 'org-clock)
 
@@ -47,7 +48,9 @@
   :group 'emacs)
 
 (defcustom org-clock-waybar-filename
-  (expand-file-name "waybar-current-task.json" (xdg-cache-home))
+  (if (fboundp 'xdg-cache-home)
+      (expand-file-name "waybar-current-task.json" (xdg-cache-home))
+    (expand-file-name "~/.cache/waybar-current-task.json"))
   "Name of the file to save task data to."
   :type 'string
   :group 'org-clock-waybar)
@@ -58,78 +61,160 @@
   :type 'string
   :group 'org-clock-waybar)
 
+(defcustom org-clock-waybar-text-function
+  nil
+  "Function to generate the title text.
+
+The function must return a single string.
+When nil, `org-clock-waybar-get-task-title' is used."
+  :type 'function
+  :group 'org-clock-waybar)
+
+(defcustom org-clock-waybar-alt-function
+  nil
+  "Function to generate the alternative text.
+
+The function must return a single string.
+When nil, `org-clock-waybar-get-task-category' is used."
+  :type 'function
+  :group 'org-clock-waybar)
+
+(defcustom org-clock-waybar-class-function
+  nil
+  "Function to generate the class.
+
+The function must either return a string, or a list of strings.
+When nil, `org-clock-waybar-get-tags' is used."
+  :type 'function
+  :group 'org-clock-waybar)
+
+(defcustom org-clock-waybar-tooltip-function
+  nil
+  "Function to generate the tooltip.
+
+The function must return a string.
+When nil, `org-clock-waybar-get-tooltip' is used."
+  :type 'function
+  :group 'org-clock-waybar)
+
+(defcustom org-clock-waybar-percentage-function
+  nil
+  "Function to generate the percentage text.
+
+When nil, the percentage text will be an empty string."
+  :type 'function
+  :group 'org-clock-waybar)
+
 (defconst org-clock-waybar-filename-coding-system
   (if (coding-system-p 'utf-8-emacs)
       'utf-8-emacs
     'emacs-mule)
   "Coding system of the file `org-clock-waybar-filename'.")
 
-(defun org-clock-waybar-tooltip ()
+(defsubst org-clock-waybar-get-task-title ()
+  "Get the title of TASK."
+  (if (org-clocking-p)
+      (substring-no-properties org-clock-current-task)
+    org-clock-waybar-not-clocked-in-text))
+
+(defsubst org-clock-waybar-get-task-category ()
+  "Get the category of TASK."
+  (when (org-clocking-p) (get-text-property 0 'org-category org-clock-current-task)))
+
+(defun org-clock-waybar--list-of-strings-p (object)
+  "Return t if OBJECT is a list of strings."
+  (not (null (delq nil
+                   (mapcar (lambda (x) (and (stringp x) x)) object)))))
+
+(defun org-clock-waybar-get-tooltip ()
   "The default tooltip to send to waybar."
-  (when org-clock-current-task
+  (when (org-clocking-p)
     (let ((clocked-time (org-clock-get-clocked-time)))
       (format "%s: %s (%s)"
-              (org-clock-waybar-alt)
+              (org-clock-waybar-get-task-category)
-              (org-clock-waybar-text)
+              (org-clock-waybar-get-task-title)
               (org-duration-from-minutes clocked-time)))))
 
-(defun org-clock-waybar--get-clocked-task-json (&optional clocking-out)
+(defun org-clock-waybar-get-tags ()
-  "Get the currently clocked-in task’s data as a stringified JSON object.
+  "Get the tags of the currently clocked-in task."
+  (when (org-clocking-p)
+    (or (org-with-point-at org-clock-marker (org-get-tags))
+        "")
+    ))
+
+(defun org-clock-waybar--get-clocked-task-json ()
+  "Get the currently clocked-in task's data as a stringified JSON object.
 
 The output is in JSON format constructed in a way so Waybar can process it.
 If there is no clocked in task, alt becomes empty and text will be set to the
-value of `org-clock-waybar-not-clocked-in-text'.
+value of `org-clock-waybar-not-clocked-in-text'."
-
+  (let* ((text-func (or 'org-clock-waybar-text-function
-If CLOCKING-OUT is non-nil, `org-clock-current-task' will be treated as if it
+                         'org-clock-waybar-get-task-title))
-were nil; this is required because `org-clock-out' calls the hook functions
+         (text (funcall text-func))
-before setting `org-clock-current-task' to nil."
+         (alt-func (or 'org-clock-waybar-alt-function
-  (let* ((task (if clocking-out nil org-clock-current-task))
+                       'org-clock-waybar-get-task-category))
-         (category (when task (get-text-property 0 'org-category task)))
+         (alt (funcall alt-func))
-         (title (when task (substring-no-properties task)))
+         (tooltip-func (or 'org-clock-waybar-tooltip-function
-         (tooltip (org-clock-waybar-tooltip))
+                           'org-clock-waybar-get-tooltip))
+         (tooltip (funcall tooltip-func))
+         (class-func (or 'org-clock-waybar-class-function
+                         'org-clock-waybar-get-tags))
+         (class (funcall class-func))
+         (percentage (when (fboundp 'org-clock-waybar-percentage-function)
+                       (funcall 'org-clock-waybar-percentage-function)))
          (output (json-new-object)))
-    (setq output (json-add-to-object
+    (or (null title)
-                  output
+        (stringp title)
-                  "text"
+        (error "Title must be a string (org-clock-waybar)!"))
-                  (if title
+    (or (null alt)
-                      title
+        (stringp alt)
-                    org-clock-waybar-not-clocked-in-text)))
+        (error "Alt text must be a string (org-clock-waybar)!"))
-    (setq output (json-add-to-object output "alt" (if category category "")))
+    (or (null tooltip)
-    (setq output (json-add-to-object output "tooltip" (if tooltip tooltip "")))
+        (stringp tooltip)
-    (setq output (json-add-to-object output "class" ""))
+        (error "Tooltip must be a string (org-clock-waybar)!"))
-    (setq output (json-add-to-object output "percentage" ""))
+    (or (null class)
+        (stringp class)
+        (org-clock-waybar--list-of-strings-p class)
+        (error "Class must be a string or a list of strings (org-clock-waybar)!"))
+    (or (null percentage)
+        (stringp percentage)
+        (error "Percentage must be a string (org-clock-waybar)!"))
+    (setq output (json-add-to-object output "text" (or text "")))
+    (setq output (json-add-to-object output "alt" (or alt "")))
+    (setq output (json-add-to-object output "tooltip" (or tooltip "")))
+    (setq output (json-add-to-object output "class" (or class "")))
+    (setq output (json-add-to-object output "percentage" (or percentage "")))
     (json-encode output)))
 
-(defun org-clock-waybar-save-task (&optional clocking-out)
+(defun org-clock-waybar-save-task ()
-  "Save the current clocked in task to `org-clock-waybar-filename'.
+  "Save the current clocked in task to `org-clock-waybar-filename'."
-
-If CLOCKING-OUT is non-nil, treat the current task as if it were nil."
   (with-temp-buffer
     (erase-buffer)
     (set-buffer-file-coding-system org-clock-waybar-filename-coding-system)
-    (insert (org-clock-waybar--get-clocked-task-json clocking-out))
+    (insert (org-clock-waybar--get-clocked-task-json))
     (write-file org-clock-waybar-filename)))
 
-(defun org-clock-waybar-clear-task ()
+(defun org-clock-waybar-output-task ()
-  "Clear the current task from `org-clock-waybar-filename'."
-  (org-clock-waybar-save-task t))
-
-(defun org-clock-waybar-ouptut-task ()
   "Output the current task in JSON format Waybar can understand.
 
 This function is ought to be used via Emacsclient:
 
 emacsclient --eval '(org-clock-waybar-output-task)'"
-  (org-clock-waybar--get-clocked-task-json))
+  (let* ((output (org-clock-waybar--get-clocked-task-json))
+         (start 0)
+         (end (length output)))
+    (set-text-properties start end nil output)
+    output))
 
 (defun org-clock-waybar-setup ()
   "Setup org-clock-waybar.
 
 It adds `org-clock-waybar-save-task' to both `org-clock-in-hook' and
 `org-clock-out-hook'."
+  (add-hook 'org-clock-cancel-hook #'org-clock-waybar-save-task)
   (add-hook 'org-clock-in-hook #'org-clock-waybar-save-task)
-  (add-hook 'org-clock-out-hook #'org-clock-waybar-task)
+  (add-hook 'org-clock-out-hook #'org-clock-waybar-save-task)
-  (add-hook 'kill-emacs-hook #'org-clock-waybar-clear-task))
+  (add-hook 'kill-emacs-hook #'org-clock-waybar-save-task))
 
 (provide 'org-clock-waybar)
 ;;; org-clock-waybar.el ends here