]> code.delx.au - gnu-emacs/blob - lisp/textmodes/remember.el
ceecbd9ba37b7d8047794ffe10b8478abb8aca86
[gnu-emacs] / lisp / textmodes / remember.el
1 ;;; remember --- a mode for quickly jotting down things to remember
2
3 ;; Copyright (C) 1999-2001, 2003-2014 Free Software Foundation, Inc.
4
5 ;; Author: John Wiegley <johnw@gnu.org>
6 ;; Created: 29 Mar 1999
7 ;; Version: 2.0
8 ;; Keywords: data memory todo pim
9 ;; URL: http://gna.org/projects/remember-el/
10
11 ;; This file is part of GNU Emacs.
12
13 ;; GNU Emacs is free software: you can redistribute it and/or modify
14 ;; it under the terms of the GNU General Public License as published by
15 ;; the Free Software Foundation, either version 3 of the License, or
16 ;; (at your option) any later version.
17
18 ;; GNU Emacs is distributed in the hope that it will be useful,
19 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
20 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21 ;; GNU General Public License for more details.
22
23 ;; You should have received a copy of the GNU General Public License
24 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
25
26 ;;; Commentary:
27
28 ;; * The idea
29 ;;
30 ;; Todo lists, schedules, phone databases... everything we use
31 ;; databases for is really just a way to extend the power of our
32 ;; memory. To be able to remember what our conscious mind may not
33 ;; currently have access to.
34 ;;
35 ;; There are many different databases out there -- and good ones --
36 ;; which this mode is not trying to replace. Rather, it's how that
37 ;; data gets there that's the question. Most of the time, we just
38 ;; want to say "Remember so-and-so's phone number, or that I have to
39 ;; buy dinner for the cats tonight." That's the FACT. How it's
40 ;; stored is really the computer's problem. But at this point in
41 ;; time, it's most definitely also the user's problem, and sometimes
42 ;; so laboriously so that people just let data slip, rather than
43 ;; expend the effort to record it.
44 ;;
45 ;; "Remember" is a mode for remembering data. It uses whatever
46 ;; back-end is appropriate to record and correlate the data, but it's
47 ;; main intention is to allow you to express as _little_ structure as
48 ;; possible up front. If you later want to express more powerful
49 ;; relationships between your data, or state assumptions that were at
50 ;; first too implicit to be recognized, you can "study" the data later
51 ;; and rearrange it. But the initial "just remember this" impulse
52 ;; should be as close to simply throwing the data at Emacs as
53 ;; possible.
54 ;;
55 ;; * Implementation
56 ;;
57 ;; Hyperbole, as a data presentation tool, always struck me as being
58 ;; very powerful, but it seemed to require a lot of "front-end" work
59 ;; before that data was really available. The problem with BBDB, or
60 ;; keeping up a Bibl-mode file, is that you have to use different
61 ;; functions to record the data, and it always takes time to stop what
62 ;; you're doing, format the data in the manner expected by that
63 ;; particular data interface, and then resume your work.
64 ;;
65 ;; With "remember", you just hit `M-x remember' (you'd probably want
66 ;; to bind this to an easily accessible keystroke, like C-x M-r), slam
67 ;; in your text however you like, and then hit C-c C-c. It will file
68 ;; the data away for later retrieval, and possibly indexing.
69 ;;
70 ;; Indexing is to data what "studying" is in the real world. What you
71 ;; do when you study (or lucubrate, for some of us) is to realize
72 ;; certain relationships implicit in the data, so that you can make
73 ;; use of those relationships. Expressing that a certain quote you
74 ;; remembered was a religious quote, and that you want the ability to
75 ;; pull up all quotes of a religious nature, is what studying does.
76 ;; This is a more labor intensive task than the original remembering
77 ;; of the data, and it's typical in real life to set aside a special
78 ;; period of time for doing this work.
79 ;;
80 ;; "Remember" works in the same way. When you enter data, either by
81 ;; typing it into a buffer, or using the contents of the selected
82 ;; region, it will store that data -- unindexed, uninterpreted -- in a
83 ;; data pool. It will also try to remember as much context
84 ;; information as possible (any text properties that were set, where
85 ;; you copied it from, when, how, etc). Later, you can walk through
86 ;; your accumulated set of data (both organized, and unorganized) and
87 ;; easily begin moving things around, and making annotations that will
88 ;; express the full meaning of that data, as far as you know it.
89 ;;
90 ;; Obviously this latter stage is more user-interface intensive, and
91 ;; it would be nice if "remember" could do it as elegantly as
92 ;; possible, rather than requiring a billion keystrokes to reorganize
93 ;; your hierarchy. Well, as the future arrives, hopefully experience
94 ;; and user feedback will help to make this as intuitive a tool as
95 ;; possible.
96 ;;
97 ;; * Future Goals
98 ;;
99 ;; This tool hopes to track (and by doing it with as little new code
100 ;; as possible):
101 ;;
102 ;; - The raw data that gets entered
103 ;;
104 ;; - The relationships between that data (either determined
105 ;; implicitly by parsing the input, or explicitly by the user's
106 ;; studying the data).
107 ;;
108 ;; - Revisioning of the data
109 ;;
110 ;; - Where it came from, and any context information that can be
111 ;; programmatically determined.
112 ;;
113 ;; - Allowing particular views of the initially amorphous data pool
114 ;; (ala the Xanadu concept).
115 ;;
116 ;; - Storage of the data in a manner most appropriate to that data,
117 ;; such as keeping address-book type information in BBDB, etc.
118 ;;
119 ;; * Using "remember"
120 ;;
121 ;; As a rough beginning, what I do is to keep my .notes file in
122 ;; outline-mode format, with a final entry called "* Raw data". Then,
123 ;; at intervals, I can move the data that gets appended there into
124 ;; other places. But certainly this should evolve into an intuitive
125 ;; mechanism for shuffling data off to its appropriate corner of the
126 ;; universe.
127 ;;
128 ;; To map the primary remember function to the keystroke F8, do the
129 ;; following.
130 ;;
131 ;; (autoload 'remember "remember" nil t)
132 ;;
133 ;; (define-key global-map [f8] 'remember)
134 ;;
135 ;; * Feedback
136 ;;
137 ;; If Emacs could become a more intelligent data store, where
138 ;; brainstorming would focus on the IDEAS involved -- rather than the
139 ;; structuring and format of those ideas, or having to stop your
140 ;; current flow of work in order to record them -- it would map much
141 ;; more closely to how the mind (well, at least mine) works, and hence
142 ;; would eliminate that very manual-ness which computers from the very
143 ;; beginning have been championed as being able to reduce.
144 ;;
145 ;; Have you ever noticed that having a laptop to write on doesn't
146 ;; _actually_ increase the amount of quality material that you turn
147 ;; out, in the long run? Perhaps its because the time we save
148 ;; electronically in one way, we're losing electronically in another;
149 ;; the tool should never dominate one's focus. As the mystic
150 ;; Faridu'd-Din `Attar wrote: "Be occupied as little as possible with
151 ;; things of the outer world but much with things of the inner world;
152 ;; then right action will overcome inaction."
153 ;;
154 ;; * Diary integration
155 ;;
156 ;; To use, add the following to your .emacs:
157 ;;
158 ;; ;; This should be before other entries that may return t
159 ;; (add-to-list 'remember-handler-functions 'remember-diary-extract-entries)
160 ;;
161 ;; This module recognizes entries of the form
162 ;;
163 ;; DIARY: ....
164 ;;
165 ;; and puts them in your ~/.diary (or remember-diary-file) together
166 ;; with an annotation. Dates in the form YYYY.MM.DD are converted to
167 ;; YYYY-MM-DD so that diary can understand them.
168 ;;
169 ;; For example:
170 ;;
171 ;; DIARY: 2003.08.12 Sacha's birthday
172 ;;
173 ;; is stored as
174 ;;
175 ;; 2003.08.12 Sacha's birthday
176
177 ;;; History:
178
179 ;;; Code:
180
181 (provide 'remember)
182
183 (defconst remember-version "2.0"
184 "This version of remember.")
185
186 (defgroup remember nil
187 "A mode to remember information."
188 :group 'data)
189
190 ;;; User Variables:
191
192 (defcustom remember-mode-hook nil
193 "Functions run upon entering `remember-mode'."
194 :type 'hook
195 :options '(flyspell-mode turn-on-auto-fill org-remember-apply-template)
196 :group 'remember)
197
198 (defcustom remember-in-new-frame nil
199 "Non-nil means use a separate frame for capturing remember data."
200 :type 'boolean
201 :group 'remember)
202
203 (defcustom remember-register ?R
204 "The register in which the window configuration is stored."
205 :type 'character
206 :group 'remember)
207
208 (defcustom remember-filter-functions nil
209 "Functions run to filter remember data.
210 All functions are run in the remember buffer."
211 :type 'hook
212 :group 'remember)
213
214 (defcustom remember-handler-functions '(remember-append-to-file)
215 "Functions run to process remember data.
216 Each function is called with the current buffer narrowed to what the
217 user wants remembered.
218 If any function returns non-nil, the data is assumed to have been
219 recorded somewhere by that function."
220 :type 'hook
221 :options '(remember-store-in-mailbox
222 remember-append-to-file
223 remember-store-in-files
224 remember-diary-extract-entries
225 org-remember-handler)
226 :group 'remember)
227
228 (defcustom remember-all-handler-functions nil
229 "If non-nil every function in `remember-handler-functions' is called."
230 :type 'boolean
231 :group 'remember)
232
233 ;;; Internal Variables:
234
235 (defvar remember-buffer "*Remember*"
236 "The name of the remember data entry buffer.")
237
238 (defcustom remember-save-after-remembering t
239 "Non-nil means automatically save after remembering."
240 :type 'boolean
241 :group 'remember)
242
243 ;;; User Functions:
244
245 (defcustom remember-annotation-functions '(buffer-file-name)
246 "Hook that returns an annotation to be inserted into the remember buffer."
247 :type 'hook
248 :options '(org-remember-annotation buffer-file-name)
249 :group 'remember)
250
251 (defvar remember-annotation nil
252 "Current annotation.")
253 (defvar remember-initial-contents nil
254 "Initial contents to place into *Remember* buffer.")
255
256 (defcustom remember-before-remember-hook nil
257 "Functions run before switching to the *Remember* buffer."
258 :type 'hook
259 :group 'remember)
260
261 (defcustom remember-run-all-annotation-functions-flag nil
262 "Non-nil means use all annotations returned by `remember-annotation-functions'."
263 :type 'boolean
264 :group 'remember)
265
266 ;;;###autoload
267 (defun remember (&optional initial)
268 "Remember an arbitrary piece of data.
269 INITIAL is the text to initially place in the *Remember* buffer,
270 or nil to bring up a blank *Remember* buffer.
271
272 With a prefix or a visible region, use the region as INITIAL."
273 (interactive
274 (list (when (or current-prefix-arg
275 (and mark-active
276 transient-mark-mode))
277 (buffer-substring (region-beginning) (region-end)))))
278 (funcall (if remember-in-new-frame
279 #'frame-configuration-to-register
280 #'window-configuration-to-register) remember-register)
281 (let* ((annotation
282 (if remember-run-all-annotation-functions-flag
283 (mapconcat 'identity
284 (delq nil
285 (mapcar 'funcall remember-annotation-functions))
286 "\n")
287 (run-hook-with-args-until-success
288 'remember-annotation-functions)))
289 (buf (get-buffer-create remember-buffer)))
290 (run-hooks 'remember-before-remember-hook)
291 (funcall (if remember-in-new-frame
292 #'switch-to-buffer-other-frame
293 #'switch-to-buffer-other-window) buf)
294 (if remember-in-new-frame
295 (set-window-dedicated-p
296 (get-buffer-window (current-buffer) (selected-frame)) t))
297 (setq buffer-offer-save t)
298 (remember-mode)
299 (when (= (point-max) (point-min))
300 (when initial (insert initial))
301 (setq remember-annotation annotation)
302 (when remember-initial-contents (insert remember-initial-contents))
303 (when (and (stringp annotation)
304 (not (equal annotation "")))
305 (insert "\n\n" annotation))
306 (setq remember-initial-contents nil)
307 (goto-char (point-min)))
308 (message "Use C-c C-c to remember the data.")))
309
310 ;;;###autoload
311 (defun remember-other-frame (&optional initial)
312 "Call `remember' in another frame."
313 (interactive
314 (list (when current-prefix-arg
315 (buffer-substring (point) (mark)))))
316 (let ((remember-in-new-frame t))
317 (remember initial)))
318
319 (defsubst remember-mail-date (&optional rfc822-p)
320 "Return a simple date. Nothing fancy."
321 (if rfc822-p
322 (format-time-string "%a, %e %b %Y %T %z" (current-time))
323 (format-time-string "%a %b %e %T %Y" (current-time))))
324
325 (defun remember-buffer-desc ()
326 "Using the first line of the current buffer, create a short description."
327 (buffer-substring (point-min)
328 (save-excursion
329 (goto-char (point-min))
330 (end-of-line)
331 (if (> (- (point) (point-min)) 60)
332 (goto-char (+ (point-min) 60)))
333 (point))))
334
335 ;; Remembering to UNIX mailboxes
336
337 (defcustom remember-mailbox "~/Mail/remember"
338 "The file in which to store remember data as mail."
339 :type 'file
340 :group 'remember)
341
342 (defcustom remember-default-priority "medium"
343 "The default priority for remembered mail messages."
344 :type 'string
345 :group 'remember)
346
347 (defun remember-store-in-mailbox ()
348 "Store remember data as if it were incoming mail.
349 In which case `remember-mailbox' should be the name of the mailbox.
350 Each piece of pseudo-mail created will have an `X-Todo-Priority'
351 field, for the purpose of appropriate splitting."
352 (let ((who (read-string "Who is this item related to? "))
353 (moment (format "%.0f" (float-time)))
354 (desc (remember-buffer-desc))
355 (text (buffer-string)))
356 (with-temp-buffer
357 (insert (format "From %s %s
358 Date: %s
359 From: %s
360 Message-Id: <remember-%s@%s>
361 X-Todo-Priority: %s
362 To: %s <%s>
363 Subject: %s\n\n"
364 (user-login-name)
365 (remember-mail-date)
366 (remember-mail-date t)
367 who
368 moment (system-name)
369 remember-default-priority
370 (user-full-name) user-mail-address
371 desc))
372 (let ((here (point)))
373 (insert text)
374 (unless (bolp)
375 (insert "\n"))
376 (insert "\n")
377 (goto-char here)
378 (while (re-search-forward "^\\(From[: ]\\)" nil t)
379 (replace-match ">\\1")))
380 (append-to-file (point-min) (point-max) remember-mailbox)
381 t)))
382
383 ;; Remembering to plain files
384
385 (defcustom remember-data-file (locate-user-emacs-file "notes" ".notes")
386 "The file in which to store unprocessed data.
387 When set via customize, visited file of the notes buffer (if it
388 exists) might be changed."
389 :type 'file
390 :set (lambda (symbol value)
391 (let ((buf (find-buffer-visiting (default-value symbol))))
392 (set-default symbol value)
393 (when (buffer-live-p buf)
394 (with-current-buffer buf
395 (set-visited-file-name
396 (expand-file-name remember-data-file))))))
397 :initialize 'custom-initialize-default
398 :group 'remember)
399
400 (defcustom remember-leader-text "** "
401 "The text used to begin each remember item."
402 :type 'string
403 :group 'remember)
404
405 (defun remember-append-to-file ()
406 "Remember, with description DESC, the given TEXT."
407 (let* ((text (buffer-string))
408 (desc (remember-buffer-desc))
409 (remember-text (concat "\n" remember-leader-text (current-time-string)
410 " (" desc ")\n\n" text
411 (save-excursion (goto-char (point-max))
412 (if (bolp) nil "\n"))))
413 (buf (find-buffer-visiting remember-data-file)))
414 (if buf
415 (with-current-buffer buf
416 (save-excursion
417 (goto-char (point-max))
418 (insert remember-text))
419 (if remember-save-after-remembering (save-buffer)))
420 (append-to-file remember-text nil remember-data-file))))
421
422 (defun remember-region (&optional beg end)
423 "Remember the data from BEG to END.
424 It is called from within the *Remember* buffer to save the text
425 that was entered.
426
427 If BEG and END are nil, the entire buffer will be remembered.
428
429 If you want to remember a region, supply a universal prefix to
430 `remember' instead. For example: \\[universal-argument] \\[remember] RET."
431 ;; Sacha: I have no idea where remember.el gets this context information, but
432 ;; you can just use remember-annotation-functions.
433 (interactive)
434 (let ((b (or beg (min (point) (or (mark) (point-min)))))
435 (e (or end (max (point) (or (mark) (point-max))))))
436 (save-restriction
437 (narrow-to-region b e)
438 (if remember-all-handler-functions
439 (run-hooks 'remember-handler-functions)
440 (run-hook-with-args-until-success 'remember-handler-functions))
441 (remember-destroy))))
442
443 (defcustom remember-data-directory "~/remember"
444 "The directory in which to store remember data as files."
445 :type 'directory
446 :version "24.4"
447 :group 'remember)
448
449 (defcustom remember-directory-file-name-format "%Y-%m-%d_%T-%z"
450 "Format string for the file name in which to store unprocessed data."
451 :type 'string
452 :version "24.4"
453 :group 'remember)
454
455 (defun remember-store-in-files ()
456 "Store remember data in a file in `remember-data-directory'.
457 The file is named after `remember-directory-file-name-format' fed through
458 `format-time-string'."
459 (let ((name (format-time-string
460 remember-directory-file-name-format (current-time)))
461 (text (buffer-string)))
462 (with-temp-buffer
463 (insert text)
464 (write-file (convert-standard-filename
465 (format "%s/%s" remember-data-directory name))))))
466
467 ;;;###autoload
468 (defun remember-clipboard ()
469 "Remember the contents of the current clipboard.
470 Most useful for remembering things from other applications."
471 (interactive)
472 (remember (current-kill 0)))
473
474 (defun remember-finalize ()
475 "Remember the contents of the current buffer."
476 (interactive)
477 (remember-region (point-min) (point-max)))
478
479 ;; Org needs this
480 (define-obsolete-function-alias 'remember-buffer 'remember-finalize "23.1")
481
482 (defun remember-destroy ()
483 "Destroy the current *Remember* buffer."
484 (interactive)
485 (when (equal remember-buffer (buffer-name))
486 (kill-buffer (current-buffer))
487 (jump-to-register remember-register)))
488
489 ;;; Diary integration
490
491 (defcustom remember-diary-file nil
492 "File for extracted diary entries.
493 If this is nil, then `diary-file' will be used instead."
494 :type '(choice (const :tag "diary-file" nil) file)
495 :group 'remember)
496
497 (defun remember-diary-convert-entry (entry)
498 "Translate MSG to an entry readable by diary."
499 (save-match-data
500 (when remember-annotation
501 (setq entry (concat entry " " remember-annotation)))
502 (if (string-match "\\([0-9]+\\)\\.\\([0-9]+\\)\\.\\([0-9]+\\)" entry)
503 (progn
504 ;; For calendar-date-style. This costs us nothing because
505 ;; the call to diary-make-entry below loads diary-lib
506 ;; which requires calendar.
507 (require 'calendar)
508 (replace-match
509 (let ((style (if (boundp 'calendar-date-style)
510 calendar-date-style
511 ;; Don't complain about obsolescence.
512 (if (with-no-warnings european-calendar-style)
513 'european
514 'american))))
515 (cond ((eq style 'european)
516 (concat (match-string 3 entry) "/"
517 (match-string 2 entry) "/"
518 (match-string 1 entry)))
519 ((eq style 'iso)
520 (concat (match-string 1 entry) "-"
521 (match-string 2 entry) "-"
522 (match-string 3 entry)))
523 (t (concat (match-string 2 entry) "/"
524 (match-string 3 entry) "/"
525 (match-string 1 entry)))))
526 t t entry))
527 entry)))
528
529 (autoload 'diary-make-entry "diary-lib")
530
531 ;;;###autoload
532 (defun remember-diary-extract-entries ()
533 "Extract diary entries from the region."
534 (save-excursion
535 (goto-char (point-min))
536 (let (list)
537 (while (re-search-forward "^DIARY:\\s-*\\(.+\\)" nil t)
538 (push (remember-diary-convert-entry (match-string 1)) list))
539 (when list
540 (diary-make-entry (mapconcat 'identity list "\n")
541 nil remember-diary-file))
542 nil))) ;; Continue processing
543
544 ;;; Internal Functions:
545
546 (defvar remember-mode-map
547 (let ((map (make-sparse-keymap)))
548 (define-key map "\C-x\C-s" 'remember-finalize)
549 (define-key map "\C-c\C-c" 'remember-finalize)
550 (define-key map "\C-c\C-k" 'remember-destroy)
551 map)
552 "Keymap used in Remember mode.")
553
554 (define-derived-mode remember-mode indented-text-mode "Remember"
555 "Major mode for output from \\[remember].
556 This buffer is used to collect data that you want to remember.
557 \\<remember-mode-map>
558 Just hit \\[remember-finalize] when you're done entering, and it will file
559 the data away for latter retrieval, and possible indexing.
560
561 \\{remember-mode-map}"
562 (set-keymap-parent remember-mode-map nil))
563
564 ;; Notes buffer showing the notes:
565
566 (defcustom remember-notes-buffer-name "*notes*"
567 "Name of the notes buffer.
568 Setting it to *scratch* will hijack the *scratch* buffer for the
569 purpose of storing notes."
570 :type 'string
571 :version "24.4")
572
573 (defcustom remember-notes-initial-major-mode nil
574 "Major mode to set to notes buffer when it's created.
575 If set to nil will use the same mode as `initial-major-mode'."
576 :type '(choice (const :tag "Same as `initial-major-mode'" nil)
577 (function :tag "Major mode" text-mode))
578 :version "24.4")
579
580 (defcustom remember-notes-bury-on-kill t
581 "Whether to bury notes buffer instead of killing."
582 :type 'boolean
583 :version "24.4")
584
585 (defun remember-notes-save-and-bury-buffer ()
586 "Saves and buries current buffer.
587 Buffer is saved only if `buffer-modified-p' returns non-nil."
588 (interactive)
589 (when (buffer-modified-p)
590 (save-buffer))
591 (bury-buffer))
592
593
594
595 (defvar remember-notes-mode-map
596 (let ((map (make-sparse-keymap)))
597 (define-key map "\C-c\C-c" 'remember-notes-save-and-bury-buffer)
598 map)
599 "Keymap used in remember-notes mode.")
600
601 (define-minor-mode remember-notes-mode
602 "Minor mode for the `remember-notes' buffer."
603 nil nil nil
604 (cond
605 (remember-notes-mode
606 (add-hook 'kill-buffer-query-functions
607 #'remember-notes--kill-buffer-query nil t)
608 (setq buffer-save-without-query t))))
609
610 ;;;###autoload
611 (defun remember-notes (&optional switch-to)
612 "Creates notes buffer and switches to it if called interactively.
613
614 If a notes buffer created by a previous invocation of this
615 function already exist, it will be returned. Otherwise a new
616 buffer will be created whose content will be read from file
617 pointed by `remember-data-file'. If a buffer visiting this file
618 already exist, that buffer will be used instead of creating a new
619 one (see `find-file-noselect' function for more details).
620
621 Name of the created buffer is taken from `remember-notes-buffer-name'
622 variable and if a buffer with that name already exist (but was not
623 created by this function), it will be first killed.
624 \\<remember-notes-mode-map>
625 `remember-notes-mode' is active in the notes buffer which by default
626 contains only one \\[save-and-bury-buffer] binding which saves and
627 buries the buffer.
628
629 Function returns notes buffer. When called interactively,
630 switches to it as well.
631
632 Notes buffer is meant for keeping random notes which you'd like to
633 preserve across Emacs restarts. The notes will be stored in the
634 `remember-data-file'."
635 (interactive "p")
636 (let ((buf (or (find-buffer-visiting remember-data-file)
637 (with-current-buffer (find-file-noselect remember-data-file)
638 (and remember-notes-buffer-name
639 (not (get-buffer remember-notes-buffer-name))
640 (rename-buffer remember-notes-buffer-name))
641 (funcall (or remember-notes-initial-major-mode
642 initial-major-mode))
643 (remember-notes-mode 1)
644 (current-buffer)))))
645 (when switch-to
646 (switch-to-buffer buf))
647 buf))
648
649 (defun remember-notes--kill-buffer-query ()
650 (when (buffer-modified-p)
651 (save-buffer))
652 (if remember-notes-bury-on-kill
653 (bury-buffer)
654 t))
655
656 ;;; remember.el ends here