| blob | 60dd969e2cc07070fd3bb38c85ae3b5b07e4183c |
1 ;;; todo-mode.el --- facilities for making and maintaining todo lists
3 ;; Copyright (C) 1997, 1999, 2001-2014 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 Todo mode 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, edit and delete them. You can add new
41 ;; categories, rename and delete them, move categories to another file
42 ;; and merge the items of two categories. You can also reorder the
43 ;; sequence of categories in a todo file for the purpose of
44 ;; navigation. You can display summary tables of the categories in a
45 ;; file and the types of items they contain. And you can compile
46 ;; lists of existing items from multiple categories in one or more
47 ;; todo files, which are filtered by various criteria.
49 ;; To get started, load this package and type `M-x todo-show'. This
50 ;; will prompt you for the name of the first todo file, its first
51 ;; category and the category's first item, create these and display
52 ;; them in Todo mode. Now you can insert further items into the list
53 ;; (i.e., the category) and assign them priorities by typing `i i'.
55 ;; You will probably find it convenient to give `todo-show' a global
56 ;; key binding in your init file, since it is one of the entry points
57 ;; to Todo mode; a good choice is `C-c t', since `todo-show' is
58 ;; bound to `t' in Todo mode.
60 ;; To see a list of all Todo mode commands and their key bindings,
61 ;; including other entry points, type `C-h m' in Todo mode. Consult
62 ;; the documentation strings of the commands for details of their use.
63 ;; The `todo' customization group and its subgroups list the options
64 ;; you can set to alter the behavior of many commands and various
65 ;; aspects of the display.
67 ;; This package is a new version of Oliver Seidel's todo-mode.el.
68 ;; While it retains the same basic organization and handling of todo
69 ;; lists and the basic UI, it significantly extends these and adds
70 ;; many features. This required also making changes to the internals,
71 ;; including the file format. If you have a todo file in old format,
72 ;; then the first time you invoke `todo-show' (i.e., before you have
73 ;; created any todo file in the current format), it will ask you
74 ;; whether to convert that file and show it. If you choose not to
75 ;; convert the old-style file at this time, you can do so later by
76 ;; calling the command `todo-convert-legacy-files'.
78 ;;; Code:
81 ;; For cl-remove-duplicates (in todo-insertion-commands-args) and
82 ;; cl-oddp.
85 ;; -----------------------------------------------------------------------------
86 ;;; Setting up todo files, categories, and items
87 ;; -----------------------------------------------------------------------------
90 "Directory where user's todo files are saved."
95 "Default value of `todo-files-function'.
96 This returns the case-insensitive alphabetically sorted list of
97 file truenames in `todo-directory' with the extension
109 "Function returning the value of the variable `todo-files'.
110 This function should take an optional argument that, if non-nil,
111 makes it return the value of the variable `todo-archives'."
122 "List of todo files visited in this session by `todo-show'.
123 Used to determine initial display according to the value of
130 "Variable holding name of current todo file.
131 Used by functions called from outside of Todo mode to visit the
132 current todo file rather than the default todo file (i.e. when
139 "Alist of categories in the current todo file.
140 The elements are cons cells whose car is a category name and
141 whose cdr is a vector of the category's item counts. These are,
142 in order, the numbers of todo items, of todo items included in
146 "Variable holding the number of the current todo category.
159 "String determining the value of variable `todo-done-separator'.
160 If the string consists of a single character,
161 `todo-done-separator' will be the string made by repeating this
162 character for the width of the window, and the length is
163 automatically recalculated when the window width changes. If the
164 string consists of more (or less) than one character, it will be
165 the value of `todo-done-separator'."
172 "Return string used as value of variable `todo-done-separator'."
176 todo-done-separator-string)
180 "String used to visually separate done from not done items.
181 Displayed as an overlay instead of `todo-category-done' when
182 done items are shown. Its value is determined by user option
186 "If non-nil display only done items in current category.
187 Set by the command `todo-toggle-view-done-only' and used by
191 "List of strings surrounding item date to block diary inclusion.
192 The first string is inserted before the item date and must be a
193 non-empty string that does not match a diary date in order to
194 have its intended effect. The second string is inserted after
195 the diary date."
209 "Array of month names, in order.
214 "Array of abbreviated month names, in order.
222 todo-month-name-array
223 todo-month-abbrev-array)))
231 ;; By itself this matches anything, because of the `?'; however, it's only
232 ;; used in the context of `todo-date-pattern' (but Emacs Lisp lacks
233 ;; lookahead).
240 "Identifying string appended to the front of done todo items."
252 todo-date-pattern)
255 ;; -----------------------------------------------------------------------------
256 ;;; Todo mode display options
257 ;; -----------------------------------------------------------------------------
260 "String prefixed to todo items for visual distinction."
265 widget :error
267 widget)))
273 "Non-nil to prefix items with consecutively increasing integers.
274 These reflect the priorities of the items in each category."
281 "Return a mode line control for todo or archive file buffers.
282 Argument CAT is the name of the current todo category.
283 This function is the value of the user variable
284 `todo-mode-line-function'."
289 "Function that returns a mode line control for Todo mode buffers.
290 The function expects one argument holding the name of the current
291 todo category. The resulting control becomes the local value of
292 `mode-line-buffer-identification' in each Todo mode buffer."
297 "Non-nil means highlight items at point."
304 "Non-nil to activate Visual Line mode and use wrap prefix."
309 "Number of spaces to indent continuation lines of items.
310 This must be a positive number to ensure such items are fully
311 shown in the Fancy Diary display."
317 widget)))
321 "Indent from point to `todo-indent-to-here'."
325 "Non-nil to display done items in all categories."
329 ;; -----------------------------------------------------------------------------
330 ;;; Faces
331 ;; -----------------------------------------------------------------------------
335 "Face for making keys in item insertion prompt stand out."
339 ;; '((t :inherit font-lock-warning-face))
361 "Face for marks on marked items."
365 ;; '((t :inherit font-lock-constant-face))
376 "Face for todo item prefix or numerical priority string."
380 ;; bold font-lock-comment-face
391 "Face for top priority todo item numerical priority string.
392 The item's priority number string has this face if the number is
393 less than or equal the category's top priority setting."
397 ;; '((t :inherit font-lock-type-face))
406 "Face for non-diary markers around todo item date/time header."
411 "Face for the date string of a todo item."
416 "Face for the time string of a todo item."
420 ;; Doesn't contrast enough with todo-date (= diary) face.
421 ;; ;; '((t :inherit warning))
422 ;; '((default :weight bold)
423 ;; (((class color) (min-colors 16)) :foreground "DarkOrange")
424 ;; (((class color)) :foreground "yellow"))
425 ;; bold font-lock-function-name-face
433 "Face for expired dates of diary items."
437 ;; '((t :inherit font-lock-builtin-face))
446 "Face for separator string between done and not done todo items."
450 ;; '((t :inherit font-lock-keyword-face))
459 "Face for done todo item header string."
463 ;; '((t :inherit font-lock-comment-face))
481 "Face for comments appended to done todo items."
485 ;; '((t :inherit match))
507 "Face for matches found by `todo-search'."
511 ;; '((t :inherit widget-field))
522 "Face for buttons in table of categories."
536 "Face for sorted column in table of categories."
540 ;; '((t (:inherit (shadow))))
549 "Face for archived-only category names in table of categories."
553 ;; '((t :inherit font-lock-type-face))
562 "Face for category-file header in Todo Filtered Items mode."
565 ;; -----------------------------------------------------------------------------
566 ;;; Entering and exiting
567 ;; -----------------------------------------------------------------------------
570 "List of file finding commands for `todo-display-as-todo-file'.
571 Invoking these commands to visit a todo file or todo archive file
572 calls `todo-show' or `todo-find-archive', so that the file is
573 displayed correctly."
578 "Return the short form of todo file FILE's name.
579 This lacks the extension and directory components."
585 "Todo file visited by first session invocation of `todo-show'."
593 "Non-nil to make `todo-show' visit the current todo file.
594 Otherwise, `todo-show' always visits `todo-default-todo-file'."
601 "What action to take on first use of `todo-show' on a file."
610 "Non-nil to prompt for an item after adding a new category."
615 "Default file name offered on adding first todo file."
620 "Default category name offered on initializing a new todo file."
625 "List of files for building `todo-read-category' completions."
632 "Non-nil means case is ignored by `todo-read-*' functions."
636 ;;;###autoload
638 "Visit a todo file and display one of its categories.
640 When invoked in Todo mode, prompt for which todo file to visit.
641 When invoked outside of Todo mode with non-nil prefix argument
642 SOLICIT-FILE prompt for which todo file to visit; otherwise visit
643 `todo-default-todo-file'. Subsequent invocations from outside
644 of Todo mode revisit this file or, with option
645 `todo-show-current-file' non-nil (the default), whichever todo
646 file was last visited.
648 If you call this command before you have created any todo file in
649 the current format, and you have an todo file in old format, it
650 will ask you whether to convert that file and show it.
651 Otherwise, calling this command before any todo file exists
652 prompts for a file name and an initial category (defaulting to
653 `todo-initial-file' and `todo-initial-category'), creates both of
654 these, visits the file and displays the category, and if option
655 `todo-add-item-if-new-category' is non-nil (the default), prompts
656 for the first item.
658 The first invocation of this command on an existing todo file
659 interacts with the option `todo-show-first': if its value is
660 `first' (the default), show the first category in the file; if
661 its value is `table', show the table of categories in the file;
662 if its value is one of `top', `diary' or `regexp', show the
663 corresponding saved top priorities, diary items, or regexp items
664 file, if any. Subsequent invocations always show the file's
665 current (i.e., last displayed) category.
667 In Todo mode just the category's unfinished todo items are shown
668 by default. The done items are hidden, but typing
670 items. With non-nil user option `todo-show-with-done' both todo
671 and done items are always shown on visiting a category.
673 Invoking this command in Todo Archive mode visits the
674 corresponding todo file, displaying the corresponding category."
679 ;; Before initializing the first todo first, check if there is a
680 ;; legacy todo file and if so, offer to convert to the current
681 ;; format and make it the first new todo file.
684 todo-file-do
697 todo-archive-mode
698 todo-filtered-items-mode))))
701 nil t)
704 ;; Called noninteractively via todo-quit
705 ;; to jump to corresponding category in
706 ;; todo file.
714 todo-global-current-todo-file)
717 add-item first-file)
719 ;; We just initialized the first todo file, so make it the default.
721 first-file t)
724 ;; Can't setq t-c-t-f here, otherwise wrong file shown when
725 ;; todo-show is called from todo-show-categories-table.
732 shortf todo-show-first)))
740 "Choose a regexp items file: "
753 shortf)
760 ;; When quitting an archive file, show the corresponding
761 ;; category in the corresponding todo file, if it exists.
764 ;; If this is a new todo file, add its first category.
770 add-item todo-add-item-if-new-category
771 cat-added t)
773 ;; If the category was added, save the file now, so we
774 ;; don't risk having an empty todo file, which would
775 ;; signal an error if we tried to visit it later,
776 ;; since doing that looks for category boundaries.
778 ;; If user cancels before adding the category, clean up
779 ;; and exit, so we have a fresh slate the next time.
781 ;; (setq todo-files (funcall todo-files-function))
785 todo-current-todo-file nil)
795 "Save the current todo file."
806 "Exit the current Todo-related buffer.
807 Depending on the specific mode, this either kills the buffer or
808 buries it and restores state as needed."
812 ;; Postpone killing buffer till after calling todo-show, to
813 ;; prevent killing todo-mode buffer.
815 ;; Ensure todo-show calls todo-show-categories-table only on
816 ;; first invocation per file.
825 ;; Have to write a newly created archive to file to avoid
826 ;; subsequent errors.
834 ;; When todo-check-file runs in todo-show, it kills the
835 ;; buffer if the archive file was deleted externally.
839 ;; If we just quit archive mode, just burying the buffer
840 ;; in todo-mode would return to archive.
845 ;; -----------------------------------------------------------------------------
846 ;;; Navigation between and within categories
847 ;; -----------------------------------------------------------------------------
850 "Non-nil to handle categories with only archived items specially.
854 archived items. Other commands still recognize these categories.
856 categories shown in `todo-archived-only' face and pressing the
857 category button visits the category in the archive instead of the
858 todo file."
863 "Visit the numerically next category in this todo file.
864 If the current category is the highest numbered, visit the first
865 category. With non-nil argument BACK, visit the numerically
866 previous category (the highest numbered one, if the current
867 category is the first)."
882 "Visit the numerically previous category in this todo file.
883 If the current category is the highest numbered, visit the first
884 category."
891 "Prompt for a category in a todo file and jump to it.
893 With non-nil FILE (interactively a prefix argument), prompt for a
894 specific todo file and choose (with TAB completion) a category
895 in it to jump to; otherwise, choose and jump to any category in
896 either the current todo file or a file in
897 `todo-category-completions-files'.
899 Also accept a non-existing category name and ask whether to add a
900 new category by that name; on confirmation, add it and jump to
901 that category, and if option `todo-add-item-if-new-category' is
902 non-nil (the default), then prompt for the first item.
904 In noninteractive calls non-nil WHERE specifies either the goal
905 category or its file. If its value is `archive', the choice of
906 categories is restricted to the current archive file or the
907 archive you were prompted to choose; this is used by
908 `todo-jump-to-archive-category'. If its value is the name of a
909 category, jump directly to that category; this is used in Todo
910 Categories mode."
912 ;; If invoked outside of Todo mode and there is not yet any Todo
913 ;; file, initialize one.
919 ;; With non-nil `todo-skip-archived-categories'
920 ;; jump to archive file of a category with only
921 ;; archived items.
928 ;; Otherwise, jump to current todo file.
929 todo-current-todo-file)))
940 ;; If called from Todo Categories mode, clean up before jumping.
953 "Move point down to the beginning of the next item.
954 With positive numerical prefix COUNT, move point COUNT items
955 downward.
957 If the category's done items are hidden, this command also moves
958 point to the empty line below the last todo item from any higher
959 item in the category, i.e., when invoked with or without a prefix
960 argument. If the category's done items are visible, this command
961 called with a prefix argument only moves point to a lower item,
962 e.g., with point on the last todo item and called with prefix 1,
963 it moves point to the first done item; but if called with point
964 on the last todo item without a prefix argument, it moves point
965 the the empty line above the done items separator."
967 ;; It's not worth the trouble to allow prefix arg value < 1, since
968 ;; we have the corresponding command.
977 "Move point up to start of item with next higher priority.
978 With positive numerical prefix COUNT, move point COUNT items
979 upward.
981 If the category's done items are visible, this command called
982 with a prefix argument only moves point to a higher item, e.g.,
983 with point on the first done item and called with prefix 1, it
984 moves to the last todo item; but if called with point on the
985 first done item without a prefix argument, it moves point the the
986 empty line above the done items separator."
988 ;; Avoid moving to bob if on the first item but not at bob.
990 ;; It's not worth the trouble to allow prefix arg value < 1, since
991 ;; we have the corresponding command.
999 ;; -----------------------------------------------------------------------------
1000 ;;; Display toggle commands
1001 ;; -----------------------------------------------------------------------------
1004 "Hide item numbering if shown, show if hidden."
1019 "Show hidden or hide visible done items in current category."
1029 ;; If start of done items sections is below the bottom of the
1030 ;; window, make it visible.
1040 "Switch between displaying only done or only todo items."
1046 "Highlight or unhighlight the todo item the cursor is on."
1056 "Hide or show item date-time headers in the current file.
1057 With done items, this hides only the done date-time string, not
1058 the the original date-time string."
1073 nil t)
1079 ;; -----------------------------------------------------------------------------
1080 ;;; File and category editing
1081 ;; -----------------------------------------------------------------------------
1084 "Name and initialize a new todo file.
1085 Interactively, prompt for a category and display it, and if
1086 option `todo-add-item-if-new-category' is non-nil (the default),
1087 prompt for the first item.
1088 Noninteractively, return the name of the new file."
1105 file)))
1108 "Rename the current todo file.
1109 With prefix ARG, prompt for a todo file and rename it.
1110 If there are corresponding archive or filtered items files,
1111 rename these accordingly. If there are live buffers visiting
1112 these files, also rename them accordingly."
1116 nil t))
1154 "Delete the current todo, archive or filtered items file.
1155 If the todo file has a corresponding archive file, or vice versa,
1156 prompt whether to delete that as well. Also kill the buffers
1157 visiting the deleted files."
1206 "Put current buffer in `todo-edit-mode'.
1207 This makes the entire file visible and the buffer writeable and
1208 you can use the self-insertion keys and standard Emacs editing
1209 commands to make changes. To return to Todo mode, type
1211 an error if the format has become invalid. However, this check
1212 cannot tell if the number of items changed, which could result in
1213 the file containing inconsistent information. For this reason
1214 this command should be used with caution."
1224 "Add a new category to a todo file.
1226 Called interactively with prefix argument FILE, prompt for a file
1227 and then for a new category to add to that file, otherwise prompt
1228 just for a category to add to the current todo file. After
1229 adding the category, visit it in Todo mode and if option
1230 `todo-add-item-if-new-category' is non-nil (the default), prompt
1231 for the first item.
1233 Non-interactively, add category CAT to file FILE; if FILE is nil,
1234 add CAT to the current todo file. After adding the category,
1235 return the new category number."
1238 ;; If cat is passed from caller, don't prompt, unless it is "",
1239 ;; which means the file was just added and has no category yet.
1242 todo-current-todo-file))
1245 file))
1249 file)))
1262 ;; If invoked by user, display the newly added category, if
1263 ;; called programmatically return the category number to the
1264 ;; caller.
1271 num))))
1274 "Rename current todo category.
1275 If this file has an archive containing this category, rename the
1276 category there as well."
1299 nil t)
1305 "Delete current todo category provided it contains no items.
1306 With prefix ARG delete the category even if it does contain
1307 todo or done items."
1327 "after deleting the todo category. "
1329 "(see `todo-skip-archived-categories' "
1348 ;; If deleted category was the only one, delete the file.
1351 ;; Skip confirming killing the archive buffer if it has been
1352 ;; modified and not saved.
1358 todo-categories))
1367 "Move current category to a different todo file.
1368 If the todo file chosen does not exist, it is created.
1369 If the current category has archived items, also move those to
1370 the archive of the file moved to, creating it if it does not exist."
1384 new)
1403 nil t))
1411 buffer-read-only)
1412 ;; Move the category to the new file. Also update or create
1413 ;; archive file if necessary.
1416 ;; Regenerate todo-archives in case there
1417 ;; is a newly created archive.
1420 nfile))
1424 nfile-short)
1427 buffer-read-only)
1431 ;; If the file moved to has a category with the same
1432 ;; name, rename the moved category.
1438 ;; Replace old with new name in todo and archive files.
1448 ;; If archive was just created, save it to avoid "File
1449 ;; <xyz> no longer exists!" message on invoking
1450 ;; `todo-view-archived-items'.
1455 ;; Delete the category from the old file, and if that was the
1456 ;; last category, delete the file. Also handle archive file
1457 ;; if necessary.
1461 ;; Put point after todo-categories sexp.
1465 ;; Skip confirming killing the archive buffer.
1472 todo-categories))
1481 "Merge current category into another existing category.
1483 With prefix argument FILE, prompt for a specific todo file and
1484 choose (with TAB completion) a category in it to merge into;
1485 otherwise, choose and merge into a category in either the
1486 current todo file or a file in `todo-category-completions-files'.
1488 After merging, the current category's todo and done items are
1489 appended to the chosen goal category's todo and done items,
1490 respectively. The goal category becomes the current category,
1491 and the previous current category is deleted.
1493 If both the first and goal categories also have archived items,
1494 the former are merged to the latter. If only the first category
1495 has archived items, the archived category is renamed to the goal
1496 category."
1505 archived-count here)
1506 ;; Merge in todo file.
1519 ;; Omit empty line between todo and done items.
1531 ;; Merge any todo items.
1535 nil t)
1542 ;; Merge any done items.
1554 todo-categories))
1558 ;; Merge in archive file.
1567 nil t)
1574 nil t)
1577 cend carch)
1583 nil t)
1588 ;; If both categories of the merge have archived items, merge the
1589 ;; source items to the goal items, else "merge" by renaming the
1590 ;; source category to goal.
1595 nil t)
1612 ;; If there are only merged done items, show them.
1615 ;; Put point on the first merged item.
1619 ;; -----------------------------------------------------------------------------
1620 ;;; Item editing
1621 ;; -----------------------------------------------------------------------------
1624 "Non-nil to allow new todo items to be included in the diary."
1629 "Non-nil to insert new todo diary items as nonmarking by default.
1630 This appends `diary-nonmarking-symbol' to the front of an item on
1631 insertion provided it doesn't begin with `todo-nondiary-marker'."
1636 "Non-nil adds current time to a new item's date header by default.
1638 argument, this reverses the effect of
1639 `todo-always-add-time-string': if t, these commands omit the
1640 current time, if nil, they include it."
1645 "Non-nil to enable inserting only highlighted region as new item."
1650 "Default priority of new and moved items."
1656 "String used to mark items.
1657 To ensure item marking works, change the value of this option
1658 only when no items are marked."
1663 widget :error
1665 widget)))
1671 "String inserted before optional comment appended to done item."
1678 "Whether to omit done item comment on undoing the item.
1679 Nil means never omit the comment, t means always omit it, `ask'
1680 means prompt user and omit comment only on confirmation."
1687 "Mark item with `todo-item-mark' if unmarked, otherwise unmark it.
1688 With a positive numerical prefix argument N, change the
1689 marking of the next N items."
1715 "Mark all visible items in this category with `todo-item-mark'."
1732 "Remove `todo-item-mark' from all visible items in this category."
1740 ;; No overlay on empty line between todo and done items.
1755 "Insert a new todo item into a category.
1757 With no prefix argument ARG, add the item to the current
1758 category; with one prefix argument (`C-u'), prompt for a category
1759 from the current todo file; with two prefix arguments (`C-u
1760 C-u'), first prompt for a todo file, then a category in that
1761 file. If a non-existing category is entered, ask whether to add
1762 it to the todo file; if answered affirmatively, add the category
1763 and insert the item there.
1765 There are a number of item insertion parameters which can be
1766 combined by entering specific keys to produce different insertion
1767 commands. After entering each key, a message shows which have
1768 already been entered and which remain available. See
1769 `todo-basic-insert-item' for details of the parameters and their
1770 effects."
1776 region-or-here)
1777 "Insert a new todo item into a category.
1778 This is the function from which the generated Todo mode item
1779 insertion commands derive.
1781 The generated commands have mnemonic key bindings based on the
1782 arguments' values and their order in the command's argument list,
1783 as follows: (1) for DIARY `d', (2) for NONMARKING `k', (3) for
1784 DATE-TYPE either `c' for calendar or `d' for date or `n' for
1785 weekday name, (4) for TIME `t', (5) for REGION-OR-HERE either `r'
1786 for region or `h' for here. Sequences of these keys are appended
1787 to the insertion prefix key `i'. Keys that allow a following
1788 key (i.e., any but `r' or `h') must be doubled when used finally.
1789 For example, the command bound to the key sequence `i y h' will
1790 insert a new item with today's date, marked according to the
1791 DIARY argument described below, and with priority according to
1792 the HERE argument; `i y y' does the same except that the priority
1793 is not given by HERE but by prompting.
1795 In command invocations, ARG is passed as a prefix argument as
1796 follows. With no prefix argument, add the item to the current
1797 category; with one prefix argument (`C-u'), prompt for a category
1798 from the current todo file; with two prefix arguments (`C-u C-u'),
1799 first prompt for a todo file, then a category in that file. If
1800 a non-existing category is entered, ask whether to add it to the
1801 todo file; if answered affirmatively, add the category and
1802 insert the item there.
1804 The remaining arguments are set or left nil by the generated item
1805 insertion commands; their meanings are described in the follows
1806 paragraphs.
1808 When argument DIARY is non-nil, this overrides the intent of the
1809 user option `todo-include-in-diary' for this item: if
1810 `todo-include-in-diary' is nil, include the item in the Fancy
1811 Diary display, and if it is non-nil, exclude the item from the
1812 Fancy Diary display. When DIARY is nil, `todo-include-in-diary'
1813 has its intended effect.
1815 When the item is included in the Fancy Diary display and the
1816 argument NONMARKING is non-nil, this overrides the intent of the
1817 user option `todo-diary-nonmarking' for this item: if
1818 `todo-diary-nonmarking' is nil, append `diary-nonmarking-symbol'
1819 to the item, and if it is non-nil, omit `diary-nonmarking-symbol'.
1821 The argument DATE-TYPE determines the content of the item's
1822 mandatory date header string and how it is added:
1823 - If DATE-TYPE is the symbol `calendar', the Calendar pops up and
1824 when the user puts the cursor on a date and hits RET, that
1825 date, in the format set by `calendar-date-display-form',
1826 becomes the date in the header.
1827 - If DATE-TYPE is a string matching the regexp
1828 `todo-date-pattern', that string becomes the date in the
1829 header. This case is for the command
1830 `todo-insert-item-from-calendar' which is called from the
1831 Calendar.
1832 - If DATE-TYPE is the symbol `date', the header contains the date
1833 in the format set by `calendar-date-display-form', with year,
1834 month and day individually prompted for (month with tab
1835 completion).
1836 - If DATE-TYPE is the symbol `dayname' the header contains a
1837 weekday name instead of a date, prompted for with tab
1838 completion.
1839 - If DATE-TYPE has any other value (including nil or none) the
1840 header contains the current date (in the format set by
1841 `calendar-date-display-form').
1843 With non-nil argument TIME prompt for a time string, which must
1844 match `diary-time-regexp'. Typing `<return>' at the prompt
1845 returns the current time, if the user option
1846 `todo-always-add-time-string' is non-nil, otherwise the empty
1847 string (i.e., no time string). If TIME is absent or nil, add or
1848 omit the current time string according as
1849 `todo-always-add-time-string' is non-nil or nil, respectively.
1851 The argument REGION-OR-HERE determines the source and location of
1852 the new item:
1853 - If the REGION-OR-HERE is the symbol `here', prompt for the text of
1854 the new item and, if the command was invoked with point in the todo
1855 items section of the current category, give the new item the
1856 priority of the item at point, lowering the latter's priority and
1857 the priority of the remaining items. If point is in the done items
1858 section of the category, insert the new item as the first todo item
1859 in the category. Likewise, if the command with `here' is invoked
1860 outside of the current category, jump to the chosen category and
1861 insert the new item as the first item in the category.
1862 - If REGION-OR-HERE is the symbol `region', use the region of the
1863 current buffer as the text of the new item, depending on the
1864 value of user option `todo-use-only-highlighted-region': if
1865 this is non-nil, then use the region only when it is
1866 highlighted; otherwise, use the region regardless of
1867 highlighting. An error is signalled if there is no region in
1868 the current buffer. Prompt for the item's priority in the
1869 category (an integer between 1 and one more than the number of
1870 items in the category), and insert the item accordingly.
1871 - If REGION-OR-HERE has any other value (in particular, nil or
1872 none), prompt for the text and the item's priority, and insert
1873 the item accordingly."
1874 ;; If invoked outside of Todo mode and there is not yet any Todo
1875 ;; file, initialize one.
1897 todo-global-current-todo-file)
1899 todo-default-todo-file))))))
1914 ;; If user exits Calendar before choosing
1915 ;; a date, cancel item insertion.
1931 ;; If this command was invoked outside of a Todo mode buffer,
1932 ;; the call to todo-current-category above returned nil. If
1933 ;; we just entered Todo mode now, then cat was set to the
1934 ;; file's first category, but if todo-mode was already
1935 ;; enabled, cat did not get set, so we have to do that.
1943 done-only item-added)
1945 ;; Add date, time and diary marking as required.
1947 todo-nondiary-start
1949 diary-nonmarking-symbol))
1952 time-string))))
1955 todo-nondiary-end)
1957 ;; Indent newlines inserted by C-q C-j if nonspace char follows.
1962 ;; Make sure the correct category is selected. There
1963 ;; are two cases: (i) we just visited the file, so no
1964 ;; category is selected yet, or (ii) we invoked
1965 ;; insertion "here" from outside the category we want
1966 ;; to insert in (with priority insertion, category
1967 ;; selection is done by todo-set-item-priority).
1972 ;; If only done items are displayed in category,
1973 ;; toggle to todo items before inserting new item.
1981 ;; If command was invoked with point in done
1982 ;; items section or outside of the current
1983 ;; category, can't insert "here", so to be
1984 ;; useful give new item top priority.
1986 called-from-outside
1987 done-only)
1992 ;; If user cancels before setting priority, restore
1993 ;; display.
2003 ;; If the todo items section is not visible when the
2004 ;; insertion command is called (either because only done
2005 ;; items were shown or because the category was not in the
2006 ;; current buffer), then if the item is inserted at the
2007 ;; end of the category, point is at eob and eob at
2008 ;; window-start, so that higher priority todo items are
2009 ;; out of view. So we recenter to make sure the todo
2010 ;; items are displayed in the window.
2017 "Return string of date chosen from Calendar."
2020 todo-date-from-calendar)
2025 ;; If user exits Calendar before choosing a date, clean up properly.
2039 todo-date-from-calendar)
2044 todo-date-from-calendar)))))
2047 "Prompt for and insert a new item with date selected from calendar.
2048 Invoked without prefix argument ARG, insert the item into the
2049 current category, without one prefix argument, prompt for the
2050 category from the current todo file or from one listed in
2051 `todo-category-completions-files'; with two prefix arguments,
2052 prompt for a todo file and then for a category in it."
2062 "Copy item at point and insert the copy as a new item."
2073 "Delete at least one item in this category.
2074 If there are marked items, delete all of these; otherwise, delete
2075 the item at point."
2091 buffer-read-only)
2105 ;; Don't leave point below last item.
2119 "Edit the todo item at point.
2120 With non-nil prefix argument ARG, include the item's date/time
2121 header, making it also editable; otherwise, include only the item
2122 content.
2124 If the item consists of only one logical line, edit it in the
2125 minibuffer; otherwise, edit it in Todo Edit mode."
2153 ;; Ensure lines following hard newlines are indented.
2156 ;; If user moved point during editing, make sure it moves back.
2163 "Edit current todo item in Todo Edit mode.
2164 Use of newlines invokes `todo-indent' to insure compliance with
2165 the format of Diary entries."
2178 "Return from Todo Edit mode to Todo mode.
2179 If the item contains hard line breaks, make sure the following
2180 lines are indented by `todo-indent-to-here' to conform to diary
2181 format.
2183 If the whole file was in Todo Edit mode, check before returning
2184 whether the file is still a valid todo file and if so, also
2185 recalculate the todo file's categories sexp, in case changes were
2186 made in the number or names of categories."
2189 ;; We got here via `e m'.
2197 ;; Ensure lines following hard newlines are indented.
2205 ;; We got here via `F e'.
2207 ;; FIXME: separate out sexp check?
2208 ;; If manual editing makes e.g. item counts change, have to
2209 ;; call this to update todo-categories, but it restores
2210 ;; category order to list order.
2211 ;; (todo-repair-categories-sexp)
2212 ;; Compare (todo-make-categories-list t) with sexp and if
2213 ;; different ask (todo-update-categories-sexp) ?
2229 "Function underlying commands to edit item date/time header.
2231 The argument WHAT (passed by invoking commands) specifies what
2232 part of the header to edit; possible values are these symbols:
2233 `date', to edit the year, month, and day of the date string;
2234 `time', to edit just the time string; `calendar', to select the
2235 date from the Calendar; `today', to set the date to today's date;
2236 `dayname', to set the date string to the name of a day or to
2237 change the day name; and `year', `month' or `day', to edit only
2238 these respective parts of the date string (`day' is the number of
2239 the given day of the month, and `month' is either the name of the
2240 given month or its number, depending on the value of
2241 `calendar-date-display-form').
2243 The optional argument INC is a positive or negative integer
2244 \(passed by invoking commands as a numerical prefix argument)
2245 that in conjunction with the WHAT values `year', `month' or
2246 `day', increments or decrements the specified date string
2247 component by the specified number of suitable units, i.e., years,
2248 months, or days, with automatic adjustment of the other date
2249 string components as necessary.
2251 If there are marked items, apply the same edit to all of these;
2252 otherwise, edit just the item at point."
2258 ndate ntime year monthname month day
2269 todo-date-pattern
2293 ;; If there are marked items, use only the first to set
2294 ;; header changes, and apply these to all marked items.
2309 ;; When date string consists only of a day name,
2310 ;; passing other date components is a noop.
2314 monthname omonthname
2315 month omonth
2324 year oyear
2326 month
2327 monthname)
2334 ;; Increment or decrement month by INC
2335 ;; modulo 12.
2337 ;; If result is 0, make month December.
2339 ;; Adjust year if necessary.
2346 oyear)))
2347 ;; Return the changed numerical month as
2348 ;; a string or the corresponding month name.
2353 ;; When mm is 13 (corresponding to "*" as value
2354 ;; of month), this raises an args-out-of-range
2355 ;; error in calendar-last-day-of-month, so use 1
2356 ;; (corresponding to January) to get 31 days.
2365 month omonth
2366 monthname omonthname
2377 ;; Increment or decrement day by INC,
2378 ;; adjusting month and year if necessary
2379 ;; (if year is "*" assume current year to
2380 ;; calculate adjustment).
2388 ;; Set year and month(name) to adjusted values.
2394 ;; Return changed numerical day as a string.
2397 ;; If year, month or day date string components were
2398 ;; changed, rebuild the date string.
2402 ;; Add new time string to the header, if it was supplied.
2410 ;; Apply the changes to the first marked item header to the
2411 ;; remaining marked items. If there are no marked items,
2412 ;; we're finished.
2418 "Interactively edit at least the date of item's date/time header.
2419 If user option `todo-always-add-time-string' is non-nil, also
2420 edit item's time string."
2427 "Interactively edit the time string of item's date/time header."
2432 "Interactively edit item's date using the Calendar."
2437 "Set item's date to today's date."
2442 "Replace item's date with the name of a day of the week."
2447 "Interactively edit the year of item's date string.
2448 With prefix argument INC a positive or negative integer,
2449 increment or decrement the year by INC."
2454 "Interactively edit the month of item's date string.
2455 With prefix argument INC a positive or negative integer,
2456 increment or decrement the month by INC."
2461 "Interactively edit the day of the month of item's date string.
2462 With prefix argument INC a positive or negative integer,
2463 increment or decrement the day by INC."
2468 "Change diary status of one or more todo items in this category.
2469 That is, insert `todo-nondiary-marker' if the candidate items
2470 lack this marking; otherwise, remove it.
2472 If there are marked todo items, change the diary status of all
2473 and only these, otherwise change the diary status of the item at
2474 point."
2478 todo-categories-with-marks)))
2507 "Make all items in this category diary items.
2508 With prefix ARG, make all items in this category non-diary
2509 items."
2542 "Change non-marking of one or more diary items in this category.
2543 That is, insert `diary-nonmarking-symbol' if the candidate items
2544 lack this marking; otherwise, remove it.
2546 If there are marked todo items, change the non-marking status of
2547 all and only these, otherwise change the non-marking status of
2548 the item at point."
2552 todo-categories-with-marks)))
2569 "Add `diary-nonmarking-symbol' to all diary items in this category.
2570 With prefix ARG, remove `diary-nonmarking-symbol' from all diary
2571 items in this category."
2589 "Prompt for and set ITEM's priority in CATegory.
2591 Interactively, ITEM is the todo item at point, CAT is the current
2592 category, and the priority is a number between 1 and the number
2593 of items in the category. Non-interactively, non-nil NEW means
2594 ITEM is a new item and the lowest priority is one more than the
2595 number of items in CAT.
2597 The new priority is set either interactively by prompt or by a
2598 numerical prefix argument, or noninteractively by argument ARG,
2599 whose value can be either of the symbols `raise' or `lower',
2600 meaning to raise or lower the item's priority by one."
2611 todo-date-pattern
2618 curnum
2629 count)))
2635 current-prefix-arg)
2640 candidate
2641 buffer-read-only)
2645 ;; When moving item to another category, show the category before
2646 ;; prompting for its priority.
2649 ;; If done items in category are visible, keep them visible.
2657 ;; Keep top of category in view while setting priority.
2659 ;; Prompt for priority only when the category has at least one
2660 ;; todo item.
2668 maxnum)))
2670 ;; In Top Priorities buffer, an item's priority can be changed
2671 ;; wrt items in another category, but not wrt items in the same
2672 ;; category.
2694 ;; Interactively or with non-nil ARG, relocate the item within its
2695 ;; category.
2702 ;; When called from todo-item-undone and the highest priority
2703 ;; is chosen, this advances point to the first done item, so
2704 ;; move it up to the empty line above the done items
2705 ;; separator.
2711 ;; If item was marked, restore the mark.
2719 "Raise priority of current item by moving it up by one item."
2724 "Lower priority of current item by moving it down by one item."
2729 "Move at least one todo or done item to another category.
2730 If there are marked items, move all of these; otherwise, move
2731 the item at point.
2733 With prefix argument FILE, prompt for a specific todo file and
2734 choose (with TAB completion) a category in it to move the item or
2735 items to; otherwise, choose and move to any category in either
2736 the current todo file or one of the files in
2737 `todo-category-completions-files'. If the chosen category is
2738 not an existing categories, then it is created and the item(s)
2739 become(s) the first entry/entries in that category.
2741 With moved todo items, prompt to set the priority in the category
2742 moved to (with multiple todo items, the one that had the highest
2743 priority in the category moved from gets the new priority and the
2744 rest of the moved todo items are inserted in sequence below it).
2745 Moved done items are appended to the top of the done items
2746 section in the category moved to."
2750 ;; Noop if point is not on an item and there are no marked items.
2763 ov cat2 file2 moved nmark todo-items done-items)
2773 nil file)))
2797 ;; Chop off last newline of multiple todo item string,
2798 ;; since it will be reinserted when setting priority
2799 ;; (but with done items priority is not set, so keep
2800 ;; last newline).
2813 ;; Move done items en bloc to top of done items section.
2827 ;; Move succeeded, so remove item from starting category,
2828 ;; update item counts and display the category containing
2829 ;; the moved item.
2872 ;; If item is moved to end of (just first?) category, make
2873 ;; sure the items above it are displayed in the window.
2875 ;; User quit before setting priority of todo item(s), so
2876 ;; return to starting category.
2885 "Tag a todo item in this category as done and relocate it.
2887 With prefix argument ARG prompt for a comment and append it to
2888 the done item; this is only possible if there are no marked
2889 items. If there are marked items, tag all of these with
2890 `todo-done-string' plus the current date and, if
2891 `todo-always-add-time-string' is non-nil, the current time;
2892 otherwise, just tag the item at point. Items tagged as done are
2893 relocated to the category's (by default hidden) done section. If
2894 done items are visible on invoking this command, they remain
2895 visible."
2916 ;; Point is between todo and done items.
2932 item done-item opoint)
2933 ;; Don't add empty comment to done item.
2938 ;; Stop looping when we hit the empty line below the last
2939 ;; todo item (this is eobp if only done items are hidden).
2953 ;; Chop off last newline of done item string.
2970 ;; When done items are shown, put cursor on first just done item.
2974 "Add a comment to this done item or edit an existing comment.
2975 With prefix ARG delete an existing comment."
2981 comment buffer-read-only)
2994 ;; If user moved point during editing, make sure it moves back.
3000 "Restore at least one done item to this category's todo section.
3001 Prompt for the new priority. If there are marked items, undo all
3002 of these, giving the first undone item the new priority and the
3003 rest following directly in sequence; otherwise, undo just the
3004 item at point.
3006 If the done item has a comment, ask whether to omit the comment
3007 from the restored item. With multiple marked done items with
3008 comments, only ask once, and if affirmed, omit subsequent
3009 comments without asking."
3021 start end item ov npoint undone)
3033 ;; Find the end of the date string added upon tagging item as
3034 ;; done.
3040 ;; Ask (once) whether to omit done item's comment. If
3041 ;; affirmed, omit subsequent comments without asking.
3051 " from restored item"
3055 t)
3066 ;; Chop off last newline of multiple items string, since
3067 ;; it will be reinserted on setting priority.
3094 ;; Put cursor on undone item.
3098 ;; -----------------------------------------------------------------------------
3099 ;;; Done item archives
3100 ;; -----------------------------------------------------------------------------
3103 "Visit the archive of the current todo category, if it exists.
3104 If the category has no archived items, prompt to visit the
3105 archive anyway. If there is no archive for this file or with
3106 non-nil argument ASK, prompt to visit another archive.
3108 The buffer showing the archive is in Todo Archive mode. The
3109 first visit in a session displays the first category in the
3110 archive, subsequent visits return to the last category
3111 displayed."
3141 "Choose an archive and visit it."
3146 "Archive at least one done item in this category.
3148 With prefix argument ALL, prompt whether to archive all done
3149 items in this category and on confirmation archive them.
3150 Otherwise, if there are marked done items (and no marked todo
3151 items), archive all of these; otherwise, archive the done item at
3152 point.
3154 If the archive of this file does not exist, it is created. If
3155 this category does not exist in the archive, it is created."
3171 marked-items beg end all-done
3172 buffer-read-only)
3182 nil t)
3187 nil t)
3192 ;; Restore starting point, unless it was on a done
3193 ;; item, since they will all be deleted.
3216 nil t)
3218 nil t))
3219 ;; Start of done items section in existing category.
3222 ;; Start of done items section in new category.
3229 ;; If archive is new, save to file now (with
3230 ;; write-region to avoid prompt for file to save to)
3231 ;; to update todo-archives, and to let auto-mode-alist
3232 ;; take effect below on visiting the archive.
3242 ;; Make sure done items are accessible.
3249 ;; If we're archiving all done items, can't
3250 ;; first archive item point was on, since
3251 ;; that will short-circuit the rest.
3261 ;; Don't leave point below last item.
3277 ;; Make todo file current to select category.
3279 ;; Make sure done item separator is hidden (if done items
3280 ;; were initially visible).
3284 "Unarchive at least one item in this archive category.
3285 If there are marked items, unarchive all of these; otherwise,
3286 unarchive the item at point.
3288 Unarchived items are restored as done items to the corresponding
3289 category in the todo file, inserted at the top of done items
3290 section. If all items in the archive category have been
3291 restored, the category is deleted from the archive. If this was
3292 the only category in the archive, the archive file is deleted."
3302 marked-items
3303 buffer-read-only)
3312 ;; Restore items to top of category's done section and update counts.
3317 ;; Find the corresponding todo category, or if there isn't
3318 ;; one, add it.
3324 ;; Go to top of category's done section.
3339 ;; Delete restored items from archive.
3352 ;; If that was the last category in the archive, delete the whole file.
3356 ;; Kill the archive buffer silently.
3359 ;; Otherwise, if the archive category is now empty, delete it.
3364 nil t))
3373 todo-categories))
3375 ;; Visit category in todo file and show restored done items.
3385 "Prompt for a category in a todo archive and jump to it.
3386 With prefix argument FILE, prompt for an archive and choose (with
3387 TAB completion) a category in it to jump to; otherwise, choose
3388 and jump to any category in the current archive."
3392 ;; -----------------------------------------------------------------------------
3393 ;;; Displaying and sorting tables of categories
3394 ;; -----------------------------------------------------------------------------
3397 "Category button label in Todo Categories mode."
3402 "Todo button label in Todo Categories mode."
3407 "Diary button label in Todo Categories mode."
3412 "Done button label in Todo Categories mode."
3417 "Archived button label in Todo Categories mode."
3422 "String to label total item counts in Todo Categories mode."
3427 "String between number and category in Todo Categories mode.
3428 This separates the number from the category name in the default
3429 categories display according to priority."
3434 "Alignment of category names in Todo Categories mode."
3439 "Display a table of the current file's categories and item counts.
3441 In the initial display the lines of the table are numbered,
3442 indicating the current order of the categories when sequentially
3449 with a numeric prefix. If you save the todo file after
3450 reordering the categories, the new order persists in subsequent
3451 Emacs sessions.
3453 The labels above the category names and item counts are buttons,
3454 and clicking these changes the display: sorted by category name
3455 or by the respective item counts (alternately descending or
3456 ascending). In these displays the categories are not numbered
3459 sorting is triggered by passing a non-nil SORTKEY argument.)
3461 In addition, the lines with the category names and item counts
3462 are buttonized, and pressing one of these button jumps to the
3463 category in Todo mode (or Todo Archive mode, for categories
3464 containing only archived items, provided user option
3465 `todo-skip-archived-categories' is non-nil. These categories
3466 are shown in `todo-archived-only' face."
3473 "Move point to the Nth next button in the table of categories."
3477 ;; Align with beginning of category label.
3481 "Move point to the Nth previous button in the table of categories."
3485 ;; Align with beginning of category label.
3489 "Change number of category at point in the table of categories.
3491 With ARG nil, prompt for the new number. Alternatively, the
3492 enter the new number with numerical prefix ARG. Otherwise, if
3493 ARG is either of the symbols `raise' or `lower', raise or lower
3494 the category line in the table by one, respectively, thereby
3495 decreasing or increasing its number."
3498 ;; Get the number representing the priority of the category
3499 ;; on the current line.
3510 candidate)
3517 maxnum))
3526 todo-categories))
3527 ;; Category's name and items counts list.
3530 newcats)
3544 "Raise priority of category at point in the table of categories."
3549 "Lower priority of category at point in the table of categories."
3554 "Sort table of categories alphabetically or numerically."
3567 "Sort table of categories by number of todo items."
3575 "Sort table of categories by number of diary items."
3583 "Sort table of categories by number of non-archived done items."
3591 "Sort table of categories by number of archived items."
3602 "Return the length of the longest name in list CATEGORIES."
3608 "Return adjusted length of category label button.
3609 The adjustment ensures proper tabular alignment in Todo
3610 Categories mode."
3620 "Return category name or label string STR padded with spaces.
3621 The placement of the padding is determined by the value of user
3622 option `todo-categories-align'."
3642 "Return a copy of LIST, possibly sorted according to KEY."
3647 ;; Keep track of whether the last sort by key was descending or
3648 ;; ascending.
3658 ;; Switch between descending and ascending sort order.
3663 l))
3666 "Keep point on the TYPE count sorting button just clicked."
3672 "Return symbol for sort key associated with LABEL."
3684 key))
3687 "Insert button for displaying categories sorted by item counts.
3688 LABEL determines which type of count is sorted."
3691 label))
3694 ov)
3696 'action
3702 ;; If display is alphabetical, switch back to
3703 ;; category priority order.
3712 "Return a list of total item counts for the current file."
3721 "Insert button with category CAT's name and item counts.
3722 With non-nil argument NONUM show only these; otherwise, insert a
3723 number in front of the button indicating the category's priority.
3724 The number and the category name are separated by the string
3725 which is the value of the user option
3726 `todo-categories-number-separator'."
3737 str
3742 ;; Add an extra space if label length is odd.
3757 'todo-archived-only
3758 nil)
3762 ;; Highlight the sorted count column.
3764 end ovl)
3786 "Prepare buffer for displaying table of categories and item counts."
3796 buffer-read-only)
3803 ;; Make space for the column of category numbers.
3805 ;; Add the category and item count buttons (if this is the list of
3806 ;; categories in an archive, show only done item counts).
3823 "Populate table of categories and sort by SORTKEY."
3828 ;; Find start of Category button if we just entered Todo Categories
3829 ;; mode.
3838 ;; Fill in the table with buttonized lines, each showing a category and
3839 ;; its item counts.
3843 ;; Add a line showing item count totals.
3851 ;; Add an extra space if label length is odd.
3860 ;; Put cursor on Category button initially.
3864 ;; -----------------------------------------------------------------------------
3865 ;;; Searching and item filtering
3866 ;; -----------------------------------------------------------------------------
3869 "Search for a regular expression in this todo file.
3870 The search runs through the whole file and encompasses all and
3871 only todo and done items; it excludes category names. Multiple
3872 matches are shown sequentially, highlighted in `todo-search'
3873 face."
3877 matches match cat in-done ov mlen msg)
3911 mlen)
3916 mlen)
3930 "Remove highlighting on matches found by todo-search."
3935 "List of rules specifying number of top priority items to show.
3936 These rules override `todo-top-priorities' on invocations of
3939 of the form (FILE NUM ALIST), where FILE is a member of
3940 `todo-files', NUM is a number specifying the default number of
3941 top priority items for each category in that file, and ALIST,
3942 when non-nil, consists of conses of a category name in FILE and a
3943 number specifying the default number of top priority items in
3944 that category, which overrides NUM.
3946 This variable should be set interactively by
3953 "Default number of top priorities shown by `todo-filter-top-priorities'."
3958 "List of default files for multifile item filtering."
3965 "Non-nil to include done items when processing regexp filters.
3966 Done items from corresponding archive files are also included."
3971 "Set number of top priorities for this file.
3972 See `todo-set-top-priorities' for more details."
3977 "Set number of top priorities for this category.
3978 See `todo-set-top-priorities' for more details."
3983 "Display a list of top priority items from different categories.
3984 The categories can be any of those in the current todo file.
3986 With numerical prefix ARG show at most ARG top priority items
3987 from each category. With `C-u' as prefix argument show the
3988 numbers of top priority items specified by category in
3989 `todo-top-priorities-overrides', if this has an entry for the file(s);
3990 otherwise show `todo-top-priorities' items per category in the
3991 file(s). With no prefix argument, if a top priorities file for
3992 the current todo file has previously been saved (see
3993 `todo-save-filtered-items-buffer'), visit this file; if there is
3994 no such file, build the list as with prefix argument `C-u'.
3996 The prefix ARG regulates how many top priorities from
3997 each category to show, as described above."
4002 "Display a list of top priority items from different categories.
4003 The categories are a subset of the categories in the files listed
4004 in `todo-filter-files', or if this nil, in the files chosen from
4005 a file selection dialog that pops up in this case.
4007 With numerical prefix ARG show at most ARG top priority items
4008 from each category in each file. With `C-u' as prefix argument
4009 show the numbers of top priority items specified in
4010 `todo-top-priorities-overrides', if this is non-nil; otherwise show
4011 `todo-top-priorities' items per category. With no prefix
4012 argument, if a top priorities file for the chosen todo files
4013 exists (see `todo-save-filtered-items-buffer'), visit this file;
4014 if there is no such file, do the same as with prefix argument
4015 `C-u'."
4020 "Display a list of todo diary items from different categories.
4021 The categories can be any of those in the current todo file.
4023 Called with no prefix ARG, if a diary items file for the current
4024 todo file has previously been saved (see
4025 `todo-save-filtered-items-buffer'), visit this file; if there is
4026 no such file, build the list of diary items. Called with a
4027 prefix argument, build the list even if there is a saved file of
4028 diary items."
4033 "Display a list of todo diary items from different categories.
4034 The categories are a subset of the categories in the files listed
4035 in `todo-filter-files', or if this nil, in the files chosen from
4036 a file selection dialog that pops up in this case.
4038 Called with no prefix ARG, if a diary items file for the chosen
4039 todo files has previously been saved (see
4040 `todo-save-filtered-items-buffer'), visit this file; if there is
4041 no such file, build the list of diary items. Called with a
4042 prefix argument, build the list even if there is a saved file of
4043 diary items."
4048 "Prompt for a regular expression and display items that match it.
4049 The matches can be from any categories in the current todo file
4050 and with non-nil option `todo-filter-done-items', can include
4051 not only todo items but also done items, including those in
4052 Archive files.
4054 Called with no prefix ARG, if a regexp items file for the current
4055 todo file has previously been saved (see
4056 `todo-save-filtered-items-buffer'), visit this file; if there is
4057 no such file, build the list of regexp items. Called with a
4058 prefix argument, build the list even if there is a saved file of
4059 regexp items."
4064 "Prompt for a regular expression and display items that match it.
4065 The matches can be from any categories in the files listed in
4066 `todo-filter-files', or if this nil, in the files chosen from a
4067 file selection dialog that pops up in this case. With non-nil
4068 option `todo-filter-done-items', the matches can include not
4069 only todo items but also done items, including those in Archive
4070 files.
4072 Called with no prefix ARG, if a regexp items file for the current
4073 todo file has previously been saved (see
4074 `todo-save-filtered-items-buffer'), visit this file; if there is
4075 no such file, build the list of regexp items. Called with a
4076 prefix argument, build the list even if there is a saved file of
4077 regexp items."
4082 "Choose a filtered items file and visit it."
4085 falist file)
4091 falist)))
4098 "Display the file and category of the filtered item at point."
4115 t
4116 todo-show-with-done)))
4127 "Pop to a buffer with a widget for choosing multiple filter files."
4157 todo-multiple-filter-files-widget)))
4179 "Display a list of items filtered by FILTER.
4180 The values of FILTER can be `top' for top priority items, a cons
4181 of `top' and a number passed by the caller, `diary' for diary
4182 items, or `regexp' for items matching a regular expression
4183 entered by the user. The items can come from any categories in
4184 the current todo file or, with non-nil MULTIFILE, from several
4185 files. If NEW is nil, visit an appropriate file containing the
4186 list of filtered items; if there is no such file, or with non-nil
4187 NEW, build the list and display it.
4189 See the documentation strings of the commands
4190 `todo-filter-top-priorities', `todo-filter-diary-items',
4191 `todo-filter-regexp-items', and those of the corresponding
4192 multifile commands for further details."
4202 todo-multiple-filter-files))
4206 ;; Pressed `cancel' in t-m-f-f file selection dialog.
4216 bufname)
4233 'todo-short-file-name
4234 todo-files))
4236 s)))
4241 "Build a list of items by applying FILTER to FILE-LIST.
4242 Internal subroutine called by `todo-filter-items', which passes
4243 the values of FILTER and FILE-LIST."
4247 regexp fname bufstr cat beg end done)
4258 ;; Before inserting file contents into temp buffer, save a modified
4259 ;; buffer visiting it.
4266 ;; If there is a corresponding archive file for the
4267 ;; todo file, insert it first and add identifiers for
4268 ;; todo-go-to-source-item.
4272 ;; Delete todo archive file's categories sexp.
4282 todo-date-string-start)
4288 nil t)
4292 ;; Delete todo file's categories sexp.
4295 ;; Unless the number of top priorities to show was
4296 ;; passed by the caller, the file-wide value from
4297 ;; `todo-top-priorities-overrides', if non-nil, overrides
4298 ;; `todo-top-priorities'.
4301 todo-top-priorities)))
4307 ;; Unless the number of top priorities to show was
4308 ;; passed by the caller, the category-wide value
4309 ;; from `todo-top-priorities-overrides', if non-nil,
4310 ;; overrides a non-nil file-wide value from
4311 ;; `todo-top-priorities-overrides' as well as
4312 ;; `todo-top-priorities'.
4320 nil t)
4327 end t)
4329 end))
4331 ;; Leave done items.
4336 ;; Apply the filter.
4348 ;; Kill lines that aren't part of a todo or done
4349 ;; item (empty or todo-category-done).
4352 ;; If last todo item in file matches regexp and
4353 ;; there are no following done items,
4354 ;; todo-category-done string is left dangling,
4355 ;; because todo-forward-item jumps over it.
4368 ;; Delete non-top-priority items.
4372 ;; Add file (if using multiple files) and category tags to
4373 ;; item.
4380 todo-date-string-start)
4386 nil t)
4401 "Set number of top priorities shown by `todo-filter-top-priorities'.
4402 With non-nil ARG, set the number only for the current Todo
4403 category; otherwise, set the number for all categories in the
4404 current todo file.
4406 Calling this function via either of the commands
4407 `todo-set-top-priorities-in-file' or
4408 `todo-set-top-priorities-in-category' is the recommended way to
4409 set the user customizable option `todo-top-priorities-overrides'."
4417 todo-top-priorities))
4423 nrule)
4427 prompt "Enter a non-negative number: "
4428 cur0 nil)))
4434 nrule)
4440 "Search for filtered item STR in its saved todo file.
4441 Return the list (FOUND FILE CAT), where CAT and FILE are the
4442 item's category and file, and FOUND is a cons cell if the search
4443 succeeds, whose car is the start of the item in FILE and whose
4444 cdr is `done', if the item is now a done item, `changed', if its
4445 text was truncated or augmented or, for a top priority item, if
4446 its priority has changed, and `same' otherwise."
4450 todo-date-string-start)
4463 found)
4466 ;; Calculate priority of STR wrt its category.
4476 todo-global-current-todo-file)))
4485 nil t))
4492 nil t)
4499 'done
4503 ;; Not top item in category.
4507 ;; Can't move backward beyond
4508 ;; first item in file.
4512 ;; Proper substring is not the same.
4514 str))
4515 'same
4520 "Check if filtered items file is up to date and a show suitable message."
4521 ;; (catch 'old
4531 ;; (throw 'old (message "The marked item is not up to date.")))
4536 "not up to date."
4537 ;; "\nType <return> on item for details."
4538 )))))
4541 "Return absolute file name for saving this Filtered Items buffer."
4559 "Save current Filtered Items buffer to a file.
4560 If the file already exists, overwrite it only on confirmation."
4564 ;; -----------------------------------------------------------------------------
4565 ;;; Printing Todo mode buffers
4566 ;; -----------------------------------------------------------------------------
4569 "Function called by the command `todo-print-buffer'."
4577 "Produce a printable version of the current Todo mode buffer.
4578 This converts overlays and soft line wrapping and, depending on
4579 the value of `todo-print-buffer-function', includes faces. With
4580 non-nil argument TO-FILE write the printable version to a file;
4581 otherwise, send it to the default printer."
4596 file)
4609 ;; Calling todo-forward-item infloops at todo-item-start due to
4610 ;; non-overlay prefix, so search for item start instead.
4615 nil t)
4627 "Save printable version of this Todo mode buffer to a file."
4631 ;; -----------------------------------------------------------------------------
4632 ;;; Legacy Todo mode files
4633 ;; -----------------------------------------------------------------------------
4638 "Regexp matching legacy todo-mode.el item date-time strings.
4639 In order for `todo-convert-legacy-files' to correctly convert
4640 this string to the current Todo mode format, the regexp must
4641 contain four explicitly numbered groups (see `(elisp) Regexp
4642 Backslash'), where group 1 matches a string for the year, group 2
4643 a string for the month, group 3 a string for the day and group 4
4644 a string for the time. The default value converts date-time
4645 strings built using the default value of
4646 `todo-time-string-format' from todo-mode.el."
4651 "Return converted date-time string.
4652 Helper function for `todo-convert-legacy-files'."
4658 dayname)
4664 "Convert legacy todo files to the current Todo mode format.
4665 The old-style files named by the variables `todo-file-do' and
4666 `todo-file-done' from the old package are converted to the new
4667 format and saved (the latter as a todo archive file) with a new
4668 name in `todo-directory'. See also the documentation string of
4669 `todo-legacy-date-time-regexp' for further details."
4671 ;; If there are user customizations of legacy options, use them,
4672 ;; otherwise use the legacy default values.
4674 todo-file-do
4677 todo-file-done
4681 todo-entry-prefix-function))
4682 todo-prefix-tem)
4683 ;; Convert `todo-file-do'.
4687 file archive-sexp)
4690 ;; Eliminate old-style local variables list in first line.
4698 ;; Old-style category start delimiter.
4701 ;; Old-style category end delimiter.
4704 ;; Old-style category separator.
4709 ;; Old-style item header (date/time/initials).
4723 nil nil default)
4735 ;; Convert `todo-file-done'.
4741 cat cats comment item)
4756 todo-initials-tem)
4769 ;; If the item ends with a non-comment parenthesis not
4770 ;; followed by a period, we lose (but we inherit that
4771 ;; problem from the legacy code).
4778 ;; If item is already in its category, leave it there.
4784 ;; Else move it to its category.
4792 nil t)
4822 ;; Update categories sexp of converted todo file again, adding
4823 ;; counts of archived items.
4842 ;; We just initialized the first todo file, so make it the
4843 ;; default now to avoid an infinite recursion with todo-show.
4847 ;; -----------------------------------------------------------------------------
4848 ;;; Utility functions for todo files, categories and items
4849 ;; -----------------------------------------------------------------------------
4852 "Return the absolute file name of short todo file NAME.
4853 With TYPE `archive' or `top' return the absolute file name of the
4854 short todo archive or top priorities file name, respectively."
4855 ;; No-op if there is no todo file yet (i.e. don't concatenate nil).
4866 "Check the state associated with FILE and update it if necessary.
4867 If FILE exists, return t. If it does not exist and there is no
4868 live buffer with its content, return nil; if there is such a
4869 buffer and the user tries to show it, ask whether to restore
4870 FILE, and if confirmed, do so and return t; else delete the
4871 buffer, clean up the state and return nil."
4875 t
4889 t)
4906 nil)))))
4909 "Return the number of category CAT in this todo file.
4910 The buffer-local variable `todo-category-number' holds this
4911 number as its value."
4914 ;; Increment by one, so that the number of the first
4915 ;; category is one rather than zero.
4920 "Return the name of the current category."
4924 "Display the current category correctly."
4926 cat-begin cat-end done-start done-sep-start done-end)
4952 ;; Now we want to see the done items, so reset displayed end to end of
4953 ;; done items.
4955 ;; Make display overlay for done items separator string, unless there
4956 ;; already is one.
4965 ;; Loading this from todo-mode, or adding it to the mode hook, causes
4966 ;; Emacs to hang in todo-item-start, at (looking-at todo-item-start).
4972 "Return count of TYPE items in CATEGORY.
4973 If CATEGORY is nil, default to the current category."
4983 "Change count of TYPE items in CATEGORY by integer INCREMENT.
4984 With nil or omitted CATEGORY, default to the current category."
4994 "Set `todo-categories' from the sexp at the top of the file."
4995 ;; New archive files created by `todo-move-category' are empty, which would
4996 ;; make the sexp test fail and raise an error, so in this case we skip it.
5010 "Update the `todo-categories' sexp at the top of the file."
5023 "Return an alist of todo categories and their item counts.
5024 With non-nil argument FORCE parse the entire file to build the
5025 list; otherwise, get the value by reading the sexp at the top of
5026 the file."
5033 ;; If the file is a todo file and has archived items, identify the
5034 ;; archive, in order to count its items. But skip this with
5035 ;; `todo-convert-legacy-files', since that converts filed items to
5036 ;; archived items.
5038 ;; If the file is an archive, it doesn't have an archive.
5047 ;; Counts for each category: [todo diary done archive]
5051 ;; Add archived item count to the todo file item counts.
5052 ;; Make sure to include newly created archives, e.g. due to
5053 ;; todo-move-category.
5082 ;; If first line is todo-categories list, use it and end loop
5083 ;; -- unless FORCEd to scan whole file.
5091 todo-categories)
5094 "Repair corrupt todo file categories sexp.
5095 This should only be needed as a consequence of careless manual
5096 editing or a bug in todo.el.
5098 *Warning*: Calling this command restores the category order to
5099 the list element order in the todo file categories sexp, so any
5100 order changes made in Todo Categories mode will have to be made
5101 again."
5107 "Signal an error if the current todo file is ill-formatted.
5108 Otherwise return t. Display a message if the file is well-formed
5109 but the categories sexp differs from the current value of
5110 `todo-categories'."
5119 ;; Check the first line for `todo-categories' sexp.
5127 ;; Check well-formedness of categories.
5140 ;; Warn user if categories sexp has changed.
5144 "If the sexp is wrong, you can fix it with "
5146 "but note this reverts any changes you have "
5148 t)
5151 "Move to start of current todo item and return its position."
5153 ;; Buffer is empty (invocation possible e.g. via todo-forward-item
5154 ;; from todo-filter-items when processing category with no todo
5155 ;; items).
5157 ;; Point is on the empty line below category's last todo item...
5164 ;; Buffer is widened.
5172 "Move to end of current todo item and return its position."
5173 ;; Items cannot end with a blank line.
5177 ;; For todo items, end is before the done items section, for done
5178 ;; items, end is before the next category. If these limits are
5179 ;; missing or inaccessible, end it before the end of the buffer.
5183 todo-category-beg
5184 todo-category-done)))
5185 nil t))
5192 ;; For last todo item, skip back over the empty line before the done
5193 ;; items section, else just back to the end of the previous line.
5198 "Return bare text of current item as a string."
5206 "Move point COUNT items down (by default, move down by one item)."
5213 ;; If points advances by one from a todo to a done item, go back
5214 ;; to the space above todo-done-separator, since that is a
5215 ;; legitimate place to insert an item. But skip this space if
5216 ;; count > 1, since that should only stop on an item.
5218 ;; (if (or (not count) (= count 1))
5220 ;; The preceding sexp is insufficient when buffer is not narrowed,
5221 ;; since there could be no done items in this category, so the
5222 ;; search puts us on first todo item of next category. Does this
5223 ;; ever happen? If so:
5224 ;; (let ((opoint) (point))
5225 ;; (forward-line -1)
5226 ;; (when (or (not count) (= count 1))
5227 ;; (cond ((looking-at (concat "^" (regexp-quote todo-category-beg)))
5228 ;; (forward-line -2))
5229 ;; ((looking-at (concat "^" (regexp-quote todo-category-done)))
5230 ;; (forward-line -1))
5231 ;; (t
5232 ;; (goto-char opoint)))))))
5235 "Move point up to start of item with next higher priority.
5236 With positive numerical prefix COUNT, move point COUNT items
5237 upward.
5239 If the category's done items are visible, this command called
5240 with a prefix argument only moves point to a higher item, e.g.,
5241 with point on the first done item and called with prefix 1, it
5242 moves to the last todo item; but if called with point on the
5243 first done item without a prefix argument, it moves point the the
5244 empty line above the done items separator."
5249 ;; Unless this is a regexp filtered items buffer (which can contain
5250 ;; intermixed todo and done items), if points advances by one from a
5251 ;; done to a todo item, go back to the space above
5252 ;; todo-done-separator, since that is a legitimate place to insert an
5253 ;; item. But skip this space if count > 1, since that should only
5254 ;; stop on an item.
5256 ;(or (not count) (= count 1))
5259 nil t)
5263 "Internal function called in editing, deleting or moving items."
5271 "Return non-nil if item at point has diary entry format."
5277 ;; This duplicates the item locating code from diary-goto-entry, but
5278 ;; without the marker code, to test whether the latter is dispensable.
5279 ;; If it is, diary-goto-entry can be simplified. The code duplication
5280 ;; here can also be eliminated, leaving only the widening and category
5281 ;; selection, and instead of :override advice :around can be used.
5284 "Jump to the diary entry for the BUTTON at point.
5285 If the entry is a todo item, display its category properly.
5286 Overrides `diary-goto-entry'."
5287 ;; Locate the diary item in its source file.
5299 ;; If it's a todo item, determine its category and display the
5300 ;; category properly.
5328 "Return non-nil if item at point is a done item."
5334 "Return non-nil if point is in category's done items section."
5337 nil t)
5342 "Replace existing overlays of done items separator string SEP."
5354 new-ov)
5363 "Return the overlay at point whose `todo' property has value VAL."
5364 ;; Use overlays-in to find prefix overlays and check over two
5365 ;; positions to find done separator overlay.
5367 ov)
5375 "Non-nil if this item begins with `todo-item-mark'.
5376 In that case, return the item's prefix overlay."
5378 ;; If an item insertion command is called on a todo file
5379 ;; before it is visited, it has no prefix overlays yet, so
5380 ;; check for this.
5384 pref))))
5388 "Insert ITEM at point and update prefix/priority number overlays."
5390 ;; Insertion pushes item down but not its prefix overlay. When the
5391 ;; overlay includes a mark, this would now mark the inserted ITEM,
5392 ;; so move it to the pushed down item.
5401 "Update the prefix overlays of the current category's items.
5402 The overlay's value is the string `todo-prefix' or with non-nil
5403 `todo-number-prefix' an integer in the sequence from 1 to
5404 the number of todo or done items in the category indicating the
5405 item's priority. Todo and done items are numbered independently
5406 of each other."
5411 todo-top-priorities-overrides))))
5412 todo-top-priorities))
5413 done prefix)
5421 ;; Reset number to 1 for first done item.
5428 done t))
5432 todo-prefix)
5433 'face
5434 ;; Prefix of top priority items has a
5435 ;; distinct face in Todo mode.
5439 'todo-top-priority
5444 ;; Prefix overlay must be at a single position so its
5445 ;; bounds aren't changed when (re)moving an item.
5450 prefix))))
5453 ;; -----------------------------------------------------------------------------
5454 ;;; Utilities for generating item insertion commands and key bindings
5455 ;; -----------------------------------------------------------------------------
5457 ;; Thanks to Stefan Monnier for suggesting dynamically generating item
5458 ;; insertion commands and their key bindings, and offering an elegant
5459 ;; implementation, which, however, relies on lexical scoping and so
5460 ;; cannot be used here until the Calendar code used by todo-mode.el is
5461 ;; converted to lexical binding. Hence, the following implementation
5462 ;; uses dynamic binding.
5466 "List of all item insertion parameters.
5467 Passed by `todo-insert-item' to `todo-insert-item--next-param' to
5484 "Return key paired with item insertion PARAM."
5488 "Return sublist of LIST whose first member corresponds to KEY."
5501 list)
5507 list))
5520 "Build list of arguments for item insertion and apply them.
5521 The list consists of item insertion parameters that can be passed
5522 as insertion command arguments in fixed positions. If a position
5523 in the list is not occupied by the corresponding parameter, it is
5524 occupied by `nil'."
5529 todo-insert-item--argsleft)))))
5551 "Build item insertion command from LAST, ARGS and ARGSLEFT and call it.
5552 Dynamically generate key bindings, prompting with the keys
5553 already entered and those still available."
5564 "%s=>%s"
5571 name))))))
5611 todo-insert-item--argsleft))
5615 todo-insert-item--argsleft))))
5618 todo-insert-item--argsleft)))))))))
5621 todo-insert-item--keys-so-far prompt))
5625 ;; -----------------------------------------------------------------------------
5626 ;;; Todo minibuffer utilities
5627 ;; -----------------------------------------------------------------------------
5637 SPC to affirm the question only if option `todo-y-with-space' is
5638 non-nil."
5646 "Return a list of completions for `todo-read-category'.
5647 Each element of the list is a cons of a category name and the
5648 file or list of files (as short file names) it is in. The files
5649 are either the current (or if there is none, the default) todo
5650 file plus the files listed in `todo-category-completions-files',
5651 or, with non-nil ARCHIVE, the current archive file.
5653 Before calculating the completions, update the value of
5654 `todo-category-completions-files' in case any files named in it
5655 have been removed."
5674 todo-global-current-todo-file)
5678 todo-category-completions-files))
5680 listall listf)
5681 ;; If file was just added, it has no category completions.
5687 ;; Ensure category is properly displayed in case user
5688 ;; switches to file via a non-Todo mode command. And if
5689 ;; done items in category are visible, keep them visible.
5710 listf)))))
5713 "Choose and return the name of a todo file, prompting with PROMPT.
5715 Show completions with TAB or SPC; the names are shown in short
5716 form but the absolute truename is returned. With non-nil ARCHIVE
5717 return the absolute truename of a todo archive file. With non-nil
5718 MUSTMATCH the name of an existing file must be chosen;
5719 otherwise, a new file name is allowed."
5722 ;; (funcall todo-files-function archive)))
5726 ;; If user hit RET without
5727 ;; choosing a file, default to
5728 ;; current or default file.
5732 todo-global-current-todo-file)
5734 todo-default-todo-file)))
5735 ;; Trigger prompt for initial file.
5745 "Choose and return a category name, prompting with PROMPT.
5746 Show completions for existing categories with TAB or SPC.
5748 The argument MATCH-TYPE specifies the matching requirements on
5749 the category name: with the value `todo' or `archive' the name
5750 must complete to that of an existing todo or archive category,
5751 respectively; with the value `add' the name must not be that of
5752 an existing category; with all other values both existing and new
5753 valid category names are accepted.
5755 With non-nil argument FILE prompt for a file and complete only
5756 against categories in that file; otherwise complete against all
5757 categories from `todo-category-completions-files'."
5758 ;; Allow SPC to insert spaces, for adding new category names.
5765 "n archive"
5773 todo-categories)))
5777 todo-categories))
5779 completions)))
5783 ;; Unless we're adding a category via
5784 ;; todo-add-category, set default
5785 ;; for existing categories to the
5786 ;; current category of the chosen
5787 ;; file or else of the current file.
5792 todo-current-todo-file
5794 todo-default-todo-file)))
5796 ;; Trigger prompt for initial category.
5800 ;; If we do category completion and the chosen category name
5801 ;; occurs in more than one file, prompt to choose one file.
5805 catfil
5809 ;; Default to the current file.
5811 ;; First validate only a name passed interactively from
5812 ;; todo-add-category, which must be of a nonexistent category.
5814 ;; Validate only against completion categories.
5817 ;; When user enters a nonexistent category name by jumping or
5818 ;; moving, confirm that it should be added, then validate.
5826 ;; Restore point and narrowing after adding new
5827 ;; category, to avoid moving to beginning of file when
5828 ;; moving marked items to a new category
5829 ;; (todo-move-item).
5833 ;; If we decide not to add a category, exit without returning.
5838 "Prompt for new NAME for TYPE until it is valid, then return it.
5839 TYPE can be either of the symbols `file' or `category'."
5842 prompt)
5849 "Enter a non-empty file name: "
5850 ;; Empty string passed by todo-show to
5851 ;; prompt for initial todo file.
5856 "Enter a non-empty category name: "
5857 ;; Empty string passed by todo-show to
5858 ;; prompt for initial category of a new
5859 ;; todo file.
5872 files)
5874 categories)))
5875 ;; Offer default initial name.
5877 files
5878 categories)
5880 todo-initial-file
5881 todo-initial-category))))))
5882 name))
5884 ;; Adapted from calendar-read-date and calendar-date-string.
5886 "Prompt for Gregorian date and return it in the current format.
5888 With non-nil ARG, prompt for and return only the date component
5889 specified by ARG, which can be one of these symbols:
5890 `month' (prompt for name, return name or number according to
5891 value of `calendar-date-display-form'), `day' of month, or
5892 `year'. The value of each of these components can be `*',
5893 indicating an unspecified month, day, or year.
5895 When ARG is `day', non-nil arguments MO and YR determine the
5896 number of the last the day of the month."
5902 "Year (>0 or RET for this year or * for any year): "
5913 "Month name (RET for current month, * for any month): "
5914 mlist nil t nil nil
5924 ;; If month is unspecified, use a month with 31
5925 ;; days for checking day of month input. Does
5926 ;; Calendar do anything special when * is
5927 ;; currently a shorter month?
5929 ;; If year is unspecified, use a leap year to
5930 ;; allow Feb. 29.
5936 last)
5940 ;; Stringify read values (monthname is already a string).
5955 month
5956 monthname)))
5960 "Choose name of a day of the week with completion and return it."
5964 nil t)))
5967 "Prompt for and return a valid clock time as a string.
5969 Valid time strings are those matching `diary-time-regexp'.
5970 Typing `<return>' at the prompt returns the current time, if the
5971 user option `todo-always-add-time-string' is non-nil, otherwise
5972 the empty string (i.e., no time string)."
5981 answer))
5983 ;; -----------------------------------------------------------------------------
5984 ;;; Customization groups and utilities
5985 ;; -----------------------------------------------------------------------------
5988 "Create and maintain categorized lists of todo items."
5994 "User options for adding and editing todo items."
5999 "User options for Todo Categories mode."
6004 "User options for Todo Filter Items mode."
6009 "User display options for Todo mode."
6014 "Faces for the Todo modes."
6019 "The :set function for user option `todo-show-current-file'."
6026 "The :set function for `todo-prefix' and `todo-number-prefix'."
6033 ;; Activate the new setting in the current category.
6037 "The :set function for user option `todo-nondiary-marker'."
6041 ;; Need to reset these to get font-locking right.
6044 todo-date-string-start
6045 ;; See comment in defvar of `todo-date-string-start'.
6061 nil t)
6069 "The :set function for `todo-done-separator-string'."
6084 "The :set function for user option `todo-done-string'."
6088 ;; Need to reset this to get font-locking right.
6101 nil t)
6107 "The :set function for user option `todo-comment-string'."
6122 nil t)
6128 "The :set function for `todo-toggle-item-highlighting'."
6143 "Reevaluate defcustoms that provide choice list of todo files."
6154 "Reevaluate defcustom of `todo-default-todo-file'.
6155 Called after adding or deleting a todo file. If the value of
6156 `todo-default-todo-file' before calling this function was
6157 associated with an existing file, keep that value."
6158 ;; (let ((curval todo-default-todo-file))
6162 "Todo file visited by first session invocation of `todo-show'."
6168 ;; (when (and curval (file-exists-p (todo-absolute-file-name curval)))
6169 ;; (custom-set-default 'todo-default-todo-file curval)
6170 ;; ;; (custom-reevaluate-setting 'todo-default-todo-file)
6171 ;; )))
6172 )
6175 "Reevaluate defcustom of `todo-category-completions-files'.
6176 Called after adding or deleting a todo file."
6178 "List of files for building `todo-read-category' completions."
6185 "Reevaluate defcustom of `todo-filter-files'.
6186 Called after adding or deleting a todo file."
6188 "List of files for multifile item filtering."
6194 ;; -----------------------------------------------------------------------------
6195 ;;; Font locking
6196 ;; -----------------------------------------------------------------------------
6199 "Search for todo item nondiary markers within LIM for font-locking."
6203 lim t))
6206 "Search for diary nonmarking symbol within LIM for font-locking."
6211 "Search for todo item date string within LIM for font-locking."
6216 "Search for todo item time string within LIM for font-locking."
6221 "Search for expired diary item date within LIM for font-locking."
6228 ;; Function days-between requires a non-empty time string.
6235 "Search for done todo item header within LIM for font-locking."
6238 lim t))
6241 "Search for done todo item comment within LIM for font-locking."
6243 lim t))
6246 "Search for todo category name within LIM for font-locking.
6247 This is for fontifying category and file names appearing in Todo
6248 Filtered Items mode following done items."
6252 ;; Use non-greedy operator to prevent
6253 ;; capturing possible following non-diary
6254 ;; date string.
6256 lim t)))
6259 "Search for todo category name within LIM for font-locking.
6260 This is for fontifying category and file names appearing in Todo
6261 Filtered Items mode following todo (not done) items."
6267 lim t)))
6281 ;; diary-lib.el uses font-lock-constant-face for diary-nonmarking-symbol.
6291 )
6294 ;; -----------------------------------------------------------------------------
6295 ;;; Key binding
6296 ;; -----------------------------------------------------------------------------
6299 `(
6344 )
6348 `(
6370 )
6374 `(
6379 )
6383 `(
6387 )
6392 ;; Don't suppress digit keys, so they can supply prefix arguments.
6402 map)
6414 map)
6421 map)
6438 (define-key map [backtab] 'todo-previous-button)
6439 (define-key map "q" 'todo-quit)
6440 map)
6441 "Todo Categories mode keymap.")
6443 (defvar todo-filtered-items-mode-map
6444 (let ((map (make-sparse-keymap)))
6445 (suppress-keymap map)
6446 (dolist (kb todo-key-bindings-t+a+f)
6447 (define-key map (nth 0 kb) (nth 1 kb)))
6448 (dolist (kb todo-key-bindings-t+f)
6449 (define-key map (nth 0 kb) (nth 1 kb)))
6450 (define-key map "g" 'todo-go-to-source-item)
6451 (define-key map [remap newline] 'todo-go-to-source-item)
6452 map)
6453 "Todo Filtered Items mode keymap.")
6455 ;; FIXME: Is it worth having a menu and if so, which commands?
6456 ;; (easy-menu-define
6457 ;; todo-menu todo-mode-map "Todo Menu"
6458 ;; '("Todo"
6459 ;; ("Navigation"
6460 ;; ["Next Item" todo-forward-item t]
6461 ;; ["Previous Item" todo-backward-item t]
6462 ;; "---"
6463 ;; ["Next Category" todo-forward-category t]
6464 ;; ["Previous Category" todo-backward-category t]
6465 ;; ["Jump to Category" todo-jump-to-category t]
6466 ;; "---"
6467 ;; ["Search Todo File" todo-search t]
6468 ;; ["Clear Highlighting on Search Matches" todo-category-done t])
6469 ;; ("Display"
6470 ;; ["List Current Categories" todo-show-categories-table t]
6471 ;; ;; ["List Categories Alphabetically" todo-display-categories-alphabetically t]
6472 ;; ["Turn Item Highlighting on/off" todo-toggle-item-highlighting t]
6473 ;; ["Turn Item Numbering on/off" todo-toggle-prefix-numbers t]
6474 ;; ["Turn Item Time Stamp on/off" todo-toggle-item-header t]
6475 ;; ["View/Hide Done Items" todo-toggle-view-done-items t]
6476 ;; "---"
6477 ;; ["View Diary Items" todo-filter-diary-items t]
6478 ;; ["View Top Priority Items" todo-filter-top-priorities t]
6479 ;; ["View Multifile Top Priority Items" todo-filter-top-priorities-multifile t]
6480 ;; "---"
6481 ;; ["Print Category" todo-print-buffer t])
6482 ;; ("Editing"
6483 ;; ["Insert New Item" todo-insert-item t]
6484 ;; ["Insert Item Here" todo-insert-item-here t]
6485 ;; ("More Insertion Commands")
6486 ;; ["Edit Item" todo-edit-item t]
6487 ;; ["Edit Multiline Item" todo-edit-multiline-item t]
6488 ;; ["Edit Item Header" todo-edit-item-header t]
6489 ;; ["Edit Item Date" todo-edit-item-date t]
6490 ;; ["Edit Item Time" todo-edit-item-time t]
6491 ;; "---"
6492 ;; ["Lower Item Priority" todo-lower-item-priority t]
6493 ;; ["Raise Item Priority" todo-raise-item-priority t]
6494 ;; ["Set Item Priority" todo-set-item-priority t]
6495 ;; ["Move (Recategorize) Item" todo-move-item t]
6496 ;; ["Delete Item" todo-delete-item t]
6497 ;; ["Undo Done Item" todo-item-undone t]
6498 ;; ["Mark/Unmark Item for Diary" todo-toggle-item-diary-inclusion t]
6499 ;; ["Mark/Unmark Items for Diary" todo-edit-item-diary-inclusion t]
6500 ;; ["Mark & Hide Done Item" todo-item-done t]
6501 ;; ["Archive Done Items" todo-archive-category-done-items t]
6502 ;; "---"
6503 ;; ["Add New Todo File" todo-add-file t]
6504 ;; ["Add New Category" todo-add-category t]
6505 ;; ["Delete Current Category" todo-delete-category t]
6506 ;; ["Rename Current Category" todo-rename-category t]
6507 ;; "---"
6508 ;; ["Save Todo File" todo-save t]
6509 ;; )
6510 ;; "---"
6511 ;; ["Quit" todo-quit t]
6512 ;; ))
6514 ;; -----------------------------------------------------------------------------
6515 ;;; Hook functions and mode definitions
6516 ;; -----------------------------------------------------------------------------
6518 (defun todo-show-current-file ()
6519 "Visit current instead of default todo file with `todo-show'.
6520 Added to `pre-command-hook' in Todo mode when user option
6521 `todo-show-current-file' is set to non-nil."
6522 (setq todo-global-current-todo-file todo-current-todo-file))
6524 (defun todo-display-as-todo-file ()
6525 "Show todo files correctly when visited from outside of Todo mode.
6526 Added to `find-file-hook' in Todo mode and Todo Archive mode."
6527 (and (member this-command todo-visit-files-commands)
6528 (= (- (point-max) (point-min)) (buffer-size))
6529 (member major-mode '(todo-mode todo-archive-mode))
6530 (todo-category-select)))
6532 (defun todo-add-to-buffer-list ()
6533 "Add name of just visited todo file to `todo-file-buffers'.
6534 This function is added to `find-file-hook' in Todo mode."
6535 (let ((filename (file-truename (buffer-file-name))))
6536 (when (member filename todo-files)
6537 (add-to-list 'todo-file-buffers filename))))
6539 (defun todo-update-buffer-list ()
6540 "Make current Todo mode buffer file car of `todo-file-buffers'.
6541 This function is added to `post-command-hook' in Todo mode."
6542 (let ((filename (file-truename (buffer-file-name))))
6543 (unless (eq (car todo-file-buffers) filename)
6544 (setq todo-file-buffers
6545 (cons filename (delete filename todo-file-buffers))))))
6547 (defun todo-reset-global-current-todo-file ()
6548 "Update the value of `todo-global-current-todo-file'.
6549 This becomes the latest existing todo file or, if there is none,
6550 the value of `todo-default-todo-file'.
6551 This function is added to `kill-buffer-hook' in Todo mode."
6552 (let ((filename (file-truename (buffer-file-name))))
6553 (setq todo-file-buffers (delete filename todo-file-buffers))
6554 (setq todo-global-current-todo-file
6555 (or (car todo-file-buffers)
6556 (todo-absolute-file-name todo-default-todo-file)))))
6558 (defun todo-reset-and-enable-done-separator ()
6559 "Show resized done items separator overlay after window change.
6560 Added to `window-configuration-change-hook' in Todo mode."
6561 (when (= 1 (length todo-done-separator-string))
6562 (let ((sep todo-done-separator))
6563 (setq todo-done-separator (todo-done-separator))
6564 (save-match-data (todo-reset-done-separator sep)))))
6566 (defun todo-modes-set-1 ()
6567 "Make some settings that apply to multiple Todo modes."
6568 (setq-local font-lock-defaults '(todo-font-lock-keywords t))
6569 (setq-local tab-width todo-indent-to-here)
6570 (setq-local indent-line-function 'todo-indent)
6571 (when todo-wrap-lines
6572 (visual-line-mode)
6573 (setq wrap-prefix (make-string todo-indent-to-here 32))))
6575 (defun todo-modes-set-2 ()
6576 "Make some settings that apply to multiple Todo modes."
6577 (add-to-invisibility-spec 'todo)
6578 (setq buffer-read-only t)
6579 (when (and (boundp 'desktop-save-mode) desktop-save-mode)
6580 (setq-local desktop-save-buffer 'todo-desktop-save-buffer))
6581 (when (boundp 'hl-line-range-function)
6582 (setq-local hl-line-range-function
6583 (lambda() (save-excursion
6584 (when (todo-item-end)
6585 (cons (todo-item-start)
6586 (todo-item-end))))))))
6588 (defun todo-modes-set-3 ()
6589 "Make some settings that apply to multiple Todo modes."
6590 (setq-local todo-categories (todo-set-categories))
6591 (setq-local todo-category-number 1)
6592 (add-hook 'find-file-hook 'todo-display-as-todo-file nil t))
6594 (put 'todo-mode 'mode-class 'special)
6596 ;;;###autoload
6597 (define-derived-mode todo-mode special-mode "Todo"
6598 "Major mode for displaying, navigating and editing todo lists.
6601 ;; (easy-menu-add todo-menu)
6602 (todo-modes-set-1)
6603 (todo-modes-set-2)
6604 (todo-modes-set-3)
6605 ;; Initialize todo-current-todo-file.
6606 (when (member (file-truename (buffer-file-name))
6607 (funcall todo-files-function))
6608 (setq-local todo-current-todo-file (file-truename (buffer-file-name))))
6609 (setq-local todo-show-done-only nil)
6610 (setq-local todo-categories-with-marks nil)
6611 (add-hook 'find-file-hook 'todo-add-to-buffer-list nil t)
6612 (add-hook 'post-command-hook 'todo-update-buffer-list nil t)
6613 (when todo-show-current-file
6614 (add-hook 'pre-command-hook 'todo-show-current-file nil t))
6615 (add-hook 'window-configuration-change-hook
6616 'todo-reset-and-enable-done-separator nil t)
6617 (add-hook 'kill-buffer-hook 'todo-reset-global-current-todo-file nil t))
6619 (put 'todo-archive-mode 'mode-class 'special)
6621 ;; If todo-mode is parent, all todo-mode key bindings appear to be
6622 ;; available in todo-archive-mode (e.g. shown by C-h m).
6623 ;;;###autoload
6624 (define-derived-mode todo-archive-mode special-mode "Todo-Arch"
6625 "Major mode for archived todo categories.
6628 (todo-modes-set-1)
6629 (todo-modes-set-2)
6630 (todo-modes-set-3)
6631 (setq-local todo-current-todo-file (file-truename (buffer-file-name)))
6632 (setq-local todo-show-done-only t))
6634 (defun todo-mode-external-set ()
6635 "Set `todo-categories' externally to `todo-current-todo-file'."
6636 (setq-local todo-current-todo-file todo-global-current-todo-file)
6637 (let ((cats (with-current-buffer
6638 ;; Can't use find-buffer-visiting when
6639 ;; `todo-show-categories-table' is called on first
6640 ;; invocation of `todo-show', since there is then
6641 ;; no buffer visiting the current file.
6642 (find-file-noselect todo-current-todo-file 'nowarn)
6643 (or todo-categories
6644 ;; In Todo Edit mode todo-categories is now nil
6645 ;; since it uses same buffer as Todo mode but
6646 ;; doesn't have the latter's local variables.
6647 (save-excursion
6648 (goto-char (point-min))
6649 (read (buffer-substring-no-properties
6650 (line-beginning-position)
6651 (line-end-position))))))))
6652 (setq-local todo-categories cats)))
6654 (define-derived-mode todo-edit-mode text-mode "Todo-Ed"
6655 "Major mode for editing multiline todo items.
6658 (todo-modes-set-1)
6659 (todo-mode-external-set)
6660 (setq buffer-read-only nil))
6662 (put 'todo-categories-mode 'mode-class 'special)
6664 (define-derived-mode todo-categories-mode special-mode "Todo-Cats"
6665 "Major mode for displaying and editing todo categories.
6668 (todo-mode-external-set))
6670 (put 'todo-filtered-items-mode 'mode-class 'special)
6672 ;;;###autoload
6673 (define-derived-mode todo-filtered-items-mode special-mode "Todo-Fltr"
6674 "Mode for displaying and reprioritizing top priority Todo.
6677 (todo-modes-set-1)
6678 (todo-modes-set-2))
6680 ;;;###autoload
6682 ;;;###autoload
6684 ;;;###autoload
6687 ;; -----------------------------------------------------------------------------
6688 (provide 'todo-mode)
6690 ;;; todo-mode.el ends here