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