Commit | Line | Data |
---|---|---|
20908596 CD |
1 | ;;; org-bbdb.el --- Support for links to BBDB entries from within Org-mode |
2 | ||
114f9c96 | 3 | ;; Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009, 2010 |
eb2ffb18 | 4 | ;; Free Software Foundation, Inc. |
20908596 CD |
5 | |
6 | ;; Author: Carsten Dominik <carsten at orgmode dot org>, | |
7 | ;; Thomas Baumann <thomas dot baumann at ch dot tum dot de> | |
8 | ;; Keywords: outlines, hypermedia, calendar, wp | |
9 | ;; Homepage: http://orgmode.org | |
ed21c5c8 | 10 | ;; Version: 6.35i |
20908596 CD |
11 | ;; |
12 | ;; This file is part of GNU Emacs. | |
13 | ;; | |
b1fc2b50 | 14 | ;; GNU Emacs is free software: you can redistribute it and/or modify |
20908596 | 15 | ;; it under the terms of the GNU General Public License as published by |
b1fc2b50 GM |
16 | ;; the Free Software Foundation, either version 3 of the License, or |
17 | ;; (at your option) any later version. | |
20908596 CD |
18 | |
19 | ;; GNU Emacs is distributed in the hope that it will be useful, | |
20 | ;; but WITHOUT ANY WARRANTY; without even the implied warranty of | |
21 | ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
22 | ;; GNU General Public License for more details. | |
23 | ||
24 | ;; You should have received a copy of the GNU General Public License | |
b1fc2b50 | 25 | ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>. |
20908596 CD |
26 | ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; |
27 | ;; | |
28 | ;;; Commentary: | |
29 | ||
30 | ;; This file implements links to BBDB database entries from within Org-mode. | |
31 | ;; Org-mode loads this module by default - if this is not what you want, | |
32 | ;; configure the variable `org-modules'. | |
33 | ||
20908596 CD |
34 | ;; It also implements an interface (based on Ivar Rummelhoff's |
35 | ;; bbdb-anniv.el) for those org-mode users, who do not use the diary | |
36 | ;; but who do want to include the anniversaries stored in the BBDB | |
37 | ;; into the org-agenda. If you already include the `diary' into the | |
38 | ;; agenda, you might want to prefer to include the anniversaries in | |
39 | ;; the diary using bbdb-anniv.el. | |
40 | ;; | |
41 | ;; Put the following in /somewhere/at/home/diary.org and make sure | |
42 | ;; that this file is in `org-agenda-files` | |
43 | ;; | |
44 | ;; %%(org-bbdb-anniversaries) | |
45 | ;; | |
46 | ;; For example my diary.org looks like: | |
47 | ;; * Anniversaries | |
48 | ;; #+CATEGORY: Anniv | |
49 | ;; %%(org-bbdb-anniversaries) | |
50 | ;; | |
51 | ;; | |
c8d0cf5c CD |
52 | ;; To add an anniversary to a BBDB record, press `C-o' in the record. |
53 | ;; You will be prompted for the field name, in this case it must be | |
54 | ;; "anniversary". If this is the first time you are using this field, | |
55 | ;; you need to confirm that it should be created. | |
20908596 | 56 | ;; |
c8d0cf5c CD |
57 | ;; The format of an anniversary field stored in BBDB is the following |
58 | ;; (items in {} are optional): | |
59 | ;; | |
60 | ;; YYYY-MM-DD{ CLASS-OR-FORMAT-STRING} | |
61 | ;; {\nYYYY-MM-DD CLASS-OR-FORMAT-STRING}... | |
20908596 CD |
62 | ;; |
63 | ;; CLASS-OR-FORMAT-STRING is one of two things: | |
64 | ;; | |
c8d0cf5c CD |
65 | ;; - an identifier for a class of anniversaries (eg. birthday or |
66 | ;; wedding) from `org-bbdb-anniversary-format-alist' which then | |
8bfe682a | 67 | ;; defines the format string for this class |
c8d0cf5c CD |
68 | ;; - the (format) string displayed in the diary. |
69 | ;; | |
70 | ;; You can enter multiple anniversaries for a single BBDB record by | |
71 | ;; separating them with a newline character. At the BBDB prompt for | |
72 | ;; the field value, type `C-q C-j' to enter a newline between two | |
73 | ;; anniversaries. | |
20908596 | 74 | ;; |
c8d0cf5c CD |
75 | ;; If you omit the CLASS-OR-FORMAT-STRING entirely, it defaults to the |
76 | ;; value of `org-bbdb-default-anniversary-format' ("birthday" by | |
77 | ;; default). | |
20908596 CD |
78 | ;; |
79 | ;; The substitutions in the format string are (in order): | |
c8d0cf5c CD |
80 | ;; - the name of the record containing this anniversary |
81 | ;; - the number of years | |
82 | ;; - an ordinal suffix (st, nd, rd, th) for the year | |
20908596 CD |
83 | ;; |
84 | ;; See the documentation of `org-bbdb-anniversary-format-alist' for | |
85 | ;; further options. | |
86 | ;; | |
87 | ;; Example | |
88 | ;; | |
89 | ;; 1973-06-22 | |
90 | ;; 20??-??-?? wedding | |
91 | ;; 1998-03-12 %s created bbdb-anniv.el %d years ago | |
b349f79f CD |
92 | ;; |
93 | ;; From Org's agenda, you can use `C-c C-o' to jump to the BBDB | |
94 | ;; link from which the entry at point originates. | |
95 | ;; | |
20908596 CD |
96 | ;;; Code: |
97 | ||
98 | (require 'org) | |
99 | (eval-when-compile | |
100 | (require 'cl)) | |
101 | ||
102 | ;; Declare external functions and variables | |
103 | ||
104 | (declare-function bbdb "ext:bbdb-com" (string elidep)) | |
105 | (declare-function bbdb-company "ext:bbdb-com" (string elidep)) | |
106 | (declare-function bbdb-current-record "ext:bbdb-com" | |
107 | (&optional planning-on-modifying)) | |
108 | (declare-function bbdb-name "ext:bbdb-com" (string elidep)) | |
c8d0cf5c CD |
109 | (declare-function bbdb-completing-read-record "ext:bbdb-com" |
110 | (prompt &optional omit-records)) | |
20908596 CD |
111 | (declare-function bbdb-record-getprop "ext:bbdb" (record property)) |
112 | (declare-function bbdb-record-name "ext:bbdb" (record)) | |
113 | (declare-function bbdb-records "ext:bbdb" | |
114 | (&optional dont-check-disk already-in-db-buffer)) | |
115 | (declare-function bbdb-split "ext:bbdb" (string separators)) | |
116 | (declare-function bbdb-string-trim "ext:bbdb" (string)) | |
c8d0cf5c | 117 | |
20908596 CD |
118 | (declare-function calendar-leap-year-p "calendar" (year)) |
119 | (declare-function diary-ordinal-suffix "diary-lib" (n)) | |
120 | ||
b349f79f | 121 | (defvar date) ;; dynamically scoped from Org |
20908596 CD |
122 | |
123 | ;; Customization | |
124 | ||
125 | (defgroup org-bbdb-anniversaries nil | |
126 | "Customizations for including anniversaries from BBDB into Agenda." | |
127 | :group 'org-bbdb) | |
128 | ||
129 | (defcustom org-bbdb-default-anniversary-format "birthday" | |
130 | "Default anniversary class." | |
131 | :type 'string | |
132 | :group 'org-bbdb-anniversaries | |
133 | :require 'bbdb) | |
134 | ||
135 | (defcustom org-bbdb-anniversary-format-alist | |
b349f79f CD |
136 | '(("birthday" lambda |
137 | (name years suffix) | |
138 | (concat "Birthday: [[bbdb:" name "][" name " (" | |
139 | (number-to-string years) | |
140 | suffix ")]]")) | |
141 | ("wedding" lambda | |
142 | (name years suffix) | |
143 | (concat "[[bbdb:" name "][" name "'s " | |
144 | (number-to-string years) | |
145 | suffix " wedding anniversary]]"))) | |
20908596 CD |
146 | "How different types of anniversaries should be formatted. |
147 | An alist of elements (STRING . FORMAT) where STRING is the name of an | |
148 | anniversary class and format is either: | |
149 | 1) A format string with the following substitutions (in order): | |
150 | * the name of the record containing this anniversary | |
151 | * the number of years | |
152 | * an ordinal suffix (st, nd, rd, th) for the year | |
153 | ||
154 | 2) A function to be called with three arguments: NAME YEARS SUFFIX | |
155 | (string int string) returning a string for the diary or nil. | |
156 | ||
157 | 3) An Emacs Lisp form that should evaluate to a string (or nil) in the | |
158 | scope of variables NAME, YEARS and SUFFIX (among others)." | |
159 | :type 'sexp | |
160 | :group 'org-bbdb-anniversaries | |
161 | :require 'bbdb) | |
162 | ||
163 | (defcustom org-bbdb-anniversary-field 'anniversary | |
164 | "The BBDB field which contains anniversaries. | |
165 | The anniversaries are stored in the following format | |
166 | ||
167 | YYYY-MM-DD Class-or-Format-String | |
168 | ||
169 | where class is one of the customized classes for anniversaries; | |
170 | birthday and wedding are predefined. Format-String can take three | |
171 | substitutions 1) the name of the record containing this | |
172 | anniversary, 2) the number of years, and 3) an ordinal suffix for | |
173 | the year. | |
174 | ||
888b663c | 175 | Multiple anniversaries can be separated by \\n." |
20908596 CD |
176 | :type 'symbol |
177 | :group 'org-bbdb-anniversaries | |
178 | :require 'bbdb) | |
179 | ||
180 | (defcustom org-bbdb-extract-date-fun 'org-bbdb-anniv-extract-date | |
181 | "How to retrieve `month date year' from the anniversary field. | |
182 | ||
888b663c | 183 | Customize if you have already filled your BBDB with dates |
20908596 | 184 | different from YYYY-MM-DD. The function must return a list (month |
888b663c | 185 | date year)." |
20908596 CD |
186 | :type 'function |
187 | :group 'org-bbdb-anniversaries | |
188 | :require 'bbdb) | |
189 | ||
190 | ||
191 | ;; Install the link type | |
192 | (org-add-link-type "bbdb" 'org-bbdb-open 'org-bbdb-export) | |
193 | (add-hook 'org-store-link-functions 'org-bbdb-store-link) | |
194 | ||
195 | ;; Implementation | |
196 | (defun org-bbdb-store-link () | |
197 | "Store a link to a BBDB database entry." | |
198 | (when (eq major-mode 'bbdb-mode) | |
199 | ;; This is BBDB, we make this link! | |
200 | (let* ((name (bbdb-record-name (bbdb-current-record))) | |
201 | (company (bbdb-record-getprop (bbdb-current-record) 'company)) | |
202 | (link (org-make-link "bbdb:" name))) | |
203 | (org-store-link-props :type "bbdb" :name name :company company | |
204 | :link link :description name) | |
205 | link))) | |
206 | ||
207 | (defun org-bbdb-export (path desc format) | |
208 | "Create the export version of a BBDB link specified by PATH or DESC. | |
209 | If exporting to either HTML or LaTeX FORMAT the link will be | |
210 | italicised, in all other cases it is left unchanged." | |
20908596 CD |
211 | (cond |
212 | ((eq format 'html) (format "<i>%s</i>" (or desc path))) | |
213 | ((eq format 'latex) (format "\\textit{%s}" (or desc path))) | |
214 | (t (or desc path)))) | |
215 | ||
216 | (defun org-bbdb-open (name) | |
217 | "Follow a BBDB link to NAME." | |
218 | (require 'bbdb) | |
219 | (let ((inhibit-redisplay (not debug-on-error)) | |
220 | (bbdb-electric-p nil)) | |
221 | (catch 'exit | |
222 | ;; Exact match on name | |
223 | (bbdb-name (concat "\\`" name "\\'") nil) | |
224 | (if (< 0 (buffer-size (get-buffer "*BBDB*"))) (throw 'exit nil)) | |
225 | ;; Exact match on name | |
226 | (bbdb-company (concat "\\`" name "\\'") nil) | |
227 | (if (< 0 (buffer-size (get-buffer "*BBDB*"))) (throw 'exit nil)) | |
228 | ;; Partial match on name | |
229 | (bbdb-name name nil) | |
230 | (if (< 0 (buffer-size (get-buffer "*BBDB*"))) (throw 'exit nil)) | |
231 | ;; Partial match on company | |
232 | (bbdb-company name nil) | |
233 | (if (< 0 (buffer-size (get-buffer "*BBDB*"))) (throw 'exit nil)) | |
234 | ;; General match including network address and notes | |
235 | (bbdb name nil) | |
236 | (when (= 0 (buffer-size (get-buffer "*BBDB*"))) | |
237 | (delete-window (get-buffer-window "*BBDB*")) | |
238 | (error "No matching BBDB record"))))) | |
239 | ||
240 | (defun org-bbdb-anniv-extract-date (time-str) | |
241 | "Convert YYYY-MM-DD to (month date year). | |
242 | Argument TIME-STR is the value retrieved from BBDB." | |
90ca3a46 | 243 | (multiple-value-bind (y m d) (values-list (bbdb-split time-str "-")) |
20908596 CD |
244 | (list (string-to-number m) |
245 | (string-to-number d) | |
246 | (string-to-number y)))) | |
247 | ||
248 | (defun org-bbdb-anniv-split (str) | |
888b663c | 249 | "Split multiple entries in the BBDB anniversary field. |
20908596 CD |
250 | Argument STR is the anniversary field in BBDB." |
251 | (let ((pos (string-match "[ \t]" str))) | |
252 | (if pos (list (substring str 0 pos) | |
253 | (bbdb-string-trim (substring str pos))) | |
254 | (list str nil)))) | |
255 | ||
b349f79f CD |
256 | (defvar org-bbdb-anniv-hash nil |
257 | "A hash holding anniversaries extracted from BBDB. | |
258 | The hash table is created on first use.") | |
20908596 | 259 | |
b349f79f CD |
260 | (defvar org-bbdb-updated-p t |
261 | "This is non-nil if BBDB has been updated since we last built the hash.") | |
262 | ||
263 | (defun org-bbdb-make-anniv-hash () | |
264 | "Create a hash with anniversaries extracted from BBDB, for fast access. | |
265 | The anniversaries are assumed to be stored `org-bbdb-anniversary-field'." | |
266 | ||
267 | (let (split tmp annivs) | |
268 | (clrhash org-bbdb-anniv-hash) | |
20908596 CD |
269 | (dolist (rec (bbdb-records)) |
270 | (when (setq annivs (bbdb-record-getprop | |
271 | rec org-bbdb-anniversary-field)) | |
272 | (setq annivs (bbdb-split annivs "\n")) | |
273 | (while annivs | |
274 | (setq split (org-bbdb-anniv-split (pop annivs))) | |
275 | (multiple-value-bind (m d y) | |
90ca3a46 | 276 | (values-list (funcall org-bbdb-extract-date-fun (car split))) |
b349f79f | 277 | (setq tmp (gethash (list m d) org-bbdb-anniv-hash)) |
ff4be292 CD |
278 | (puthash (list m d) (cons (list y |
279 | (bbdb-record-name rec) | |
b349f79f CD |
280 | (cadr split)) |
281 | tmp) | |
282 | org-bbdb-anniv-hash)))))) | |
283 | (setq org-bbdb-updated-p nil)) | |
284 | ||
285 | (defun org-bbdb-updated (rec) | |
286 | "Record the fact that BBDB has been updated. | |
287 | This is used by Org to re-create the anniversary hash table." | |
288 | (setq org-bbdb-updated-p t)) | |
20908596 | 289 | |
b349f79f CD |
290 | (add-hook 'bbdb-after-change-hook 'org-bbdb-updated) |
291 | ||
292 | ;;;###autoload | |
293 | (defun org-bbdb-anniversaries() | |
294 | "Extract anniversaries from BBDB for display in the agenda." | |
621f83e4 | 295 | (require 'bbdb) |
b349f79f CD |
296 | (require 'diary-lib) |
297 | (unless (hash-table-p org-bbdb-anniv-hash) | |
298 | (setq org-bbdb-anniv-hash | |
299 | (make-hash-table :test 'equal :size 366))) | |
300 | ||
301 | (when (or org-bbdb-updated-p | |
302 | (= 0 (hash-table-count org-bbdb-anniv-hash))) | |
303 | (org-bbdb-make-anniv-hash)) | |
304 | ||
305 | (let* ((m (car date)) ; month | |
306 | (d (nth 1 date)) ; day | |
307 | (y (nth 2 date)) ; year | |
308 | (annivs (gethash (list m d) org-bbdb-anniv-hash)) | |
309 | (text ()) | |
65c439fd | 310 | rec recs) |
ff4be292 | 311 | |
b349f79f | 312 | ;; we don't want to miss people born on Feb. 29th |
621f83e4 CD |
313 | (when (and (= m 3) (= d 1) |
314 | (not (null (gethash (list 2 29) org-bbdb-anniv-hash))) | |
315 | (not (calendar-leap-year-p y))) | |
316 | (setq recs (gethash (list 2 29) org-bbdb-anniv-hash)) | |
317 | (while (setq rec (pop recs)) | |
318 | (push rec annivs))) | |
b349f79f CD |
319 | |
320 | (when annivs | |
321 | (while (setq rec (pop annivs)) | |
ff4be292 | 322 | (when rec |
b349f79f CD |
323 | (let* ((class (or (nth 2 rec) |
324 | org-bbdb-default-anniversary-format)) | |
325 | (form (or (cdr (assoc class | |
326 | org-bbdb-anniversary-format-alist)) | |
327 | class)) ; (as format string) | |
328 | (name (nth 1 rec)) | |
329 | (years (- y (car rec))) | |
330 | (suffix (diary-ordinal-suffix years)) | |
331 | (tmp (cond | |
332 | ((functionp form) | |
333 | (funcall form name years suffix)) | |
334 | ((listp form) (eval form)) | |
335 | (t (format form name years suffix))))) | |
336 | (org-add-props tmp nil 'org-bbdb-name name) | |
337 | (if text | |
338 | (setq text (append text (list tmp))) | |
339 | (setq text (list tmp))))) | |
340 | )) | |
20908596 CD |
341 | (when text |
342 | (mapconcat 'identity text "; ")))) | |
343 | ||
c8d0cf5c CD |
344 | (defun org-bbdb-complete-link () |
345 | "Read a bbdb link with name completion." | |
346 | (require 'bbdb-com) | |
347 | (concat "bbdb:" | |
348 | (bbdb-record-name (car (bbdb-completing-read-record "Name: "))))) | |
349 | ||
350 | (defun org-bbdb-anniv-export-ical () | |
351 | "Extract anniversaries from BBDB and convert them to icalendar format." | |
352 | (require 'bbdb) | |
353 | (require 'diary-lib) | |
354 | (unless (hash-table-p org-bbdb-anniv-hash) | |
355 | (setq org-bbdb-anniv-hash | |
356 | (make-hash-table :test 'equal :size 366))) | |
357 | (when (or org-bbdb-updated-p | |
358 | (= 0 (hash-table-count org-bbdb-anniv-hash))) | |
359 | (org-bbdb-make-anniv-hash)) | |
360 | (maphash 'org-bbdb-format-vevent org-bbdb-anniv-hash)) | |
361 | ||
362 | (defun org-bbdb-format-vevent (key recs) | |
363 | (let (rec categ) | |
364 | (while (setq rec (pop recs)) | |
365 | (setq categ (or (nth 2 rec) org-bbdb-default-anniversary-format)) | |
366 | (princ (format "BEGIN:VEVENT | |
367 | UID: ANNIV-%4i%02i%02i-%s | |
368 | DTSTART:%4i%02i%02i | |
369 | SUMMARY:%s | |
370 | DESCRIPTION:%s | |
371 | CATEGORIES:%s | |
372 | RRULE:FREQ=YEARLY | |
373 | END:VEVENT\n" | |
374 | (nth 0 rec) (nth 0 key) (nth 1 key) | |
375 | (mapconcat 'identity | |
376 | (org-split-string (nth 1 rec) "[^a-zA-Z0-90]+") | |
377 | "-") | |
378 | (nth 0 rec) (nth 0 key) (nth 1 key) | |
379 | (nth 1 rec) | |
380 | (concat (capitalize categ) " " (nth 1 rec)) | |
381 | categ))))) | |
382 | ||
20908596 CD |
383 | (provide 'org-bbdb) |
384 | ||
88ac7b50 | 385 | ;; arch-tag: 9e4f275d-d080-48c1-b040-62247f66b5c2 |
b349f79f | 386 | |
20908596 | 387 | ;;; org-bbdb.el ends here |