···
;; Copyright (C) 2025 Ryan Gibb
;; Author: Ryan Gibb <ryan@freumh.org>
7
-
;; Package-Requires: ((emacs "27.1"))
8
-
;; Keywords: calendar, caledonia
6
+
;; Maintainer: Ryan Gibb <ryan@freumh.org>
8
+
;; Keywords: calendar
9
+
;; Package-Requires: ((emacs "24.4"))
;; URL: https://ryan.freumh.org/caledonia.html
;; This file is not part of GNU Emacs.
···
30
-
(defcustom caledonia-executable "caled"
31
+
(defcustom caledonia-executable (executable-find "caled")
"Path to the Caledonia executable."
···
(defvar caledonia--response-line nil
"Last response line received.")
(defvar caledonia--response-flag nil
112
-
"Flag set when response is received.")
113
+
"Non-nil means a responce has been recieved.")
(defvar-local caledonia--current-query nil
"The current query parameters being displayed in this buffer.")
···
(defvar caledonia--server-line-buffer "")
(defun caledonia--server-filter (process output)
122
+
"Filter PROCESS OUTPUT."
;; Append to the ongoing buffer for logging/debugging
(when (buffer-live-p (process-buffer process))
(with-current-buffer (process-buffer process)
···
(setq caledonia--response-flag t)))))
(defun caledonia--server-sentinel (process event)
142
+
"Listen on PROCESS for an EVENT."
(message "Caledonia Server process event: %s (%s)" process event)
(setq caledonia--server-process nil))
(defun caledonia--ensure-server-running ()
147
+
"Run the caledonia binary in server mode."
(unless (and caledonia--server-process (process-live-p caledonia--server-process))
(message "Caledonia Starting server...")
(setq caledonia--server-process
···
(unless (and caledonia--server-process (process-live-p caledonia--server-process))
152
-
(error "Caledonia Failed to start server process."))
156
+
(error "Caledonia Failed to start server process"))
(set-process-filter caledonia--server-process #'caledonia--server-filter)
(set-process-sentinel caledonia--server-process #'caledonia--server-sentinel)
(message "Caledonia Server started.")))
(defun caledonia--send-request (request-str)
162
+
"Send REQUEST-STR and get responce back."
(caledonia--ensure-server-running)
(setq caledonia--response-line nil)
(setq caledonia--response-flag nil)
···
(process-live-p caledonia--server-process))
(accept-process-output caledonia--server-process 0 100000))) ; Wait 100ms
(unless caledonia--response-flag
169
-
(error "Caledonia Timeout or server died waiting for response."))
174
+
(error "Caledonia Timeout or server died waiting for response"))
(let ((response-sexp (read caledonia--response-line)))
(unless (and (listp response-sexp) (memq (car response-sexp) '(Ok Error)))
···
(error "Caledonia Server Error: %s" (cadr response-sexp))
;; Return the (Ok ...) payload
178
-
(error (error "Caledonia Failed to parse response line: %s"
179
-
caledonia--response-line (error-message-string err)))))
183
+
(error "Caledonia Failed to parse response line: %s"
184
+
caledonia--response-line (error-message-string err))))
(defun caledonia--get-events (event-payload)
182
-
"Parse SEXP-STRING of structure (Events (events...))"
187
+
"Parse EVENT-PAYLOAD of structure (Events (events...))."
(if (and (listp event-payload) (eq (car event-payload) 'Events))
(let ((event-list (cadr event-payload)))
···
(defun caledonia--format-timestamp (iso-string &optional format)
193
-
"Format ISO-8601 time string to human-readable format.
198
+
"Format ISO-8601 time string ISO-STRING to human-readable format.
FORMAT defaults to \"%Y-%m-%d %H:%M\" if not specified."
(let* ((parsed (parse-time-string iso-string))
(time (apply #'encode-time
···
(defun caledonia--sort-calendar (A B)
255
-
"Sort function for calendar column."
260
+
"Sort function for calendar column between A and B."
(let ((a (aref (cadr A) 0))
(defun caledonia--sort-start (A B)
261
-
"Sort function for date/time column."
266
+
"Sort function for date/time column between A and B."
(let ((a (aref (cadr A) 1))
(time-less-p (date-to-time a) (date-to-time b))))
(defun caledonia--sort-end (A B)
267
-
"Sort function for date/time column."
272
+
"Sort function for date/time column between A and B."
(let ((a (aref (cadr A) 2))
(time-less-p (date-to-time a) (date-to-time b))))
···
(run-with-timer 0.5 nil (lambda () (delete-overlay overlay))))))
(defun caledonia--read-date-range ()
405
-
"Read a date range from the user with org-mode date picker integration.
410
+
"Read a date range from the user with `org-mode' date picker integration.
Returns a cons cell (from-date . to-date).
The from-date can be nil to indicate no start date constraint."
(if (y-or-n-p "Set a start date? ")
(org-read-date nil nil nil "From date: " nil nil t)
412
-
; empty string differentiates from nil for optional args later on
417
+
; empty string differentiates from nil for optional args later on
;; Use org-mode's date picker for To date (must have a value)
(setq to (org-read-date nil nil nil "To date: " nil nil t))
···
"Set the date range for the current calendar view."
(when (eq major-mode 'caledonia-mode)
424
-
(let* ((dates (caledonia--read-date-range
425
-
"From date" "" 'caledonia-from-history
426
-
"To date" "" 'caledonia-to-history))
429
+
(let* ((dates (caledonia--read-date-range))
(current-query caledonia--current-query)
···
"Set whether to filter by recurring events for the current calendar view."
(when (eq major-mode 'caledonia-mode)
520
-
(let* ((recurring-str (completing-read "Recurring events (yes/no/all, leave empty for all): "
521
-
'("" "yes" "no") nil nil nil))
522
-
(recurring (cond ((string= recurring-str "yes") t)
523
-
((string= recurring-str "no") nil)
523
+
(let* ((recurring (completing-read "Recurring events (yes/no/all, leave empty for all): "
524
+
'("" "yes" "no") nil nil nil))
(current-query caledonia--current-query)
(new-query (copy-tree current-query)))
;; Update the query with the recurring filter
(setq new-query (assq-delete-all 'recurring new-query))
529
-
(when (not (string-empty-p recurring-str))
530
-
(push `(recurring ,(if (string= recurring-str "yes") t nil)) new-query))
529
+
(when (not (string-empty-p recurring))
530
+
(push `(recurring ,(if (string= recurring "yes") t nil)) new-query))
;; Execute the updated query
(caledonia--make-query new-query))))
···
(defun caledonia-open-event-file ()
"Open the file associated with the event at point.
581
-
If the file contains the event ID, the cursor will be positioned at that location."
581
+
If the file contains the event ID, the cursor will be positioned at that
(when (eq major-mode 'caledonia-mode)
(let* ((id (tabulated-list-get-id))
···
(defun caledonia-refresh ()
"Refresh calendar data from disk and update the current view.
601
-
This is useful when calendar files have been modified outside Emacs
602
-
(for example, by a sync program or direct file edits)."
602
+
This is useful when calendar files have been modified outside Emacs."
(when (eq major-mode 'caledonia-mode)
;; Send a refresh command to clear the server's cache
···
(defun caledonia-query ()
"Query events with interactive prompts for all filter parameters.
616
-
Opens a series of prompts to build a complete query and then displays the results.
617
-
After the initial query is displayed, you can further refine the results
618
-
using the caledonia-query-* family of functions."
616
+
Opens a series of prompts to build a complete query and then displays the
617
+
results. After the initial query is displayed, you can further refine the
618
+
results using the caledonia-query-* family of functions."
621
-
(dates (caledonia--read-date-range))
624
-
(timezone-str (read-string "Timezone (e.g. Europe/London, leave empty for default): "
625
-
nil 'caledonia-timezone-history))
626
-
(timezone (when (not (string-empty-p timezone-str)) timezone-str))
627
-
(available-calendars
628
-
(caledonia--send-request "ListCalendars"))
630
-
(if (and (listp available-calendars)
631
-
(eq (car available-calendars) 'Calendars))
632
-
(cadr available-calendars)
634
-
(message "Failed to get calendar list from server")
636
-
(selected-calendars
637
-
(completing-read-multiple
638
-
"Select calendars (comma-separated, empty for all): "
639
-
(or calendars-list '()) nil nil nil 'caledonia-calendars-history))
640
-
(calendars (mapcar #'string-trim selected-calendars))
641
-
(text (read-string "Search text (leave empty for no text search): "
642
-
nil 'caledonia-text-history))
643
-
(search-in-str (when (and text (not (string-empty-p text)))
644
-
(read-string "Search in (summary,description,location - leave empty for all): "
645
-
nil 'caledonia-search-fields-history)))
646
-
(search-in (when (and search-in-str (not (string-empty-p search-in-str)))
647
-
(mapcar (lambda (field)
648
-
(intern (string-trim field)))
649
-
(split-string search-in-str "," t))))
650
-
(id (read-string "Event ID (leave empty for all events): "
651
-
nil 'caledonia-id-history))
652
-
(recurring (completing-read "Recurring events (yes/no/all, leave empty for all): "
653
-
'("" "yes" "no") nil nil nil))
654
-
(limit-str (read-string "Maximum events to show (leave empty for no limit): "
655
-
nil 'caledonia-limit-history))
656
-
(limit (when (and limit-str (not (string-empty-p limit-str)))
657
-
(string-to-number limit-str)))
621
+
(dates (caledonia--read-date-range))
624
+
(timezone-str (read-string "Timezone (e.g. Europe/London, leave empty for default): "
625
+
nil 'caledonia-timezone-history))
626
+
(timezone (when (not (string-empty-p timezone-str)) timezone-str))
627
+
(available-calendars
628
+
(caledonia--send-request "ListCalendars"))
630
+
(if (and (listp available-calendars)
631
+
(eq (car available-calendars) 'Calendars))
632
+
(cadr available-calendars)
634
+
(message "Failed to get calendar list from server")
636
+
(selected-calendars
637
+
(completing-read-multiple
638
+
"Select calendars (comma-separated, empty for all): "
639
+
(or calendars-list '()) nil nil nil 'caledonia-calendars-history))
640
+
(calendars (mapcar #'string-trim selected-calendars))
641
+
(text (read-string "Search text (leave empty for no text search): "
642
+
nil 'caledonia-text-history))
643
+
(search-in-str (when (and text (not (string-empty-p text)))
644
+
(read-string "Search in (summary,description,location - leave empty for all): "
645
+
nil 'caledonia-search-fields-history)))
646
+
(search-in (when (and search-in-str (not (string-empty-p search-in-str)))
647
+
(mapcar (lambda (field)
648
+
(intern (string-trim field)))
649
+
(split-string search-in-str "," t))))
650
+
(id (read-string "Event ID (leave empty for all events): "
651
+
nil 'caledonia-id-history))
652
+
(recurring (completing-read "Recurring events (yes/no/all, leave empty for all): "
653
+
'("" "yes" "no") nil nil nil))
654
+
(limit-str (read-string "Maximum events to show (leave empty for no limit): "
655
+
nil 'caledonia-limit-history))
656
+
(limit (when (and limit-str (not (string-empty-p limit-str)))
657
+
(string-to-number limit-str)))
;; Build query based on parameters
(when (and from (not (string-empty-p from)))
(push `(from ,from) query))
···
(defun caledonia-list (&optional from-date to-date)
"List calendar in a new buffer within the default date range.
691
-
FROM-DATE and TO-DATE override the default date range if provided.
692
-
TO-DATE is required and will use a default if not specified.
693
-
With prefix arg (C-u), prompts for the date range with an interactive calendar."
691
+
FROM-DATE and TO-DATE override the default date range if provided. TO-DATE is
692
+
required and will use a default if not specified. With prefix arg, prompts for
693
+
the date range with an interactive calendar."
(let* ((dates (caledonia--read-date-range)))
697
-
(list (car dates) (cdr dates)))))
697
+
(list (car dates) (cdr dates)))))
(let ((buffer (get-buffer-create caledonia--events-buffer))
(from (or from-date caledonia-list-from-date))
;; Ensure to date is always provided
···
(defun caledonia-search (&optional expr from-date to-date)
"Search for query EXPR with optional FROM-DATE and TO-DATE.
719
-
This is an interactive function which asks user for EXPR if not passed as an argument.
720
-
With prefix arg (C-u), also prompts for date range with an interactive calendar.
721
-
Use this to find events matching specific text across all calendars.
719
+
This is an interactive function which asks user for EXPR if not passed as an
720
+
argument. With prefix arg, also prompts for date range with an interactive
721
+
calendar. Use this to find events matching specific text across all calendars.
TO-DATE is required; a default will be used if not provided."
(let* ((search-text (read-string "Search for: " nil 'caledonia-search-prompt-history))
···
(define-derived-mode caledonia-mode tabulated-list-mode "Caledonia"
"Major mode for displaying calendar entries in a tabular view.")
787
-
;; Define a prefix map specifically for Evil mode
788
-
(defvar caledonia-evil-filter-map
789
-
(let ((map (make-sparse-keymap)))
790
-
(define-key map "d" 'caledonia-query-date-range)
791
-
(define-key map "c" 'caledonia-query-calendars)
792
-
(define-key map "t" 'caledonia-query-text)
793
-
(define-key map "i" 'caledonia-query-id)
794
-
(define-key map "r" 'caledonia-query-recurring)
795
-
(define-key map "l" 'caledonia-query-limit)
796
-
(define-key map "z" 'caledonia-query-timezone)
798
-
"Evil mode keymap for filter commands in Caledonia mode.")
800
-
(eval-after-load 'evil
802
-
;; Basic navigation and commands
803
-
(evil-define-key 'normal caledonia-mode-map
804
-
(kbd "RET") 'caledonia-show-event
805
-
(kbd "M-RET") 'caledonia-open-event-file
806
-
"l" 'caledonia-list
807
-
"s" 'caledonia-search
808
-
"r" 'caledonia-refresh
810
-
;; Set up a proper Evil prefix key
811
-
(evil-define-key 'normal caledonia-mode-map "f" caledonia-evil-filter-map)))
813
-
(defun caledonia--setup-evil-integration ()
814
-
"Set up Evil integration for Caledonia mode."
815
-
(when (bound-and-true-p evil-mode)
816
-
(evil-make-overriding-map caledonia-mode-map 'normal)
817
-
(evil-normalize-keymaps)))
819
-
(add-hook 'caledonia-mode-hook 'caledonia--setup-evil-integration)
;;; caledonia.el ends here
ryan.freumh.org