Guest User

Untitled

a guest
Nov 21st, 2026
62
0
Never
Not a member of Pastebin yet? Sign Up, it unlocks many cool features!
Lisp 18.45 KB | None | 0 0
  1. ;;; org-agenda-day-index.el --- Fast multi-day Org agendas from a per-day index  -*- lexical-binding: t; -*-
  2.  
  3. ;; Version: 0.1.0
  4. ;; Keywords: calendar, outlines
  5. ;; Package-Requires: ((emacs "29.1") (org "9.8"))
  6. ;; SPDX-License-Identifier: GPL-3.0-or-later
  7.  
  8. ;; This file is not part of GNU Emacs.
  9.  
  10. ;; This program is free software: you can redistribute it and/or modify
  11. ;; it under the terms of the GNU General Public License as published by
  12. ;; the Free Software Foundation, either version 3 of the License, or
  13. ;; (at your option) any later version.
  14.  
  15. ;; This program is distributed in the hope that it will be useful,
  16. ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  17. ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18. ;; GNU General Public License for more details.
  19.  
  20. ;; You should have received a copy of the GNU General Public License
  21. ;; along with this program.  If not, see <https://www.gnu.org/licenses/>.
  22.  
  23. ;;; Commentary:
  24.  
  25. ;; Org builds a multi-day agenda -- a week view, a 60-day calendar block,
  26. ;; anything that calls `org-agenda-get-day-entries' day after day -- one
  27. ;; day at a time, and each day it scans every agenda file whole.  Its
  28. ;; deadline, timestamp and scheduled scans take each dated entry through
  29. ;; `org-agenda-skip', the repeat arithmetic and an inherited APPT_WARNTIME
  30. ;; lookup before they compare its date with the day's.  So the cost is days
  31. ;; times dated entries, not the size of the files: on a 1.9 MB file with
  32. ;; 308 active timestamps, ~22 ms a day, 1.6 s for 60 days, and a copy
  33. ;; without the 88% of its bytes that held no timestamp saved only 12%.
  34. ;;
  35. ;; On any day but today an entry shows only for an active timestamp that
  36. ;; falls on that day: a SCHEDULED, DEADLINE or plain stamp on its base date
  37. ;; or one of its repeats, a range on each day it covers, a diary sexp on
  38. ;; the days it says.  Prewarnings, overdue deadlines, past-scheduled items
  39. ;; and the TODO list belong to today alone.  So `org-agenda-day-index-mode'
  40. ;; makes one regexp pass over each file and maps each day to the entries
  41. ;; with a stamp on it, and Org's own scans then run over those entries only,
  42. ;; each narrowed to in turn through `org-agenda-restrict' -- what the agenda
  43. ;; dispatcher's `<' restriction uses.  What shows, and how, stays Org's
  44. ;; decision: the index only has to hold every entry that might show, so it
  45. ;; errs towards more (a diary sexp or an hourly repeater is on every day).
  46. ;; The items come back in the order one whole-file scan returns them.  The
  47. ;; index is kept per buffer and built again when the buffer's text changes
  48. ;; (~15 ms for that file).
  49. ;;
  50. ;; Measured on that file: a 60-day calendar block 1.65 s -> 0.6 s, 120 days
  51. ;; 3.9 s -> 1.2 s, with the same agenda text, and the same markers, types,
  52. ;; tags and categories on every line.
  53. ;;
  54. ;; Usage:
  55. ;;
  56. ;;   (require 'org-agenda-day-index)
  57. ;;   (org-agenda-day-index-mode 1)
  58. ;;
  59. ;; Every agenda view then builds each day but today from the index where
  60. ;; that gives exactly what Org's scan gives.  Where it might not, the day
  61. ;; is scanned the stock way:
  62. ;;
  63. ;; - today, with its prewarnings, overdue items and TODO list;
  64. ;; - a skip function (`org-agenda-skip-function' or
  65. ;;   `org-agenda-skip-function-global') that is not listed in
  66. ;;   `org-agenda-day-index-entry-local-skip-functions': a skip function may
  67. ;;   skip a whole subtree from its parent heading, which an entry scanned on
  68. ;;   its own never sees.  One listed there judges each entry by itself; it
  69. ;;   is called on the widened buffer, so it may still look at ancestors;
  70. ;; - a restriction of the agenda (the dispatcher's `<'), which narrows the
  71. ;;   buffer itself;
  72. ;; - `org-agenda-include-inactive-timestamps', as the index reads only
  73. ;;   active stamps;
  74. ;; - an entry type the index does not know.  Log items (`:closed', in log
  75. ;;   mode) are gathered by a whole-file scan of their own and put in their
  76. ;;   place among the rest.
  77. ;;
  78. ;; To keep one view on the stock scan, bind `org-agenda-day-index' to nil
  79. ;; in its settings:
  80. ;;
  81. ;;   ("w" "Week, scanned whole" agenda "" ((org-agenda-day-index nil)))
  82. ;;
  83. ;; Item formatting (`org-agenda-format-item') runs on the widened buffer,
  84. ;; so `%(...)' expressions in `org-agenda-prefix-format' see the whole file
  85. ;; as they always do.
  86. ;;
  87. ;; It leans on Org internals: the `org-agenda-restrict' branch of
  88. ;; `org-agenda-get-day-entries', the `type' each of its scans gives its
  89. ;; items, and `org-agenda--timestamp-to-absolute'.  Tested with Org 9.8.10
  90. ;; and 10.0-pre.  Its tests compare each day it builds with Org's own scan
  91. ;; of the day over a fixture of every kind of timestamp, and over the
  92. ;; options that change which occurrence of a repeat shows: run them after
  93. ;; upgrading Org.
  94.  
  95. ;;; Code:
  96.  
  97. (require 'org)
  98. (require 'org-agenda)
  99. (require 'seq)
  100.  
  101. (defgroup org-agenda-day-index nil
  102.   "Build multi-day Org agendas from a per-day index of timestamps."
  103.   :group 'org-agenda
  104.   :prefix "org-agenda-day-index-")
  105.  
  106. (defcustom org-agenda-day-index t
  107.   "Non-nil: `org-agenda-day-index-mode' builds days from the index.
  108. Bind it to nil in an agenda command's or block's settings to have that
  109. view scanned the stock way."
  110.   :type 'boolean)
  111.  
  112. (defcustom org-agenda-day-index-entry-local-skip-functions
  113.   '(org-agenda-skip-entry-if)
  114.   "Skip functions that judge each entry by itself.
  115. While `org-agenda-skip-function' or `org-agenda-skip-function-global'
  116. holds a skip function not on this list, days are scanned the stock way:
  117. the function may skip a whole subtree from its parent heading, which an
  118. entry scanned on its own never sees.  One on the list -- a function, or
  119. the head of a form such as (org-agenda-skip-entry-if \\='scheduled) --
  120. is called on the widened buffer, so it may look at the entry's
  121. ancestors; it must give each entry the verdict it would give it in a
  122. scan of the whole file."
  123.   :type '(repeat function))
  124.  
  125. (defconst org-agenda-day-index--days-before 30
  126.   "Days before the first day asked for that an index covers.
  127. So that a scan walking backwards does not build it again for each day.")
  128.  
  129. (defconst org-agenda-day-index--days-after 149
  130.   "Days after the first day asked for that an index covers.")
  131.  
  132. (defvar-local org-agenda-day-index--cache nil
  133.   "This buffer's index, as (TICK FIRST LAST TABLE).
  134. TABLE maps each absolute day from FIRST to LAST to the regions, (BEG
  135. . END), of the entries with a stamp on that day, in buffer order, as the
  136. buffer stood at `buffer-chars-modified-tick' TICK.")
  137.  
  138. (defvar org-agenda-day-index--narrowed nil
  139.   "Non-nil while Org's scans run narrowed to one entry.")
  140.  
  141. (defconst org-agenda-day-index--stamp-regexp
  142.   (rx (or (seq bol (? "&") "%%(")
  143.           "<%%("
  144.           (seq "<" (= 4 digit) "-" (= 2 digit) "-" (= 2 digit))))
  145.   "Where a stamp the agenda reads starts.
  146. A diary sexp line, a diary sexp stamp, or a date stamp, which may begin
  147. a range.")
  148.  
  149. (defconst org-agenda-day-index--scans
  150.   '((:deadline ("deadline" "upcoming-deadline"))
  151.     (:deadline* ("deadline" "upcoming-deadline"))
  152.     (:timestamp ("block") ("timestamp"))
  153.     (:sexp ("sexp"))
  154.     (:scheduled ("scheduled" "past-scheduled"))
  155.     (:scheduled* ("scheduled" "past-scheduled"))
  156.     (:closed ("closed" "state" "clock"))
  157.     (:todo))
  158.   "The entry types of `org-agenda-get-day-entries' the index can serve.
  159. Each with the item types of the scans it runs, one list per scan, in the
  160. order it returns them.  A scan returns its items in buffer order whatever
  161. their type: a scheduled line and a past-scheduled one (the future repeat
  162. of a stamp whose base date has passed) rank alike.  `:todo' gives items
  163. on today only, which is never built from the index.")
  164.  
  165. (defun org-agenda-day-index--headline-p ()
  166.   "Non-nil when the line at point begins a headline, as Org parses it.
  167. Not an inline task or its END line, and not a line of stars inside a
  168. block: Org's scans, narrowed to a region that starts inside one of
  169. those elements, map that element again, or never finish."
  170.   (and (looking-at org-outline-regexp-bol)
  171.        (org-element-type-p (org-element-at-point) 'headline)))
  172.  
  173. (defun org-agenda-day-index--entry-region (pos)
  174.   "The entry holding POS, from its headline to the next one: (BEG . END).
  175. Headlines as `org-agenda-day-index--headline-p' finds them, so that the
  176. regions of a buffer never overlap and each starts where an element
  177. does; an inline task is part of the entry it sits in.  Before the first
  178. headline, the region starts at the beginning of the buffer."
  179.   (save-excursion
  180.     (goto-char pos)
  181.     (forward-line 0)
  182.     (let ((beg (progn
  183.                  (while (and (not (org-agenda-day-index--headline-p))
  184.                              (re-search-backward org-outline-regexp-bol nil 'move)))
  185.                  (point))))
  186.       (goto-char pos)
  187.       (end-of-line)
  188.       (cons beg
  189.             (progn
  190.               (while (and (re-search-forward org-outline-regexp-bol nil 'move)
  191.                           (progn (goto-char (match-beginning 0))
  192.                                  (not (org-agenda-day-index--headline-p))))
  193.                 (end-of-line))
  194.               (point))))))
  195.  
  196. (defun org-agenda-day-index--stamp-days (stamp first last pos)
  197.   "The days from FIRST to LAST on which the active STAMP can fall.
  198. STAMP is the text inside its brackets and POS where it is.  That is its
  199. base date and every repeat, by `org-agenda--timestamp-to-absolute' as
  200. Org's own scans reckon them; every day for an hourly repeater."
  201.   (cond
  202.    ((string-match-p "\\+[0-9]+h" stamp) (number-sequence first last))
  203.    ((not (string-match-p "\\+[0-9]+[dwmy]" stamp))
  204.     (let ((day (org-agenda--timestamp-to-absolute stamp)))
  205.       (and (<= first day last) (list day))))
  206.    (t (let ((day first) days)
  207.         (while (<= day last)
  208.           (let ((next (org-agenda--timestamp-to-absolute
  209.                        stamp day 'future (current-buffer) pos)))
  210.             (when (<= first next last) (push next days))
  211.             (setq day (1+ (max next day)))))
  212.         days))))
  213.  
  214. (defun org-agenda-day-index--build (first last)
  215.   "Map each day from FIRST to LAST to the entries with a stamp on it.
  216. Return a hash table from absolute days to lists of entry regions, as
  217. `org-agenda-day-index--entry-region' gives them, in buffer order.  A
  218. stamp whose days cannot be worked out counts on every day."
  219.   (let ((table (make-hash-table)))
  220.     (org-with-wide-buffer
  221.      (goto-char (point-min))
  222.      (while (re-search-forward org-agenda-day-index--stamp-regexp nil t)
  223.        (let* ((pos (match-beginning 0))
  224.               (days
  225.                (save-excursion
  226.                  (goto-char pos)
  227.                  (condition-case nil
  228.                      (cond
  229.                       ((looking-at-p "&?%%(\\|<%%(") (number-sequence first last))
  230.                       ;; `org-agenda--timestamp-to-absolute' clobbers the
  231.                       ;; match data: read both ends first.
  232.                       ((looking-at org-tr-regexp)
  233.                        (let ((from (match-string 1))
  234.                              (to (match-string 2)))
  235.                          (number-sequence
  236.                           (max first (org-agenda--timestamp-to-absolute from))
  237.                           (min last (org-agenda--timestamp-to-absolute to)))))
  238.                       ((looking-at org-ts-regexp)
  239.                        (org-agenda-day-index--stamp-days
  240.                         (match-string 1) first last pos)))
  241.                    (error (number-sequence first last))))))
  242.          (when days
  243.            (let ((region (org-agenda-day-index--entry-region pos)))
  244.              (dolist (day days)
  245.                (unless (member region (gethash day table))
  246.                  (push region (gethash day table)))))))))
  247.     (maphash (lambda (day regions)
  248.                (puthash day (sort regions (lambda (a b) (< (car a) (car b))))
  249.                         table))
  250.              table)
  251.     table))
  252.  
  253. (defun org-agenda-day-index--regions (day)
  254.   "The regions of the entries with a stamp on absolute DAY, in buffer order.
  255. From the current buffer's index, built again when its text has changed
  256. or DAY lies outside it."
  257.   (let ((cache org-agenda-day-index--cache))
  258.     (unless (and cache
  259.                  (= (nth 0 cache) (buffer-chars-modified-tick))
  260.                  (<= (nth 1 cache) day (nth 2 cache)))
  261.       (let ((first (- day org-agenda-day-index--days-before))
  262.             (last (+ day org-agenda-day-index--days-after)))
  263.         (setq cache (list (buffer-chars-modified-tick) first last
  264.                           (org-agenda-day-index--build first last))
  265.               org-agenda-day-index--cache cache)))
  266.     (gethash day (nth 3 cache))))
  267.  
  268. (defun org-agenda-day-index--order (types)
  269.   "The scans `org-agenda-get-day-entries' runs for TYPES, in its order.
  270. Each as the list of the item types it gives.  Like that function, keep
  271. one deadline type and move it to the front, and keep one scheduled
  272. type."
  273.   (let ((types (delete-dups (copy-sequence types))))
  274.     (when (and (memq :scheduled types) (memq :scheduled* types))
  275.       (setq types (delq :scheduled* types)))
  276.     (let ((deadline (or (car (memq :deadline types))
  277.                         (car (memq :deadline* types)))))
  278.       (when deadline
  279.         (setq types (cons deadline (delq :deadline (delq :deadline* types))))))
  280.     (mapcan (lambda (type)
  281.               (copy-sequence (cdr (assq type org-agenda-day-index--scans))))
  282.             types)))
  283.  
  284. (defun org-agenda-day-index--entry-local-p (skip)
  285.   "Non-nil when the skip function or form SKIP judges each entry by itself.
  286. That is, when there is none, or it is on
  287. `org-agenda-day-index-entry-local-skip-functions'."
  288.   (or (null skip)
  289.       (memq skip org-agenda-day-index-entry-local-skip-functions)
  290.       (and (consp skip)
  291.            (symbolp (car skip))
  292.            (memq (car skip) org-agenda-day-index-entry-local-skip-functions))))
  293.  
  294. (defun org-agenda-day-index--widened (skip)
  295.   "SKIP, a skip function or form, as a function run on the widened buffer."
  296.   (and skip
  297.        (lambda ()
  298.          (save-restriction
  299.            (widen)
  300.            (org-agenda-skip-eval skip)))))
  301.  
  302. (defun org-agenda-day-index--get-day-entries-a (fn file date &rest args)
  303.   "Build DATE for FILE from the index where that is exact.
  304. Around advice for `org-agenda-get-day-entries' (FN), with its FILE, DATE
  305. and ARGS.  Its scans run over each entry with a stamp on DATE, narrowed
  306. to it, instead of over the whole file, and their items come back in the
  307. order a single call gives.  Any other day is built by FN as it is."
  308.   (let* ((types (or args org-agenda-entry-types))
  309.          (day (calendar-absolute-from-gregorian date))
  310.          (buffer (and org-agenda-day-index
  311.                       (/= day (org-today))
  312.                       (not org-agenda-restrict)
  313.                       (not org-agenda-include-inactive-timestamps)
  314.                       (org-agenda-day-index--entry-local-p org-agenda-skip-function)
  315.                       (org-agenda-day-index--entry-local-p
  316.                        org-agenda-skip-function-global)
  317.                       types
  318.                       (seq-every-p (lambda (type)
  319.                                      (assq type org-agenda-day-index--scans))
  320.                                    types)
  321.                       (file-exists-p file)
  322.                       ;; As FN visits it.
  323.                       (let ((org-startup-folded nil)
  324.                             (org-startup-align-all-tables nil))
  325.                         (org-get-agenda-file-buffer file)))))
  326.     (if (not (and buffer (with-current-buffer buffer (derived-mode-p 'org-mode))))
  327.         (apply fn file date args)
  328.       (let* ((order (org-agenda-day-index--order types))
  329.              (dated (remq :closed types))
  330.              (log (and (memq :closed types) (funcall fn file date :closed)))
  331.              (regions (with-current-buffer buffer
  332.                         ;; What FN does first, even on a day with no entries.
  333.                         (setq org-agenda-buffer (or org-agenda-buffer buffer))
  334.                         (setf org-agenda-current-date date)
  335.                         (and dated (org-agenda-day-index--regions day))))
  336.              (items
  337.               (let ((org-agenda-restrict buffer)
  338.                     (org-agenda-skip-function
  339.                      (org-agenda-day-index--widened org-agenda-skip-function))
  340.                     (org-agenda-skip-function-global
  341.                      (org-agenda-day-index--widened org-agenda-skip-function-global))
  342.                     (org-agenda-day-index--narrowed t))
  343.                 (mapcan (lambda (region)
  344.                           (let ((org-agenda-restrict-begin (car region))
  345.                                 (org-agenda-restrict-end (cdr region)))
  346.                             (apply fn file date dated)))
  347.                         regions))))
  348.         ;; `sort' is stable: within a scan's items, buffer order stands.
  349.         (seq-sort-by (lambda (item)
  350.                        (or (seq-position order (get-text-property 0 'type item)
  351.                                          (lambda (scan type) (member type scan)))
  352.                            (length order)))
  353.                      #'<
  354.                      (nconc log items))))))
  355.  
  356. (defun org-agenda-day-index--format-item-a (fn &rest args)
  357.   "Apply FN to ARGS on the widened buffer while a scan runs narrowed.
  358. Around advice for `org-agenda-format-item', so that `%(...)' prefix
  359. expressions see the whole file, as they do in a stock scan."
  360.   (if org-agenda-day-index--narrowed
  361.       (save-restriction
  362.         (widen)
  363.         (apply fn args))
  364.     (apply fn args)))
  365.  
  366. ;;;###autoload
  367. (define-minor-mode org-agenda-day-index-mode
  368.   "Build the days of an agenda but today from a per-day index.
  369. Each agenda file's active timestamps are mapped once to the days they
  370. fall on, and Org's scans of a day then visit only the entries with a
  371. stamp on it, instead of the whole file.  A day where that might not give
  372. what the whole-file scan gives is scanned the stock way; see the
  373. Commentary of org-agenda-day-index.el.  `org-agenda-day-index' turns it
  374. off for one view."
  375.   :global t
  376.   :group 'org-agenda-day-index
  377.   (if org-agenda-day-index-mode
  378.       (progn
  379.         (advice-add 'org-agenda-get-day-entries :around
  380.                     #'org-agenda-day-index--get-day-entries-a)
  381.         (advice-add 'org-agenda-format-item :around
  382.                     #'org-agenda-day-index--format-item-a))
  383.     (advice-remove 'org-agenda-get-day-entries
  384.                    #'org-agenda-day-index--get-day-entries-a)
  385.     (advice-remove 'org-agenda-format-item
  386.                    #'org-agenda-day-index--format-item-a)))
  387.  
  388. (provide 'org-agenda-day-index)
  389. ;;; org-agenda-day-index.el ends here
  390.  
Advertisement
Add Comment
Please, Sign In to add comment