Not a member of Pastebin yet?
Sign Up,
it unlocks many cool features!
- ;;; org-agenda-day-index.el --- Fast multi-day Org agendas from a per-day index -*- lexical-binding: t; -*-
- ;; Version: 0.1.0
- ;; Keywords: calendar, outlines
- ;; Package-Requires: ((emacs "29.1") (org "9.8"))
- ;; SPDX-License-Identifier: GPL-3.0-or-later
- ;; This file is not part of GNU Emacs.
- ;; 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
- ;; the Free Software Foundation, either version 3 of the License, or
- ;; (at your option) any later version.
- ;; This program is distributed in the hope that it will be useful,
- ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
- ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- ;; GNU General Public License for more details.
- ;; You should have received a copy of the GNU General Public License
- ;; along with this program. If not, see <https://www.gnu.org/licenses/>.
- ;;; Commentary:
- ;; Org builds a multi-day agenda -- a week view, a 60-day calendar block,
- ;; anything that calls `org-agenda-get-day-entries' day after day -- one
- ;; day at a time, and each day it scans every agenda file whole. Its
- ;; deadline, timestamp and scheduled scans take each dated entry through
- ;; `org-agenda-skip', the repeat arithmetic and an inherited APPT_WARNTIME
- ;; lookup before they compare its date with the day's. So the cost is days
- ;; times dated entries, not the size of the files: on a 1.9 MB file with
- ;; 308 active timestamps, ~22 ms a day, 1.6 s for 60 days, and a copy
- ;; without the 88% of its bytes that held no timestamp saved only 12%.
- ;;
- ;; On any day but today an entry shows only for an active timestamp that
- ;; falls on that day: a SCHEDULED, DEADLINE or plain stamp on its base date
- ;; or one of its repeats, a range on each day it covers, a diary sexp on
- ;; the days it says. Prewarnings, overdue deadlines, past-scheduled items
- ;; and the TODO list belong to today alone. So `org-agenda-day-index-mode'
- ;; makes one regexp pass over each file and maps each day to the entries
- ;; with a stamp on it, and Org's own scans then run over those entries only,
- ;; each narrowed to in turn through `org-agenda-restrict' -- what the agenda
- ;; dispatcher's `<' restriction uses. What shows, and how, stays Org's
- ;; decision: the index only has to hold every entry that might show, so it
- ;; errs towards more (a diary sexp or an hourly repeater is on every day).
- ;; The items come back in the order one whole-file scan returns them. The
- ;; index is kept per buffer and built again when the buffer's text changes
- ;; (~15 ms for that file).
- ;;
- ;; Measured on that file: a 60-day calendar block 1.65 s -> 0.6 s, 120 days
- ;; 3.9 s -> 1.2 s, with the same agenda text, and the same markers, types,
- ;; tags and categories on every line.
- ;;
- ;; Usage:
- ;;
- ;; (require 'org-agenda-day-index)
- ;; (org-agenda-day-index-mode 1)
- ;;
- ;; Every agenda view then builds each day but today from the index where
- ;; that gives exactly what Org's scan gives. Where it might not, the day
- ;; is scanned the stock way:
- ;;
- ;; - today, with its prewarnings, overdue items and TODO list;
- ;; - a skip function (`org-agenda-skip-function' or
- ;; `org-agenda-skip-function-global') that is not listed in
- ;; `org-agenda-day-index-entry-local-skip-functions': a skip function may
- ;; skip a whole subtree from its parent heading, which an entry scanned on
- ;; its own never sees. One listed there judges each entry by itself; it
- ;; is called on the widened buffer, so it may still look at ancestors;
- ;; - a restriction of the agenda (the dispatcher's `<'), which narrows the
- ;; buffer itself;
- ;; - `org-agenda-include-inactive-timestamps', as the index reads only
- ;; active stamps;
- ;; - an entry type the index does not know. Log items (`:closed', in log
- ;; mode) are gathered by a whole-file scan of their own and put in their
- ;; place among the rest.
- ;;
- ;; To keep one view on the stock scan, bind `org-agenda-day-index' to nil
- ;; in its settings:
- ;;
- ;; ("w" "Week, scanned whole" agenda "" ((org-agenda-day-index nil)))
- ;;
- ;; Item formatting (`org-agenda-format-item') runs on the widened buffer,
- ;; so `%(...)' expressions in `org-agenda-prefix-format' see the whole file
- ;; as they always do.
- ;;
- ;; It leans on Org internals: the `org-agenda-restrict' branch of
- ;; `org-agenda-get-day-entries', the `type' each of its scans gives its
- ;; items, and `org-agenda--timestamp-to-absolute'. Tested with Org 9.8.10
- ;; and 10.0-pre. Its tests compare each day it builds with Org's own scan
- ;; of the day over a fixture of every kind of timestamp, and over the
- ;; options that change which occurrence of a repeat shows: run them after
- ;; upgrading Org.
- ;;; Code:
- (require 'org)
- (require 'org-agenda)
- (require 'seq)
- (defgroup org-agenda-day-index nil
- "Build multi-day Org agendas from a per-day index of timestamps."
- :group 'org-agenda
- :prefix "org-agenda-day-index-")
- (defcustom org-agenda-day-index t
- "Non-nil: `org-agenda-day-index-mode' builds days from the index.
- Bind it to nil in an agenda command's or block's settings to have that
- view scanned the stock way."
- :type 'boolean)
- (defcustom org-agenda-day-index-entry-local-skip-functions
- '(org-agenda-skip-entry-if)
- "Skip functions that judge each entry by itself.
- While `org-agenda-skip-function' or `org-agenda-skip-function-global'
- holds a skip function not on this list, days are scanned the stock way:
- the function may skip a whole subtree from its parent heading, which an
- entry scanned on its own never sees. One on the list -- a function, or
- the head of a form such as (org-agenda-skip-entry-if \\='scheduled) --
- is called on the widened buffer, so it may look at the entry's
- ancestors; it must give each entry the verdict it would give it in a
- scan of the whole file."
- :type '(repeat function))
- (defconst org-agenda-day-index--days-before 30
- "Days before the first day asked for that an index covers.
- So that a scan walking backwards does not build it again for each day.")
- (defconst org-agenda-day-index--days-after 149
- "Days after the first day asked for that an index covers.")
- (defvar-local org-agenda-day-index--cache nil
- "This buffer's index, as (TICK FIRST LAST TABLE).
- TABLE maps each absolute day from FIRST to LAST to the regions, (BEG
- . END), of the entries with a stamp on that day, in buffer order, as the
- buffer stood at `buffer-chars-modified-tick' TICK.")
- (defvar org-agenda-day-index--narrowed nil
- "Non-nil while Org's scans run narrowed to one entry.")
- (defconst org-agenda-day-index--stamp-regexp
- (rx (or (seq bol (? "&") "%%(")
- "<%%("
- (seq "<" (= 4 digit) "-" (= 2 digit) "-" (= 2 digit))))
- "Where a stamp the agenda reads starts.
- A diary sexp line, a diary sexp stamp, or a date stamp, which may begin
- a range.")
- (defconst org-agenda-day-index--scans
- '((:deadline ("deadline" "upcoming-deadline"))
- (:deadline* ("deadline" "upcoming-deadline"))
- (:timestamp ("block") ("timestamp"))
- (:sexp ("sexp"))
- (:scheduled ("scheduled" "past-scheduled"))
- (:scheduled* ("scheduled" "past-scheduled"))
- (:closed ("closed" "state" "clock"))
- (:todo))
- "The entry types of `org-agenda-get-day-entries' the index can serve.
- Each with the item types of the scans it runs, one list per scan, in the
- order it returns them. A scan returns its items in buffer order whatever
- their type: a scheduled line and a past-scheduled one (the future repeat
- of a stamp whose base date has passed) rank alike. `:todo' gives items
- on today only, which is never built from the index.")
- (defun org-agenda-day-index--headline-p ()
- "Non-nil when the line at point begins a headline, as Org parses it.
- Not an inline task or its END line, and not a line of stars inside a
- block: Org's scans, narrowed to a region that starts inside one of
- those elements, map that element again, or never finish."
- (and (looking-at org-outline-regexp-bol)
- (org-element-type-p (org-element-at-point) 'headline)))
- (defun org-agenda-day-index--entry-region (pos)
- "The entry holding POS, from its headline to the next one: (BEG . END).
- Headlines as `org-agenda-day-index--headline-p' finds them, so that the
- regions of a buffer never overlap and each starts where an element
- does; an inline task is part of the entry it sits in. Before the first
- headline, the region starts at the beginning of the buffer."
- (save-excursion
- (goto-char pos)
- (forward-line 0)
- (let ((beg (progn
- (while (and (not (org-agenda-day-index--headline-p))
- (re-search-backward org-outline-regexp-bol nil 'move)))
- (point))))
- (goto-char pos)
- (end-of-line)
- (cons beg
- (progn
- (while (and (re-search-forward org-outline-regexp-bol nil 'move)
- (progn (goto-char (match-beginning 0))
- (not (org-agenda-day-index--headline-p))))
- (end-of-line))
- (point))))))
- (defun org-agenda-day-index--stamp-days (stamp first last pos)
- "The days from FIRST to LAST on which the active STAMP can fall.
- STAMP is the text inside its brackets and POS where it is. That is its
- base date and every repeat, by `org-agenda--timestamp-to-absolute' as
- Org's own scans reckon them; every day for an hourly repeater."
- (cond
- ((string-match-p "\\+[0-9]+h" stamp) (number-sequence first last))
- ((not (string-match-p "\\+[0-9]+[dwmy]" stamp))
- (let ((day (org-agenda--timestamp-to-absolute stamp)))
- (and (<= first day last) (list day))))
- (t (let ((day first) days)
- (while (<= day last)
- (let ((next (org-agenda--timestamp-to-absolute
- stamp day 'future (current-buffer) pos)))
- (when (<= first next last) (push next days))
- (setq day (1+ (max next day)))))
- days))))
- (defun org-agenda-day-index--build (first last)
- "Map each day from FIRST to LAST to the entries with a stamp on it.
- Return a hash table from absolute days to lists of entry regions, as
- `org-agenda-day-index--entry-region' gives them, in buffer order. A
- stamp whose days cannot be worked out counts on every day."
- (let ((table (make-hash-table)))
- (org-with-wide-buffer
- (goto-char (point-min))
- (while (re-search-forward org-agenda-day-index--stamp-regexp nil t)
- (let* ((pos (match-beginning 0))
- (days
- (save-excursion
- (goto-char pos)
- (condition-case nil
- (cond
- ((looking-at-p "&?%%(\\|<%%(") (number-sequence first last))
- ;; `org-agenda--timestamp-to-absolute' clobbers the
- ;; match data: read both ends first.
- ((looking-at org-tr-regexp)
- (let ((from (match-string 1))
- (to (match-string 2)))
- (number-sequence
- (max first (org-agenda--timestamp-to-absolute from))
- (min last (org-agenda--timestamp-to-absolute to)))))
- ((looking-at org-ts-regexp)
- (org-agenda-day-index--stamp-days
- (match-string 1) first last pos)))
- (error (number-sequence first last))))))
- (when days
- (let ((region (org-agenda-day-index--entry-region pos)))
- (dolist (day days)
- (unless (member region (gethash day table))
- (push region (gethash day table)))))))))
- (maphash (lambda (day regions)
- (puthash day (sort regions (lambda (a b) (< (car a) (car b))))
- table))
- table)
- table))
- (defun org-agenda-day-index--regions (day)
- "The regions of the entries with a stamp on absolute DAY, in buffer order.
- From the current buffer's index, built again when its text has changed
- or DAY lies outside it."
- (let ((cache org-agenda-day-index--cache))
- (unless (and cache
- (= (nth 0 cache) (buffer-chars-modified-tick))
- (<= (nth 1 cache) day (nth 2 cache)))
- (let ((first (- day org-agenda-day-index--days-before))
- (last (+ day org-agenda-day-index--days-after)))
- (setq cache (list (buffer-chars-modified-tick) first last
- (org-agenda-day-index--build first last))
- org-agenda-day-index--cache cache)))
- (gethash day (nth 3 cache))))
- (defun org-agenda-day-index--order (types)
- "The scans `org-agenda-get-day-entries' runs for TYPES, in its order.
- Each as the list of the item types it gives. Like that function, keep
- one deadline type and move it to the front, and keep one scheduled
- type."
- (let ((types (delete-dups (copy-sequence types))))
- (when (and (memq :scheduled types) (memq :scheduled* types))
- (setq types (delq :scheduled* types)))
- (let ((deadline (or (car (memq :deadline types))
- (car (memq :deadline* types)))))
- (when deadline
- (setq types (cons deadline (delq :deadline (delq :deadline* types))))))
- (mapcan (lambda (type)
- (copy-sequence (cdr (assq type org-agenda-day-index--scans))))
- types)))
- (defun org-agenda-day-index--entry-local-p (skip)
- "Non-nil when the skip function or form SKIP judges each entry by itself.
- That is, when there is none, or it is on
- `org-agenda-day-index-entry-local-skip-functions'."
- (or (null skip)
- (memq skip org-agenda-day-index-entry-local-skip-functions)
- (and (consp skip)
- (symbolp (car skip))
- (memq (car skip) org-agenda-day-index-entry-local-skip-functions))))
- (defun org-agenda-day-index--widened (skip)
- "SKIP, a skip function or form, as a function run on the widened buffer."
- (and skip
- (lambda ()
- (save-restriction
- (widen)
- (org-agenda-skip-eval skip)))))
- (defun org-agenda-day-index--get-day-entries-a (fn file date &rest args)
- "Build DATE for FILE from the index where that is exact.
- Around advice for `org-agenda-get-day-entries' (FN), with its FILE, DATE
- and ARGS. Its scans run over each entry with a stamp on DATE, narrowed
- to it, instead of over the whole file, and their items come back in the
- order a single call gives. Any other day is built by FN as it is."
- (let* ((types (or args org-agenda-entry-types))
- (day (calendar-absolute-from-gregorian date))
- (buffer (and org-agenda-day-index
- (/= day (org-today))
- (not org-agenda-restrict)
- (not org-agenda-include-inactive-timestamps)
- (org-agenda-day-index--entry-local-p org-agenda-skip-function)
- (org-agenda-day-index--entry-local-p
- org-agenda-skip-function-global)
- types
- (seq-every-p (lambda (type)
- (assq type org-agenda-day-index--scans))
- types)
- (file-exists-p file)
- ;; As FN visits it.
- (let ((org-startup-folded nil)
- (org-startup-align-all-tables nil))
- (org-get-agenda-file-buffer file)))))
- (if (not (and buffer (with-current-buffer buffer (derived-mode-p 'org-mode))))
- (apply fn file date args)
- (let* ((order (org-agenda-day-index--order types))
- (dated (remq :closed types))
- (log (and (memq :closed types) (funcall fn file date :closed)))
- (regions (with-current-buffer buffer
- ;; What FN does first, even on a day with no entries.
- (setq org-agenda-buffer (or org-agenda-buffer buffer))
- (setf org-agenda-current-date date)
- (and dated (org-agenda-day-index--regions day))))
- (items
- (let ((org-agenda-restrict buffer)
- (org-agenda-skip-function
- (org-agenda-day-index--widened org-agenda-skip-function))
- (org-agenda-skip-function-global
- (org-agenda-day-index--widened org-agenda-skip-function-global))
- (org-agenda-day-index--narrowed t))
- (mapcan (lambda (region)
- (let ((org-agenda-restrict-begin (car region))
- (org-agenda-restrict-end (cdr region)))
- (apply fn file date dated)))
- regions))))
- ;; `sort' is stable: within a scan's items, buffer order stands.
- (seq-sort-by (lambda (item)
- (or (seq-position order (get-text-property 0 'type item)
- (lambda (scan type) (member type scan)))
- (length order)))
- #'<
- (nconc log items))))))
- (defun org-agenda-day-index--format-item-a (fn &rest args)
- "Apply FN to ARGS on the widened buffer while a scan runs narrowed.
- Around advice for `org-agenda-format-item', so that `%(...)' prefix
- expressions see the whole file, as they do in a stock scan."
- (if org-agenda-day-index--narrowed
- (save-restriction
- (widen)
- (apply fn args))
- (apply fn args)))
- ;;;###autoload
- (define-minor-mode org-agenda-day-index-mode
- "Build the days of an agenda but today from a per-day index.
- Each agenda file's active timestamps are mapped once to the days they
- fall on, and Org's scans of a day then visit only the entries with a
- stamp on it, instead of the whole file. A day where that might not give
- what the whole-file scan gives is scanned the stock way; see the
- Commentary of org-agenda-day-index.el. `org-agenda-day-index' turns it
- off for one view."
- :global t
- :group 'org-agenda-day-index
- (if org-agenda-day-index-mode
- (progn
- (advice-add 'org-agenda-get-day-entries :around
- #'org-agenda-day-index--get-day-entries-a)
- (advice-add 'org-agenda-format-item :around
- #'org-agenda-day-index--format-item-a))
- (advice-remove 'org-agenda-get-day-entries
- #'org-agenda-day-index--get-day-entries-a)
- (advice-remove 'org-agenda-format-item
- #'org-agenda-day-index--format-item-a)))
- (provide 'org-agenda-day-index)
- ;;; org-agenda-day-index.el ends here
Advertisement
Add Comment
Please, Sign In to add comment