| blob | 667b69a66f3e1407926816b789192f1f3b6ba43c |
1 ;;; todos.el --- facilities for making and maintaining todo lists
3 ;; Copyright (C) 1997, 1999, 2001-2013 Free Software Foundation, Inc.
5 ;; Author: Oliver Seidel <privat@os10000.net>
6 ;; Stephen Berman <stephen.berman@gmx.net>
7 ;; Maintainer: Stephen Berman <stephen.berman@gmx.net>
8 ;; Keywords: calendar, todo
10 ;; This file is part of GNU Emacs.
12 ;; GNU Emacs is free software: you can redistribute it and/or modify
13 ;; it under the terms of the GNU General Public License as published by
14 ;; the Free Software Foundation, either version 3 of the License, or
15 ;; (at your option) any later version.
17 ;; GNU Emacs is distributed in the hope that it will be useful,
18 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
19 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20 ;; GNU General Public License for more details.
22 ;; You should have received a copy of the GNU General Public License
23 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
25 ;;; Commentary:
27 ;; This package provides facilities for making, displaying, navigating
28 ;; and editing todo lists, which are prioritized lists of todo items.
29 ;; Todo lists are identified with named categories, so you can group
30 ;; together and separately prioritize thematically related todo items.
31 ;; Each category is stored in a file, which thus provides a further
32 ;; level of organization. You can create as many todo files, and in
33 ;; each as many categories, as you want.
35 ;; With Todos you can navigate among the items of a category, and
36 ;; between categories in the same and in different todo files. You
37 ;; can edit todo items, reprioritize them within their category, move
38 ;; them to another category, delete them, or mark items as done and
39 ;; store them separately from the not yet done items in a category.
40 ;; You can add new todo files and categories, rename categories, move
41 ;; them to another file or delete them. You can also display summary
42 ;; tables of the categories in a file and the types of items they
43 ;; contain. And you can build cross-categorial lists of items that
44 ;; satisfy various criteria.
46 ;; To get started, load this package and type `M-x todos-show'. This
47 ;; will prompt you for the name of the first todo file, its first
48 ;; category and the category's first item, create these and display
49 ;; them in Todos mode. Now you can insert further items into the list
50 ;; (i.e., the category) and assign them priorities by typing `i i'.
52 ;; You will probably find it convenient to give `todos-show' a global
53 ;; key binding in your init file, since it is one of the entry points
54 ;; to Todos mode; a good choice is `C-c t', since `todos-show' is
55 ;; bound to `t' in Todos mode.
57 ;; To see a list of all Todos mode commands and their key bindings,
58 ;; including other entry points, type `C-h m' in Todos mode. Consult
59 ;; the document strings of the commands for details of their use. The
60 ;; `todos' customization group and its subgroups list the options you
61 ;; can set to alter the behavior of many commands and various aspects
62 ;; of the display.
64 ;; This package is a new version of Oliver Seidel's todo-mode.el.
65 ;; While it retains the same basic organization and handling of todo
66 ;; lists and the basic UI, it significantly extends these and adds
67 ;; many features. This also required making changes to the internals,
68 ;; including the file format. To convert files in the old format to
69 ;; the new format, use the command `todos-convert-legacy-files'.
71 ;;; Code:
74 ;; For cl-remove-duplicates (in todos-insertion-commands-args) and
75 ;; cl-oddp.
78 ;; -----------------------------------------------------------------------------
79 ;;; Setting up Todos files, categories, and items
80 ;; -----------------------------------------------------------------------------
83 "Directory where user's Todos files are saved."
88 "Default value of `todos-files-function'.
89 This returns the case-insensitive alphabetically sorted list of
90 file truenames in `todos-directory' with the extension
102 "Function returning the value of the variable `todos-files'.
103 This function should take an optional argument that, if non-nil,
104 makes it return the value of the variable `todos-archives'."
115 "List of Todos files visited in this session by `todos-show'.
116 Used to determine initial display according to the value of
123 "Variable holding name of current Todos file.
124 Used by functions called from outside of Todos mode to visit the
125 current Todos file rather than the default Todos file (i.e. when
132 "Alist of categories in the current Todos file.
133 The elements are cons cells whose car is a category name and
134 whose cdr is a vector of the category's item counts. These are,
135 in order, the numbers of todo items, of todo items included in
139 "Variable holding the number of the current Todos category.
152 "String determining the value of variable `todos-done-separator'.
153 If the string consists of a single character,
154 `todos-done-separator' will be the string made by repeating this
155 character for the width of the window, and the length is
156 automatically recalculated when the window width changes. If the
157 string consists of more (or less) than one character, it will be
158 the value of `todos-done-separator'."
165 "Return string used as value of variable `todos-done-separator'."
168 ;; Until bug#2749 is fixed, if separator's length
169 ;; is window-width and todos-wrap-lines is
170 ;; non-nil, an indented empty line appears between
171 ;; the separator and the first done item.
172 ;; (make-string (window-width) (string-to-char sep))
174 todos-done-separator-string)
178 "String used to visually separate done from not done items.
179 Displayed as an overlay instead of `todos-category-done' when
180 done items are shown. Its value is determined by user option
184 "If non-nil display only done items in current category.
185 Set by the command `todos-toggle-view-done-only' and used by
189 "List of strings surrounding item date to block diary inclusion.
190 The first string is inserted before the item date and must be a
191 non-empty string that does not match a diary date in order to
192 have its intended effect. The second string is inserted after
193 the diary date."
207 "Array of month names, in order.
212 "Array of abbreviated month names, in order.
220 todos-month-name-array
221 todos-month-abbrev-array)))
229 ;; By itself this matches anything, because of the `?'; however, it's only
230 ;; used in the context of `todos-date-pattern' (but Emacs Lisp lacks
231 ;; lookahead).
238 "Identifying string appended to the front of done todos items."
250 todos-date-pattern)
253 ;; -----------------------------------------------------------------------------
254 ;;; Todos mode display options
255 ;; -----------------------------------------------------------------------------
258 "String prefixed to todo items for visual distinction."
263 widget :error
265 widget)))
271 "Non-nil to prefix items with consecutively increasing integers.
272 These reflect the priorities of the items in each category."
279 "Return a mode line control for todo or archive file buffers.
280 Argument CAT is the name of the current Todos category.
281 This function is the value of the user variable
282 `todos-mode-line-function'."
287 "Function that returns a mode line control for Todos buffers.
288 The function expects one argument holding the name of the current
289 Todos category. The resulting control becomes the local value of
290 `mode-line-buffer-identification' in each Todos buffer."
295 "Non-nil means highlight items at point."
302 "Non-nil to activate Visual Line mode and use wrap prefix."
307 "Number of spaces to indent continuation lines of items.
308 This must be a positive number to ensure such items are fully
309 shown in the Fancy Diary display."
315 widget)))
319 "Indent from point to `todos-indent-to-here'."
323 "Non-nil to display done items in all categories."
327 ;; -----------------------------------------------------------------------------
328 ;;; Faces
329 ;; -----------------------------------------------------------------------------
332 ;; '((t :inherit font-lock-warning-face))
354 "Face for marks on marked items."
358 ;; '((t :inherit font-lock-constant-face))
369 "Face for Todos prefix or numerical priority string."
373 ;; bold font-lock-comment-face
384 "Face for top priority Todos item numerical priority string.
385 The item's priority number string has this face if the number is
386 less than or equal the category's top priority setting."
390 ;; '((t :inherit font-lock-type-face))
399 "Face for non-diary markers around todo item date/time header."
404 "Face for the date string of a Todos item."
409 "Face for the time string of a Todos item."
413 ;; Doesn't contrast enough with todos-date (= diary) face.
414 ;; ;; '((t :inherit warning))
415 ;; '((default :weight bold)
416 ;; (((class color) (min-colors 16)) :foreground "DarkOrange")
417 ;; (((class color)) :foreground "yellow"))
418 ;; bold font-lock-function-name-face
426 "Face for expired dates of diary items."
430 ;; '((t :inherit font-lock-builtin-face))
439 "Face for separator string bewteen done and not done Todos items."
443 ;; '((t :inherit font-lock-keyword-face))
452 "Face for done Todos item header string."
456 ;; '((t :inherit font-lock-comment-face))
474 "Face for comments appended to done Todos items."
478 ;; '((t :inherit match))
500 "Face for matches found by `todos-search'."
504 ;; '((t :inherit widget-field))
515 "Face for buttons in table of categories."
529 "Face for sorted column in table of categories."
533 ;; '((t (:inherit (shadow))))
542 "Face for archived-only category names in table of categories."
546 ;; '((t :inherit font-lock-type-face))
555 "Face for category-file header in Todos Filtered Items mode."
558 ;; -----------------------------------------------------------------------------
559 ;;; Entering and exiting Todos
560 ;; -----------------------------------------------------------------------------
563 "List of file finding commands for `todos-display-as-todos-file'.
564 Invoking these commands to visit a Todos or Todos Archive file
565 calls `todos-show' or `todos-find-archive', so that the file is
566 displayed correctly."
571 "Return short form of Todos FILE.
572 This lacks the extension and directory components."
578 "Todos file visited by first session invocation of `todos-show'."
585 "Non-nil to make `todos-show' visit the current Todos file.
586 Otherwise, `todos-show' always visits `todos-default-todos-file'."
593 "What action to take on first use of `todos-show' on a file."
602 "Non-nil to prompt for an item after adding a new category."
607 "Default file name offered on adding first Todos file."
612 "Default category name offered on initializing a new Todos file."
617 "List of files for building `todos-read-category' completions."
624 "Non-nil means case is ignored by `todos-read-*' functions."
629 "Visit a Todos file and display one of its categories.
631 When invoked in Todos mode, prompt for which todo file to visit.
632 When invoked outside of Todos mode with non-nil prefix argument
633 SOLICIT-FILE prompt for which todo file to visit; otherwise visit
634 `todos-default-todos-file'. Subsequent invocations from outside
635 of Todos mode revisit this file or, with option
636 `todos-show-current-file' non-nil (the default), whichever Todos
637 file was last visited.
639 Calling this command before any Todos file exists prompts for a
640 file name and an initial category (defaulting to
641 `todos-initial-file' and `todos-initial-category'), creates both
642 of these, visits the file and displays the category, and if
643 option `todos-add-item-if-new-category' is non-nil (the default),
644 prompts for the first item.
646 The first invocation of this command on an existing Todos file
647 interacts with the option `todos-show-first': if its value is
648 `first' (the default), show the first category in the file; if
649 its value is `table', show the table of categories in the file;
650 if its value is one of `top', `diary' or `regexp', show the
651 corresponding saved top priorities, diary items, or regexp items
652 file, if any. Subsequent invocations always show the file's
653 current (i.e., last displayed) category.
655 In Todos mode just the category's unfinished todo items are shown
656 by default. The done items are hidden, but typing
658 items. With non-nil user option `todos-show-with-done' both todo
659 and done items are always shown on visiting a category.
661 Invoking this command in Todos Archive mode visits the
662 corresponding Todos file, displaying the corresponding category."
669 todos-archive-mode
670 todos-filtered-items-mode))))
673 nil t)
676 ;; Called noninteractively via todos-quit
677 ;; to jump to corresponding category in
678 ;; todo file.
686 todos-global-current-todos-file)
689 add-item first-file)
691 ;; We just initialized the first todo file, so make it the default.
693 first-file t)
696 ;; Can't setq t-c-t-f here, otherwise wrong file shown when
697 ;; todos-show is called from todos-show-categories-table.
704 shortf todos-show-first)))
712 "Choose a regexp items file: "
725 shortf)
731 ;; When quitting archive file, show corresponding category in
732 ;; Todos file, if it exists.
735 ;; If this is a new Todos file, add its first category.
741 add-item todos-add-item-if-new-category
742 cat-added t)
744 ;; If the category was added, save the file now, so we
745 ;; don't risk having an empty todo file, which would
746 ;; signal an error if we tried to visit it later,
747 ;; since doing that looks for category boundaries.
749 ;; If user cancels before adding the category, clean up
750 ;; and exit, so we have a fresh slate the next time.
755 todos-current-todos-file nil))
764 "Save the current Todos file."
775 "Exit the current Todos-related buffer.
776 Depending on the specific mode, this either kills the buffer or
777 buries it and restores state as needed."
781 ;; Postpone killing buffer till after calling todos-show, to
782 ;; prevent killing todos-mode buffer.
784 ;; Ensure todos-show calls todos-show-categories-table only on
785 ;; first invocation per file.
794 ;; Have to write a newly created archive to file to avoid
795 ;; subsequent errors.
801 ;; If we just quit archive mode, just burying the buffer
802 ;; in todos-mode would return to archive.
807 ;; -----------------------------------------------------------------------------
808 ;;; Navigation between and within categories
809 ;; -----------------------------------------------------------------------------
812 "Non-nil to handle categories with only archived items specially.
816 archived items. Other commands still recognize these categories.
818 categories shown in `todos-archived-only' face and pressing the
819 category button visits the category in the archive instead of the
820 todo file."
825 "Visit the numerically next category in this Todos file.
826 If the current category is the highest numbered, visit the first
827 category. With non-nil argument BACK, visit the numerically
828 previous category (the highest numbered one, if the current
829 category is the first)."
844 "Visit the numerically previous category in this Todos file.
845 If the current category is the highest numbered, visit the first
846 category."
853 "Prompt for a category in a Todos file and jump to it.
855 With non-nil FILE (interactively a prefix argument), prompt for a
856 specific Todos file and choose (with TAB completion) a category
857 in it to jump to; otherwise, choose and jump to any category in
858 either the current Todos file or a file in
859 `todos-category-completions-files'.
861 Also accept a non-existing category name and ask whether to add a
862 new category by that name; on confirmation, add it and jump to
863 that category, and if option `todos-add-item-if-new-category' is
864 non-nil (the default), then prompt for the first item.
866 In noninteractive calls non-nil WHERE specifies either the goal
867 category or its file. If its value is `archive', the choice of
868 categories is restricted to the current archive file or the
869 archive you were prompted to choose; this is used by
870 `todos-jump-to-archive-category'. If its value is the name of a
871 category, jump directly to that category; this is used in Todos
872 Categories mode."
874 ;; If invoked outside of Todos mode and there is not yet any Todos
875 ;; file, initialize one.
881 ;; With non-nil `todos-skip-archived-categories'
882 ;; jump to archive file of a category with only
883 ;; archived items.
890 ;; Otherwise, jump to current todos file.
891 todos-current-todos-file)))
902 ;; If called from Todos Categories mode, clean up before jumping.
915 "Move point down to the beginning of the next item.
916 With positive numerical prefix COUNT, move point COUNT items
917 downward.
919 If the category's done items are hidden, this command also moves
920 point to the empty line below the last todo item from any higher
921 item in the category, i.e., when invoked with or without a prefix
922 argument. If the category's done items are visible, this command
923 called with a prefix argument only moves point to a lower item,
924 e.g., with point on the last todo item and called with prefix 1,
925 it moves point to the first done item; but if called with point
926 on the last todo item without a prefix argument, it moves point
927 the the empty line above the done items separator."
929 ;; It's not worth the trouble to allow prefix arg value < 1, since we have
930 ;; the corresponding command.
939 "Move point up to start of item with next higher priority.
940 With positive numerical prefix COUNT, move point COUNT items
941 upward.
943 If the category's done items are visible, this command called
944 with a prefix argument only moves point to a higher item, e.g.,
945 with point on the first done item and called with prefix 1, it
946 moves to the last todo item; but if called with point on the
947 first done item without a prefix argument, it moves point the the
948 empty line above the done items separator."
950 ;; Avoid moving to bob if on the first item but not at bob.
952 ;; It's not worth the trouble to allow prefix arg value < 1, since we have
953 ;; the corresponding command.
961 ;; -----------------------------------------------------------------------------
962 ;;; Display toggle commands
963 ;; -----------------------------------------------------------------------------
966 "Hide item numbering if shown, show if hidden."
981 "Show hidden or hide visible done items in current category."
991 ;; If start of done items sections is below the bottom of the
992 ;; window, make it visible.
1002 "Switch between displaying only done or only todo items."
1008 "Highlight or unhighlight the todo item the cursor is on."
1018 "Hide or show item date-time headers in the current file.
1019 With done items, this hides only the done date-time string, not
1020 the the original date-time string."
1035 nil t)
1041 ;; -----------------------------------------------------------------------------
1042 ;;; File and category editing
1043 ;; -----------------------------------------------------------------------------
1046 "Name and initialize a new Todos file.
1047 Interactively, prompt for a category and display it, and if
1048 option `todos-add-item-if-new-category' is non-nil (the default),
1049 prompt for the first item.
1050 Noninteractively, return the name of the new file."
1054 file)
1068 file)))
1074 "Put current buffer in `todos-edit-mode'.
1075 This makes the entire file visible and the buffer writeable and
1076 you can use the self-insertion keys and standard Emacs editing
1077 commands to make changes. To return to Todos mode, type
1079 an error if the format has become invalid. However, this check
1080 cannot tell if the number of items changed, which could result in
1081 the file containing inconsistent information. For this reason
1082 this command should be used with caution."
1092 "Add a new category to a Todos file.
1094 Called interactively with prefix argument FILE, prompt for a file
1095 and then for a new category to add to that file, otherwise prompt
1096 just for a category to add to the current Todos file. After
1097 adding the category, visit it in Todos mode and if option
1098 `todos-add-item-if-new-category' is non-nil (the default), prompt
1099 for the first item.
1101 Non-interactively, add category CAT to file FILE; if FILE is nil,
1102 add CAT to the current Todos file. After adding the category,
1103 return the new category number."
1106 ;; If cat is passed from caller, don't prompt, unless it is "",
1107 ;; which means the file was just added and has no category yet.
1110 todos-current-todos-file))
1113 file))
1117 file)))
1130 ;; If invoked by user, display the newly added category, if
1131 ;; called programmatically return the category number to the
1132 ;; caller.
1139 num))))
1142 "Rename current Todos category.
1143 If this file has an archive containing this category, rename the
1144 category there as well."
1167 nil t)
1173 "Delete current Todos category provided it is empty.
1174 With ARG non-nil delete the category unconditionally,
1175 i.e. including all existing todo and done items."
1195 "after deleting the todo category. "
1197 "(see `todos-skip-archived-categories' "
1216 ;; If deleted category was the only one, delete the file.
1219 ;; Skip confirming killing the archive buffer if it has been
1220 ;; modified and not saved.
1226 todos-categories))
1235 "Move current category to a different Todos file.
1236 If current category has archived items, also move those to the
1237 archive of the file moved to, creating it if it does not exist."
1251 new)
1263 nil t))
1271 buffer-read-only)
1272 ;; Move the category to the new file. Also update or create
1273 ;; archive file if necessary.
1276 ;; Regenerate todos-archives in case there
1277 ;; is a newly created archive.
1280 nfile))
1284 nfile-short)
1287 buffer-read-only)
1291 ;; If the file moved to has a category with the same
1292 ;; name, rename the moved category.
1298 ;; Replace old with new name in Todos and archive files.
1308 ;; If archive was just created, save it to avoid "File
1309 ;; <xyz> no longer exists!" message on invoking
1310 ;; `todos-view-archived-items'.
1315 ;; Delete the category from the old file, and if that was the
1316 ;; last category, delete the file. Also handle archive file
1317 ;; if necessary.
1321 ;; Put point after todos-categories sexp.
1325 ;; Skip confirming killing the archive buffer.
1332 todos-categories))
1341 "Merge current category into another existing category.
1343 With prefix argument FILE, prompt for a specific Todos file and
1344 choose (with TAB completion) a category in it to merge into;
1345 otherwise, choose and merge into a category in either the
1346 current Todos file or a file in `todos-category-completions-files'.
1348 After merging, the current category's todo and done items are
1349 appended to the chosen goal category's todo and done items,
1350 respectively. The goal category becomes the current category,
1351 and the previous current category is deleted.
1353 If both the first and goal categories also have archived items,
1354 the former are merged to the latter. If only the first category
1355 has archived items, the archived category is renamed to the goal
1356 category."
1365 archived-count here)
1366 ;; Merge in todo file.
1379 ;; Omit empty line between todo and done items.
1391 ;; Merge any todo items.
1395 nil t)
1402 ;; Merge any done items.
1414 todos-categories))
1418 ;; Merge in archive file.
1427 nil t)
1434 nil t)
1437 cend carch)
1443 nil t)
1448 ;; If both categories of the merge have archived items, merge the
1449 ;; source items to the goal items, else "merge" by renaming the
1450 ;; source category to goal.
1455 nil t)
1472 ;; If there are only merged done items, show them.
1475 ;; Put point on the first merged item.
1479 ;; -----------------------------------------------------------------------------
1480 ;;; Item editing
1481 ;; -----------------------------------------------------------------------------
1484 "Non-nil to allow new Todo items to be included in the diary."
1489 "Non-nil to insert new Todo diary items as nonmarking by default.
1490 This appends `diary-nonmarking-symbol' to the front of an item on
1491 insertion provided it doesn't begin with `todos-nondiary-marker'."
1496 "Non-nil adds current time to a new item's date header by default.
1498 argument, this reverses the effect of
1499 `todos-always-add-time-string': if t, these commands omit the
1500 current time, if nil, they include it."
1505 "Non-nil to enable inserting only highlighted region as new item."
1510 "String used to mark items.
1511 To ensure item marking works, change the value of this option
1512 only when no items are marked."
1517 widget :error
1519 widget)))
1525 "String inserted before optional comment appended to done item."
1532 "Whether to omit done item comment on undoing the item.
1533 Nil means never omit the comment, t means always omit it, `ask'
1534 means prompt user and omit comment only on confirmation."
1541 "Mark item with `todos-item-mark' if unmarked, otherwise unmark it.
1542 With a positive numerical prefix argument N, change the
1543 marking of the next N items."
1569 "Mark all visiblw items in this category with `todos-item-mark'."
1586 "Remove `todos-item-mark' from all visible items in this category."
1594 ;; No overlay on empty line between todo and done items.
1606 region-or-here)
1607 "Insert a new Todo item into a category.
1608 This is the function from which the generated Todos item
1609 insertion commands derive.
1611 The generated commands have mnenomic key bindings based on the
1612 arguments' values and their order in the command's argument list,
1613 as follows: (1) for DIARY `d', (2) for NONMARKING `k', (3) for
1614 DATE-TYPE either `c' for calendar or `d' for date or `n' for
1615 weekday name, (4) for TIME `t', (5) for REGION-OR-HERE either `r'
1616 for region or `h' for here. Sequences of these keys are appended
1617 to the insertion prefix key `i'. Keys that allow a following
1618 key (i.e., any but `r' or `h') must be doubled when used finally.
1619 For example, the command bound to the key sequence `i y h' will
1620 insert a new item with today's date, marked according to the
1621 DIARY argument described below, and with priority according to
1622 the HERE argument; `i y y' does the same except that the priority
1623 is not given by HERE but by prompting.
1625 In command invocations, ARG is passed as a prefix argument as
1626 follows. With no prefix argument, add the item to the current
1627 category; with one prefix argument (`C-u'), prompt for a category
1628 from the current Todos file; with two prefix arguments (`C-u C-u'),
1629 first prompt for a Todos file, then a category in that file. If
1630 a non-existing category is entered, ask whether to add it to the
1631 Todos file; if answered affirmatively, add the category and
1632 insert the item there.
1634 The remaining arguments are set or left nil by the generated item
1635 insertion commands; their meanings are described in the follows
1636 paragraphs.
1638 When argument DIARY is non-nil, this overrides the intent of the
1639 user option `todos-include-in-diary' for this item: if
1640 `todos-include-in-diary' is nil, include the item in the Fancy
1641 Diary display, and if it is non-nil, exclude the item from the
1642 Fancy Diary display. When DIARY is nil, `todos-include-in-diary'
1643 has its intended effect.
1645 When the item is included in the Fancy Diary display and the
1646 argument NONMARKING is non-nil, this overrides the intent of the
1647 user option `todos-diary-nonmarking' for this item: if
1648 `todos-diary-nonmarking' is nil, append `diary-nonmarking-symbol'
1649 to the item, and if it is non-nil, omit `diary-nonmarking-symbol'.
1651 The argument DATE-TYPE determines the content of the item's
1652 mandatory date header string and how it is added:
1653 - If DATE-TYPE is the symbol `calendar', the Calendar pops up and
1654 when the user puts the cursor on a date and hits RET, that
1655 date, in the format set by `calendar-date-display-form',
1656 becomes the date in the header.
1657 - If DATE-TYPE is a string matching the regexp
1658 `todos-date-pattern', that string becomes the date in the
1659 header. This case is for the command
1660 `todos-insert-item-from-calendar' which is called from the
1661 Calendar.
1662 - If DATE-TYPE is the symbol `date', the header contains the date
1663 in the format set by `calendar-date-display-form', with year,
1664 month and day individually prompted for (month with tab
1665 completion).
1666 - If DATE-TYPE is the symbol `dayname' the header contains a
1667 weekday name instead of a date, prompted for with tab
1668 completion.
1669 - If DATE-TYPE has any other value (including nil or none) the
1670 header contains the current date (in the format set by
1671 `calendar-date-display-form').
1673 With non-nil argument TIME prompt for a time string, which must
1674 match `diary-time-regexp'. Typing `<return>' at the prompt
1675 returns the current time, if the user option
1676 `todos-always-add-time-string' is non-nil, otherwise the empty
1677 string (i.e., no time string). If TIME is absent or nil, add or
1678 omit the current time string according as
1679 `todos-always-add-time-string' is non-nil or nil, respectively.
1681 The argument REGION-OR-HERE determines the source and location of
1682 the new item:
1683 - If the REGION-OR-HERE is the symbol `here', prompt for the text of
1684 the new item and, if the command was invoked with point in the todo
1685 items section of the current category, give the new item the
1686 priority of the item at point, lowering the latter's priority and
1687 the priority of the remaining items. If point is in the done items
1688 section of the category, insert the new item as the first todo item
1689 in the category. Likewise, if the command with `here' is invoked
1690 outside of the current category, jump to the chosen category and
1691 insert the new item as the first item in the category.
1692 - If REGION-OR-HERE is the symbol `region', use the region of the
1693 current buffer as the text of the new item, depending on the
1694 value of user option `todos-use-only-highlighted-region': if
1695 this is non-nil, then use the region only when it is
1696 highlighted; otherwise, use the region regardless of
1697 highlighting. An error is signalled if there is no region in
1698 the current buffer. Prompt for the item's priority in the
1699 category (an integer between 1 and one more than the number of
1700 items in the category), and insert the item accordingly.
1701 - If REGION-OR-HERE has any other value (in particular, nil or
1702 none), prompt for the text and the item's priority, and insert
1703 the item accordingly."
1704 ;; If invoked outside of Todos mode and there is not yet any Todos
1705 ;; file, initialize one.
1727 todos-global-current-todos-file)
1729 todos-default-todos-file))))))
1744 ;; If user exits Calendar before choosing
1745 ;; a date, cancel item insertion.
1761 ;; If this command was invoked outside of a Todos buffer, the
1762 ;; call to todos-current-category above returned nil. If we
1763 ;; just entered Todos mode now, then cat was set to the file's
1764 ;; first category, but if todos-mode was already enabled, cat
1765 ;; did not get set, so we have to set it explicitly.
1773 done-only item-added)
1775 ;; Add date, time and diary marking as required.
1777 todos-nondiary-start
1779 diary-nonmarking-symbol))
1782 time-string))))
1785 todos-nondiary-end)
1787 ;; Indent newlines inserted by C-q C-j if nonspace char follows.
1792 ;; Make sure the correct category is selected. There
1793 ;; are two cases: (i) we just visited the file, so no
1794 ;; category is selected yet, or (ii) we invoked
1795 ;; insertion "here" from outside the category we want
1796 ;; to insert in (with priority insertion, category
1797 ;; selection is done by todos-set-item-priority).
1802 ;; If only done items are displayed in category,
1803 ;; toggle to todo items before inserting new item.
1811 ;; If command was invoked with point in done
1812 ;; items section or outside of the current
1813 ;; category, can't insert "here", so to be
1814 ;; useful give new item top priority.
1816 called-from-outside
1817 done-only)
1822 ;; If user cancels before setting priority, restore
1823 ;; display.
1833 ;; If the todo items section is not visible when the
1834 ;; insertion command is called (either because only done
1835 ;; items were shown or because the category was not in the
1836 ;; current buffer), then if the item is inserted at the
1837 ;; end of the category, point is at eob and eob at
1838 ;; window-start, so that higher priority todo items are
1839 ;; out of view. So we recenter to make sure the todo
1840 ;; items are displayed in the window.
1847 "Return string of date chosen from Calendar."
1850 todos-date-from-calendar)
1855 ;; If user exits Calendar before choosing a date, clean up properly.
1869 todos-date-from-calendar)
1874 todos-date-from-calendar)))))
1877 "Prompt for and insert a new item with date selected from calendar.
1878 Invoked without prefix argument ARG, insert the item into the
1879 current category, without one prefix argument, prompt for the
1880 category from the current todo file or from one listed in
1881 `todos-category-completions-files'; with two prefix arguments,
1882 prompt for a todo file and then for a category in it."
1892 "Copy item at point and insert the copy as a new item."
1903 "Delete at least one item in this category.
1904 If there are marked items, delete all of these; otherwise, delete
1905 the item at point."
1921 buffer-read-only)
1935 ;; Don't leave point below last item.
1949 "Edit the Todo item at point.
1950 With non-nil prefix argument ARG, include the item's date/time
1951 header, making it also editable; otherwise, include only the item
1952 content.
1954 If the item consists of only one logical line, edit it in the
1955 minibuffer; otherwise, edit it in Todos Edit mode."
1983 ;; Ensure lines following hard newlines are indented.
1986 ;; If user moved point during editing, make sure it moves back.
1993 "Edit current Todo item in Todos Edit mode.
1994 Use of newlines invokes `todos-indent' to insure compliance with
1995 the format of Diary entries."
2008 "Return from Todos Edit mode to Todos mode.
2009 If the item contains hard line breaks, make sure the following
2010 lines are indented by `todos-indent-to-here' to conform to diary
2011 format.
2013 If the whole file was in Todos Edit mode, check before returning
2014 whether the file is still a valid Todos file and if so, also
2015 recalculate the Todos categories sexp, in case changes were made
2016 in the number or names of categories."
2019 ;; We got here via `e m'.
2027 ;; Ensure lines following hard newlines are indented.
2035 ;; We got here via `F e'.
2037 ;; FIXME: separate out sexp check?
2038 ;; If manual editing makes e.g. item counts change, have to
2039 ;; call this to update todos-categories, but it restores
2040 ;; category order to list order.
2041 ;; (todos-repair-categories-sexp)
2042 ;; Compare (todos-make-categories-list t) with sexp and if
2043 ;; different ask (todos-update-categories-sexp) ?
2059 "Function underlying commands to edit item date/time header.
2061 The argument WHAT (passed by invoking commands) specifies what
2062 part of the header to edit; possible values are these symbols:
2063 `date', to edit the year, month, and day of the date string;
2064 `time', to edit just the time string; `calendar', to select the
2065 date from the Calendar; `today', to set the date to today's date;
2066 `dayname', to set the date string to the name of a day or to
2067 change the day name; and `year', `month' or `day', to edit only
2068 these respective parts of the date string (`day' is the number of
2069 the given day of the month, and `month' is either the name of the
2070 given month or its number, depending on the value of
2071 `calendar-date-display-form').
2073 The optional argument INC is a positive or negative integer
2074 \(passed by invoking commands as a numerical prefix argument)
2075 that in conjunction with the WHAT values `year', `month' or
2076 `day', increments or decrements the specified date string
2077 component by the specified number of suitable units, i.e., years,
2078 months, or days, with automatic adjustment of the other date
2079 string components as necessary.
2081 If there are marked items, apply the same edit to all of these;
2082 otherwise, edit just the item at point."
2088 ndate ntime year monthname month day
2099 todos-date-pattern
2123 ;; If there are marked items, use only the first to set
2124 ;; header changes, and apply these to all marked items.
2139 ;; When date string consists only of a day name,
2140 ;; passing other date components is a noop.
2144 monthname omonthname
2145 month omonth
2154 year oyear
2156 month
2157 monthname)
2164 ;; Increment or decrement month by INC
2165 ;; modulo 12.
2167 ;; If result is 0, make month December.
2169 ;; Adjust year if necessary.
2176 oyear)))
2177 ;; Return the changed numerical month as
2178 ;; a string or the corresponding month name.
2183 ;; When mm is 13 (corresponding to "*" as value
2184 ;; of month), this raises an args-out-of-range
2185 ;; error in calendar-last-day-of-month, so use 1
2186 ;; (corresponding to January) to get 31 days.
2195 month omonth
2196 monthname omonthname
2207 ;; Increment or decrement day by INC,
2208 ;; adjusting month and year if necessary
2209 ;; (if year is "*" assume current year to
2210 ;; calculate adjustment).
2218 ;; Set year and month(name) to adjusted values.
2224 ;; Return changed numerical day as a string.
2227 ;; If year, month or day date string components were
2228 ;; changed, rebuild the date string.
2232 ;; Add new time string to the header, if it was supplied.
2240 ;; Apply the changes to the first marked item header to the
2241 ;; remaining marked items. If there are no marked items,
2242 ;; we're finished.
2248 "Interactively edit at least the date of item's date/time header.
2249 If user option `todos-always-add-time-string' is non-nil, also
2250 edit item's time string."
2257 "Interactively edit the time string of item's date/time header."
2262 "Interactively edit item's date using the Calendar."
2267 "Set item's date to today's date."
2272 "Replace item's date with the name of a day of the week."
2277 "Interactively edit the year of item's date string.
2278 With prefix argument INC a positive or negative integer,
2279 increment or decrement the year by INC."
2284 "Interactively edit the month of item's date string.
2285 With prefix argument INC a positive or negative integer,
2286 increment or decrement the month by INC."
2291 "Interactively edit the day of the month of item's date string.
2292 With prefix argument INC a positive or negative integer,
2293 increment or decrement the day by INC."
2298 "Change diary status of one or more todo items in this category.
2299 That is, insert `todos-nondiary-marker' if the candidate items
2300 lack this marking; otherwise, remove it.
2302 If there are marked todo items, change the diary status of all
2303 and only these, otherwise change the diary status of the item at
2304 point."
2308 todos-categories-with-marks)))
2337 "Make all items in this category diary items.
2338 With prefix ARG, make all items in this category non-diary
2339 items."
2372 "Change non-marking of one or more diary items in this category.
2373 That is, insert `diary-nonmarking-symbol' if the candidate items
2374 lack this marking; otherwise, remove it.
2376 If there are marked todo items, change the non-marking status of
2377 all and only these, otherwise change the non-marking status of
2378 the item at point."
2382 todos-categories-with-marks)))
2399 "Add `diary-nonmarking-symbol' to all diary items in this category.
2400 With prefix ARG, remove `diary-nonmarking-symbol' from all diary
2401 items in this category."
2419 "Prompt for and set ITEM's priority in CATegory.
2421 Interactively, ITEM is the todo item at point, CAT is the current
2422 category, and the priority is a number between 1 and the number
2423 of items in the category. Non-interactively, non-nil NEW means
2424 ITEM is a new item and the lowest priority is one more than the
2425 number of items in CAT.
2427 The new priority is set either interactively by prompt or by a
2428 numerical prefix argument, or noninteractively by argument ARG,
2429 whose value can be either of the symbols `raise' or `lower',
2430 meaning to raise or lower the item's priority by one."
2441 todos-date-pattern
2448 curnum
2459 count)))
2465 current-prefix-arg)
2470 candidate
2471 buffer-read-only)
2475 ;; When moving item to another category, show the category before
2476 ;; prompting for its priority.
2479 ;; If done items in category are visible, keep them visible.
2487 ;; Keep top of category in view while setting priority.
2489 ;; Prompt for priority only when the category has at least one
2490 ;; todo item.
2496 maxnum)))
2498 ;; In Top Priorities buffer, an item's priority can be changed
2499 ;; wrt items in another category, but not wrt items in the same
2500 ;; category.
2522 ;; Interactively or with non-nil ARG, relocate the item within its
2523 ;; category.
2530 ;; When called from todos-item-undone and the highest priority
2531 ;; is chosen, this advances point to the first done item, so
2532 ;; move it up to the empty line above the done items
2533 ;; separator.
2539 ;; If item was marked, restore the mark.
2547 "Raise priority of current item by moving it up by one item."
2552 "Lower priority of current item by moving it down by one item."
2557 "Move at least one todo or done item to another category.
2558 If there are marked items, move all of these; otherwise, move
2559 the item at point.
2561 With prefix argument FILE, prompt for a specific Todos file and
2562 choose (with TAB completion) a category in it to move the item or
2563 items to; otherwise, choose and move to any category in either
2564 the current Todos file or one of the files in
2565 `todos-category-completions-files'. If the chosen category is
2566 not an existing categories, then it is created and the item(s)
2567 become(s) the first entry/entries in that category.
2569 With moved Todo items, prompt to set the priority in the category
2570 moved to (with multiple todos items, the one that had the highest
2571 priority in the category moved from gets the new priority and the
2572 rest of the moved todo items are inserted in sequence below it).
2573 Moved done items are appended to the top of the done items
2574 section in the category moved to."
2578 ;; Noop if point is not on an item and there are no marked items.
2591 ov cat2 file2 moved nmark todo-items done-items)
2601 nil file)))
2625 ;; Chop off last newline of multiple todo item string,
2626 ;; since it will be reinserted when setting priority
2627 ;; (but with done items priority is not set, so keep
2628 ;; last newline).
2641 ;; Move done items en bloc to top of done items section.
2655 ;; Move succeeded, so remove item from starting category,
2656 ;; update item counts and display the category containing
2657 ;; the moved item.
2700 ;; If item is moved to end of (just first?) category, make
2701 ;; sure the items above it are displayed in the window.
2703 ;; User quit before setting priority of todo item(s), so
2704 ;; return to starting category.
2713 "Tag a todo item in this category as done and relocate it.
2715 With prefix argument ARG prompt for a comment and append it to
2716 the done item; this is only possible if there are no marked
2717 items. If there are marked items, tag all of these with
2718 `todos-done-string' plus the current date and, if
2719 `todos-always-add-time-string' is non-nil, the current time;
2720 otherwise, just tag the item at point. Items tagged as done are
2721 relocated to the category's (by default hidden) done section. If
2722 done items are visible on invoking this command, they remain
2723 visible."
2744 ;; Point is between todo and done items.
2760 item done-item opoint)
2761 ;; Don't add empty comment to done item.
2766 ;; Stop looping when we hit the empty line below the last
2767 ;; todo item (this is eobp if only done items are hidden).
2781 ;; Chop off last newline of done item string.
2798 ;; When done items are shown, put cursor on first just done item.
2802 "Add a comment to this done item or edit an existing comment.
2803 With prefix ARG delete an existing comment."
2809 comment buffer-read-only)
2822 ;; If user moved point during editing, make sure it moves back.
2828 "Restore at least one done item to this category's todo section.
2829 Prompt for the new priority. If there are marked items, undo all
2830 of these, giving the first undone item the new priority and the
2831 rest following directly in sequence; otherwise, undo just the
2832 item at point.
2834 If the done item has a comment, ask whether to omit the comment
2835 from the restored item. With multiple marked done items with
2836 comments, only ask once, and if affirmed, omit subsequent
2837 comments without asking."
2849 start end item ov npoint undone)
2861 ;; Find the end of the date string added upon tagging item as
2862 ;; done.
2868 ;; Ask (once) whether to omit done item's comment. If
2869 ;; affirmed, omit subsequent comments without asking.
2879 " from restored item"
2883 t)
2894 ;; Chop off last newline of multiple items string, since
2895 ;; it will be reinserted on setting priority.
2922 ;; Put cursor on undone item.
2926 ;; -----------------------------------------------------------------------------
2927 ;;; Done item archives
2928 ;; -----------------------------------------------------------------------------
2931 "Visit the archive of the current Todos category, if it exists.
2932 If the category has no archived items, prompt to visit the
2933 archive anyway. If there is no archive for this file or with
2934 non-nil argument ASK, prompt to visit another archive.
2936 The buffer showing the archive is in Todos Archive mode. The
2937 first visit in a session displays the first category in the
2938 archive, subsequent visits return to the last category
2939 displayed."
2945 place)
2968 "Choose an archive and visit it."
2973 "Archive at least one done item in this category.
2975 With prefix argument ALL, prompt whether to archive all done
2976 items in this category and on confirmation archive them.
2977 Otherwise, if there are marked done items (and no marked todo
2978 items), archive all of these; otherwise, archive the done item at
2979 point.
2981 If the archive of this file does not exist, it is created. If
2982 this category does not exist in the archive, it is created."
3000 marked-items beg end all-done
3001 buffer-read-only)
3011 nil t)
3016 nil t)
3021 ;; Restore starting point, unless it was on a done
3022 ;; item, since they will all be deleted.
3046 nil t)
3048 nil t))
3049 ;; Start of done items section in existing category.
3052 ;; Start of done items section in new category.
3059 ;; If archive is new, save to file now (using write-region in
3060 ;; order not to get prompted for file to save to), to let
3061 ;; auto-mode-alist take effect below.
3070 ;; Make sure done items are accessible.
3077 ;; If we're archiving all done items, can't
3078 ;; first archive item point was on, since
3079 ;; that will short-circuit the rest.
3089 ;; Don't leave point below last item.
3105 ;; Make todo file current to select category.
3107 ;; Make sure done item separator is hidden (if done items
3108 ;; were initially visible).
3112 "Unarchive at least one item in this archive category.
3113 If there are marked items, unarchive all of these; otherwise,
3114 unarchive the item at point.
3116 Unarchived items are restored as done items to the corresponding
3117 category in the Todos file, inserted at the top of done items
3118 section. If all items in the archive category have been
3119 restored, the category is deleted from the archive. If this was
3120 the only category in the archive, the archive file is deleted."
3130 marked-items
3131 buffer-read-only)
3140 ;; Restore items to top of category's done section and update counts.
3145 ;; Find the corresponding todo category, or if there isn't
3146 ;; one, add it.
3152 ;; Go to top of category's done section.
3167 ;; Delete restored items from archive.
3180 ;; If that was the last category in the archive, delete the whole file.
3184 ;; Kill the archive buffer silently.
3187 ;; Otherwise, if the archive category is now empty, delete it.
3192 nil t))
3201 todos-categories))
3203 ;; Visit category in Todos file and show restored done items.
3213 "Prompt for a category in a Todos archive and jump to it.
3214 With prefix argument FILE, prompt for an archive and choose (with
3215 TAB completion) a category in it to jump to; otherwise, choose
3216 and jump to any category in the current archive."
3220 ;; -----------------------------------------------------------------------------
3221 ;;; Displaying and sorting tables of categories
3222 ;; -----------------------------------------------------------------------------
3225 "Category button label in Todos Categories mode."
3230 "Todo button label in Todos Categories mode."
3235 "Diary button label in Todos Categories mode."
3240 "Done button label in Todos Categories mode."
3245 "Archived button label in Todos Categories mode."
3250 "String to label total item counts in Todos Categories mode."
3255 "String between number and category in Todos Categories mode.
3256 This separates the number from the category name in the default
3257 categories display according to priority."
3262 "Alignment of category names in Todos Categories mode."
3267 "Display a table of the current file's categories and item counts.
3269 In the initial display the categories are numbered, indicating
3272 order of the category at point by typing
3276 The labels above the category names and item counts are buttons,
3277 and clicking these changes the display: sorted by category name
3278 or by the respective item counts (alternately descending or
3279 ascending). In these displays the categories are not numbered
3282 sorting is triggered by passing a non-nil SORTKEY argument.)
3284 In addition, the lines with the category names and item counts
3285 are buttonized, and pressing one of these button jumps to the
3286 category in Todos mode (or Todos Archive mode, for categories
3287 containing only archived items, provided user option
3288 `todos-skip-archived-categories' is non-nil. These categories
3289 are shown in `todos-archived-only' face."
3296 "Move point to the Nth next button in the table of categories."
3300 ;; Align with beginning of category label.
3304 "Move point to the Nth previous button in the table of categories."
3308 ;; Align with beginning of category label.
3312 "Change number of category at point in the table of categories.
3314 With ARG nil, prompt for the new number. Alternatively, the
3315 enter the new number with numerical prefix ARG. Otherwise, if
3316 ARG is either of the symbols `raise' or `lower', raise or lower
3317 the category line in the table by one, respectively, thereby
3318 decreasing or increasing its number."
3321 ;; Get the number representing the priority of the category
3322 ;; on the current line.
3333 candidate)
3340 maxnum))
3349 todos-categories))
3350 ;; Category's name and items counts list.
3353 newcats)
3367 "Raise priority of category at point in Todos Categories buffer."
3372 "Lower priority of category at point in Todos Categories buffer."
3377 "Sort table of categories alphabetically or numerically."
3390 "Sort table of categories by number of todo items."
3398 "Sort table of categories by number of diary items."
3406 "Sort table of categories by number of non-archived done items."
3414 "Sort table of categories by number of archived items."
3425 "Return the length of the longest name in list CATEGORIES."
3431 "Return adjusted length of category label button.
3432 The adjustment ensures proper tabular alignment in Todos
3433 Categories mode."
3443 "Return category name or label string STR padded with spaces.
3444 The placement of the padding is determined by the value of user
3445 option `todos-categories-align'."
3465 "Return a copy of LIST, possibly sorted according to KEY."
3470 ;; Keep track of whether the last sort by key was descending or
3471 ;; ascending.
3481 ;; Switch between descending and ascending sort order.
3486 l))
3489 "Keep point on the TYPE count sorting button just clicked."
3495 "Return symbol for sort key associated with LABEL."
3507 key))
3510 "Insert button for displaying categories sorted by item counts.
3511 LABEL determines which type of count is sorted."
3514 label))
3517 ov)
3519 'action
3525 ;; If display is alphabetical, switch back to
3526 ;; category priority order.
3535 "Return a list of total item counts for the current file."
3544 "Insert button with category CAT's name and item counts.
3545 With non-nil argument NONUM show only these; otherwise, insert a
3546 number in front of the button indicating the category's priority.
3547 The number and the category name are separated by the string
3548 which is the value of the user option
3549 `todos-categories-number-separator'."
3560 str
3565 ;; Add an extra space if label length is odd.
3580 'todos-archived-only
3581 nil)
3585 ;; Highlight the sorted count column.
3587 end ovl)
3609 "Prepare buffer for displaying table of categories and item counts."
3619 buffer-read-only)
3626 ;; Make space for the column of category numbers.
3628 ;; Add the category and item count buttons (if this is the list of
3629 ;; categories in an archive, show only done item counts).
3646 "Populate table of categories and sort by SORTKEY."
3651 ;; Find start of Category button if we just entered Todos Categories
3652 ;; mode.
3661 ;; Fill in the table with buttonized lines, each showing a category and
3662 ;; its item counts.
3666 ;; Add a line showing item count totals.
3674 ;; Add an extra space if label length is odd.
3683 ;; Put cursor on Category button initially.
3687 ;; -----------------------------------------------------------------------------
3688 ;;; Searching and item filtering
3689 ;; -----------------------------------------------------------------------------
3692 "Search for a regular expression in this Todos file.
3693 The search runs through the whole file and encompasses all and
3694 only todo and done items; it excludes category names. Multiple
3695 matches are shown sequentially, highlighted in `todos-search'
3696 face."
3700 matches match cat in-done ov mlen msg)
3734 mlen)
3739 mlen)
3753 "Remove highlighting on matches found by todos-search."
3758 "List of rules specifying number of top priority items to show.
3759 These rules override `todos-top-priorities' on invocations of
3762 of the form (FILE NUM ALIST), where FILE is a member of
3763 `todos-files', NUM is a number specifying the default number of
3764 top priority items for each category in that file, and ALIST,
3765 when non-nil, consists of conses of a category name in FILE and a
3766 number specifying the default number of top priority items in
3767 that category, which overrides NUM.
3769 This variable should be set interactively by
3776 "Default number of top priorities shown by `todos-filter-top-priorities'."
3781 "List of default files for multifile item filtering."
3788 "Non-nil to include done items when processing regexp filters.
3789 Done items from corresponding archive files are also included."
3794 "Set number of top priorities for this file.
3795 See `todos-set-top-priorities' for more details."
3800 "Set number of top priorities for this category.
3801 See `todos-set-top-priorities' for more details."
3806 "Display a list of top priority items from different categories.
3807 The categories can be any of those in the current Todos file.
3809 With numerical prefix ARG show at most ARG top priority items
3810 from each category. With `C-u' as prefix argument show the
3811 numbers of top priority items specified by category in
3812 `todos-top-priorities-overrides', if this has an entry for the file(s);
3813 otherwise show `todos-top-priorities' items per category in the
3814 file(s). With no prefix argument, if a top priorities file for
3815 the current Todos file has previously been saved (see
3816 `todos-save-filtered-items-buffer'), visit this file; if there is
3817 no such file, build the list as with prefix argument `C-u'.
3819 The prefix ARG regulates how many top priorities from
3820 each category to show, as described above."
3825 "Display a list of top priority items from different categories.
3826 The categories are a subset of the categories in the files listed
3827 in `todos-filter-files', or if this nil, in the files chosen from
3828 a file selection dialog that pops up in this case.
3830 With numerical prefix ARG show at most ARG top priority items
3831 from each category in each file. With `C-u' as prefix argument
3832 show the numbers of top priority items specified in
3833 `todos-top-priorities-overrides', if this is non-nil; otherwise show
3834 `todos-top-priorities' items per category. With no prefix
3835 argument, if a top priorities file for the chosen Todos files
3836 exists (see `todos-save-filtered-items-buffer'), visit this file;
3837 if there is no such file, do the same as with prefix argument
3838 `C-u'."
3843 "Display a list of todo diary items from different categories.
3844 The categories can be any of those in the current Todos file.
3846 Called with no prefix ARG, if a diary items file for the current
3847 Todos file has previously been saved (see
3848 `todos-save-filtered-items-buffer'), visit this file; if there is
3849 no such file, build the list of diary items. Called with a
3850 prefix argument, build the list even if there is a saved file of
3851 diary items."
3856 "Display a list of todo diary items from different categories.
3857 The categories are a subset of the categories in the files listed
3858 in `todos-filter-files', or if this nil, in the files chosen from
3859 a file selection dialog that pops up in this case.
3861 Called with no prefix ARG, if a diary items file for the chosen
3862 Todos files has previously been saved (see
3863 `todos-save-filtered-items-buffer'), visit this file; if there is
3864 no such file, build the list of diary items. Called with a
3865 prefix argument, build the list even if there is a saved file of
3866 diary items."
3871 "Prompt for a regular expression and display items that match it.
3872 The matches can be from any categories in the current Todos file
3873 and with non-nil option `todos-filter-done-items', can include
3874 not only todo items but also done items, including those in
3875 Archive files.
3877 Called with no prefix ARG, if a regexp items file for the current
3878 Todos file has previously been saved (see
3879 `todos-save-filtered-items-buffer'), visit this file; if there is
3880 no such file, build the list of regexp items. Called with a
3881 prefix argument, build the list even if there is a saved file of
3882 regexp items."
3887 "Prompt for a regular expression and display items that match it.
3888 The matches can be from any categories in the files listed in
3889 `todos-filter-files', or if this nil, in the files chosen from a
3890 file selection dialog that pops up in this case. With non-nil
3891 option `todos-filter-done-items', the matches can include not
3892 only todo items but also done items, including those in Archive
3893 files.
3895 Called with no prefix ARG, if a regexp items file for the current
3896 Todos file has previously been saved (see
3897 `todos-save-filtered-items-buffer'), visit this file; if there is
3898 no such file, build the list of regexp items. Called with a
3899 prefix argument, build the list even if there is a saved file of
3900 regexp items."
3905 "Choose a filtered items file and visit it."
3908 falist file)
3914 falist)))
3921 "Display the file and category of the filtered item at point."
3938 t
3939 todos-show-with-done)))
3950 "Pop to a buffer with a widget for choosing multiple filter files."
3980 todos-multiple-filter-files-widget)))
4002 "Display a cross-categorial list of items filtered by FILTER.
4003 The values of FILTER can be `top' for top priority items, a cons
4004 of `top' and a number passed by the caller, `diary' for diary
4005 items, or `regexp' for items matching a regular expresion entered
4006 by the user. The items can be from any categories in the current
4007 todo file or, with non-nil MULTIFILE, from several files. If NEW
4008 is nil, visit an appropriate file containing the list of filtered
4009 items; if there is no such file, or with non-nil NEW, build the
4010 list and display it.
4012 See the document strings of the commands
4013 `todos-filter-top-priorities', `todos-filter-diary-items',
4014 `todos-filter-regexp-items', and those of the corresponding
4015 multifile commands for further details."
4025 todos-multiple-filter-files))
4029 ;; Pressed `cancel' in t-m-f-f file selection dialog.
4058 "Build a list of items by applying FILTER to FILE-LIST.
4059 Internal subroutine called by `todos-filter-items', which passes
4060 the values of FILTER and FILE-LIST."
4064 regexp fname bufstr cat beg end done)
4075 ;; Before inserting file contents into temp buffer, save a modified
4076 ;; buffer visiting it.
4083 ;; If there is a corresponding archive file for the
4084 ;; Todos file, insert it first and add identifiers for
4085 ;; todos-go-to-source-item.
4089 ;; Delete Todos archive file categories sexp.
4099 todos-date-string-start)
4105 nil t)
4109 ;; Delete Todos file categories sexp.
4112 ;; Unless the number of top priorities to show was
4113 ;; passed by the caller, the file-wide value from
4114 ;; `todos-top-priorities-overrides', if non-nil, overrides
4115 ;; `todos-top-priorities'.
4118 todos-top-priorities)))
4124 ;; Unless the number of top priorities to show was
4125 ;; passed by the caller, the category-wide value
4126 ;; from `todos-top-priorities-overrides', if non-nil,
4127 ;; overrides a non-nil file-wide value from
4128 ;; `todos-top-priorities-overrides' as well as
4129 ;; `todos-top-priorities'.
4137 nil t)
4144 end t)
4146 end))
4148 ;; Leave done items.
4153 ;; Apply the filter.
4165 ;; Kill lines that aren't part of a todo or done
4166 ;; item (empty or todos-category-done).
4169 ;; If last todo item in file matches regexp and
4170 ;; there are no following done items,
4171 ;; todos-category-done string is left dangling,
4172 ;; because todos-forward-item jumps over it.
4185 ;; Delete non-top-priority items.
4189 ;; Add file (if using multiple files) and category tags to
4190 ;; item.
4197 todos-date-string-start)
4203 nil t)
4218 "Set number of top priorities shown by `todos-filter-top-priorities'.
4219 With non-nil ARG, set the number only for the current Todos
4220 category; otherwise, set the number for all categories in the
4221 current Todos file.
4223 Calling this function via either of the commands
4224 `todos-set-top-priorities-in-file' or
4225 `todos-set-top-priorities-in-category' is the recommended way to
4226 set the user customizable option `todos-top-priorities-overrides'."
4234 todos-top-priorities))
4240 nrule)
4244 prompt "Enter a non-negative number: "
4245 cur0 nil)))
4251 nrule)
4257 "Search for filtered item STR in its saved Todos file.
4258 Return the list (FOUND FILE CAT), where CAT and FILE are the
4259 item's category and file, and FOUND is a cons cell if the search
4260 succeeds, whose car is the start of the item in FILE and whose
4261 cdr is `done', if the item is now a done item, `changed', if its
4262 text was truncated or augmented or, for a top priority item, if
4263 its priority has changed, and `same' otherwise."
4267 todos-date-string-start)
4280 found)
4283 ;; Calculate priority of STR wrt its category.
4293 todos-global-current-todos-file)))
4302 nil t))
4309 nil t)
4316 'done
4320 ;; Not top item in category.
4324 ;; Can't move backward beyond
4325 ;; first item in file.
4329 ;; Proper substring is not the same.
4331 str))
4332 'same
4337 "Check if filtered items file is up to date and a show suitable message."
4338 ;; (catch 'old
4348 ;; (throw 'old (message "The marked item is not up to date.")))
4353 "not up to date."
4354 ;; "\nType <return> on item for details."
4355 )))))
4358 "Return absolute file name for saving this Filtered Items buffer."
4376 "Save current Filtered Items buffer to a file.
4377 If the file already exists, overwrite it only on confirmation."
4381 ;; -----------------------------------------------------------------------------
4382 ;;; Printing Todos buffers
4383 ;; -----------------------------------------------------------------------------
4386 "Function called by the command `todos-print-buffer'."
4394 "Produce a printable version of the current Todos buffer.
4395 This converts overlays and soft line wrapping and, depending on
4396 the value of `todos-print-buffer-function', includes faces. With
4397 non-nil argument TO-FILE write the printable version to a file;
4398 otherwise, send it to the default printer."
4413 file)
4426 ;; Calling todos-forward-item infloops at todos-item-start due to
4427 ;; non-overlay prefix, so search for item start instead.
4432 nil t)
4444 "Save printable version of this Todos buffer to a file."
4448 ;; -----------------------------------------------------------------------------
4449 ;;; Legacy Todo mode files
4450 ;; -----------------------------------------------------------------------------
4455 "Regexp matching legacy todo-mode.el item date-time strings.
4456 In order for `todos-convert-legacy-files' to correctly convert this
4457 string to the current Todos format, the regexp must contain four
4458 explicitly numbered groups (see `(elisp) Regexp Backslash'),
4459 where group 1 matches a string for the year, group 2 a string for
4460 the month, group 3 a string for the day and group 4 a string for
4461 the time. The default value converts date-time strings built
4462 using the default value of `todo-time-string-format' from
4463 todo-mode.el."
4468 "Return converted date-time string.
4469 Helper function for `todos-convert-legacy-files'."
4475 dayname)
4481 "Convert legacy Todo files to the current Todos format.
4482 The old-style files named by the variables `todo-file-do' and
4483 `todo-file-done' from the old package are converted to the new
4484 format and saved (the latter as a Todos Archive file) with a new
4485 name in `todos-directory'. See also the documentation string of
4486 `todos-legacy-date-time-regexp' for further details."
4490 ;; Before loading legacy code we have to void symbols whose names
4491 ;; are the same in the old and new versions, so use placeholders
4492 ;; during conversion and restore them afterwards.
4502 ;; We can't use require because the feature provided by the
4503 ;; old version is the same as the new version's.
4505 ;; Convert `todo-file-do'.
4508 file archive-sexp)
4524 todo-category-sep)))
4527 todos-legacy-date-time-regexp " "
4529 ;; FIXME: Should todo-initials be converted? That
4530 ;; would require changes to item insertion and editing.
4536 nil nil default)
4545 ;; Convert `todo-file-done'.
4551 cat cats comment item)
4566 ;; FIXME: Should todo-initials be converted?
4577 ;; If the item ends with a non-comment parenthesis not
4578 ;; followed by a period, we lose (but we inherit that problem
4579 ;; from todo-mode.el).
4586 ;; If item is already in its category, leave it there.
4592 ;; Else move it to its category.
4600 nil t)
4630 ;; Update categories sexp of converted Todos file again, adding
4631 ;; counts of archived items.
4647 ;; (setq todos-categories todos-categories-tem
4648 ;; todos-prefix todos-prefix-tem
4649 ;; todos-category-beg todos-category-beg-tem)
4650 ;; (fset 'todos-mode 'todos-mode-tem)
4651 ;; (makunbound 'todos-categories-tem)
4652 ;; (makunbound 'todos-prefix-tem)
4653 ;; (makunbound 'todos-category-beg-tem)
4654 ;; (fmakunbound 'todos-mode-tem)
4658 ;; -----------------------------------------------------------------------------
4659 ;;; Utility functions for Todos files, categories and items
4660 ;; -----------------------------------------------------------------------------
4663 "Return the absolute file name of short Todos file NAME.
4664 With TYPE `archive' or `top' return the absolute file name of the
4665 short Todos Archive or Top Priorities file name, respectively."
4666 ;; NOP if there is no Todos file yet (i.e. don't concatenate nil).
4677 "Return the number of category CAT in this Todos file.
4678 The buffer-local variable `todos-category-number' holds this
4679 number as its value."
4682 ;; Increment by one, so that the highest priority category in Todos
4683 ;; Categories mode is numbered one rather than zero.
4688 "Return the name of the current category."
4692 "Display the current category correctly."
4694 cat-begin cat-end done-start done-sep-start done-end)
4720 ;; Now we want to see the done items, so reset displayed end to end of
4721 ;; done items.
4723 ;; Make display overlay for done items separator string, unless there
4724 ;; already is one.
4733 ;; Loading this from todos-mode, or adding it to the mode hook, causes
4734 ;; Emacs to hang in todos-item-start, at (looking-at todos-item-start).
4740 "Return count of TYPE items in CATEGORY.
4741 If CATEGORY is nil, default to the current category."
4751 "Change count of TYPE items in CATEGORY by integer INCREMENT.
4752 With nil or omitted CATEGORY, default to the current category."
4762 "Set `todos-categories' from the sexp at the top of the file."
4763 ;; New archive files created by `todos-move-category' are empty, which would
4764 ;; make the sexp test fail and raise an error, so in this case we skip it.
4778 "Update the `todos-categories' sexp at the top of the file."
4791 "Return an alist of Todos categories and their item counts.
4792 With non-nil argument FORCE parse the entire file to build the
4793 list; otherwise, get the value by reading the sexp at the top of
4794 the file."
4801 ;; If the file is a todo file and has archived items, identify the
4802 ;; archive, in order to count its items. But skip this with
4803 ;; `todos-convert-legacy-files', since that converts filed items to
4804 ;; archived items.
4806 ;; If the file is an archive, it doesn't have an archive.
4815 ;; Counts for each category: [todo diary done archive]
4819 ;; Add archived item count to the todo file item counts.
4820 ;; Make sure to include newly created archives, e.g. due to
4821 ;; todos-move-category.
4850 ;; If first line is todos-categories list, use it and end loop
4851 ;; -- unless FORCEd to scan whole file.
4859 todos-categories)
4862 "Repair corrupt Todos categories sexp.
4863 This should only be needed as a consequence of careless manual
4864 editing or a bug in todos.el.
4866 *Warning*: Calling this command restores the category order to
4867 the list element order in the Todos categories sexp, so any order
4868 changes made in Todos Categories mode will have to be made again."
4874 "Signal an error if the current Todos file is ill-formatted.
4875 Otherwise return t. Display a message if the file is well-formed
4876 but the categories sexp differs from the current value of
4877 `todos-categories'."
4886 ;; Check the first line for `todos-categories' sexp.
4894 ;; Check well-formedness of categories.
4907 ;; Warn user if categories sexp has changed.
4911 "If the sexp is wrong, you can fix it with "
4913 "but note this reverts any changes you have "
4915 t)
4918 "Move to start of current Todos item and return its position."
4920 ;; Buffer is empty (invocation possible e.g. via todos-forward-item
4921 ;; from todos-filter-items when processing category with no todo
4922 ;; items).
4924 ;; Point is on the empty line below category's last todo item...
4931 ;; Buffer is widened.
4939 "Move to end of current Todos item and return its position."
4940 ;; Items cannot end with a blank line.
4944 ;; For todo items, end is before the done items section, for done
4945 ;; items, end is before the next category. If these limits are
4946 ;; missing or inaccessible, end it before the end of the buffer.
4950 todos-category-beg
4951 todos-category-done)))
4952 nil t))
4959 ;; For last todo item, skip back over the empty line before the done
4960 ;; items section, else just back to the end of the previous line.
4965 "Return bare text of current item as a string."
4973 "Move point COUNT items down (by default, move down by one item)."
4980 ;; If points advances by one from a todo to a done item, go back
4981 ;; to the space above todos-done-separator, since that is a
4982 ;; legitimate place to insert an item. But skip this space if
4983 ;; count > 1, since that should only stop on an item.
4985 ;; (if (or (not count) (= count 1))
4987 ;; The preceding sexp is insufficient when buffer is not narrowed,
4988 ;; since there could be no done items in this category, so the
4989 ;; search puts us on first todo item of next category. Does this
4990 ;; ever happen? If so:
4991 ;; (let ((opoint) (point))
4992 ;; (forward-line -1)
4993 ;; (when (or (not count) (= count 1))
4994 ;; (cond ((looking-at (concat "^" (regexp-quote todos-category-beg)))
4995 ;; (forward-line -2))
4996 ;; ((looking-at (concat "^" (regexp-quote todos-category-done)))
4997 ;; (forward-line -1))
4998 ;; (t
4999 ;; (goto-char opoint)))))))
5002 "Move point up to start of item with next higher priority.
5003 With positive numerical prefix COUNT, move point COUNT items
5004 upward.
5006 If the category's done items are visible, this command called
5007 with a prefix argument only moves point to a higher item, e.g.,
5008 with point on the first done item and called with prefix 1, it
5009 moves to the last todo item; but if called with point on the
5010 first done item without a prefix argument, it moves point the the
5011 empty line above the done items separator."
5016 ;; Unless this is a regexp filtered items buffer (which can contain
5017 ;; intermixed todo and done items), if points advances by one from a
5018 ;; done to a todo item, go back to the space above
5019 ;; todos-done-separator, since that is a legitimate place to insert an
5020 ;; item. But skip this space if count > 1, since that should only
5021 ;; stop on an item.
5023 ;(or (not count) (= count 1))
5026 nil t)
5030 "Internal function called in editing, deleting or moving items."
5038 "Return non-nil if item at point has diary entry format."
5044 ;; This duplicates the item locating code from diary-goto-entry, but
5045 ;; without the marker code, to test whether the latter is dispensible.
5046 ;; If it is, diary-goto-entry can be simplified. The code duplication
5047 ;; here can also be eliminated, leaving only the widening and category
5048 ;; selection, and instead of :override advice :around can be used.
5051 "Jump to the diary entry for the BUTTON at point.
5052 If the entry is a todo item, display its category properly.
5053 Overrides `diary-goto-entry'."
5054 ;; Locate the diary item in its source file.
5066 ;; If it's a todo item, determine its category and display the
5067 ;; category properly.
5079 "Return non-nil if item at point is a done item."
5085 "Return non-nil if point is in category's done items section."
5088 nil t)
5093 "Replace existing overlays of done items separator string SEP."
5105 new-ov)
5114 "Return the overlay at point whose `todos' property has value VAL."
5115 ;; Use overlays-in to find prefix overlays and check over two
5116 ;; positions to find done separator overlay.
5118 ov)
5126 "Non-nil if this item begins with `todos-item-mark'.
5127 In that case, return the item's prefix overlay."
5129 ;; If an item insertion command is called on a Todos file
5130 ;; before it is visited, it has no prefix overlays yet, so
5131 ;; check for this.
5135 pref))))
5139 "Insert ITEM at point and update prefix/priority number overlays."
5141 ;; Insertion pushes item down but not its prefix overlay. When the
5142 ;; overlay includes a mark, this would now mark the inserted ITEM,
5143 ;; so move it to the pushed down item.
5152 "Update the prefix overlays of the current category's items.
5153 The overlay's value is the string `todos-prefix' or with non-nil
5154 `todos-number-prefix' an integer in the sequence from 1 to
5155 the number of todo or done items in the category indicating the
5156 item's priority. Todo and done items are numbered independently
5157 of each other."
5162 todos-top-priorities-overrides))))
5163 todos-top-priorities))
5164 done prefix)
5172 ;; Reset number to 1 for first done item.
5179 done t))
5183 todos-prefix)
5184 'face
5185 ;; Prefix of top priority items has a
5186 ;; distinct face in Todos mode.
5190 'todos-top-priority
5195 ;; Prefix overlay must be at a single position so its
5196 ;; bounds aren't changed when (re)moving an item.
5201 prefix))))
5204 ;; -----------------------------------------------------------------------------
5205 ;;; Utilities for generating item insertion commands and key bindings
5206 ;; -----------------------------------------------------------------------------
5208 ;; Wolfgang Jenkner posted this powerset definition to emacs-devel
5209 ;; (http://lists.gnu.org/archive/html/emacs-devel/2013-06/msg00423.html)
5210 ;; and kindly gave me permission to use it.
5213 "Return the powerset of LIST."
5219 "Return list of lists of non-nil atoms produced from ARGLIST.
5220 The elements of ARGLIST may be atoms or lists."
5234 arg))))))
5243 res new)
5266 new)
5270 "Generate Todos item insertion command name from ARGLIST."
5275 ;; (concat "todos-item-insert-"
5282 todos-insertion-commands-args)
5286 "Generate item insertion command definitions from ARGS."
5294 "Todos item insertion command generated from ARGS.
5295 For descriptions of the individual arguments, their values, and
5296 their relation to key bindings, see `todos-basic-insert-item'."
5303 todos-insertion-commands-args)
5318 "Generate key binding definitions for item insertion keymap MAP."
5330 todos-insertion-commands-arg-key-list)
5335 ;; -----------------------------------------------------------------------------
5336 ;;; Todos minibuffer utilities
5337 ;; -----------------------------------------------------------------------------
5347 SPC to affirm the question only if option `todos-y-with-space' is
5348 non-nil."
5356 "Return a list of completions for `todos-read-category'.
5357 Each element of the list is a cons of a category name and the
5358 file or list of files (as short file names) it is in. The files
5359 are either the current (or if there is none, the default) todo
5360 file plus the files listed in `todos-category-completions-files',
5361 or, with non-nil ARCHIVE, the current archive file."
5364 todos-global-current-todos-file)
5368 todos-category-completions-files))
5370 listall listf)
5371 ;; If file was just added, it has no category completions.
5377 ;; Ensure category is properly displayed in case user
5378 ;; switches to file via a non-Todos command. And if done
5379 ;; items in category are visible, keep them visible.
5400 listf)))))
5403 "Choose and return the name of a Todos file, prompting with PROMPT.
5405 Show completions with TAB or SPC; the names are shown in short
5406 form but the absolute truename is returned. With non-nil ARCHIVE
5407 return the absolute truename of a Todos archive file. With non-nil
5408 MUSTMATCH the name of an existing file must be chosen;
5409 otherwise, a new file name is allowed."
5415 ;; If user hit RET without
5416 ;; choosing a file, default to
5417 ;; current or default file.
5421 todos-global-current-todos-file)
5423 todos-default-todos-file)))
5424 ;; Trigger prompt for initial file.
5434 "Choose and return a category name, prompting with PROMPT.
5435 Show completions for existing categories with TAB or SPC.
5437 The argument MATCH-TYPE specifies the matching requirements on
5438 the category name: with the value `todo' or `archive' the name
5439 must complete to that of an existing todo or archive category,
5440 respectively; with the value `add' the name must not be that of
5441 an existing category; with all other values both existing and new
5442 valid category names are accepted.
5444 With non-nil argument FILE prompt for a file and complete only
5445 against categories in that file; otherwise complete against all
5446 categories from `todos-category-completions-files'."
5447 ;; Allow SPC to insert spaces, for adding new category names.
5454 "n archive"
5462 todos-categories)))
5466 todos-categories))
5468 completions)))
5472 ;; Unless we're adding a category via
5473 ;; todos-add-category, set default
5474 ;; for existing categories to the
5475 ;; current category of the chosen
5476 ;; file or else of the current file.
5481 todos-current-todos-file
5483 todos-default-todos-file)))
5485 ;; Trigger prompt for initial category.
5489 ;; If we do category completion and the chosen category name
5490 ;; occurs in more than one file, prompt to choose one file.
5494 catfil
5498 ;; Default to the current file.
5500 ;; First validate only a name passed interactively from
5501 ;; todos-add-category, which must be of a nonexisting category.
5503 ;; Validate only against completion categories.
5506 ;; When user enters a nonexisting category name by jumping or
5507 ;; moving, confirm that it should be added, then validate.
5515 ;; Restore point and narrowing after adding new
5516 ;; category, to avoid moving to beginning of file when
5517 ;; moving marked items to a new category
5518 ;; (todos-move-item).
5522 ;; If we decide not to add a category, exit without returning.
5527 "Prompt for new NAME for TYPE until it is valid, then return it.
5528 TYPE can be either of the symbols `file' or `category'."
5531 prompt)
5538 "Enter a non-empty file name: "
5539 ;; Empty string passed by todos-show to
5540 ;; prompt for initial Todos file.
5545 "Enter a non-empty category name: "
5546 ;; Empty string passed by todos-show to
5547 ;; prompt for initial category of a new
5548 ;; Todos file.
5561 files)
5563 categories)))
5564 ;; Offer default initial name.
5566 files
5567 categories)
5569 todos-initial-file
5570 todos-initial-category))))))
5571 name))
5573 ;; Adapted from calendar-read-date and calendar-date-string.
5575 "Prompt for Gregorian date and return it in the current format.
5577 With non-nil ARG, prompt for and return only the date component
5578 specified by ARG, which can be one of these symbols:
5579 `month' (prompt for name, return name or number according to
5580 value of `calendar-date-display-form'), `day' of month, or
5581 `year'. The value of each of these components can be `*',
5582 indicating an unspecified month, day, or year.
5584 When ARG is `day', non-nil arguments MO and YR determine the
5585 number of the last the day of the month."
5591 "Year (>0 or RET for this year or * for any year): "
5602 "Month name (RET for current month, * for any month): "
5603 ;; (mapcar 'list (append marray nil))
5604 mlist nil t nil nil
5607 ;; month (cdr (assoc-string
5608 ;; monthname (calendar-make-alist marray nil nil
5609 ;; abbrevs))))))
5617 ;; If month is unspecified, use a month with 31
5618 ;; days for checking day of month input. Does
5619 ;; Calendar do anything special when * is
5620 ;; currently a shorter month?
5622 ;; If year is unspecified, use a leap year to
5623 ;; allow Feb. 29.
5629 last)
5633 ;; Stringify read values (monthname is already a string).
5648 month
5649 monthname)))
5653 "Choose name of a day of the week with completion and return it."
5657 nil t)))
5660 "Prompt for and return a valid clock time as a string.
5662 Valid time strings are those matching `diary-time-regexp'.
5663 Typing `<return>' at the prompt returns the current time, if the
5664 user option `todos-always-add-time-string' is non-nil, otherwise
5665 the empty string (i.e., no time string)."
5674 answer))
5676 ;; -----------------------------------------------------------------------------
5677 ;;; Customization groups and utilities
5678 ;; -----------------------------------------------------------------------------
5681 "Create and maintain categorized lists of todo items."
5687 "User options for adding and editing todo items."
5692 "User options for Todos Categories mode."
5697 "User options for Todos Filter Items mode."
5702 "User display options for Todos mode."
5707 "Faces for the Todos modes."
5712 "The :set function for user option `todos-show-current-file'."
5719 "The :set function for `todos-prefix' and `todos-number-prefix'."
5726 ;; Activate the new setting in the current category.
5730 "The :set function for user option `todos-nondiary-marker'."
5734 ;; Need to reset these to get font-locking right.
5737 todos-date-string-start
5738 ;; See comment in defvar of `todos-date-string-start'.
5754 nil t)
5762 "The :set function for `todos-done-separator-string'."
5777 "The :set function for user option `todos-done-string'."
5781 ;; Need to reset this to get font-locking right.
5794 nil t)
5800 "The :set function for user option `todos-comment-string'."
5815 nil t)
5821 "The :set function for `todos-toggle-item-highlighting'."
5836 "Reevaluate defcustoms that provide choice list of Todos files."
5847 "Reevaluate defcustom of `todos-default-todos-file'.
5848 Called after adding or deleting a Todos file."
5850 "Todos file visited by first session invocation of `todos-show'."
5857 "Reevaluate defcustom of `todos-category-completions-files'.
5858 Called after adding or deleting a Todos file."
5860 "List of files for building `todos-read-category' completions."
5867 "Reevaluate defcustom of `todos-filter-files'.
5868 Called after adding or deleting a Todos file."
5870 "List of files for multifile item filtering."
5876 ;; -----------------------------------------------------------------------------
5877 ;;; Font locking
5878 ;; -----------------------------------------------------------------------------
5881 "Search for Todos nondiary markers within LIM for font-locking."
5885 lim t))
5888 "Search for diary nonmarking symbol within LIM for font-locking."
5893 "Search for Todos date string within LIM for font-locking."
5898 "Search for Todos time string within LIM for font-locking."
5903 "Search for expired diary item date within LIM for font-locking."
5910 ;; Function days-between requires a non-empty time string.
5917 "Search for Todos done header within LIM for font-locking."
5920 lim t))
5923 "Search for Todos done comment within LIM for font-locking."
5925 lim t))
5928 "Search for Todos category name within LIM for font-locking.
5929 This is for fontifying category and file names appearing in Todos
5930 Filtered Items mode following done items."
5934 ;; Use non-greedy operator to prevent
5935 ;; capturing possible following non-diary
5936 ;; date string.
5938 lim t)))
5941 "Search for Todos category name within LIM for font-locking.
5942 This is for fontifying category and file names appearing in Todos
5943 Filtered Items mode following todo (not done) items."
5949 lim t)))
5963 ;; diary-lib.el uses font-lock-constant-face for diary-nonmarking-symbol.
5973 )
5976 ;; -----------------------------------------------------------------------------
5977 ;;; Key binding
5978 ;; -----------------------------------------------------------------------------
5984 map)
5988 `(
6032 )
6036 `(
6057 )
6061 `(
6066 )
6070 `(
6074 )
6079 ;; Don't suppress digit keys, so they can supply prefix arguments.
6089 map)
6101 map)
6108 map)
6125 (define-key map [backtab] 'todos-previous-button)
6126 (define-key map "q" 'todos-quit)
6127 map)
6128 "Todos Categories mode keymap.")
6130 (defvar todos-filtered-items-mode-map
6131 (let ((map (make-sparse-keymap)))
6132 (suppress-keymap map)
6133 (dolist (kb todos-key-bindings-t+a+f)
6134 (define-key map (nth 0 kb) (nth 1 kb)))
6135 (dolist (kb todos-key-bindings-t+f)
6136 (define-key map (nth 0 kb) (nth 1 kb)))
6137 (define-key map "g" 'todos-go-to-source-item)
6138 (define-key map [remap newline] 'todos-go-to-source-item)
6139 map)
6140 "Todos Filtered Items mode keymap.")
6142 ;; FIXME: Is it worth having a menu and if so, which commands?
6143 ;; (easy-menu-define
6144 ;; todos-menu todos-mode-map "Todos Menu"
6145 ;; '("Todos"
6146 ;; ("Navigation"
6147 ;; ["Next Item" todos-forward-item t]
6148 ;; ["Previous Item" todos-backward-item t]
6149 ;; "---"
6150 ;; ["Next Category" todos-forward-category t]
6151 ;; ["Previous Category" todos-backward-category t]
6152 ;; ["Jump to Category" todos-jump-to-category t]
6153 ;; "---"
6154 ;; ["Search Todos File" todos-search t]
6155 ;; ["Clear Highlighting on Search Matches" todos-category-done t])
6156 ;; ("Display"
6157 ;; ["List Current Categories" todos-show-categories-table t]
6158 ;; ;; ["List Categories Alphabetically" todos-display-categories-alphabetically t]
6159 ;; ["Turn Item Highlighting on/off" todos-toggle-item-highlighting t]
6160 ;; ["Turn Item Numbering on/off" todos-toggle-prefix-numbers t]
6161 ;; ["Turn Item Time Stamp on/off" todos-toggle-item-header t]
6162 ;; ["View/Hide Done Items" todos-toggle-view-done-items t]
6163 ;; "---"
6164 ;; ["View Diary Items" todos-filter-diary-items t]
6165 ;; ["View Top Priority Items" todos-filter-top-priorities t]
6166 ;; ["View Multifile Top Priority Items" todos-filter-top-priorities-multifile t]
6167 ;; "---"
6168 ;; ["Print Category" todos-print-buffer t])
6169 ;; ("Editing"
6170 ;; ["Insert New Item" todos-insert-item t]
6171 ;; ["Insert Item Here" todos-insert-item-here t]
6172 ;; ("More Insertion Commands")
6173 ;; ["Edit Item" todos-edit-item t]
6174 ;; ["Edit Multiline Item" todos-edit-multiline-item t]
6175 ;; ["Edit Item Header" todos-edit-item-header t]
6176 ;; ["Edit Item Date" todos-edit-item-date t]
6177 ;; ["Edit Item Time" todos-edit-item-time t]
6178 ;; "---"
6179 ;; ["Lower Item Priority" todos-lower-item-priority t]
6180 ;; ["Raise Item Priority" todos-raise-item-priority t]
6181 ;; ["Set Item Priority" todos-set-item-priority t]
6182 ;; ["Move (Recategorize) Item" todos-move-item t]
6183 ;; ["Delete Item" todos-delete-item t]
6184 ;; ["Undo Done Item" todos-item-undone t]
6185 ;; ["Mark/Unmark Item for Diary" todos-toggle-item-diary-inclusion t]
6186 ;; ["Mark/Unmark Items for Diary" todos-edit-item-diary-inclusion t]
6187 ;; ["Mark & Hide Done Item" todos-item-done t]
6188 ;; ["Archive Done Items" todos-archive-category-done-items t]
6189 ;; "---"
6190 ;; ["Add New Todos File" todos-add-file t]
6191 ;; ["Add New Category" todos-add-category t]
6192 ;; ["Delete Current Category" todos-delete-category t]
6193 ;; ["Rename Current Category" todos-rename-category t]
6194 ;; "---"
6195 ;; ["Save Todos File" todos-save t]
6196 ;; )
6197 ;; "---"
6198 ;; ["Quit" todos-quit t]
6199 ;; ))
6201 ;; -----------------------------------------------------------------------------
6202 ;;; Hook functions and mode definitions
6203 ;; -----------------------------------------------------------------------------
6205 (defun todos-show-current-file ()
6206 "Visit current instead of default Todos file with `todos-show'.
6207 This function is added to `pre-command-hook' when user option
6208 `todos-show-current-file' is set to non-nil."
6209 (setq todos-global-current-todos-file todos-current-todos-file))
6211 (defun todos-display-as-todos-file ()
6212 "Show Todos files correctly when visited from outside of Todos mode."
6213 (and (member this-command todos-visit-files-commands)
6214 (= (- (point-max) (point-min)) (buffer-size))
6215 (member major-mode '(todos-mode todos-archive-mode))
6216 (todos-category-select)))
6218 (defun todos-add-to-buffer-list ()
6219 "Add name of just visited Todos file to `todos-file-buffers'.
6220 This function is added to `find-file-hook' in Todos mode."
6221 (let ((filename (file-truename (buffer-file-name))))
6222 (when (member filename todos-files)
6223 (add-to-list 'todos-file-buffers filename))))
6225 (defun todos-update-buffer-list ()
6226 "Make current Todos mode buffer file car of `todos-file-buffers'.
6227 This function is added to `post-command-hook' in Todos mode."
6228 (let ((filename (file-truename (buffer-file-name))))
6229 (unless (eq (car todos-file-buffers) filename)
6230 (setq todos-file-buffers
6231 (cons filename (delete filename todos-file-buffers))))))
6233 (defun todos-reset-global-current-todos-file ()
6234 "Update the value of `todos-global-current-todos-file'.
6235 This becomes the latest existing Todos file or, if there is none,
6236 the value of `todos-default-todos-file'.
6237 This function is added to `kill-buffer-hook' in Todos mode."
6238 (let ((filename (file-truename (buffer-file-name))))
6239 (setq todos-file-buffers (delete filename todos-file-buffers))
6240 (setq todos-global-current-todos-file
6241 (or (car todos-file-buffers)
6242 (todos-absolute-file-name todos-default-todos-file)))))
6244 (defun todos-reset-and-enable-done-separator ()
6245 "Show resized done items separator overlay after window change.
6246 Added to `window-configuration-change-hook' in `todos-mode'."
6247 (when (= 1 (length todos-done-separator-string))
6248 (let ((sep todos-done-separator))
6249 (setq todos-done-separator (todos-done-separator))
6250 (save-match-data (todos-reset-done-separator sep)))))
6252 (defun todos-modes-set-1 ()
6253 "Make some settings that apply to multiple Todos modes."
6254 (setq-local font-lock-defaults '(todos-font-lock-keywords t))
6255 (setq-local tab-width todos-indent-to-here)
6256 (setq-local indent-line-function 'todos-indent)
6257 (when todos-wrap-lines
6258 (visual-line-mode)
6259 (setq wrap-prefix (make-string todos-indent-to-here 32))))
6261 (defun todos-modes-set-2 ()
6262 "Make some settings that apply to multiple Todos modes."
6263 (add-to-invisibility-spec 'todos)
6264 (setq buffer-read-only t)
6265 (when (boundp 'hl-line-range-function)
6266 (setq-local hl-line-range-function
6267 (lambda() (save-excursion
6268 (when (todos-item-end)
6269 (cons (todos-item-start)
6270 (todos-item-end))))))))
6272 (defun todos-modes-set-3 ()
6273 "Make some settings that apply to multiple Todos modes."
6274 (setq-local todos-categories (todos-set-categories))
6275 (setq-local todos-category-number 1)
6276 (add-hook 'find-file-hook 'todos-display-as-todos-file nil t))
6278 (put 'todos-mode 'mode-class 'special)
6280 (define-derived-mode todos-mode special-mode "Todos"
6281 "Major mode for displaying, navigating and editing Todo lists.
6284 ;; (easy-menu-add todos-menu)
6285 (todos-modes-set-1)
6286 (todos-modes-set-2)
6287 (todos-modes-set-3)
6288 ;; Initialize todos-current-todos-file.
6289 (when (member (file-truename (buffer-file-name))
6290 (funcall todos-files-function))
6291 (setq-local todos-current-todos-file (file-truename (buffer-file-name))))
6292 (setq-local todos-show-done-only nil)
6293 (setq-local todos-categories-with-marks nil)
6294 (add-hook 'find-file-hook 'todos-add-to-buffer-list nil t)
6295 (add-hook 'post-command-hook 'todos-update-buffer-list nil t)
6296 (when todos-show-current-file
6297 (add-hook 'pre-command-hook 'todos-show-current-file nil t))
6298 (add-hook 'window-configuration-change-hook
6299 'todos-reset-and-enable-done-separator nil t)
6300 (add-hook 'kill-buffer-hook 'todos-reset-global-current-todos-file nil t))
6302 (put 'todos-archive-mode 'mode-class 'special)
6304 ;; If todos-mode is parent, all todos-mode key bindings appear to be
6305 ;; available in todos-archive-mode (e.g. shown by C-h m).
6306 (define-derived-mode todos-archive-mode special-mode "Todos-Arch"
6307 "Major mode for archived Todos categories.
6310 (todos-modes-set-1)
6311 (todos-modes-set-2)
6312 (todos-modes-set-3)
6313 (setq-local todos-current-todos-file (file-truename (buffer-file-name)))
6314 (setq-local todos-show-done-only t))
6316 (defun todos-mode-external-set ()
6317 "Set `todos-categories' externally to `todos-current-todos-file'."
6318 (setq-local todos-current-todos-file todos-global-current-todos-file)
6319 (let ((cats (with-current-buffer
6320 ;; Can't use find-buffer-visiting when
6321 ;; `todos-show-categories-table' is called on first
6322 ;; invocation of `todos-show', since there is then
6323 ;; no buffer visiting the current file.
6324 (find-file-noselect todos-current-todos-file 'nowarn)
6325 (or todos-categories
6326 ;; In Todos Edit mode todos-categories is now nil
6327 ;; since it uses same buffer as Todos mode but
6328 ;; doesn't have the latter's local variables.
6329 (save-excursion
6330 (goto-char (point-min))
6331 (read (buffer-substring-no-properties
6332 (line-beginning-position)
6333 (line-end-position))))))))
6334 (setq-local todos-categories cats)))
6336 (define-derived-mode todos-edit-mode text-mode "Todos-Ed"
6337 "Major mode for editing multiline Todo items.
6340 (todos-modes-set-1)
6341 (todos-mode-external-set)
6342 (setq buffer-read-only nil))
6344 (put 'todos-categories-mode 'mode-class 'special)
6346 (define-derived-mode todos-categories-mode special-mode "Todos-Cats"
6347 "Major mode for displaying and editing Todos categories.
6350 (todos-mode-external-set))
6352 (put 'todos-filtered-items-mode 'mode-class 'special)
6354 (define-derived-mode todos-filtered-items-mode special-mode "Todos-Fltr"
6355 "Mode for displaying and reprioritizing top priority Todos.
6358 (todos-modes-set-1)
6359 (todos-modes-set-2))
6365 ;; -----------------------------------------------------------------------------
6366 (provide 'todos)
6368 ;;; todos.el ends here