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