| blob | 6d3d9ec0ccb90a0a849d3298b8acd4dced9cdaa1 |
1 ;;; todos.el --- facilities for making and maintaining todo lists
3 ;; Copyright (C) 2013 Free Software Foundation, Inc.
5 ;; Author: Stephen Berman <stephen.berman@gmx.net>
6 ;; Keywords: calendar, todo
8 ;; This file is [not yet] part of GNU Emacs.
10 ;; GNU Emacs is free software: you can redistribute it and/or modify
11 ;; it under the terms of the GNU General Public License as published by
12 ;; the Free Software Foundation, either version 3 of the License, or
13 ;; (at your option) any later version.
15 ;; GNU Emacs is distributed in the hope that it will be useful,
16 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
17 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 ;; GNU General Public License for more details.
20 ;; You should have received a copy of the GNU General Public License
21 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
23 ;;; Commentary:
25 ;; This package provides facilities for making, displaying, navigating
26 ;; and editing todo lists, which are prioritized lists of todo items.
27 ;; Todo lists are identified with named categories, providing a means
28 ;; of grouping thematically related todo items. Each category is
29 ;; stored in a file, which provides a further level of organization.
31 ;; You can navigate among the items of a category, and between
32 ;; categories and files. You can edit items, reprioritize them within
33 ;; their category, move them to another category, delete them, or mark
34 ;; items as done and store them separately from the not yet done items
35 ;; in a category. You can add new files and categories, rename
36 ;; categories, move them to another file or delete them. You can also
37 ;; build cross-categorial lists of items that satisfy various
38 ;; criteria. And you can display summary tables of the categories in
39 ;; a file and the types of items they contain.
41 ;; To get started, load this package and type `M-x todos-show'. This
42 ;; will prompt you for the name of the first todo file and its first
43 ;; category, create these and display the empty category in Todos
44 ;; mode. Then type `i i' to add the first todo item to the category
45 ;; (i.e., to the list). To see a list of all Todos mode commands,
46 ;; which include entry points to several auxiliary modes, type `C-h
47 ;; m'. Consult the document strings of the commands for details of
48 ;; their use. The `todos' customization group and its subgroups list
49 ;; the options you can set to alter the behavior of many commands and
50 ;; various aspects of the display.
52 ;; This package is a new version of Oliver Seidel's todo-mode.el,
53 ;; which retains the same basic organization and handling of todo
54 ;; lists and the basic UI, but extends these in many ways and
55 ;; reimplements most of the internals.
57 ;;; Code:
60 ;; For cl-remove-duplicates (in todos-insertion-commands-args) and cl-oddp.
63 ;; =============================================================================
64 ;;; User interface
65 ;; =============================================================================
66 ;; -----------------------------------------------------------------------------
67 ;;; Options for file and category selection
68 ;; -----------------------------------------------------------------------------
71 "Directory where user's Todos files are saved."
76 "Default value of `todos-files-function'.
77 This returns the case-insensitive alphabetically sorted list of
78 file truenames in `todos-directory' with the extension
90 "Function returning the value of the variable `todos-files'.
91 This function should take an optional argument that, if non-nil,
92 makes it return the value of the variable `todos-archives'."
97 "Return short form of Todos FILE.
98 This lacks the extension and directory components."
103 "List of file finding commands for `todos-display-as-todos-file'.
104 Invoking these commands to visit a Todos or Todos Archive file
105 calls `todos-show' or `todos-find-archive', so that the file is
106 displayed correctly."
112 "Todos file visited by first session invocation of `todos-show'."
119 "Non-nil to make `todos-show' visit the current Todos file.
120 Otherwise, `todos-show' always visits `todos-default-todos-file'."
127 "What action to take on first use of `todos-show' on a file."
136 "Default file name offered on adding first Todos file."
141 "Default category name offered on initializing a new Todos file."
146 "List of files for building `todos-read-category' completions."
153 "Non-nil means case is ignored by `todos-read-*' functions."
157 ;; -----------------------------------------------------------------------------
158 ;;; Entering and exiting Todos mode
159 ;; -----------------------------------------------------------------------------
161 ;;;###autoload
163 "Visit a Todos file and display one of its categories.
165 When invoked in Todos mode, prompt for which todo file to visit.
166 When invoked outside of Todos mode with non-nil prefix argument
167 SOLICIT-FILE prompt for which todo file to visit; otherwise visit
168 `todos-default-todos-file'. Subsequent invocations from outside
169 of Todos mode revisit this file or, with option
170 `todos-show-current-file' non-nil (the default), whichever Todos
171 file was last visited.
173 Calling this command before any Todos file exists prompts for a
174 file name and an initial category (defaulting to
175 `todos-initial-file' and `todos-initial-category'), creates both
176 of these, visits the file and displays the category.
178 The first invocation of this command on an existing Todos file
179 interacts with the option `todos-show-first': if its value is
180 `first' (the default), show the first category in the file; if
181 its value is `table', show the table of categories in the file;
182 if its value is one of `top', `diary' or `regexp', show the
183 corresponding saved top priorities, diary items, or regexp items
184 file, if any. Subsequent invocations always show the file's
185 current (i.e., last displayed) category.
187 In Todos mode just the category's unfinished todo items are shown
188 by default. The done items are hidden, but typing
190 items. With non-nil user option `todos-show-with-done' both todo
191 and done items are always shown on visiting a category.
193 Invoking this command in Todos Archive mode visits the
194 corresponding Todos file, displaying the corresponding category."
202 todos-archive-mode
203 todos-filtered-items-mode))))
206 nil t)
209 ;; Called noninteractively via todos-quit
210 ;; to jump to corresponding category in
211 ;; todo file.
219 todos-global-current-todos-file)
223 ;; We just initialized the first todo file, so make it the default.
227 ;; Can't setq t-c-t-f here, otherwise wrong file shown when
228 ;; todos-show is called from todos-show-categories-table.
235 shortf todos-show-first)))
243 "Choose a regexp items file: "
256 shortf)
262 ;; When quitting archive file, show corresponding category in
263 ;; Todos file, if it exists.
266 ;; If this is a new Todos file, add its first category.
270 add-item todos-add-item-if-new-category))
277 "Save the current Todos file."
286 "Exit the current Todos-related buffer.
287 Depending on the specific mode, this either kills the buffer or
288 buries it and restores state as needed."
292 ;; Postpone killing buffer till after calling todos-show, to
293 ;; prevent killing todos-mode buffer.
295 ;; Ensure todos-show calls todos-show-categories-table only on
296 ;; first invocation per file.
310 ;; If we just quit archive mode, just burying the buffer
311 ;; in todos-mode would return to archive.
316 ;; -----------------------------------------------------------------------------
317 ;;; Navigation commands
318 ;; -----------------------------------------------------------------------------
321 "Visit the numerically next category in this Todos file.
322 If the current category is the highest numbered, visit the first
323 category. With non-nil argument BACK, visit the numerically
324 previous category (the highest numbered one, if the current
325 category is the first)."
340 "Visit the numerically previous category in this Todos file.
341 If the current category is the highest numbered, visit the first
342 category."
346 ;;;###autoload
348 "Prompt for a category in a Todos file and jump to it.
350 With non-nil FILE (interactively a prefix argument), prompt for a
351 specific Todos file and choose (with TAB completion) a category
352 in it to jump to; otherwise, choose and jump to any category in
353 either the current Todos file or a file in
354 `todos-category-completions-files'.
356 You can also enter a non-existing category name, triggering a
357 prompt whether to add a new category by that name; on
358 confirmation it is added and you jump to that category.
360 In noninteractive calls non-nil WHERE specifies either the goal
361 category or its file. If its value is `archive', the choice of
362 categories is restricted to the current archive file or the
363 archive you were prompted to choose; this is used by
364 `todos-jump-to-archive-category'. If its value is the name of a
365 category, jump directly to that category; this is used in Todos
366 Categories mode."
368 ;; If invoked outside of Todos mode and there is not yet any Todos
369 ;; file, initialize one.
375 ;; With non-nil `todos-skip-archived-categories'
376 ;; jump to archive file of a category with only
377 ;; archived items.
384 ;; Otherwise, jump to current todos file.
385 todos-current-todos-file)))
396 ;; If called from Todos Categories mode, clean up before jumping.
409 "Move point down to the beginning of the next item.
410 With positive numerical prefix COUNT, move point COUNT items
411 downward.
413 If the category's done items are hidden, this command also moves
414 point to the empty line below the last todo item from any higher
415 item in the category, i.e., when invoked with or without a prefix
416 argument. If the category's done items are visible, this command
417 called with a prefix argument only moves point to a lower item,
418 e.g., with point on the last todo item and called with prefix 1,
419 it moves point to the first done item; but if called with point
420 on the last todo item without a prefix argument, it moves point
421 the the empty line above the done items separator."
423 ;; It's not worth the trouble to allow prefix arg value < 1, since we have
424 ;; the corresponding command.
433 "Move point up to start of item with next higher priority.
434 With positive numerical prefix COUNT, move point COUNT items
435 upward.
437 If the category's done items are visible, this command called
438 with a prefix argument only moves point to a higher item, e.g.,
439 with point on the first done item and called with prefix 1, it
440 moves to the last todo item; but if called with point on the
441 first done item without a prefix argument, it moves point the the
442 empty line above the done items separator."
444 ;; Avoid moving to bob if on the first item but not at bob.
446 ;; It's not worth the trouble to allow prefix arg value < 1, since we have
447 ;; the corresponding command.
455 ;; -----------------------------------------------------------------------------
456 ;;; File editing commands
457 ;; -----------------------------------------------------------------------------
460 "Name and initialize a new Todos file.
461 Interactively, prompt for a category and display it.
462 Noninteractively, return the name of the new file.
464 This command does not save the file to disk; to do that type
469 file)
483 file)))
489 "Put current buffer in `todos-edit-mode'.
490 This makes the entire file visible and the buffer writeable and
491 you can use the self-insertion keys and standard Emacs editing
492 commands to make changes. To return to Todos mode, type
494 an error if the format has become invalid. However, this check
495 cannot tell if the number of items changed, which could result in
496 the file containing inconsistent information. For this reason
497 this command should be used with caution."
506 ;; -----------------------------------------------------------------------------
507 ;;; Category editing commands
508 ;; -----------------------------------------------------------------------------
511 "Add a new category to a Todos file.
513 Called interactively with prefix argument FILE, prompt for a file
514 and then for a new category to add to that file, otherwise prompt
515 just for a category to add to the current Todos file. After adding
516 the category, visit it in Todos mode.
518 Non-interactively, add category CAT to file FILE; if FILE is nil,
519 add CAT to the current Todos file. After adding the category,
520 return the new category number."
523 ;; If cat is passed from caller, don't prompt, unless it is "",
524 ;; which means the file was just added and has no category yet.
527 todos-current-todos-file))
530 file))
534 file)))
547 ;; If invoked by user, display the newly added category, if
548 ;; called programmatically return the category number to the
549 ;; caller.
556 num))))
559 "Rename current Todos category.
560 If this file has an archive containing this category, rename the
561 category there as well."
584 nil t)
590 "Delete current Todos category provided it is empty.
591 With ARG non-nil delete the category unconditionally,
592 i.e. including all existing todo and done items."
612 "after deleting the todo category. "
614 "(see `todos-skip-archived-categories' "
633 ;; If deleted category was the only one, delete the file.
636 ;; Skip confirming killing the archive buffer if it has been
637 ;; modified and not saved.
643 todos-categories))
652 "Move current category to a different Todos file.
653 If current category has archived items, also move those to the
654 archive of the file moved to, creating it if it does not exist."
668 new)
680 nil t))
688 buffer-read-only)
689 ;; Move the category to the new file. Also update or create
690 ;; archive file if necessary.
693 ;; Regenerate todos-archives in case there
694 ;; is a newly created archive.
697 nfile))
701 nfile-short)
704 buffer-read-only)
708 ;; If the file moved to has a category with the same
709 ;; name, rename the moved category.
715 ;; Replace old with new name in Todos and archive files.
725 ;; If archive was just created, save it to avoid "File
726 ;; <xyz> no longer exists!" message on invoking
727 ;; `todos-view-archived-items'.
732 ;; Delete the category from the old file, and if that was the
733 ;; last category, delete the file. Also handle archive file
734 ;; if necessary.
738 ;; Put point after todos-categories sexp.
742 ;; Skip confirming killing the archive buffer.
749 todos-categories))
758 "Merge current category into another existing category.
760 With prefix argument FILE, prompt for a specific Todos file and
761 choose (with TAB completion) a category in it to merge into;
762 otherwise, choose and merge into a category in either the
763 current Todos file or a file in `todos-category-completions-files'.
765 After merging, the current category's todo and done items are
766 appended to the chosen goal category's todo and done items,
767 respectively. The goal category becomes the current category,
768 and the previous current category is deleted.
770 If both the first and goal categories also have archived items,
771 the former are merged to the latter. If only the first category
772 has archived items, the archived category is renamed to the goal
773 category."
782 archived-count here)
783 ;; Merge in todo file.
796 ;; Omit empty line between todo and done items.
808 ;; Merge any todo items.
812 nil t)
819 ;; Merge any done items.
831 todos-categories))
835 ;; Merge in archive file.
844 nil t)
851 nil t)
854 cend carch)
860 nil t)
865 ;; If both categories of the merge have archived items, merge the
866 ;; source items to the goal items, else "merge" by renaming the
867 ;; source category to goal.
872 nil t)
889 ;; If there are only merged done items, show them.
892 ;; Put point on the first merged item.
896 ;; -----------------------------------------------------------------------------
897 ;;; Item marking
898 ;; -----------------------------------------------------------------------------
901 "String used to mark items.
902 To ensure item marking works, change the value of this option
903 only when no items are marked."
908 widget :error
910 widget)))
916 "Mark item with `todos-item-mark' if unmarked, otherwise unmark it.
917 With a positive numerical prefix argument N, change the
918 marking of the next N items."
944 "Mark all visiblw items in this category with `todos-item-mark'."
961 "Remove `todos-item-mark' from all visible items in this category."
969 ;; No overlay on empty line between todo and done items.
977 ;; -----------------------------------------------------------------------------
978 ;;; Item editing options
979 ;; -----------------------------------------------------------------------------
982 "Non-nil to prompt for an item after adding a new category."
987 "Non-nil to allow new Todo items to be included in the diary."
992 "Non-nil to insert new Todo diary items as nonmarking by default.
993 This appends `diary-nonmarking-symbol' to the front of an item on
994 insertion provided it doesn't begin with `todos-nondiary-marker'."
999 "List of strings surrounding item date to block diary inclusion.
1000 The first string is inserted before the item date and must be a
1001 non-empty string that does not match a diary date in order to
1002 have its intended effect. The second string is inserted after
1003 the diary date."
1010 "Non-nil adds current time to a new item's date header by default.
1012 argument, this reverses the effect of
1013 `todos-always-add-time-string': if t, these commands omit the
1014 current time, if nil, they include it."
1019 "Non-nil to enable inserting only highlighted region as new item."
1024 "Whether to omit done item comment on undoing the item.
1025 Nil means never omit the comment, t means always omit it, `ask'
1026 means prompt user and omit comment only on confirmation."
1032 ;; -----------------------------------------------------------------------------
1033 ;;; Item editing commands
1034 ;; -----------------------------------------------------------------------------
1036 ;;;###autoload
1038 region-or-here)
1039 "Insert a new Todo item into a category.
1040 This is the function from which the generated Todos item
1041 insertion commands derive.
1043 The generated commands have mnenomic key bindings based on the
1044 arguments' values and their order in the command's argument list,
1045 as follows: (1) for DIARY `d', (2) for NONMARKING `k', (3) for
1046 DATE-TYPE either `c' for calendar or `d' for date or `n' for
1047 weekday name, (4) for TIME `t', (5) for REGION-OR-HERE either `r'
1048 for region or `h' for here. Sequences of these keys are appended
1049 to the insertion prefix key `i'. Keys that allow a following
1050 key (i.e., any but `r' or `h') must be doubled when used finally.
1051 For example, the command bound to the key sequence `i y h' will
1052 insert a new item with today's date, marked according to the
1053 DIARY argument described below, and with priority according to
1054 the HERE argument; `i y y' does the same except that the priority
1055 is not given by HERE but by prompting.
1057 In command invocations, ARG is passed as a prefix argument as
1058 follows. With no prefix argument, add the item to the current
1059 category; with one prefix argument (`C-u'), prompt for a category
1060 from the current Todos file; with two prefix arguments (`C-u C-u'),
1061 first prompt for a Todos file, then a category in that file. If
1062 a non-existing category is entered, ask whether to add it to the
1063 Todos file; if answered affirmatively, add the category and
1064 insert the item there.
1066 The remaining arguments are set or left nil by the generated item
1067 insertion commands; their meanings are described in the follows
1068 paragraphs.
1070 When argument DIARY is non-nil, this overrides the intent of the
1071 user option `todos-include-in-diary' for this item: if
1072 `todos-include-in-diary' is nil, include the item in the Fancy
1073 Diary display, and if it is non-nil, exclude the item from the
1074 Fancy Diary display. When DIARY is nil, `todos-include-in-diary'
1075 has its intended effect.
1077 When the item is included in the Fancy Diary display and the
1078 argument NONMARKING is non-nil, this overrides the intent of the
1079 user option `todos-diary-nonmarking' for this item: if
1080 `todos-diary-nonmarking' is nil, append `diary-nonmarking-symbol'
1081 to the item, and if it is non-nil, omit `diary-nonmarking-symbol'.
1083 The argument DATE-TYPE determines the content of the item's
1084 mandatory date header string and how it is added:
1085 - If DATE-TYPE is the symbol `calendar', the Calendar pops up and
1086 when the user puts the cursor on a date and hits RET, that
1087 date, in the format set by `calendar-date-display-form',
1088 becomes the date in the header.
1089 - If DATE-TYPE is a string matching the regexp
1090 `todos-date-pattern', that string becomes the date in the
1091 header. This case is for the command
1092 `todos-insert-item-from-calendar' which is called from the
1093 Calendar.
1094 - If DATE-TYPE is the symbol `date', the header contains the date
1095 in the format set by `calendar-date-display-form', with year,
1096 month and day individually prompted for (month with tab
1097 completion).
1098 - If DATE-TYPE is the symbol `dayname' the header contains a
1099 weekday name instead of a date, prompted for with tab
1100 completion.
1101 - If DATE-TYPE has any other value (including nil or none) the
1102 header contains the current date (in the format set by
1103 `calendar-date-display-form').
1105 With non-nil argument TIME prompt for a time string, which must
1106 match `diary-time-regexp'. Typing `<return>' at the prompt
1107 returns the current time, if the user option
1108 `todos-always-add-time-string' is non-nil, otherwise the empty
1109 string (i.e., no time string). If TIME is absent or nil, add or
1110 omit the current time string according as
1111 `todos-always-add-time-string' is non-nil or nil, respectively.
1113 The argument REGION-OR-HERE determines the source and location of
1114 the new item:
1115 - If the REGION-OR-HERE is the symbol `here', prompt for the text of
1116 the new item and, if the command was invoked with point in the todo
1117 items section of the current category, give the new item the
1118 priority of the item at point, lowering the latter's priority and
1119 the priority of the remaining items. If point is in the done items
1120 section of the category, insert the new item as the first todo item
1121 in the category. Likewise, if the command with `here' is invoked
1122 outside of the current category, jump to the chosen category and
1123 insert the new item as the first item in the category.
1124 - If REGION-OR-HERE is the symbol `region', use the region of the
1125 current buffer as the text of the new item, depending on the
1126 value of user option `todos-use-only-highlighted-region': if
1127 this is non-nil, then use the region only when it is
1128 highlighted; otherwise, use the region regardless of
1129 highlighting. An error is signalled if there is no region in
1130 the current buffer. Prompt for the item's priority in the
1131 category (an integer between 1 and one more than the number of
1132 items in the category), and insert the item accordingly.
1133 - If REGION-OR-HERE has any other value (in particular, nil or
1134 none), prompt for the text and the item's priority, and insert
1135 the item accordingly."
1136 ;; If invoked outside of Todos mode and there is not yet any Todos
1137 ;; file, initialize one.
1159 todos-global-current-todos-file)
1161 todos-default-todos-file))))))
1176 ;; If user exits Calendar before choosing
1177 ;; a date, cancel item insertion.
1193 ;; If this command was invoked outside of a Todos buffer, the
1194 ;; call to todos-current-category above returned nil. If we
1195 ;; just entered Todos mode now, then cat was set to the file's
1196 ;; first category, but if todos-mode was already enabled, cat
1197 ;; did not get set, so we have to set it explicitly.
1205 done-only item-added)
1207 ;; Add date, time and diary marking as required.
1209 todos-nondiary-start
1211 diary-nonmarking-symbol))
1214 time-string))))
1217 todos-nondiary-end)
1219 ;; Indent newlines inserted by C-q C-j if nonspace char follows.
1224 ;; Make sure the correct category is selected. There
1225 ;; are two cases: (i) we just visited the file, so no
1226 ;; category is selected yet, or (ii) we invoked
1227 ;; insertion "here" from outside the category we want
1228 ;; to insert in (with priority insertion, category
1229 ;; selection is done by todos-set-item-priority).
1234 ;; If only done items are displayed in category,
1235 ;; toggle to todo items before inserting new item.
1243 ;; If command was invoked with point in done
1244 ;; items section or outside of the current
1245 ;; category, can't insert "here", so to be
1246 ;; useful give new item top priority.
1248 called-from-outside
1249 done-only)
1254 ;; If user cancels before setting priority, restore
1255 ;; display.
1265 ;; If the todo items section is not visible when the
1266 ;; insertion command is called (either because only done
1267 ;; items were shown or because the category was not in the
1268 ;; current buffer), then if the item is inserted at the
1269 ;; end of the category, point is at eob and eob at
1270 ;; window-start, so that higher priority todo items are
1271 ;; out of view. So we recenter to make sure the todo
1272 ;; items are displayed in the window.
1282 "Return string of date chosen from Calendar."
1285 todos-date-from-calendar)
1290 ;; If user exits Calendar before choosing a date, clean up properly.
1304 todos-date-from-calendar)
1309 todos-date-from-calendar)))))
1312 "Prompt for and insert a new item with date selected from calendar.
1313 Invoked without prefix argument ARG, insert the item into the
1314 current category, without one prefix argument, prompt for the
1315 category from the current todo file or from one listed in
1316 `todos-category-completions-files'; with two prefix arguments,
1317 prompt for a todo file and then for a category in it."
1327 "Copy item at point and insert the copy as a new item."
1338 "Delete at least one item in this category.
1340 If there are marked items, delete all of these; otherwise, delete
1341 the item at point."
1357 buffer-read-only)
1371 ;; Don't leave point below last item.
1385 "Edit the Todo item at point.
1387 With non-nil prefix argument ARG, include the item's date/time
1388 header, making it also editable; otherwise, include only the item
1389 content.
1391 If the item consists of only one logical line, edit it in the
1392 minibuffer; otherwise, edit it in Todos Edit mode."
1420 ;; Ensure lines following hard newlines are indented.
1423 ;; If user moved point during editing, make sure it moves back.
1430 "Edit current Todo item in Todos Edit mode.
1431 Use of newlines invokes `todos-indent' to insure compliance with
1432 the format of Diary entries."
1445 "Return from Todos Edit mode to Todos mode.
1446 If the item contains hard line breaks, make sure the following
1447 lines are indented by `todos-indent-to-here' to conform to diary
1448 format.
1450 If the whole file was in Todos Edit mode, check before returning
1451 whether the file is still a valid Todos file and if so, also
1452 recalculate the Todos categories sexp, in case changes were made
1453 in the number or names of categories."
1456 ;; We got here via `e m'.
1464 ;; Ensure lines following hard newlines are indented.
1472 ;; We got here via `F e'.
1474 ;; FIXME: separate out sexp check?
1475 ;; If manual editing makes e.g. item counts change, have to
1476 ;; call this to update todos-categories, but it restores
1477 ;; category order to list order.
1478 ;; (todos-repair-categories-sexp)
1479 ;; Compare (todos-make-categories-list t) with sexp and if
1480 ;; different ask (todos-update-categories-sexp) ?
1496 "Function underlying commands to edit item date/time header.
1498 The argument WHAT (passed by invoking commands) specifies what
1499 part of the header to edit; possible values are these symbols:
1500 `date', to edit the year, month, and day of the date string;
1501 `time', to edit just the time string; `calendar', to select the
1502 date from the Calendar; `today', to set the date to today's date;
1503 `dayname', to set the date string to the name of a day or to
1504 change the day name; and `year', `month' or `day', to edit only
1505 these respective parts of the date string (`day' is the number of
1506 the given day of the month, and `month' is either the name of the
1507 given month or its number, depending on the value of
1508 `calendar-date-display-form').
1510 The optional argument INC is a positive or negative integer
1511 \(passed by invoking commands as a numerical prefix argument)
1512 that in conjunction with the WHAT values `year', `month' or
1513 `day', increments or decrements the specified date string
1514 component by the specified number of suitable units, i.e., years,
1515 months, or days, with automatic adjustment of the other date
1516 string components as necessary.
1518 If there are marked items, apply the same edit to all of these;
1519 otherwise, edit just the item at point."
1525 ndate ntime year monthname month day
1536 todos-date-pattern
1559 ;; If there are marked items, use only the first to set
1560 ;; header changes, and apply these to all marked items.
1575 ;; When date string consists only of a day name,
1576 ;; passing other date components is a NOP.
1581 monthname omonthname
1582 month omonth
1591 year oyear
1593 month
1594 monthname)
1601 ;; Increment or decrement month by INC
1602 ;; modulo 12.
1604 ;; If result is 0, make month December.
1606 ;; Adjust year if necessary.
1613 oyear)))
1614 ;; Return the changed numerical month as
1615 ;; a string or the corresponding month name.
1620 ;; When mm is 13 (corresponding to "*" as value
1621 ;; of month), this raises an args-out-of-range
1622 ;; error in calendar-last-day-of-month, so use 1
1623 ;; (corresponding to January) to get 31 days.
1632 month omonth
1633 monthname omonthname
1644 ;; Increment or decrement day by INC,
1645 ;; adjusting month and year if necessary
1646 ;; (if year is "*" assume current year to
1647 ;; calculate adjustment).
1655 ;; Set year and month(name) to adjusted values.
1661 ;; Return changed numerical day as a string.
1663 ;; If new year, month or day date string components were
1664 ;; calculated, rebuild the whole date string from them.
1670 ;; Add new time string to the header, if it was supplied.
1678 ;; Apply the changes to the first marked item header to the
1679 ;; remaining marked items. If there are no marked items,
1680 ;; we're finished.
1686 "Interactively edit at least the date of item's date/time header.
1687 If user option `todos-always-add-time-string' is non-nil, also
1688 edit item's time string."
1695 "Interactively edit the time string of item's date/time header."
1700 "Interactively edit item's date using the Calendar."
1705 "Set item's date to today's date."
1710 "Replace item's date with the name of a day of the week."
1715 "Interactively edit the year of item's date string.
1716 With prefix argument INC a positive or negative integer,
1717 increment or decrement the year by INC."
1722 "Interactively edit the month of item's date string.
1723 With prefix argument INC a positive or negative integer,
1724 increment or decrement the month by INC."
1729 "Interactively edit the day of the month of item's date string.
1730 With prefix argument INC a positive or negative integer,
1731 increment or decrement the day by INC."
1736 "Change diary status of one or more todo items in this category.
1737 That is, insert `todos-nondiary-marker' if the candidate items
1738 lack this marking; otherwise, remove it.
1740 If there are marked todo items, change the diary status of all
1741 and only these, otherwise change the diary status of the item at
1742 point."
1746 todos-categories-with-marks)))
1775 "Make all items in this category diary items.
1776 With prefix ARG, make all items in this category non-diary
1777 items."
1810 "Change non-marking of one or more diary items in this category.
1811 That is, insert `diary-nonmarking-symbol' if the candidate items
1812 lack this marking; otherwise, remove it.
1814 If there are marked todo items, change the non-marking status of
1815 all and only these, otherwise change the non-marking status of
1816 the item at point."
1820 todos-categories-with-marks)))
1837 "Add `diary-nonmarking-symbol' to all diary items in this category.
1838 With prefix ARG, remove `diary-nonmarking-symbol' from all diary
1839 items in this category."
1857 "Prompt for and set ITEM's priority in CATegory.
1859 Interactively, ITEM is the todo item at point, CAT is the current
1860 category, and the priority is a number between 1 and the number
1861 of items in the category. Non-interactively, non-nil NEW means
1862 ITEM is a new item and the lowest priority is one more than the
1863 number of items in CAT.
1865 The new priority is set either interactively by prompt or by a
1866 numerical prefix argument, or noninteractively by argument ARG,
1867 whose value can be either of the symbols `raise' or `lower',
1868 meaning to raise or lower the item's priority by one."
1879 todos-date-pattern
1886 curnum
1897 count)))
1903 current-prefix-arg)
1908 candidate
1909 buffer-read-only)
1913 ;; When moving item to another category, show the category before
1914 ;; prompting for its priority.
1917 ;; If done items in category are visible, keep them visible.
1925 ;; Keep top of category in view while setting priority.
1927 ;; Prompt for priority only when the category has at least one
1928 ;; todo item.
1934 maxnum)))
1936 ;; In Top Priorities buffer, an item's priority can be changed
1937 ;; wrt items in another category, but not wrt items in the same
1938 ;; category.
1960 ;; Interactively or with non-nil ARG, relocate the item within its
1961 ;; category.
1968 ;; When called from todos-item-undone and the highest priority
1969 ;; is chosen, this advances point to the first done item, so
1970 ;; move it up to the empty line above the done items
1971 ;; separator.
1977 ;; If item was marked, restore the mark.
1985 "Raise priority of current item by moving it up by one item."
1990 "Lower priority of current item by moving it down by one item."
1995 "Move at least one todo or done item to another category.
1996 If there are marked items, move all of these; otherwise, move
1997 the item at point.
1999 With prefix argument FILE, prompt for a specific Todos file and
2000 choose (with TAB completion) a category in it to move the item or
2001 items to; otherwise, choose and move to any category in either
2002 the current Todos file or one of the files in
2003 `todos-category-completions-files'. If the chosen category is
2004 not an existing categories, then it is created and the item(s)
2005 become(s) the first entry/entries in that category.
2007 With moved Todo items, prompt to set the priority in the category
2008 moved to (with multiple todos items, the one that had the highest
2009 priority in the category moved from gets the new priority and the
2010 rest of the moved todo items are inserted in sequence below it).
2011 Moved done items are appended to the top of the done items
2012 section in the category moved to."
2016 ;; Noop if point is not on an item and there are no marked items.
2029 ov cat2 file2 moved nmark todo-items done-items)
2039 nil file)))
2063 ;; Chop off last newline of multiple todo item string,
2064 ;; since it will be reinserted when setting priority
2065 ;; (but with done items priority is not set, so keep
2066 ;; last newline).
2079 ;; Move done items en bloc to top of done items section.
2093 ;; Move succeeded, so remove item from starting category,
2094 ;; update item counts and display the category containing
2095 ;; the moved item.
2138 ;; If item is moved to end of (just first?) category, make
2139 ;; sure the items above it are displayed in the window.
2141 ;; User quit before setting priority of todo item(s), so
2142 ;; return to starting category.
2151 "Tag a todo item in this category as done and relocate it.
2153 With prefix argument ARG prompt for a comment and append it to
2154 the done item; this is only possible if there are no marked
2155 items. If there are marked items, tag all of these with
2156 `todos-done-string' plus the current date and, if
2157 `todos-always-add-time-string' is non-nil, the current time;
2158 otherwise, just tag the item at point. Items tagged as done are
2159 relocated to the category's (by default hidden) done section. If
2160 done items are visible on invoking this command, they remain
2161 visible."
2182 ;; Point is between todo and done items.
2198 item done-item opoint)
2199 ;; Don't add empty comment to done item.
2204 ;; Stop looping when we hit the empty line below the last
2205 ;; todo item (this is eobp if only done items are hidden).
2219 ;; Chop off last newline of done item string.
2236 ;; When done items are shown, put cursor on first just done item.
2240 "Add a comment to this done item or edit an existing comment.
2241 With prefix ARG delete an existing comment."
2247 comment buffer-read-only)
2260 ;; If user moved point during editing, make sure it moves back.
2266 "Restore at least one done item to this category's todo section.
2267 Prompt for the new priority. If there are marked items, undo all
2268 of these, giving the first undone item the new priority and the
2269 rest following directly in sequence; otherwise, undo just the
2270 item at point.
2272 If the done item has a comment, ask whether to omit the comment
2273 from the restored item. With multiple marked done items with
2274 comments, only ask once, and if affirmed, omit subsequent
2275 comments without asking."
2287 start end item ov npoint undone)
2299 ;; Find the end of the date string added upon tagging item as
2300 ;; done.
2306 ;; Ask (once) whether to omit done item's comment. If
2307 ;; affirmed, omit subsequent comments without asking.
2317 " from restored item"
2321 t)
2332 ;; Chop off last newline of multiple items string, since
2333 ;; it will be reinserted on setting priority.
2360 ;; Put cursor on undone item.
2364 ;; -----------------------------------------------------------------------------
2365 ;;; Done Item Archives
2366 ;; -----------------------------------------------------------------------------
2369 "Non-nil to handle categories with only archived items specially.
2373 archived items. Other commands still recognize these categories.
2375 categories shown in `todos-archived-only' face and pressing the
2376 category button visits the category in the archive instead of the
2377 todo file."
2382 "Visit the archive of the current Todos category, if it exists.
2383 If the category has no archived items, prompt to visit the
2384 archive anyway. If there is no archive for this file or with
2385 non-nil argument ASK, prompt to visit another archive.
2387 The buffer showing the archive is in Todos Archive mode. The
2388 first visit in a session displays the first category in the
2389 archive, subsequent visits return to the last category
2390 displayed."
2396 place)
2419 "Choose an archive and visit it."
2424 "Archive at least one done item in this category.
2426 With prefix argument ALL, prompt whether to archive all done
2427 items in this category and on confirmation archive them.
2428 Otherwise, if there are marked done items (and no marked todo
2429 items), archive all of these; otherwise, archive the done item at
2430 point.
2432 If the archive of this file does not exist, it is created. If
2433 this category does not exist in the archive, it is created."
2451 marked-items beg end all-done
2452 buffer-read-only)
2462 nil t)
2467 nil t)
2472 ;; Restore starting point, unless it was on a done
2473 ;; item, since they will all be deleted.
2497 nil t)
2499 nil t))
2500 ;; Start of done items section in existing category.
2503 ;; Start of done items section in new category.
2510 ;; If archive is new, save to file now (using write-region in
2511 ;; order not to get prompted for file to save to), to let
2512 ;; auto-mode-alist take effect below.
2521 ;; Make sure done items are accessible.
2528 ;; If we're archiving all done items, can't
2529 ;; first archive item point was on, since
2530 ;; that will short-circuit the rest.
2540 ;; Don't leave point below last item.
2556 ;; Make todo file current to select category.
2558 ;; Make sure done item separator is hidden (if done items
2559 ;; were initially visible).
2563 "Unarchive at least one item in this archive category.
2564 If there are marked items, unarchive all of these; otherwise,
2565 unarchive the item at point.
2567 Unarchived items are restored as done items to the corresponding
2568 category in the Todos file, inserted at the top of done items
2569 section. If all items in the archive category have been
2570 restored, the category is deleted from the archive. If this was
2571 the only category in the archive, the archive file is deleted."
2581 marked-items
2582 buffer-read-only)
2591 ;; Restore items to top of category's done section and update counts.
2596 ;; Find the corresponding todo category, or if there isn't
2597 ;; one, add it.
2603 ;; Go to top of category's done section.
2618 ;; Delete restored items from archive.
2631 ;; If that was the last category in the archive, delete the whole file.
2635 ;; Kill the archive buffer silently.
2638 ;; Otherwise, if the archive category is now empty, delete it.
2643 nil t))
2652 todos-categories))
2654 ;; Visit category in Todos file and show restored done items.
2664 "Prompt for a category in a Todos archive and jump to it.
2665 With prefix argument FILE, prompt for an archive and choose (with
2666 TAB completion) a category in it to jump to; otherwise, choose
2667 and jump to any category in the current archive."
2671 ;; -----------------------------------------------------------------------------
2672 ;;; Todos mode display options
2673 ;; -----------------------------------------------------------------------------
2676 "String prefixed to todo items for visual distinction."
2681 widget :error
2683 widget)))
2689 "Non-nil to prefix items with consecutively increasing integers.
2690 These reflect the priorities of the items in each category."
2697 "String determining the value of variable `todos-done-separator'.
2699 If the string consists of a single character,
2700 `todos-done-separator' will be the string made by repeating this
2701 character for the width of the window, and the length is
2702 automatically recalculated when the window width changes. If the
2703 string consists of more (or less) than one character, it will be
2704 the value of `todos-done-separator'."
2711 "Identifying string appended to the front of done todos items."
2718 "String inserted before optional comment appended to done item."
2725 "Non-nil to display done items in all categories."
2730 "Return a mode line control for todo or archive file buffers.
2731 Argument CAT is the name of the current Todos category.
2732 This function is the value of the user variable
2733 `todos-mode-line-function'."
2738 "Function that returns a mode line control for Todos buffers.
2739 The function expects one argument holding the name of the current
2740 Todos category. The resulting control becomes the local value of
2741 `mode-line-buffer-identification' in each Todos buffer."
2746 "Non-nil means highlight items at point."
2753 "Non-nil to activate Visual Line mode and use wrap prefix."
2758 "Number of spaces to indent continuation lines of items.
2759 This must be a positive number to ensure such items are fully
2760 shown in the Fancy Diary display."
2766 widget)))
2770 "Indent from point to `todos-indent-to-here'."
2773 ;; -----------------------------------------------------------------------------
2774 ;;; Display Commands
2775 ;; -----------------------------------------------------------------------------
2778 "Hide item numbering if shown, show if hidden."
2793 "Show hidden or hide visible done items in current category."
2803 ;; If start of done items sections is below the bottom of the
2804 ;; window, make it visible.
2814 "Switch between displaying only done or only todo items."
2820 "Highlight or unhighlight the todo item the cursor is on."
2828 "Hide or show item date-time headers in the current file.
2829 With done items, this hides only the done date-time string, not
2830 the the original date-time string."
2844 nil t)
2850 ;; -----------------------------------------------------------------------------
2851 ;;; Faces
2852 ;; -----------------------------------------------------------------------------
2855 ;; '((t :inherit font-lock-constant-face))
2866 "Face for Todos prefix or numerical priority string."
2870 ;; bold font-lock-comment-face
2881 "Face for top priority Todos item numerical priority string.
2882 The item's priority number string has this face if the number is
2883 less than or equal the category's top priority setting."
2887 ;; '((t :inherit font-lock-warning-face))
2909 "Face for marks on marked items."
2913 ;; '((t :inherit widget-field))
2924 "Face for buttons in table of categories."
2938 "Face for sorted column in table of categories."
2942 ;; '((t (:inherit (shadow))))
2951 "Face for archived-only category names in table of categories."
2955 ;; '((t :inherit match))
2977 "Face for matches found by `todos-search'."
2981 ;; Doesn't contrast enough with todos-date (= diary) face.
2982 ;; ;; '((t :inherit warning))
2983 ;; '((default :weight bold)
2984 ;; (((class color) (min-colors 16)) :foreground "DarkOrange")
2985 ;; (((class color)) :foreground "yellow"))
2986 ;; bold font-lock-function-name-face
2994 "Face for expired dates of diary items."
2999 "Face for the date string of a Todos item."
3004 "Face for the time string of a Todos item."
3008 ;; '((t :inherit font-lock-type-face))
3017 "Face for non-diary markers around todo item date/time header."
3021 ;; '((t :inherit font-lock-type-face))
3030 "Face for category-file header in Todos Filtered Items mode."
3034 ;; '((t :inherit font-lock-keyword-face))
3043 "Face for done Todos item header string."
3047 ;; '((t :inherit font-lock-comment-face))
3065 "Face for comments appended to done Todos items."
3069 ;; '((t :inherit font-lock-builtin-face))
3078 "Face for separator string bewteen done and not done Todos items."
3081 ;; -----------------------------------------------------------------------------
3082 ;;; Todos Categories mode options
3083 ;; -----------------------------------------------------------------------------
3086 "Category button label in Todos Categories mode."
3091 "Todo button label in Todos Categories mode."
3096 "Diary button label in Todos Categories mode."
3101 "Done button label in Todos Categories mode."
3106 "Archived button label in Todos Categories mode."
3111 "String to label total item counts in Todos Categories mode."
3116 "String between number and category in Todos Categories mode.
3117 This separates the number from the category name in the default
3118 categories display according to priority."
3123 "Alignment of category names in Todos Categories mode."
3127 ;; -----------------------------------------------------------------------------
3128 ;;; Entering and using Todos Categories mode
3129 ;; -----------------------------------------------------------------------------
3132 "Display a table of the current file's categories and item counts.
3134 In the initial display the categories are numbered, indicating
3137 order of the category at point by typing
3141 The labels above the category names and item counts are buttons,
3142 and clicking these changes the display: sorted by category name
3143 or by the respective item counts (alternately descending or
3144 ascending). In these displays the categories are not numbered
3147 sorting is triggered by passing a non-nil SORTKEY argument.)
3149 In addition, the lines with the category names and item counts
3150 are buttonized, and pressing one of these button jumps to the
3151 category in Todos mode (or Todos Archive mode, for categories
3152 containing only archived items, provided user option
3153 `todos-skip-archived-categories' is non-nil. These categories
3154 are shown in `todos-archived-only' face."
3161 "Sort table of categories alphabetically or numerically."
3174 "Sort table of categories by number of todo items."
3182 "Sort table of categories by number of diary items."
3190 "Sort table of categories by number of non-archived done items."
3198 "Sort table of categories by number of archived items."
3206 "Move point to the Nth next button in the table of categories."
3210 ;; Align with beginning of category label.
3214 "Move point to the Nth previous button in the table of categories."
3218 ;; Align with beginning of category label.
3222 "Change number of category at point in the table of categories.
3224 With ARG nil, prompt for the new number. Alternatively, the
3225 enter the new number with numerical prefix ARG. Otherwise, if
3226 ARG is either of the symbols `raise' or `lower', raise or lower
3227 the category line in the table by one, respectively, thereby
3228 decreasing or increasing its number."
3231 ;; Get the number representing the priority of the category
3232 ;; on the current line.
3243 candidate)
3250 maxnum))
3259 todos-categories))
3260 ;; Category's name and items counts list.
3263 newcats)
3277 "Raise priority of category at point in Todos Categories buffer."
3282 "Lower priority of category at point in Todos Categories buffer."
3286 ;; -----------------------------------------------------------------------------
3287 ;;; Searching
3288 ;; -----------------------------------------------------------------------------
3291 "Search for a regular expression in this Todos file.
3292 The search runs through the whole file and encompasses all and
3293 only todo and done items; it excludes category names. Multiple
3294 matches are shown sequentially, highlighted in `todos-search'
3295 face."
3299 matches match cat in-done ov mlen msg)
3333 mlen)
3338 mlen)
3352 "Remove highlighting on matches found by todos-search."
3356 ;; -----------------------------------------------------------------------------
3357 ;;; Item filtering options
3358 ;; -----------------------------------------------------------------------------
3361 "List of rules specifying number of top priority items to show.
3362 These rules override `todos-top-priorities' on invocations of
3365 of the form (FILE NUM ALIST), where FILE is a member of
3366 `todos-files', NUM is a number specifying the default number of
3367 top priority items for each category in that file, and ALIST,
3368 when non-nil, consists of conses of a category name in FILE and a
3369 number specifying the default number of top priority items in
3370 that category, which overrides NUM.
3372 This variable should be set interactively by
3379 "Default number of top priorities shown by `todos-filter-top-priorities'."
3384 "List of default files for multifile item filtering."
3391 "Non-nil to include done items when processing regexp filters.
3392 Done items from corresponding archive files are also included."
3396 ;; -----------------------------------------------------------------------------
3397 ;;; Item filtering commands
3398 ;; -----------------------------------------------------------------------------
3401 "Set number of top priorities for this file.
3402 See `todos-set-top-priorities' for more details."
3407 "Set number of top priorities for this category.
3408 See `todos-set-top-priorities' for more details."
3413 "Display a list of top priority items from different categories.
3414 The categories can be any of those in the current Todos file.
3416 With numerical prefix ARG show at most ARG top priority items
3417 from each category. With `C-u' as prefix argument show the
3418 numbers of top priority items specified by category in
3419 `todos-top-priorities-overrides', if this has an entry for the file(s);
3420 otherwise show `todos-top-priorities' items per category in the
3421 file(s). With no prefix argument, if a top priorities file for
3422 the current Todos file has previously been saved (see
3423 `todos-save-filtered-items-buffer'), visit this file; if there is
3424 no such file, build the list as with prefix argument `C-u'.
3426 The prefix ARG regulates how many top priorities from
3427 each category to show, as described above."
3432 "Display a list of top priority items from different categories.
3433 The categories are a subset of the categories in the files listed
3434 in `todos-filter-files', or if this nil, in the files chosen from
3435 a file selection dialog that pops up in this case.
3437 With numerical prefix ARG show at most ARG top priority items
3438 from each category in each file. With `C-u' as prefix argument
3439 show the numbers of top priority items specified in
3440 `todos-top-priorities-overrides', if this is non-nil; otherwise show
3441 `todos-top-priorities' items per category. With no prefix
3442 argument, if a top priorities file for the chosen Todos files
3443 exists (see `todos-save-filtered-items-buffer'), visit this file;
3444 if there is no such file, do the same as with prefix argument
3445 `C-u'."
3450 "Display a list of todo diary items from different categories.
3451 The categories can be any of those in the current Todos file.
3453 Called with no prefix ARG, if a diary items file for the current
3454 Todos file has previously been saved (see
3455 `todos-save-filtered-items-buffer'), visit this file; if there is
3456 no such file, build the list of diary items. Called with a
3457 prefix argument, build the list even if there is a saved file of
3458 diary items."
3463 "Display a list of todo diary items from different categories.
3464 The categories are a subset of the categories in the files listed
3465 in `todos-filter-files', or if this nil, in the files chosen from
3466 a file selection dialog that pops up in this case.
3468 Called with no prefix ARG, if a diary items file for the chosen
3469 Todos files has previously been saved (see
3470 `todos-save-filtered-items-buffer'), visit this file; if there is
3471 no such file, build the list of diary items. Called with a
3472 prefix argument, build the list even if there is a saved file of
3473 diary items."
3478 "Prompt for a regular expression and display items that match it.
3479 The matches can be from any categories in the current Todos file
3480 and with non-nil option `todos-filter-done-items', can include
3481 not only todo items but also done items, including those in
3482 Archive files.
3484 Called with no prefix ARG, if a regexp items file for the current
3485 Todos file has previously been saved (see
3486 `todos-save-filtered-items-buffer'), visit this file; if there is
3487 no such file, build the list of regexp items. Called with a
3488 prefix argument, build the list even if there is a saved file of
3489 regexp items."
3494 "Prompt for a regular expression and display items that match it.
3495 The matches can be from any categories in the files listed in
3496 `todos-filter-files', or if this nil, in the files chosen from a
3497 file selection dialog that pops up in this case. With non-nil
3498 option `todos-filter-done-items', the matches can include not
3499 only todo items but also done items, including those in Archive
3500 files.
3502 Called with no prefix ARG, if a regexp items file for the current
3503 Todos file has previously been saved (see
3504 `todos-save-filtered-items-buffer'), visit this file; if there is
3505 no such file, build the list of regexp items. Called with a
3506 prefix argument, build the list even if there is a saved file of
3507 regexp items."
3512 "Choose a filtered items file and visit it."
3515 falist file)
3521 falist)))
3528 "Display the file and category of the filtered item at point."
3545 t
3546 todos-show-with-done)))
3550 ;; -----------------------------------------------------------------------------
3551 ;;; Printing Todos Buffers
3552 ;; -----------------------------------------------------------------------------
3555 "Function called by the command `todos-print-buffer'."
3563 "Produce a printable version of the current Todos buffer.
3564 This converts overlays and soft line wrapping and, depending on
3565 the value of `todos-print-buffer-function', includes faces. With
3566 non-nil argument TO-FILE write the printable version to a file;
3567 otherwise, send it to the default printer."
3582 file)
3595 ;; Calling todos-forward-item infloops at todos-item-start due to
3596 ;; non-overlay prefix, so search for item start instead.
3601 nil t)
3613 "Save printable version of this Todos buffer to a file."
3617 ;; -----------------------------------------------------------------------------
3618 ;;; Legacy Todo Mode Files
3619 ;; -----------------------------------------------------------------------------
3624 "Regexp matching legacy todo-mode.el item date-time strings.
3625 In order for `todos-convert-legacy-files' to correctly convert this
3626 string to the current Todos format, the regexp must contain four
3627 explicitly numbered groups (see `(elisp) Regexp Backslash'),
3628 where group 1 matches a string for the year, group 2 a string for
3629 the month, group 3 a string for the day and group 4 a string for
3630 the time. The default value converts date-time strings built
3631 using the default value of `todo-time-string-format' from
3632 todo-mode.el."
3637 "Return converted date-time string.
3638 Helper function for `todos-convert-legacy-files'."
3644 dayname)
3650 "Convert legacy Todo files to the current Todos format.
3651 The files `todo-file-do' and `todo-file-done' are converted and
3652 saved (the latter as a Todos Archive file) with a new name in
3653 `todos-directory'. See also the documentation string of
3654 `todos-todo-mode-date-time-regexp' for further details."
3659 ;; Convert `todo-file-do'.
3662 file archive-sexp)
3678 todo-category-sep)))
3681 todos-todo-mode-date-time-regexp " "
3688 nil nil default)
3696 ;; Convert `todo-file-done'.
3702 cat cats comment item)
3727 ;; If the item ends with a non-comment parenthesis not
3728 ;; followed by a period, we lose (but we inherit that problem
3729 ;; from todo-mode.el).
3736 ;; If item is already in its category, leave it there.
3742 ;; Else move it to its category.
3750 nil t)
3778 ;; Update categories sexp of converted Todos file again, adding
3779 ;; counts of archived items.
3796 ;; =============================================================================
3797 ;;; Todos utilities and internals
3798 ;; =============================================================================
3808 SPC to affirm the question only if option `todos-y-with-space' is
3809 non-nil."
3816 ;; -----------------------------------------------------------------------------
3817 ;;; File-level global variables and support functions
3818 ;; -----------------------------------------------------------------------------
3827 "List of Todos files visited in this session by `todos-show'.
3828 Used to determine initial display according to the value of
3835 "Variable holding name of current Todos file.
3836 Used by functions called from outside of Todos mode to visit the
3837 current Todos file rather than the default Todos file (i.e. when
3841 "Return the absolute file name of short Todos file NAME.
3842 With TYPE `archive' or `top' return the absolute file name of the
3843 short Todos Archive or Top Priorities file name, respectively."
3844 ;; NOP if there is no Todos file yet (i.e. don't concatenate nil).
3855 "Signal an error if the current Todos file is ill-formatted.
3856 Otherwise return t. Display a message if the file is well-formed
3857 but the categories sexp differs from the current value of
3858 `todos-categories'."
3867 ;; Check the first line for `todos-categories' sexp.
3875 ;; Check well-formedness of categories.
3888 ;; Warn user if categories sexp has changed.
3892 "If the sexp is wrong, you can fix it with "
3894 "but note this reverts any changes you have "
3896 t)
3899 "Reevaluate defcustoms that provide choice list of Todos files."
3910 "Reevaluate defcustom of `todos-default-todos-file'.
3911 Called after adding or deleting a Todos file."
3913 "Todos file visited by first session invocation of `todos-show'."
3920 "Reevaluate defcustom of `todos-category-completions-files'.
3921 Called after adding or deleting a Todos file."
3923 "List of files for building `todos-read-category' completions."
3930 "Reevaluate defcustom of `todos-filter-files'.
3931 Called after adding or deleting a Todos file."
3933 "List of files for multifile item filtering."
3939 ;; -----------------------------------------------------------------------------
3940 ;;; Category-level global variables and support functions
3941 ;; -----------------------------------------------------------------------------
3944 "Return the number of category CAT in this Todos file.
3945 The buffer-local variable `todos-category-number' holds this
3946 number as its value."
3949 ;; Increment by one, so that the highest priority category in Todos
3950 ;; Categories mode is numbered one rather than zero.
3955 "Return the name of the current category."
3959 "Display the current category correctly."
3961 cat-begin cat-end done-start done-sep-start done-end)
3987 ;; Now we want to see the done items, so reset displayed end to end of
3988 ;; done items.
3990 ;; Make display overlay for done items separator string, unless there
3991 ;; already is one.
4000 ;; Loading this from todos-mode, or adding it to the mode hook, causes
4001 ;; Emacs to hang in todos-item-start, at (looking-at todos-item-start).
4013 "Return string used as value of variable `todos-done-separator'."
4016 ;; Until bug#2749 is fixed, if separator's length
4017 ;; is window-width, then with non-nil
4018 ;; todos-wrap-lines an indented empty line appears
4019 ;; between the separator and the first done item.
4020 ;; (make-string (1- (window-width)) (string-to-char sep))
4022 todos-done-separator-string)
4026 "String used to visually separate done from not done items.
4027 Displayed as an overlay instead of `todos-category-done' when
4028 done items are shown. Its value is determined by user option
4032 "Replace existing overlays of done items separator string SEP."
4044 new-ov)
4053 "Return count of TYPE items in CATEGORY.
4054 If CATEGORY is nil, default to the current category."
4064 "Change count of TYPE items in CATEGORY by integer INCREMENT.
4065 With nil or omitted CATEGORY, default to the current category."
4075 "Set `todos-categories' from the sexp at the top of the file."
4076 ;; New archive files created by `todos-move-category' are empty, which would
4077 ;; make the sexp test fail and raise an error, so in this case we skip it.
4091 "Update the `todos-categories' sexp at the top of the file."
4104 "Return an alist of Todos categories and their item counts.
4105 With non-nil argument FORCE parse the entire file to build the
4106 list; otherwise, get the value by reading the sexp at the top of
4107 the file."
4114 ;; If the file is a todo file and has archived items, identify the
4115 ;; archive, in order to count its items. But skip this with
4116 ;; `todos-convert-legacy-files', since that converts filed items to
4117 ;; archived items.
4119 ;; If the file is an archive, it doesn't have an archive.
4128 ;; Counts for each category: [todo diary done archive]
4132 ;; Add archived item count to the todo file item counts.
4133 ;; Make sure to include newly created archives, e.g. due to
4134 ;; todos-move-category.
4163 ;; If first line is todos-categories list, use it and end loop
4164 ;; -- unless FORCEd to scan whole file.
4172 todos-categories)
4175 "Repair corrupt Todos categories sexp.
4176 This should only be needed as a consequence of careless manual
4177 editing or a bug in todos.el.
4179 *Warning*: Calling this command restores the category order to
4180 the list element order in the Todos categories sexp, so any order
4181 changes made in Todos Categories mode will have to be made again."
4186 ;; -----------------------------------------------------------------------------
4187 ;;; Item-level global variables and support functions
4188 ;; -----------------------------------------------------------------------------
4192 "Array of month names, in order.
4197 "Array of abbreviated month names, in order.
4205 todos-month-name-array
4206 todos-month-abbrev-array)))
4220 ;; By itself this matches anything, because of the `?'; however, it's only
4221 ;; used in the context of `todos-date-pattern' (but Emacs Lisp lacks
4222 ;; lookahead).
4234 todos-date-pattern)
4238 "Move to start of current Todos item and return its position."
4240 ;; Buffer is empty (invocation possible e.g. via todos-forward-item
4241 ;; from todos-filter-items when processing category with no todo
4242 ;; items).
4244 ;; Point is on the empty line below category's last todo item...
4251 ;; Buffer is widened.
4259 "Move to end of current Todos item and return its position."
4260 ;; Items cannot end with a blank line.
4264 ;; For todo items, end is before the done items section, for done
4265 ;; items, end is before the next category. If these limits are
4266 ;; missing or inaccessible, end it before the end of the buffer.
4270 todos-category-beg
4271 todos-category-done)))
4272 nil t))
4279 ;; For last todo item, skip back over the empty line before the done
4280 ;; items section, else just back to the end of the previous line.
4285 "Return bare text of current item as a string."
4293 "Move point COUNT items down (by default, move down by one item)."
4300 ;; If points advances by one from a todo to a done item, go back
4301 ;; to the space above todos-done-separator, since that is a
4302 ;; legitimate place to insert an item. But skip this space if
4303 ;; count > 1, since that should only stop on an item.
4305 ;; (if (or (not count) (= count 1))
4307 ;; The preceding sexp is insufficient when buffer is not narrowed,
4308 ;; since there could be no done items in this category, so the
4309 ;; search puts us on first todo item of next category. Does this
4310 ;; ever happen? If so:
4311 ;; (let ((opoint) (point))
4312 ;; (forward-line -1)
4313 ;; (when (or (not count) (= count 1))
4314 ;; (cond ((looking-at (concat "^" (regexp-quote todos-category-beg)))
4315 ;; (forward-line -2))
4316 ;; ((looking-at (concat "^" (regexp-quote todos-category-done)))
4317 ;; (forward-line -1))
4318 ;; (t
4319 ;; (goto-char opoint)))))))
4322 "Move point up to start of item with next higher priority.
4323 With positive numerical prefix COUNT, move point COUNT items
4324 upward.
4326 If the category's done items are visible, this command called
4327 with a prefix argument only moves point to a higher item, e.g.,
4328 with point on the first done item and called with prefix 1, it
4329 moves to the last todo item; but if called with point on the
4330 first done item without a prefix argument, it moves point the the
4331 empty line above the done items separator."
4336 ;; Unless this is a regexp filtered items buffer (which can contain
4337 ;; intermixed todo and done items), if points advances by one from a
4338 ;; done to a todo item, go back to the space above
4339 ;; todos-done-separator, since that is a legitimate place to insert an
4340 ;; item. But skip this space if count > 1, since that should only
4341 ;; stop on an item.
4343 ;(or (not count) (= count 1))
4346 nil t)
4350 "Internal function called in editing, deleting or moving items."
4358 "Return non-nil if item at point has diary entry format."
4365 "Return non-nil if item at point is a done item."
4371 "Return non-nil if point is in category's done items section."
4374 nil t)
4379 "Return the overlay at point whose `todos' property has value VAL."
4380 ;; Use overlays-in to find prefix overlays and check over two
4381 ;; positions to find done separator overlay.
4383 ov)
4391 "Non-nil if this item begins with `todos-item-mark'.
4392 In that case, return the item's prefix overlay."
4394 ;; If an item insertion command is called on a Todos file
4395 ;; before it is visited, it has no prefix overlays yet, so
4396 ;; check for this.
4400 pref))))
4404 "Insert ITEM at point and update prefix/priority number overlays."
4406 ;; Insertion pushes item down but not its prefix overlay. When the
4407 ;; overlay includes a mark, this would now mark the inserted ITEM,
4408 ;; so move it to the pushed down item.
4417 "Update the prefix overlays of the current category's items.
4418 The overlay's value is the string `todos-prefix' or with non-nil
4419 `todos-number-prefix' an integer in the sequence from 1 to
4420 the number of todo or done items in the category indicating the
4421 item's priority. Todo and done items are numbered independently
4422 of each other."
4427 todos-top-priorities-overrides))))
4428 todos-top-priorities))
4429 done prefix)
4437 ;; Reset number to 1 for first done item.
4444 done t))
4448 todos-prefix)
4449 'face
4450 ;; Prefix of top priority items has a
4451 ;; distinct face in Todos mode.
4455 'todos-top-priority
4460 ;; Prefix overlay must be at a single position so its
4461 ;; bounds aren't changed when (re)moving an item.
4466 prefix))))
4469 ;; -----------------------------------------------------------------------------
4470 ;;; Generation of item insertion commands and key bindings
4471 ;; -----------------------------------------------------------------------------
4473 ;; Can either of these be included in Emacs? The originals are GFDL'd.
4475 ;; Reformulation of http://rosettacode.org/wiki/Power_set#Common_Lisp.
4481 pset)
4486 ;; Elisp implementation of http://rosettacode.org/wiki/Power_set#C.
4489 pset elt)
4500 pset))
4502 ;; (defalias 'todos-powerset 'todos-powerset-recursive)
4506 "Return list of lists of non-nil atoms produced from ARGLIST.
4507 The elements of ARGLIST may be atoms or lists."
4521 arg))))))
4530 res new)
4553 new)
4557 "Generate Todos item insertion command name from ARGLIST."
4562 ;; (concat "todos-item-insert-"
4569 todos-insertion-commands-args)
4573 "Generate item insertion command definitions from ARGS."
4581 "Todos item insertion command generated from ARGS.
4582 For descriptions of the individual arguments, their values, and
4583 their relation to key bindings, see `todos-basic-insert-item'."
4590 todos-insertion-commands-args)
4605 "Generate key binding definitions for item insertion keymap MAP."
4617 todos-insertion-commands-arg-key-list)
4622 ;; -----------------------------------------------------------------------------
4623 ;;; Todos minibuffer completion
4624 ;; -----------------------------------------------------------------------------
4627 "Return a list of completions for `todos-read-category'.
4628 Each element of the list is a cons of a category name and the
4629 file or list of files (as short file names) it is in. The files
4630 are either the current (or if there is none, the default) todo
4631 file plus the files listed in `todos-category-completions-files',
4632 or, with non-nil ARCHIVE, the current archive file."
4635 todos-global-current-todos-file)
4639 todos-category-completions-files))
4641 listall listf)
4642 ;; If file was just added, it has no category completions.
4648 ;; Ensure category is properly displayed in case user
4649 ;; switches to file via a non-Todos command. And if done
4650 ;; items in category are visible, keep them visible.
4671 listf)))))
4674 "Choose and return the name of a Todos file, prompting with PROMPT.
4676 Show completions with TAB or SPC; the names are shown in short
4677 form but the absolute truename is returned. With non-nil ARCHIVE
4678 return the absolute truename of a Todos archive file. With non-nil
4679 MUSTMATCH the name of an existing file must be chosen;
4680 otherwise, a new file name is allowed."
4686 ;; If user hit RET without
4687 ;; choosing a file, default to
4688 ;; current or default file.
4692 todos-global-current-todos-file)
4694 todos-default-todos-file)))
4695 ;; Trigger prompt for initial file.
4705 "Choose and return a category name, prompting with PROMPT.
4706 Show completions for existing categories with TAB or SPC.
4708 The argument MATCH-TYPE specifies the matching requirements on
4709 the category name: with the value `todo' or `archive' the name
4710 must complete to that of an existing todo or archive category,
4711 respectively; with the value `add' the name must not be that of
4712 an existing category; with all other values both existing and new
4713 valid category names are accepted.
4715 With non-nil argument FILE prompt for a file and complete only
4716 against categories in that file; otherwise complete against all
4717 categories from `todos-category-completions-files'."
4718 ;; Allow SPC to insert spaces, for adding new category names.
4725 "n archive"
4733 todos-categories)))
4737 todos-categories))
4739 completions)))
4743 ;; Unless we're adding a category via
4744 ;; todos-add-category, set default
4745 ;; for existing categories to the
4746 ;; current category of the chosen
4747 ;; file or else of the current file.
4752 todos-current-todos-file
4754 todos-default-todos-file)))
4756 ;; Trigger prompt for initial category.
4760 ;; If we do category completion and the chosen category name
4761 ;; occurs in more than one file, prompt to choose one file.
4765 catfil
4769 ;; Default to the current file.
4771 ;; First validate only a name passed interactively from
4772 ;; todos-add-category, which must be of a nonexisting category.
4774 ;; Validate only against completion categories.
4777 ;; When user enters a nonexisting category name by jumping or
4778 ;; moving, confirm that it should be added, then validate.
4786 ;; Restore point and narrowing after adding new
4787 ;; category, to avoid moving to beginning of file when
4788 ;; moving marked items to a new category
4789 ;; (todos-move-item).
4793 ;; If we decide not to add a category, exit without returning.
4798 "Prompt for new NAME for TYPE until it is valid, then return it.
4799 TYPE can be either of the symbols `file' or `category'."
4802 prompt)
4809 "Enter a non-empty file name: "
4810 ;; Empty string passed by todos-show to
4811 ;; prompt for initial Todos file.
4816 "Enter a non-empty category name: "
4817 ;; Empty string passed by todos-show to
4818 ;; prompt for initial category of a new
4819 ;; Todos file.
4832 files)
4834 categories)))
4835 ;; Offer default initial name.
4837 files
4838 categories)
4840 todos-initial-file
4841 todos-initial-category))))))
4842 name))
4844 ;; Adapted from calendar-read-date and calendar-date-string.
4846 "Prompt for Gregorian date and return it in the current format.
4848 With non-nil ARG, prompt for and return only the date component
4849 specified by ARG, which can be one of these symbols:
4850 `month' (prompt for name, return name or number according to
4851 value of `calendar-date-display-form'), `day' of month, or
4852 `year'. The value of each of these components can be `*',
4853 indicating an unspecified month, day, or year.
4855 When ARG is `day', non-nil arguments MO and YR determine the
4856 number of the last the day of the month."
4862 "Year (>0 or RET for this year or * for any year): "
4873 "Month name (RET for current month, * for any month): "
4874 ;; (mapcar 'list (append marray nil))
4875 mlist nil t nil nil
4878 ;; month (cdr (assoc-string
4879 ;; monthname (calendar-make-alist marray nil nil
4880 ;; abbrevs))))))
4888 ;; If month is unspecified, use a month with 31
4889 ;; days for checking day of month input. Does
4890 ;; Calendar do anything special when * is
4891 ;; currently a shorter month?
4893 ;; If year is unspecified, use a leap year to
4894 ;; allow Feb. 29.
4900 last)
4904 ;; Stringify read values (monthname is already a string).
4919 month
4920 monthname)))
4924 "Choose name of a day of the week with completion and return it."
4928 nil t)))
4931 "Prompt for and return a valid clock time as a string.
4933 Valid time strings are those matching `diary-time-regexp'.
4934 Typing `<return>' at the prompt returns the current time, if the
4935 user option `todos-always-add-time-string' is non-nil, otherwise
4936 the empty string (i.e., no time string)."
4945 answer))
4947 ;; -----------------------------------------------------------------------------
4948 ;;; Todos Categories mode tabulation and sorting
4949 ;; -----------------------------------------------------------------------------
4955 "Return the length of the longest name in list CATEGORIES."
4961 "Return adjusted length of category label button.
4962 The adjustment ensures proper tabular alignment in Todos
4963 Categories mode."
4973 "Return category name or label string STR padded with spaces.
4974 The placement of the padding is determined by the value of user
4975 option `todos-categories-align'."
4995 "Return a copy of LIST, possibly sorted according to KEY."
5000 ;; Keep track of whether the last sort by key was descending or
5001 ;; ascending.
5011 ;; Switch between descending and ascending sort order.
5016 l))
5019 "Keep point on the TYPE count sorting button just clicked."
5025 "Return symbol for sort key associated with LABEL."
5037 key))
5040 "Insert button for displaying categories sorted by item counts.
5041 LABEL determines which type of count is sorted."
5044 label))
5048 'action
5054 ;; If display is alphabetical, switch back to
5055 ;; category priority order.
5064 "Return a list of total item counts for the current file."
5073 "Insert button with category CAT's name and item counts.
5074 With non-nil argument NONUM show only these; otherwise, insert a
5075 number in front of the button indicating the category's priority.
5076 The number and the category name are separated by the string
5077 which is the value of the user option
5078 `todos-categories-number-separator'."
5089 str
5094 ;; Add an extra space if label length is odd.
5109 'todos-archived-only
5110 nil)
5114 ;; Highlight the sorted count column.
5116 end ovl)
5138 "Prepare buffer for displaying table of categories and item counts."
5148 buffer-read-only)
5155 ;; Make space for the column of category numbers.
5157 ;; Add the category and item count buttons (if this is the list of
5158 ;; categories in an archive, show only done item counts).
5175 "Populate table of categories and sort by SORTKEY."
5180 ;; Find start of Category button if we just entered Todos Categories
5181 ;; mode.
5190 ;; Fill in the table with buttonized lines, each showing a category and
5191 ;; its item counts.
5195 ;; Add a line showing item count totals.
5203 ;; Add an extra space if label length is odd.
5212 ;; Put cursor on Category button initially.
5216 ;; -----------------------------------------------------------------------------
5217 ;;; Item filtering selection and display
5218 ;; -----------------------------------------------------------------------------
5227 "Pop to a buffer with a widget for choosing multiple filter files."
5257 todos-multiple-filter-files-widget)))
5267 "Display a cross-categorial list of items filtered by FILTER.
5268 The values of FILTER can be `top' for top priority items, a cons
5269 of `top' and a number passed by the caller, `diary' for diary
5270 items, or `regexp' for items matching a regular expresion entered
5271 by the user. The items can be from any categories in the current
5272 todo file or, with non-nil MULTIFILE, from several files. If NEW
5273 is nil, visit an appropriate file containing the list of filtered
5274 items; if there is no such file, or with non-nil NEW, build the
5275 list and display it.
5277 See the document strings of the commands
5278 `todos-filter-top-priorities', `todos-filter-diary-items',
5279 `todos-filter-regexp-items', and those of the corresponding
5280 multifile commands for further details."
5290 todos-multiple-filter-files))
5294 ;; Pressed `cancel' in t-m-f-f file selection dialog.
5323 "Build a list of items by applying FILTER to FILE-LIST.
5324 Internal subroutine called by `todos-filter-items', which passes
5325 the values of FILTER and FILE-LIST."
5329 regexp fname bufstr cat beg end done)
5340 ;; Before inserting file contents into temp buffer, save a modified
5341 ;; buffer visiting it.
5348 ;; If there is a corresponding archive file for the
5349 ;; Todos file, insert it first and add identifiers for
5350 ;; todos-go-to-source-item.
5354 ;; Delete Todos archive file categories sexp.
5364 todos-date-string-start)
5370 nil t)
5374 ;; Delete Todos file categories sexp.
5377 ;; Unless the number of top priorities to show was
5378 ;; passed by the caller, the file-wide value from
5379 ;; `todos-top-priorities-overrides', if non-nil, overrides
5380 ;; `todos-top-priorities'.
5383 todos-top-priorities)))
5389 ;; Unless the number of top priorities to show was
5390 ;; passed by the caller, the category-wide value
5391 ;; from `todos-top-priorities-overrides', if non-nil,
5392 ;; overrides a non-nil file-wide value from
5393 ;; `todos-top-priorities-overrides' as well as
5394 ;; `todos-top-priorities'.
5402 nil t)
5409 end t)
5411 end))
5413 ;; Leave done items.
5418 ;; Apply the filter.
5430 ;; Kill lines that aren't part of a todo or done
5431 ;; item (empty or todos-category-done).
5434 ;; If last todo item in file matches regexp and
5435 ;; there are no following done items,
5436 ;; todos-category-done string is left dangling,
5437 ;; because todos-forward-item jumps over it.
5450 ;; Delete non-top-priority items.
5454 ;; Add file (if using multiple files) and category tags to
5455 ;; item.
5462 todos-date-string-start)
5468 nil t)
5483 "Set number of top priorities shown by `todos-filter-top-priorities'.
5484 With non-nil ARG, set the number only for the current Todos
5485 category; otherwise, set the number for all categories in the
5486 current Todos file.
5488 Calling this function via either of the commands
5489 `todos-set-top-priorities-in-file' or
5490 `todos-set-top-priorities-in-category' is the recommended way to
5491 set the user customizable option `todos-top-priorities-overrides'."
5499 todos-top-priorities))
5505 nrule)
5509 prompt "Enter a non-negative number: "
5510 cur0 nil)))
5516 nrule)
5534 "Search for filtered item STR in its saved Todos file.
5535 Return the list (FOUND FILE CAT), where CAT and FILE are the
5536 item's category and file, and FOUND is a cons cell if the search
5537 succeeds, whose car is the start of the item in FILE and whose
5538 cdr is `done', if the item is now a done item, `changed', if its
5539 text was truncated or augmented or, for a top priority item, if
5540 its priority has changed, and `same' otherwise."
5544 todos-date-string-start)
5557 found)
5560 ;; Calculate priority of STR wrt its category.
5570 todos-global-current-todos-file)))
5579 nil t))
5586 nil t)
5593 'done
5597 ;; Not top item in category.
5601 ;; Can't move backward beyond
5602 ;; first item in file.
5606 ;; Proper substring is not the same.
5608 str))
5609 'same
5614 "Check if filtered items file is up to date and a show suitable message."
5615 ;; (catch 'old
5625 ;; (throw 'old (message "The marked item is not up to date.")))
5630 "not up to date."
5631 ;; "\nType <return> on item for details."
5632 )))))
5635 "Return absolute file name for saving this Filtered Items buffer."
5653 "Save current Filtered Items buffer to a file.
5654 If the file already exists, overwrite it only on confirmation."
5658 ;; -----------------------------------------------------------------------------
5659 ;;; Customization groups and set functions
5660 ;; -----------------------------------------------------------------------------
5663 "Create and maintain categorized lists of todo items."
5669 "User options for adding and editing todo items."
5674 "User options for Todos Categories mode."
5679 "User options for Todos Filter Items mode."
5684 "User display options for Todos mode."
5689 "Faces for the Todos modes."
5694 "The :set function for user option `todos-show-current-file'."
5701 "The :set function for `todos-prefix' and `todos-number-prefix'."
5708 ;; Activate the new setting in the current category.
5712 "The :set function for user option `todos-nondiary-marker'."
5716 ;; Need to reset these to get font-locking right.
5719 todos-date-string-start
5720 ;; See comment in defvar of `todos-date-string-start'.
5736 nil t)
5744 "The :set function for `todos-done-separator-string'."
5759 "The :set function for user option `todos-done-string'."
5763 ;; Need to reset this to get font-locking right.
5776 nil t)
5782 "The :set function for user option `todos-comment-string'."
5797 nil t)
5803 "The :set function for `todos-toggle-item-highlighting'."
5817 ;; -----------------------------------------------------------------------------
5818 ;;; Font locking
5819 ;; -----------------------------------------------------------------------------
5822 "Search for Todos date string within LIM for font-locking."
5827 "Search for Todos time string within LIM for font-locking."
5832 "Search for Todos nondiary markers within LIM for font-locking."
5836 lim t))
5839 "Search for diary nonmarking symbol within LIM for font-locking."
5844 "Search for expired diary item date within LIM for font-locking."
5851 ;; Function days-between requires a non-empty time string.
5858 "Search for Todos done header within LIM for font-locking."
5861 lim t))
5864 "Search for Todos done comment within LIM for font-locking."
5866 lim t))
5869 "Search for Todos category name within LIM for font-locking.
5870 This is for fontifying category and file names appearing in Todos
5871 Filtered Items mode following done items."
5875 ;; Use non-greedy operator to prevent
5876 ;; capturing possible following non-diary
5877 ;; date string.
5879 lim t)))
5882 "Search for Todos category name within LIM for font-locking.
5883 This is for fontifying category and file names appearing in Todos
5884 Filtered Items mode following todo (not done) items."
5890 lim t)))
5905 ;; diary-lib.el uses font-lock-constant-face for diary-nonmarking-symbol.
5915 )
5918 ;; -----------------------------------------------------------------------------
5919 ;;; Key maps and menus
5920 ;; -----------------------------------------------------------------------------
5926 map)
5930 `(
5974 )
5978 `(
5999 )
6003 `(
6008 )
6012 `(
6016 )
6021 ;; Don't suppress digit keys, so they can supply prefix arguments.
6031 map)
6043 map)
6050 map)
6067 (define-key map [backtab] 'todos-previous-button)
6068 (define-key map "q" 'todos-quit)
6069 map)
6070 "Todos Categories mode keymap.")
6072 (defvar todos-filtered-items-mode-map
6073 (let ((map (make-sparse-keymap)))
6074 (suppress-keymap map)
6075 (dolist (kb todos-key-bindings-t+a+f)
6076 (define-key map (nth 0 kb) (nth 1 kb)))
6077 (dolist (kb todos-key-bindings-t+f)
6078 (define-key map (nth 0 kb) (nth 1 kb)))
6079 (define-key map "g" 'todos-go-to-source-item)
6080 (define-key map [remap newline] 'todos-go-to-source-item)
6081 map)
6082 "Todos Filtered Items mode keymap.")
6084 ;; (easy-menu-define
6085 ;; todos-menu todos-mode-map "Todos Menu"
6086 ;; '("Todos"
6087 ;; ("Navigation"
6088 ;; ["Next Item" todos-forward-item t]
6089 ;; ["Previous Item" todos-backward-item t]
6090 ;; "---"
6091 ;; ["Next Category" todos-forward-category t]
6092 ;; ["Previous Category" todos-backward-category t]
6093 ;; ["Jump to Category" todos-jump-to-category t]
6094 ;; "---"
6095 ;; ["Search Todos File" todos-search t]
6096 ;; ["Clear Highlighting on Search Matches" todos-category-done t])
6097 ;; ("Display"
6098 ;; ["List Current Categories" todos-show-categories-table t]
6099 ;; ;; ["List Categories Alphabetically" todos-display-categories-alphabetically t]
6100 ;; ["Turn Item Highlighting on/off" todos-toggle-item-highlighting t]
6101 ;; ["Turn Item Numbering on/off" todos-toggle-prefix-numbers t]
6102 ;; ["Turn Item Time Stamp on/off" todos-toggle-item-header t]
6103 ;; ["View/Hide Done Items" todos-toggle-view-done-items t]
6104 ;; "---"
6105 ;; ["View Diary Items" todos-filter-diary-items t]
6106 ;; ["View Top Priority Items" todos-filter-top-priorities t]
6107 ;; ["View Multifile Top Priority Items" todos-filter-top-priorities-multifile t]
6108 ;; "---"
6109 ;; ["Print Category" todos-print-buffer t])
6110 ;; ("Editing"
6111 ;; ["Insert New Item" todos-insert-item t]
6112 ;; ["Insert Item Here" todos-insert-item-here t]
6113 ;; ("More Insertion Commands")
6114 ;; ["Edit Item" todos-edit-item t]
6115 ;; ["Edit Multiline Item" todos-edit-multiline-item t]
6116 ;; ["Edit Item Header" todos-edit-item-header t]
6117 ;; ["Edit Item Date" todos-edit-item-date t]
6118 ;; ["Edit Item Time" todos-edit-item-time t]
6119 ;; "---"
6120 ;; ["Lower Item Priority" todos-lower-item-priority t]
6121 ;; ["Raise Item Priority" todos-raise-item-priority t]
6122 ;; ["Set Item Priority" todos-set-item-priority t]
6123 ;; ["Move (Recategorize) Item" todos-move-item t]
6124 ;; ["Delete Item" todos-delete-item t]
6125 ;; ["Undo Done Item" todos-item-undone t]
6126 ;; ["Mark/Unmark Item for Diary" todos-toggle-item-diary-inclusion t]
6127 ;; ["Mark/Unmark Items for Diary" todos-edit-item-diary-inclusion t]
6128 ;; ["Mark & Hide Done Item" todos-item-done t]
6129 ;; ["Archive Done Items" todos-archive-category-done-items t]
6130 ;; "---"
6131 ;; ["Add New Todos File" todos-add-file t]
6132 ;; ["Add New Category" todos-add-category t]
6133 ;; ["Delete Current Category" todos-delete-category t]
6134 ;; ["Rename Current Category" todos-rename-category t]
6135 ;; "---"
6136 ;; ["Save Todos File" todos-save t]
6137 ;; )
6138 ;; "---"
6139 ;; ["Quit" todos-quit t]
6140 ;; ))
6142 ;; -----------------------------------------------------------------------------
6143 ;;; Mode local variables and hook functions
6144 ;; -----------------------------------------------------------------------------
6146 (defvar todos-current-todos-file nil
6147 "Variable holding the name of the currently active Todos file.")
6149 (defun todos-show-current-file ()
6150 "Visit current instead of default Todos file with `todos-show'.
6151 This function is added to `pre-command-hook' when user option
6152 `todos-show-current-file' is set to non-nil."
6153 (setq todos-global-current-todos-file todos-current-todos-file))
6155 (defun todos-display-as-todos-file ()
6156 "Show Todos files correctly when visited from outside of Todos mode."
6157 (and (member this-command todos-visit-files-commands)
6158 (= (- (point-max) (point-min)) (buffer-size))
6159 (member major-mode '(todos-mode todos-archive-mode))
6160 (todos-category-select)))
6162 (defun todos-add-to-buffer-list ()
6163 "Add name of just visited Todos file to `todos-file-buffers'.
6164 This function is added to `find-file-hook' in Todos mode."
6165 (let ((filename (file-truename (buffer-file-name))))
6166 (when (member filename todos-files)
6167 (add-to-list 'todos-file-buffers filename))))
6169 (defun todos-update-buffer-list ()
6170 "Make current Todos mode buffer file car of `todos-file-buffers'.
6171 This function is added to `post-command-hook' in Todos mode."
6172 (let ((filename (file-truename (buffer-file-name))))
6173 (unless (eq (car todos-file-buffers) filename)
6174 (setq todos-file-buffers
6175 (cons filename (delete filename todos-file-buffers))))))
6177 (defun todos-reset-global-current-todos-file ()
6178 "Update the value of `todos-global-current-todos-file'.
6179 This becomes the latest existing Todos file or, if there is none,
6180 the value of `todos-default-todos-file'.
6181 This function is added to `kill-buffer-hook' in Todos mode."
6182 (let ((filename (file-truename (buffer-file-name))))
6183 (setq todos-file-buffers (delete filename todos-file-buffers))
6184 (setq todos-global-current-todos-file
6185 (or (car todos-file-buffers)
6186 (todos-absolute-file-name todos-default-todos-file)))))
6188 (defvar todos-categories nil
6189 "Alist of categories in the current Todos file.
6190 The elements are cons cells whose car is a category name and
6191 whose cdr is a vector of the category's item counts. These are,
6192 in order, the numbers of todo items, of todo items included in
6193 the Diary, of done items and of archived items.")
6195 (defvar todos-categories-with-marks nil
6196 "Alist of categories and number of marked items they contain.")
6198 (defvar todos-category-number 1
6199 "Variable holding the number of the current Todos category.
6200 Todos categories are numbered starting from 1.")
6202 (defvar todos-show-done-only nil
6203 "If non-nil display only done items in current category.
6204 Set by the command `todos-toggle-view-done-only' and used by
6205 `todos-category-select'.")
6207 (defun todos-reset-and-enable-done-separator ()
6208 "Show resized done items separator overlay after window change.
6209 Added to `window-configuration-change-hook' in `todos-mode'."
6210 (when (= 1 (length todos-done-separator-string))
6211 (let ((sep todos-done-separator))
6212 (setq todos-done-separator (todos-done-separator))
6213 (save-match-data (todos-reset-done-separator sep)))))
6215 ;; -----------------------------------------------------------------------------
6216 ;;; Mode definitions
6217 ;; -----------------------------------------------------------------------------
6219 (defun todos-modes-set-1 ()
6220 ""
6221 (setq-local font-lock-defaults '(todos-font-lock-keywords t))
6222 (setq-local tab-width todos-indent-to-here)
6223 (setq-local indent-line-function 'todos-indent)
6224 (when todos-wrap-lines
6225 (visual-line-mode)
6226 (setq wrap-prefix (make-string todos-indent-to-here 32))))
6228 (defun todos-modes-set-2 ()
6229 ""
6230 (add-to-invisibility-spec 'todos)
6231 (setq buffer-read-only t)
6232 (setq-local hl-line-range-function (lambda() (save-excursion
6233 (when (todos-item-end)
6234 (cons (todos-item-start)
6235 (todos-item-end)))))))
6237 (defun todos-modes-set-3 ()
6238 ""
6239 (setq-local todos-categories (todos-set-categories))
6240 (setq-local todos-category-number 1)
6241 (add-hook 'find-file-hook 'todos-display-as-todos-file nil t))
6243 (put 'todos-mode 'mode-class 'special)
6245 (define-derived-mode todos-mode special-mode "Todos"
6246 "Major mode for displaying, navigating and editing Todo lists.
6249 ;; (easy-menu-add todos-menu)
6250 (todos-modes-set-1)
6251 (todos-modes-set-2)
6252 (todos-modes-set-3)
6253 ;; Initialize todos-current-todos-file.
6254 (when (member (file-truename (buffer-file-name))
6255 (funcall todos-files-function))
6256 (setq-local todos-current-todos-file (file-truename (buffer-file-name))))
6257 (setq-local todos-show-done-only nil)
6258 (setq-local todos-categories-with-marks nil)
6259 (add-hook 'find-file-hook 'todos-add-to-buffer-list nil t)
6260 (add-hook 'post-command-hook 'todos-update-buffer-list nil t)
6261 (when todos-show-current-file
6262 (add-hook 'pre-command-hook 'todos-show-current-file nil t))
6263 (add-hook 'window-configuration-change-hook
6264 'todos-reset-and-enable-done-separator nil t)
6265 (add-hook 'kill-buffer-hook 'todos-reset-global-current-todos-file nil t))
6267 (put 'todos-archive-mode 'mode-class 'special)
6269 ;; If todos-mode is parent, all todos-mode key bindings appear to be
6270 ;; available in todos-archive-mode (e.g. shown by C-h m).
6271 (define-derived-mode todos-archive-mode special-mode "Todos-Arch"
6272 "Major mode for archived Todos categories.
6275 (todos-modes-set-1)
6276 (todos-modes-set-2)
6277 (todos-modes-set-3)
6278 (setq-local todos-current-todos-file (file-truename (buffer-file-name)))
6279 (setq-local todos-show-done-only t))
6281 (defun todos-mode-external-set ()
6282 ""
6283 (setq-local todos-current-todos-file todos-global-current-todos-file)
6284 (let ((cats (with-current-buffer
6285 ;; Can't use find-buffer-visiting when
6286 ;; `todos-show-categories-table' is called on first
6287 ;; invocation of `todos-show', since there is then
6288 ;; no buffer visiting the current file.
6289 (find-file-noselect todos-current-todos-file 'nowarn)
6290 (or todos-categories
6291 ;; In Todos Edit mode todos-categories is now nil
6292 ;; since it uses same buffer as Todos mode but
6293 ;; doesn't have the latter's local variables.
6294 (save-excursion
6295 (goto-char (point-min))
6296 (read (buffer-substring-no-properties
6297 (line-beginning-position)
6298 (line-end-position))))))))
6299 (setq-local todos-categories cats)))
6301 (define-derived-mode todos-edit-mode text-mode "Todos-Ed"
6302 "Major mode for editing multiline Todo items.
6305 (todos-modes-set-1)
6306 (todos-mode-external-set)
6307 (setq buffer-read-only nil))
6309 (put 'todos-categories-mode 'mode-class 'special)
6311 (define-derived-mode todos-categories-mode special-mode "Todos-Cats"
6312 "Major mode for displaying and editing Todos categories.
6315 (todos-mode-external-set))
6317 (put 'todos-filtered-items-mode 'mode-class 'special)
6319 (define-derived-mode todos-filtered-items-mode special-mode "Todos-Fltr"
6320 "Mode for displaying and reprioritizing top priority Todos.
6323 (todos-modes-set-1)
6324 (todos-modes-set-2))
6330 ;; -----------------------------------------------------------------------------
6331 (provide 'todos)
6333 ;;; todos.el ends here
6335 ;;; necessitated adaptations to diary-lib.el
6337 (defun diary-goto-entry (button)
6338 "Jump to the diary entry for the BUTTON at point."
6339 (let* ((locator (button-get button 'locator))
6340 (marker (car locator))
6341 markbuf file opoint)
6342 ;; If marker pointing to diary location is valid, use that.
6343 (if (and marker (setq markbuf (marker-buffer marker)))
6344 (progn
6345 (pop-to-buffer markbuf)
6346 (when (eq major-mode 'todos-mode) (widen))
6347 (goto-char (marker-position marker))
6348 (when (eq major-mode 'todos-mode)
6349 (re-search-backward (concat "^" (regexp-quote todos-category-beg)
6351 (todos-category-number (match-string 1))
6352 (todos-category-select)
6353 (goto-char (marker-position marker))))
6354 ;; Marker is invalid (eg buffer has been killed).
6355 (or (and (setq file (cadr locator))
6356 (file-exists-p file)
6357 (find-file-other-window file)
6358 (progn
6359 (when (eq major-mode (default-value 'major-mode)) (diary-mode))
6360 (when (eq major-mode 'todos-mode) (widen))
6361 (goto-char (point-min))
6363 (regexp-quote (nth 2 locator))
6364 (regexp-quote (nth 3 locator)))
6365 nil t)
6366 (goto-char (match-beginning 1))
6367 (when (eq major-mode 'todos-mode)
6368 (setq opoint (point))
6369 (re-search-backward (concat "^"
6370 (regexp-quote todos-category-beg)
6372 nil t)
6373 (todos-category-number (match-string 1))
6374 (todos-category-select)
6375 (goto-char opoint)))))
6376 (message "Unable to locate this diary entry")))))