Commit | Line | Data |
---|---|---|
db55f368 | 1 | ;;; org-id.el --- Global identifiers for Org-mode entries |
0bd48b37 | 2 | ;; |
ba318903 | 3 | ;; Copyright (C) 2008-2014 Free Software Foundation, Inc. |
d4d1a4ac CD |
4 | ;; |
5 | ;; Author: Carsten Dominik <carsten at orgmode dot org> | |
6 | ;; Keywords: outlines, hypermedia, calendar, wp | |
7 | ;; Homepage: http://orgmode.org | |
d4d1a4ac CD |
8 | ;; |
9 | ;; This file is part of GNU Emacs. | |
10 | ;; | |
11 | ;; GNU Emacs is free software: you can redistribute it and/or modify | |
12 | ;; it under the terms of the GNU General Public License as published by | |
13 | ;; the Free Software Foundation, either version 3 of the License, or | |
14 | ;; (at your option) any later version. | |
15 | ||
16 | ;; GNU Emacs is distributed in the hope that it will be useful, | |
17 | ;; but WITHOUT ANY WARRANTY; without even the implied warranty of | |
18 | ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
19 | ;; GNU General Public License for more details. | |
20 | ||
21 | ;; You should have received a copy of the GNU General Public License | |
22 | ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>. | |
23 | ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; | |
24 | ;; | |
25 | ;;; Commentary: | |
26 | ||
27 | ;; This file implements globally unique identifiers for Org-mode entries. | |
28 | ;; Identifiers are stored in the entry as an :ID: property. Functions | |
29 | ;; are provided that create and retrieve such identifiers, and that find | |
30 | ;; entries based on the identifier. | |
31 | ||
621f83e4 CD |
32 | ;; Identifiers consist of a prefix (default "Org" given by the variable |
33 | ;; `org-id-prefix') and a unique part that can be created by a number | |
34 | ;; of different methods, see the variable `org-id-method'. | |
35 | ;; Org has a builtin method that uses a compact encoding of the creation | |
36 | ;; time of the ID, with microsecond accuracy. This virtually | |
d4d1a4ac | 37 | ;; guarantees globally unique identifiers, even if several people are |
db55f368 | 38 | ;; creating IDs at the same time in files that will eventually be used |
86fbb8ca CD |
39 | ;; together. |
40 | ;; | |
41 | ;; By default Org uses UUIDs as global unique identifiers. | |
d4d1a4ac CD |
42 | ;; |
43 | ;; This file defines the following API: | |
44 | ;; | |
45 | ;; org-id-get-create | |
46 | ;; Create an ID for the entry at point if it does not yet have one. | |
47 | ;; Returns the ID (old or new). This function can be used | |
48 | ;; interactively, with prefix argument the creation of a new ID is | |
49 | ;; forced, even if there was an old one. | |
50 | ;; | |
51 | ;; org-id-get | |
52 | ;; Get the ID property of an entry. Using appropriate arguments | |
53 | ;; to the function, it can also create the ID for this entry. | |
54 | ;; | |
55 | ;; org-id-goto | |
56 | ;; Command to go to a specific ID, this command can be used | |
57 | ;; interactively. | |
58 | ;; | |
59 | ;; org-id-get-with-outline-path-completion | |
60 | ;; Retrieve the ID of an entry, using outline path completion. | |
61 | ;; This function can work for multiple files. | |
62 | ;; | |
63 | ;; org-id-get-with-outline-drilling | |
64 | ;; Retrieve the ID of an entry, using outline path completion. | |
65 | ;; This function only works for the current file. | |
66 | ;; | |
67 | ;; org-id-find | |
68 | ;; Find the location of an entry with specific id. | |
69 | ;; | |
70 | ||
86fbb8ca CD |
71 | ;;; Code: |
72 | ||
d4d1a4ac CD |
73 | (require 'org) |
74 | ||
75 | (declare-function message-make-fqdn "message" ()) | |
14e1337f | 76 | (declare-function org-pop-to-buffer-same-window |
e66ba1df | 77 | "org-compat" (&optional buffer-or-name norecord label)) |
d4d1a4ac CD |
78 | |
79 | ;;; Customization | |
80 | ||
81 | (defgroup org-id nil | |
82 | "Options concerning global entry identifiers in Org-mode." | |
83 | :tag "Org ID" | |
84 | :group 'org) | |
85 | ||
a89c8ef0 | 86 | (define-obsolete-variable-alias |
8223b1d2 BG |
87 | 'org-link-to-org-use-id 'org-id-link-to-org-use-id "24.3") |
88 | (defcustom org-id-link-to-org-use-id nil | |
89 | "Non-nil means storing a link to an Org file will use entry IDs. | |
90 | ||
91 | The variable can have the following values: | |
92 | ||
93 | t Create an ID if needed to make a link to the current entry. | |
94 | ||
95 | create-if-interactive | |
96 | If `org-store-link' is called directly (interactively, as a user | |
97 | command), do create an ID to support the link. But when doing the | |
98 | job for capture, only use the ID if it already exists. The | |
99 | purpose of this setting is to avoid proliferation of unwanted | |
100 | IDs, just because you happen to be in an Org file when you | |
101 | call `org-capture' that automatically and preemptively creates a | |
102 | link. If you do want to get an ID link in a capture template to | |
103 | an entry not having an ID, create it first by explicitly creating | |
104 | a link to it, using `C-c C-l' first. | |
105 | ||
106 | create-if-interactive-and-no-custom-id | |
107 | Like create-if-interactive, but do not create an ID if there is | |
108 | a CUSTOM_ID property defined in the entry. | |
109 | ||
110 | use-existing | |
111 | Use existing ID, do not create one. | |
112 | ||
113 | nil Never use an ID to make a link, instead link using a text search for | |
114 | the headline text." | |
115 | :group 'org-link-store | |
116 | :group 'org-id | |
117 | :version "24.3" | |
118 | :type '(choice | |
119 | (const :tag "Create ID to make link" t) | |
120 | (const :tag "Create if storing link interactively" | |
121 | create-if-interactive) | |
122 | (const :tag "Create if storing link interactively and no CUSTOM_ID is present" | |
123 | create-if-interactive-and-no-custom-id) | |
124 | (const :tag "Only use existing" use-existing) | |
125 | (const :tag "Do not use ID to create link" nil))) | |
126 | ||
c8d0cf5c CD |
127 | (defcustom org-id-uuid-program "uuidgen" |
128 | "The uuidgen program." | |
129 | :group 'org-id | |
130 | :type 'string) | |
621f83e4 | 131 | |
86fbb8ca | 132 | (defcustom org-id-method 'uuid |
db55f368 CD |
133 | "The method that should be used to create new IDs. |
134 | ||
db55f368 CD |
135 | An ID will consist of the optional prefix specified in `org-id-prefix', |
136 | and a unique part created by the method this variable specifies. | |
621f83e4 CD |
137 | |
138 | Allowed values are: | |
139 | ||
db55f368 CD |
140 | org Org's own internal method, using an encoding of the current time to |
141 | microsecond accuracy, and optionally the current domain of the | |
142 | computer. See the variable `org-id-include-domain'. | |
621f83e4 | 143 | |
86fbb8ca CD |
144 | uuid Create random (version 4) UUIDs. If the program defined in |
145 | `org-id-uuid-program' is available it is used to create the ID. | |
146 | Otherwise an internal functions is used." | |
621f83e4 CD |
147 | :group 'org-id |
148 | :type '(choice | |
149 | (const :tag "Org's internal method" org) | |
86fbb8ca | 150 | (const :tag "external: uuidgen" uuid))) |
621f83e4 CD |
151 | |
152 | (defcustom org-id-prefix nil | |
d4d1a4ac CD |
153 | "The prefix for IDs. |
154 | ||
155 | This may be a string, or it can be nil to indicate that no prefix is required. | |
156 | When a string, the string should have no space characters as IDs are expected | |
157 | to have no space characters in them." | |
158 | :group 'org-id | |
159 | :type '(choice | |
160 | (const :tag "No prefix") | |
161 | (string :tag "Prefix"))) | |
162 | ||
db55f368 | 163 | (defcustom org-id-include-domain nil |
ed21c5c8 | 164 | "Non-nil means add the domain name to new IDs. |
db55f368 | 165 | This ensures global uniqueness of IDs, and is also suggested by |
621f83e4 CD |
166 | RFC 2445 in combination with RFC 822. This is only relevant if |
167 | `org-id-method' is `org'. When uuidgen is used, the domain will never | |
db55f368 CD |
168 | be added. |
169 | The default is to not use this because we have no really good way to get | |
170 | the true domain, and Org entries will normally not be shared with enough | |
171 | people to make this necessary." | |
172 | :group 'org-id | |
173 | :type 'boolean) | |
174 | ||
175 | (defcustom org-id-track-globally t | |
ed21c5c8 | 176 | "Non-nil means track IDs through files, so that links work globally. |
db55f368 CD |
177 | This work by maintaining a hash table for IDs and writing this table |
178 | to disk when exiting Emacs. Because of this, it works best if you use | |
179 | a single Emacs process, not many. | |
180 | ||
181 | When nil, IDs are not tracked. Links to IDs will still work within | |
182 | a buffer, but not if the entry is located in another file. | |
183 | IDs can still be used if the entry with the id is in the same file as | |
184 | the link." | |
d4d1a4ac CD |
185 | :group 'org-id |
186 | :type 'boolean) | |
187 | ||
71d35b24 | 188 | (defcustom org-id-locations-file (convert-standard-filename |
271672fa | 189 | (concat user-emacs-directory ".org-id-locations")) |
db55f368 CD |
190 | "The file for remembering in which file an ID was defined. |
191 | This variable is only relevant when `org-id-track-globally' is set." | |
d4d1a4ac CD |
192 | :group 'org-id |
193 | :type 'file) | |
194 | ||
195 | (defvar org-id-locations nil | |
3ab2c837 | 196 | "List of files with IDs in those files.") |
db55f368 CD |
197 | |
198 | (defvar org-id-files nil | |
199 | "List of files that contain IDs.") | |
d4d1a4ac CD |
200 | |
201 | (defcustom org-id-extra-files 'org-agenda-text-search-extra-files | |
db55f368 CD |
202 | "Files to be searched for IDs, besides the agenda files. |
203 | When Org reparses files to remake the list of files and IDs it is tracking, | |
204 | it will normally scan the agenda files, the archives related to agenda files, | |
205 | any files that are listed as ID containing in the current register, and | |
206 | any Org-mode files currently visited by Emacs. | |
207 | You can list additional files here. | |
208 | This variable is only relevant when `org-id-track-globally' is set." | |
d4d1a4ac CD |
209 | :group 'org-id |
210 | :type | |
211 | '(choice | |
212 | (symbol :tag "Variable") | |
213 | (repeat :tag "List of files" | |
214 | (file)))) | |
215 | ||
db55f368 | 216 | (defcustom org-id-search-archives t |
ed21c5c8 | 217 | "Non-nil means search also the archive files of agenda files for entries. |
33306645 | 218 | This is a possibility to reduce overhead, but it means that entries moved |
db55f368 CD |
219 | to the archives can no longer be found by ID. |
220 | This variable is only relevant when `org-id-track-globally' is set." | |
221 | :group 'org-id | |
222 | :type 'boolean) | |
223 | ||
d4d1a4ac CD |
224 | ;;; The API functions |
225 | ||
226 | ;;;###autoload | |
227 | (defun org-id-get-create (&optional force) | |
228 | "Create an ID for the current entry and return it. | |
229 | If the entry already has an ID, just return it. | |
230 | With optional argument FORCE, force the creation of a new ID." | |
231 | (interactive "P") | |
232 | (when force | |
233 | (org-entry-put (point) "ID" nil)) | |
234 | (org-id-get (point) 'create)) | |
ff4be292 | 235 | |
73d3db82 | 236 | ;;;###autoload |
d4d1a4ac CD |
237 | (defun org-id-copy () |
238 | "Copy the ID of the entry at point to the kill ring. | |
239 | Create an ID if necessary." | |
240 | (interactive) | |
c8d0cf5c | 241 | (org-kill-new (org-id-get nil 'create))) |
d4d1a4ac CD |
242 | |
243 | ;;;###autoload | |
244 | (defun org-id-get (&optional pom create prefix) | |
245 | "Get the ID property of the entry at point-or-marker POM. | |
246 | If POM is nil, refer to the entry at point. | |
247 | If the entry does not have an ID, the function returns nil. | |
248 | However, when CREATE is non nil, create an ID if none is present already. | |
249 | PREFIX will be passed through to `org-id-new'. | |
250 | In any case, the ID of the entry is returned." | |
8d642074 CD |
251 | (org-with-point-at pom |
252 | (let ((id (org-entry-get nil "ID"))) | |
253 | (cond | |
254 | ((and id (stringp id) (string-match "\\S-" id)) | |
255 | id) | |
256 | (create | |
257 | (setq id (org-id-new prefix)) | |
258 | (org-entry-put pom "ID" id) | |
259 | (org-id-add-location id (buffer-file-name (buffer-base-buffer))) | |
8223b1d2 | 260 | id))))) |
d4d1a4ac | 261 | |
73d3db82 | 262 | ;;;###autoload |
d4d1a4ac | 263 | (defun org-id-get-with-outline-path-completion (&optional targets) |
8a28a5b8 BG |
264 | "Use `outline-path-completion' to retrieve the ID of an entry. |
265 | TARGETS may be a setting for `org-refile-targets' to define | |
266 | eligible headlines. When omitted, all headlines in the current | |
267 | file are eligible. This function returns the ID of the entry. | |
268 | If necessary, the ID is created." | |
d4d1a4ac | 269 | (let* ((org-refile-targets (or targets '((nil . (:maxlevel . 10))))) |
ff4be292 | 270 | (org-refile-use-outline-path |
d4d1a4ac | 271 | (if (caar org-refile-targets) 'file t)) |
c8d0cf5c | 272 | (org-refile-target-verify-function nil) |
3ab2c837 | 273 | (spos (org-refile-get-location "Entry")) |
ff4be292 | 274 | (pom (and spos (move-marker (make-marker) (nth 3 spos) |
d4d1a4ac CD |
275 | (get-file-buffer (nth 1 spos)))))) |
276 | (prog1 (org-id-get pom 'create) | |
277 | (move-marker pom nil)))) | |
278 | ||
73d3db82 | 279 | ;;;###autoload |
d4d1a4ac CD |
280 | (defun org-id-get-with-outline-drilling (&optional targets) |
281 | "Use an outline-cycling interface to retrieve the ID of an entry. | |
282 | This only finds entries in the current buffer, using `org-get-location'. | |
283 | It returns the ID of the entry. If necessary, the ID is created." | |
284 | (let* ((spos (org-get-location (current-buffer) org-goto-help)) | |
285 | (pom (and spos (move-marker (make-marker) (car spos))))) | |
286 | (prog1 (org-id-get pom 'create) | |
287 | (move-marker pom nil)))) | |
288 | ||
289 | ;;;###autoload | |
290 | (defun org-id-goto (id) | |
291 | "Switch to the buffer containing the entry with id ID. | |
292 | Move the cursor to that entry in that buffer." | |
db55f368 | 293 | (interactive "sID: ") |
d4d1a4ac CD |
294 | (let ((m (org-id-find id 'marker))) |
295 | (unless m | |
296 | (error "Cannot find entry with ID \"%s\"" id)) | |
e66ba1df | 297 | (org-pop-to-buffer-same-window (marker-buffer m)) |
d4d1a4ac CD |
298 | (goto-char m) |
299 | (move-marker m nil) | |
ff4be292 | 300 | (org-show-context))) |
d4d1a4ac CD |
301 | |
302 | ;;;###autoload | |
303 | (defun org-id-find (id &optional markerp) | |
304 | "Return the location of the entry with the id ID. | |
305 | The return value is a cons cell (file-name . position), or nil | |
306 | if there is no entry with that ID. | |
307 | With optional argument MARKERP, return the position as a new marker." | |
0bd48b37 CD |
308 | (cond |
309 | ((symbolp id) (setq id (symbol-name id))) | |
310 | ((numberp id) (setq id (number-to-string id)))) | |
d4d1a4ac CD |
311 | (let ((file (org-id-find-id-file id)) |
312 | org-agenda-new-buffers where) | |
313 | (when file | |
314 | (setq where (org-id-find-id-in-file id file markerp))) | |
315 | (unless where | |
8223b1d2 | 316 | (org-id-update-id-locations nil t) |
d4d1a4ac CD |
317 | (setq file (org-id-find-id-file id)) |
318 | (when file | |
319 | (setq where (org-id-find-id-in-file id file markerp)))) | |
320 | where)) | |
321 | ||
322 | ;;; Internal functions | |
323 | ||
324 | ;; Creating new IDs | |
325 | ||
73d3db82 | 326 | ;;;###autoload |
d4d1a4ac CD |
327 | (defun org-id-new (&optional prefix) |
328 | "Create a new globally unique ID. | |
329 | ||
330 | An ID consists of two parts separated by a colon: | |
331 | - a prefix | |
621f83e4 | 332 | - a unique part that will be created according to `org-id-method'. |
d4d1a4ac CD |
333 | |
334 | PREFIX can specify the prefix, the default is given by the variable | |
335 | `org-id-prefix'. However, if PREFIX is the symbol `none', don't use any | |
336 | prefix even if `org-id-prefix' specifies one. | |
337 | ||
338 | So a typical ID could look like \"Org:4nd91V40HI\"." | |
339 | (let* ((prefix (if (eq prefix 'none) | |
621f83e4 CD |
340 | "" |
341 | (concat (or prefix org-id-prefix) ":"))) | |
342 | unique) | |
343 | (if (equal prefix ":") (setq prefix "")) | |
344 | (cond | |
86fbb8ca CD |
345 | ((memq org-id-method '(uuidgen uuid)) |
346 | (setq unique (org-trim (shell-command-to-string org-id-uuid-program))) | |
347 | (unless (org-uuidgen-p unique) | |
348 | (setq unique (org-id-uuid)))) | |
621f83e4 | 349 | ((eq org-id-method 'org) |
271672fa | 350 | (let* ((etime (org-reverse-string (org-id-time-to-b36))) |
621f83e4 CD |
351 | (postfix (if org-id-include-domain |
352 | (progn | |
353 | (require 'message) | |
354 | (concat "@" (message-make-fqdn)))))) | |
355 | (setq unique (concat etime postfix)))) | |
356 | (t (error "Invalid `org-id-method'"))) | |
357 | (concat prefix unique))) | |
358 | ||
86fbb8ca CD |
359 | (defun org-id-uuid () |
360 | "Return string with random (version 4) UUID." | |
361 | (let ((rnd (md5 (format "%s%s%s%s%s%s%s" | |
0e23ef9d | 362 | (random) |
86fbb8ca CD |
363 | (current-time) |
364 | (user-uid) | |
365 | (emacs-pid) | |
366 | (user-full-name) | |
367 | user-mail-address | |
368 | (recent-keys))))) | |
369 | (format "%s-%s-4%s-%s%s-%s" | |
370 | (substring rnd 0 8) | |
371 | (substring rnd 8 12) | |
372 | (substring rnd 13 16) | |
373 | (format "%x" | |
374 | (logior | |
375 | #b10000000 | |
376 | (logand | |
377 | #b10111111 | |
378 | (string-to-number | |
379 | (substring rnd 16 18) 16)))) | |
380 | (substring rnd 18 20) | |
381 | (substring rnd 20 32)))) | |
382 | ||
621f83e4 | 383 | (defun org-id-int-to-b36-one-digit (i) |
d4d1a4ac CD |
384 | "Turn an integer between 0 and 61 into a single character 0..9, A..Z, a..z." |
385 | (cond | |
386 | ((< i 10) (+ ?0 i)) | |
621f83e4 CD |
387 | ((< i 36) (+ ?a i -10)) |
388 | (t (error "Larger that 35")))) | |
d4d1a4ac | 389 | |
621f83e4 | 390 | (defun org-id-b36-to-int-one-digit (i) |
d4d1a4ac CD |
391 | "Turn a character 0..9, A..Z, a..z into a number 0..61. |
392 | The input I may be a character, or a single-letter string." | |
393 | (and (stringp i) (setq i (string-to-char i))) | |
394 | (cond | |
395 | ((and (>= i ?0) (<= i ?9)) (- i ?0)) | |
621f83e4 CD |
396 | ((and (>= i ?a) (<= i ?z)) (+ (- i ?a) 10)) |
397 | (t (error "Invalid b36 letter")))) | |
d4d1a4ac | 398 | |
621f83e4 CD |
399 | (defun org-id-int-to-b36 (i &optional length) |
400 | "Convert an integer to a base-36 number represented as a string." | |
d4d1a4ac CD |
401 | (let ((s "")) |
402 | (while (> i 0) | |
403 | (setq s (concat (char-to-string | |
621f83e4 CD |
404 | (org-id-int-to-b36-one-digit (mod i 36))) s) |
405 | i (/ i 36))) | |
d4d1a4ac CD |
406 | (setq length (max 1 (or length 1))) |
407 | (if (< (length s) length) | |
408 | (setq s (concat (make-string (- length (length s)) ?0) s))) | |
409 | s)) | |
410 | ||
621f83e4 CD |
411 | (defun org-id-b36-to-int (s) |
412 | "Convert a base-36 string into the corresponding integer." | |
d4d1a4ac | 413 | (let ((r 0)) |
621f83e4 | 414 | (mapc (lambda (i) (setq r (+ (* r 36) (org-id-b36-to-int-one-digit i)))) |
d4d1a4ac CD |
415 | s) |
416 | r)) | |
417 | ||
621f83e4 | 418 | (defun org-id-time-to-b36 (&optional time) |
d4d1a4ac CD |
419 | "Encode TIME as a 10-digit string. |
420 | This string holds the time to micro-second accuracy, and can be decoded | |
421 | using `org-id-decode'." | |
422 | (setq time (or time (current-time))) | |
621f83e4 CD |
423 | (concat (org-id-int-to-b36 (nth 0 time) 4) |
424 | (org-id-int-to-b36 (nth 1 time) 4) | |
425 | (org-id-int-to-b36 (or (nth 2 time) 0) 4))) | |
d4d1a4ac CD |
426 | |
427 | (defun org-id-decode (id) | |
428 | "Split ID into the prefix and the time value that was used to create it. | |
429 | The return value is (prefix . time) where PREFIX is nil or a string, | |
430 | and time is the usual three-integer representation of time." | |
431 | (let (prefix time parts) | |
432 | (setq parts (org-split-string id ":")) | |
433 | (if (= 2 (length parts)) | |
434 | (setq prefix (car parts) time (nth 1 parts)) | |
435 | (setq prefix nil time (nth 0 parts))) | |
271672fa | 436 | (setq time (org-reverse-string time)) |
621f83e4 CD |
437 | (setq time (list (org-id-b36-to-int (substring time 0 4)) |
438 | (org-id-b36-to-int (substring time 4 8)) | |
439 | (org-id-b36-to-int (substring time 8 12)))) | |
d4d1a4ac CD |
440 | (cons prefix time))) |
441 | ||
442 | ;; Storing ID locations (files) | |
443 | ||
271672fa | 444 | ;;;###autoload |
8223b1d2 | 445 | (defun org-id-update-id-locations (&optional files silent) |
db55f368 CD |
446 | "Scan relevant files for IDs. |
447 | Store the relation between files and corresponding IDs. | |
448 | This will scan all agenda files, all associated archives, and all | |
449 | files currently mentioned in `org-id-locations'. | |
450 | When FILES is given, scan these files instead. | |
33306645 | 451 | When CHECK is given, prepare detailed information about duplicate IDs." |
d4d1a4ac | 452 | (interactive) |
db55f368 | 453 | (if (not org-id-track-globally) |
f924a367 | 454 | (error "Please turn on `org-id-track-globally' if you want to track IDs") |
8bfe682a CD |
455 | (let* ((org-id-search-archives |
456 | (or org-id-search-archives | |
457 | (and (symbolp org-id-extra-files) | |
458 | (symbol-value org-id-extra-files) | |
459 | (member 'agenda-archives org-id-extra-files)))) | |
460 | (files | |
461 | (or files | |
462 | (append | |
463 | ;; Agenda files and all associated archives | |
464 | (org-agenda-files t org-id-search-archives) | |
465 | ;; Explicit extra files | |
466 | (if (symbolp org-id-extra-files) | |
467 | (symbol-value org-id-extra-files) | |
468 | org-id-extra-files) | |
8223b1d2 | 469 | ;; Files associated with live org-mode buffers |
8bfe682a CD |
470 | (delq nil |
471 | (mapcar (lambda (b) | |
472 | (with-current-buffer b | |
8223b1d2 | 473 | (and (derived-mode-p 'org-mode) (buffer-file-name)))) |
8bfe682a CD |
474 | (buffer-list))) |
475 | ;; All files known to have IDs | |
476 | org-id-files))) | |
477 | org-agenda-new-buffers | |
478 | file nfiles tfile ids reg found id seen (ndup 0)) | |
479 | (when (member 'agenda-archives files) | |
480 | (setq files (delq 'agenda-archives (copy-sequence files)))) | |
db55f368 CD |
481 | (setq nfiles (length files)) |
482 | (while (setq file (pop files)) | |
8223b1d2 BG |
483 | (unless silent |
484 | (message "Finding ID locations (%d/%d files): %s" | |
485 | (- nfiles (length files)) nfiles file)) | |
db55f368 CD |
486 | (setq tfile (file-truename file)) |
487 | (when (and (file-exists-p file) (not (member tfile seen))) | |
488 | (push tfile seen) | |
489 | (setq ids nil) | |
490 | (with-current-buffer (org-get-agenda-file-buffer file) | |
491 | (save-excursion | |
492 | (save-restriction | |
493 | (widen) | |
494 | (goto-char (point-min)) | |
495 | (while (re-search-forward "^[ \t]*:ID:[ \t]+\\(\\S-+\\)[ \t]*$" | |
496 | nil t) | |
497 | (setq id (org-match-string-no-properties 1)) | |
498 | (if (member id found) | |
499 | (progn | |
500 | (message "Duplicate ID \"%s\", also in file %s" | |
8bfe682a CD |
501 | id (or (car (delq |
502 | nil | |
503 | (mapcar | |
504 | (lambda (x) | |
505 | (if (member id (cdr x)) | |
506 | (car x))) | |
507 | reg))) | |
508 | (buffer-file-name))) | |
db55f368 CD |
509 | (when (= ndup 0) |
510 | (ding) | |
511 | (sit-for 2)) | |
512 | (setq ndup (1+ ndup))) | |
513 | (push id found) | |
514 | (push id ids))) | |
515 | (push (cons (abbreviate-file-name file) ids) reg)))))) | |
516 | (org-release-buffers org-agenda-new-buffers) | |
517 | (setq org-agenda-new-buffers nil) | |
518 | (setq org-id-locations reg) | |
519 | (setq org-id-files (mapcar 'car org-id-locations)) | |
520 | (org-id-locations-save) ;; this function can also handle the alist form | |
521 | ;; now convert to a hash | |
522 | (setq org-id-locations (org-id-alist-to-hash org-id-locations)) | |
523 | (if (> ndup 0) | |
524 | (message "WARNING: %d duplicate IDs found, check *Messages* buffer" ndup) | |
525 | (message "%d unique files scanned for IDs" (length org-id-files))) | |
526 | org-id-locations))) | |
d4d1a4ac CD |
527 | |
528 | (defun org-id-locations-save () | |
529 | "Save `org-id-locations' in `org-id-locations-file'." | |
ed21c5c8 | 530 | (when (and org-id-track-globally org-id-locations) |
db55f368 CD |
531 | (let ((out (if (hash-table-p org-id-locations) |
532 | (org-id-hash-to-alist org-id-locations) | |
533 | org-id-locations))) | |
534 | (with-temp-file org-id-locations-file | |
271672fa BG |
535 | (let ((print-level nil) |
536 | (print-length nil)) | |
537 | (print out (current-buffer))))))) | |
d4d1a4ac CD |
538 | |
539 | (defun org-id-locations-load () | |
540 | "Read the data from `org-id-locations-file'." | |
541 | (setq org-id-locations nil) | |
db55f368 CD |
542 | (when org-id-track-globally |
543 | (with-temp-buffer | |
544 | (condition-case nil | |
545 | (progn | |
546 | (insert-file-contents-literally org-id-locations-file) | |
547 | (goto-char (point-min)) | |
548 | (setq org-id-locations (read (current-buffer)))) | |
549 | (error | |
8223b1d2 | 550 | (message "Could not read org-id-values from %s. Setting it to nil." |
db55f368 CD |
551 | org-id-locations-file)))) |
552 | (setq org-id-files (mapcar 'car org-id-locations)) | |
553 | (setq org-id-locations (org-id-alist-to-hash org-id-locations)))) | |
d4d1a4ac CD |
554 | |
555 | (defun org-id-add-location (id file) | |
33306645 | 556 | "Add the ID with location FILE to the database of ID locations." |
db55f368 | 557 | ;; Only if global tracking is on, and when the buffer has a file |
33306645 | 558 | (when (and org-id-track-globally id file) |
ce4fdcb9 | 559 | (unless org-id-locations (org-id-locations-load)) |
db55f368 CD |
560 | (puthash id (abbreviate-file-name file) org-id-locations) |
561 | (add-to-list 'org-id-files (abbreviate-file-name file)))) | |
562 | ||
845fc5e5 JB |
563 | (unless noninteractive |
564 | (add-hook 'kill-emacs-hook 'org-id-locations-save)) | |
db55f368 CD |
565 | |
566 | (defun org-id-hash-to-alist (hash) | |
567 | "Turn an org-id hash into an alist, so that it can be written to a file." | |
568 | (let (res x) | |
569 | (maphash | |
570 | (lambda (k v) | |
571 | (if (setq x (member v res)) | |
572 | (setcdr x (cons k (cdr x))) | |
573 | (push (list v k) res))) | |
574 | hash) | |
575 | res)) | |
576 | ||
577 | (defun org-id-alist-to-hash (list) | |
578 | "Turn an org-id location list into a hash table." | |
579 | (let ((res (make-hash-table | |
580 | :test 'equal | |
581 | :size (apply '+ (mapcar 'length list)))) | |
65c439fd | 582 | f) |
db55f368 CD |
583 | (mapc |
584 | (lambda (x) | |
585 | (setq f (car x)) | |
586 | (mapc (lambda (i) (puthash i f res)) (cdr x))) | |
587 | list) | |
588 | res)) | |
589 | ||
590 | (defun org-id-paste-tracker (txt &optional buffer-or-file) | |
591 | "Update any IDs in TXT and assign BUFFER-OR-FILE to them." | |
592 | (when org-id-track-globally | |
593 | (save-match-data | |
594 | (setq buffer-or-file (or buffer-or-file (current-buffer))) | |
595 | (when (bufferp buffer-or-file) | |
596 | (setq buffer-or-file (or (buffer-base-buffer buffer-or-file) | |
597 | buffer-or-file)) | |
598 | (setq buffer-or-file (buffer-file-name buffer-or-file))) | |
599 | (when buffer-or-file | |
600 | (let ((fname (abbreviate-file-name buffer-or-file)) | |
601 | (s 0)) | |
602 | (while (string-match "^[ \t]*:ID:[ \t]+\\([^ \t\n\r]+\\)" txt s) | |
603 | (setq s (match-end 0)) | |
604 | (org-id-add-location (match-string 1 txt) fname))))))) | |
d4d1a4ac CD |
605 | |
606 | ;; Finding entries with specified id | |
607 | ||
0bd48b37 | 608 | ;;;###autoload |
d4d1a4ac CD |
609 | (defun org-id-find-id-file (id) |
610 | "Query the id database for the file in which this ID is located." | |
611 | (unless org-id-locations (org-id-locations-load)) | |
ed21c5c8 CD |
612 | (or (and org-id-locations |
613 | (hash-table-p org-id-locations) | |
614 | (gethash id org-id-locations)) | |
db55f368 CD |
615 | ;; ball back on current buffer |
616 | (buffer-file-name (or (buffer-base-buffer (current-buffer)) | |
617 | (current-buffer))))) | |
d4d1a4ac CD |
618 | |
619 | (defun org-id-find-id-in-file (id file &optional markerp) | |
620 | "Return the position of the entry ID in FILE. | |
621 | If that files does not exist, or if it does not contain this ID, | |
622 | return nil. | |
623 | The position is returned as a cons cell (file-name . position). With | |
624 | optional argument MARKERP, return the position as a new marker." | |
65c439fd | 625 | (let (org-agenda-new-buffers buf pos) |
d4d1a4ac CD |
626 | (cond |
627 | ((not file) nil) | |
628 | ((not (file-exists-p file)) nil) | |
629 | (t (with-current-buffer (setq buf (org-get-agenda-file-buffer file)) | |
630 | (setq pos (org-find-entry-with-id id)) | |
631 | (when pos | |
632 | (if markerp | |
633 | (move-marker (make-marker) pos buf) | |
634 | (cons file pos)))))))) | |
635 | ||
db55f368 CD |
636 | ;; id link type |
637 | ||
638 | ;; Calling the following function is hard-coded into `org-store-link', | |
639 | ;; so we do have to add it to `org-store-link-functions'. | |
640 | ||
afe98dfa | 641 | ;;;###autoload |
db55f368 | 642 | (defun org-id-store-link () |
54a0dee5 | 643 | "Store a link to the current entry, using its ID." |
db55f368 | 644 | (interactive) |
8223b1d2 BG |
645 | (when (and (buffer-file-name (buffer-base-buffer)) (derived-mode-p 'org-mode)) |
646 | (let* ((link (concat "id:" (org-id-get-create))) | |
acedf35c CD |
647 | (case-fold-search nil) |
648 | (desc (save-excursion | |
649 | (org-back-to-heading t) | |
650 | (or (and (looking-at org-complex-heading-regexp) | |
651 | (if (match-end 4) | |
652 | (match-string 4) | |
653 | (match-string 0))) | |
654 | link)))) | |
655 | (org-store-link-props :link link :description desc :type "id") | |
656 | link))) | |
db55f368 CD |
657 | |
658 | (defun org-id-open (id) | |
659 | "Go to the entry with id ID." | |
660 | (org-mark-ring-push) | |
c8d0cf5c CD |
661 | (let ((m (org-id-find id 'marker)) |
662 | cmd) | |
db55f368 CD |
663 | (unless m |
664 | (error "Cannot find entry with ID \"%s\"" id)) | |
c8d0cf5c CD |
665 | ;; Use a buffer-switching command in analogy to finding files |
666 | (setq cmd | |
667 | (or | |
668 | (cdr | |
669 | (assq | |
670 | (cdr (assq 'file org-link-frame-setup)) | |
671 | '((find-file . switch-to-buffer) | |
672 | (find-file-other-window . switch-to-buffer-other-window) | |
673 | (find-file-other-frame . switch-to-buffer-other-frame)))) | |
674 | 'switch-to-buffer-other-window)) | |
db55f368 | 675 | (if (not (equal (current-buffer) (marker-buffer m))) |
c8d0cf5c | 676 | (funcall cmd (marker-buffer m))) |
db55f368 CD |
677 | (goto-char m) |
678 | (move-marker m nil) | |
679 | (org-show-context))) | |
680 | ||
681 | (org-add-link-type "id" 'org-id-open) | |
682 | ||
d4d1a4ac CD |
683 | (provide 'org-id) |
684 | ||
bdebdb64 BG |
685 | ;; Local variables: |
686 | ;; generated-autoload-file: "org-loaddefs.el" | |
687 | ;; End: | |
688 | ||
d4d1a4ac | 689 | ;;; org-id.el ends here |