diff --git a/Makefile b/Makefile index cff1e46aa..4ec504867 100644 --- a/Makefile +++ b/Makefile @@ -70,6 +70,7 @@ LISPF = org.el \ org-colview-xemacs.el \ org-compat.el \ org-crypt.el \ + org-ctags.el \ org-datetree.el \ org-docview.el \ org-exp.el \ @@ -341,6 +342,7 @@ lisp/org-colview.elc: lisp/org.el lisp/org-colview-xemacs.elc: lisp/org.el lisp/org-compat.elc: lisp/org-macs.el lisp/org-crypt.elc: lisp/org-crypt.el lisp/org.el +lisp/org-ctags.elc: lisp/org.el lisp/org-datetree.elc: lisp/org.el lisp/org-docview.elc: lisp/org.el lisp/org-exp.elc: lisp/org.el lisp/org-agenda.el diff --git a/lisp/org-ctags.el b/lisp/org-ctags.el new file mode 100644 index 000000000..8ec833568 --- /dev/null +++ b/lisp/org-ctags.el @@ -0,0 +1,519 @@ +;;; org-ctags.el - Integrate Emacs "tags" facility with org mode. +;;; +;;; Author: Paul Sexton +;;; Version: 1.0 +;;; Repository at http://bitbucket.org/eeeickythump/org-ctags/ +;;; +;;; Synopsis +;;; ======== +;;; +;;; Allows org-mode to make use of the Emacs `etags' system. Defines tag +;;; destinations in org-mode files as any text between <>. This allows the tags-generation program `exuberant ctags' to +;;; parse these files and create tag tables that record where these +;;; destinations are found. Plain [[links]] in org mode files which do not have +;;; <> within the same file will then be interpreted as +;;; links to these 'tagged' destinations, allowing seamless navigation between +;;; multiple org-mode files. Topics can be created in any org mode file and +;;; will always be found by plain links from other files. Other file types +;;; recognised by ctags (source code files, latex files, etc) will also be +;;; available as destinations for plain links, and similarly, org-mode links +;;; will be available as tags from source files. Finally, the function +;;; `org-ctags-find-tag-interactive' lets you choose any known tag, using +;;; autocompletion, and quickly jump to it. +;;; +;;; Installation +;;; ============ +;;; +;;; Install org mode +;;; Ensure org-ctags.el is somewhere in your emacs load path. +;;; Download and install Exuberant ctags -- "http://ctags.sourceforge.net/" +;;; Edit your .emacs file (see next section) and load emacs. + +;;; To put in your init file (.emacs): +;;; ================================== +;;; +;;; Assuming you already have org mode installed and set up: +;;; +;;; (setq org-ctags-path-to-ctags "/path/to/ctags/executable") +;;; (add-hook 'org-mode-hook +;;; (lambda () +;;; (define-key org-mode-map "\C-co" 'org-ctags-find-tag-interactive))) +;;; +;;; By default, with org-ctags loaded, org will first try and visit the tag +;;; with the same name as the link; then, if unsuccessful, ask the user if +;;; he/she wants to rebuild the 'TAGS' database and try again; then ask if +;;; the user wishes to append 'tag' as a new toplevel heading at the end of +;;; the buffer; and finally, defer to org's default behaviour which is to +;;; search the entire text of the current buffer for 'tag'. +;;; +;;; This behaviour can be modified by changing the value of +;;; ORG-CTAGS-OPEN-LINK-FUNCTIONS. For example I have the following in my +;;; .emacs, which describes the same behaviour as the above paragraph with +;;; one difference: +;;; +;;; (setq org-ctags-open-link-functions +;;; '(org-ctags-find-tag +;;; org-ctags-ask-rebuild-tags-file-then-find-tag +;;; org-ctags-ask-append-topic +;;; org-ctags-fail-silently)) ; <-- prevents org default behaviour +;;; +;;; +;;; Usage +;;; ===== +;;; +;;; When you click on a link "[[foo]]" and org cannot find a matching "<>" +;;; in the current buffer, the tags facility will take over. The file TAGS in +;;; the active directory is examined to see if the tags facility knows about +;;; "<>" in any other files. If it does, the matching file will be opened +;;; and the cursor will jump to the position of "<>" in that file. +;;; +;;; User-visible functions: +;;; - `org-ctags-find-tag-interactive': type a tag (plain link) name and visit +;;; it. With autocompletion. Bound to ctrl-O in the above setup. +;;; - All the etags functions should work. These include: +;;; +;;; M-. `find-tag' -- finds the tag at point +;;; +;;; C-M-. find-tag based on regular expression +;;; +;;; M-x tags-search RET -- like C-M-. but searches through ENTIRE TEXT +;;; of ALL the files referenced in the TAGS file. A quick way to +;;; search through an entire 'project'. +;;; +;;; M-* "go back" from a tag jump. Like `org-mark-ring-goto'. +;;; You may need to bind this key yourself with (eg) +;;; (global-set-key (kbd "") 'pop-tag-mark) +;;; +;;; (see etags chapter in Emacs manual for more) +;;; +;;; +;;; Keeping the TAGS file up to date +;;; ================================ +;;; +;;; Tags mode has no way of knowing that you have created new tags by typing in +;;; your org-mode buffer. New tags make it into the TAGS file in 3 ways: +;;; +;;; 1. You re-run (org-ctags-create-tags "directory") to rebuild the file. +;;; 2. You put the function `org-ctags-ask-rebuild-tags-file-then-find-tag' in +;;; your `org-open-link-functions' list, as is done in the setup +;;; above. This will cause the TAGS file to be rebuilt whenever a link +;;; cannot be found. This may be slow with large file collections however. +;;; 3. You run the following from the command line (all 1 line): +;;; +;;; ctags --langdef=orgmode --langmap=orgmode:.org +;;; --regex-orgmode="/<<([^>]+)>>/\1/d,definition/" +;;; -f /your/path/TAGS -e -R /your/path/*.org +;;; +;;; If you are paranoid, you might want to run (org-ctags-create-tags +;;; "/path/to/org/files") at startup, by including the following toplevel form +;;; in .emacs. However this can cause a pause of several seconds if ctags has +;;; to scan lots of files. +;;; +;;; (progn +;;; (message "-- rebuilding tags tables...") +;;; (mapc 'org-create-tags tags-table-list)) + +(eval-when-compile (require 'cl)) +(require 'org) + +(defgroup org-ctags nil + "Options concerning use of ctags within org mode." + :tag "Org-Ctags" + :group 'org-link) + +(defvar org-ctags-enabled-p t + "Activate ctags support in org mode?") + +(defvar org-ctags-tag-regexp "/<<([^>]+)>>/\\1/d,definition/" + "Regexp expression used by ctags external program, that matches +tag destinations in org-mode files. +Format is: /REGEXP/TAGNAME/FLAGS,TAGTYPE/ +See the ctags documentation for more information.") + +(defcustom org-ctags-path-to-ctags + (case (operating-system) + (windows "ctags.exe") + (unix "ctags-exuberant")) + "Full path to the ctags executable file." + :group 'org-ctags + :type 'file) + + +(defcustom org-ctags-open-link-functions + '(org-ctags-find-tag + org-ctags-ask-rebuild-tags-file-then-find-tag + org-ctags-ask-append-topic) + "List of functions to be prepended to ORG-OPEN-LINK-FUNCTIONS when +ORG-CTAGS is active." + :group 'org-ctags + :type 'hook + :options '(org-ctags-find-tag + org-ctags-ask-rebuild-tags-file-then-find-tag + org-ctags-rebuild-tags-file-then-find-tag + org-ctags-ask-append-topic + org-ctags-append-topic + org-ctags-ask-visit-buffer-or-file + org-ctags-visit-buffer-or-file + org-ctags-fail-silently)) + + +(defvar org-ctags-tag-list nil + "List of all tags in the active TAGS file. Created as a local +variable in each buffer.") + +(defcustom org-ctags-new-topic-template + "* <<%t>>\n\n\n\n\n\n" + "Text to insert when creating a new org file via opening a hyperlink. +The following patterns are replaced in the string: + `%t' - replaced with the capitalized title of the hyperlink" + :group 'org-ctags + :type 'string) + + +(add-hook 'org-mode-hook + (lambda () + (when (and org-ctags-enabled-p + (buffer-file-name)) + ;; Make sure this file's directory is added to default + ;; directories in which to search for tags. + (let ((tags-filename + (expand-file-name + (concat (file-name-directory (buffer-file-name)) + "/TAGS")))) + (when (file-exists-p tags-filename) + (visit-tags-table tags-filename)))))) + + +(defadvice visit-tags-table (after org-ctags-load-tag-list activate compile) + (when (and org-ctags-enabled-p tags-file-name) + (set (make-local-variable 'org-ctags-tag-list) + (org-ctags-all-tags-in-current-tags-table)))) + + +(defun org-ctags-enable () + (put 'org-mode 'find-tag-default-function 'org-ctags-find-tag-at-point) + (setq org-ctags-enabled-p t) + (dolist (fn (reverse org-ctags-open-link-functions)) + (add-hook 'org-open-link-functions fn))) + + +;;; General utility functions. =============================================== +;;; These work outside org-ctags mode. + +(defun org-ctags-get-filename-for-tag (tag) + "TAG is a string. Search the active TAGS file for a matching tag, +and if found, return a list containing the filename, line number, and +buffer position where the tag is found." + (interactive "sTag: ") + (unless tags-file-name + (call-interactively (visit-tags-table))) + (save-excursion + (visit-tags-table-buffer 'same) + (when tags-file-name + (with-current-buffer (get-file-buffer tags-file-name) + (goto-char (point-min)) + (cond + ((re-search-forward (format "^.*%s\\([0-9]+\\),\\([0-9]+\\)$" + (regexp-quote tag)) nil t) + (let ((line (string-to-number (match-string 1))) + (pos (string-to-number (match-string 2)))) + (cond + ((re-search-backward " \n\\(.*\\),[0-9]+\n") + (list (match-string 1) line pos)) + (t ; can't find a file name preceding the matched + ; tag?? + (error "Malformed TAGS file: %s" (buffer-name)))))) + (t ; tag not found + nil)))))) + + +(defun org-ctags-all-tags-in-current-tags-table () + "Read all tags defined in the active TAGS file, into a list of strings. +Return the list." + (interactive) + (let ((taglist nil)) + (unless tags-file-name + (call-interactively (visit-tags-table))) + (save-excursion + (visit-tags-table-buffer 'same) + (with-current-buffer (get-file-buffer tags-file-name) + (goto-char (point-min)) + (while (re-search-forward "^.*\\(.*\\)\\([0-9]+\\),\\([0-9]+\\)$" + nil t) + (push (substring-no-properties (match-string 1)) taglist))) + taglist))) + + +(defun org-ctags-string-search-and-replace (search replace string) + "Replace all instances of SEARCH with REPLACE in STRING." + (replace-regexp-in-string (regexp-quote search) replace string t t)) + + +(defun y-or-n-minibuffer (prompt) + (let ((use-dialog-box nil)) + (y-or-n-p prompt))) + + +;;; Internal functions ======================================================= + + +(defun org-ctags-open-file (name &optional title) + "Visit or create a file called `NAME.org', and insert a new topic titled +NAME (or TITLE if supplied)." + (interactive "sFile name: ") + (let ((filename (substitute-in-file-name (expand-file-name name)))) + (condition-case v + (progn + (org-open-file name t) + (message "Opened file OK") + (goto-char (point-max)) + (insert (org-ctags-string-search-and-replace + "%t" (capitalize (or title name)) + org-ctags-new-topic-template)) + (message "Inserted new file text OK") + (org-mode-restart)) + (error (error "Error %S in org-ctags-open-file" v))))) + + +;;;; Misc interoperability with etags system ================================= + + +(defadvice find-tag (before org-ctags-set-org-mark-before-finding-tag + activate compile) + "Before trying to find a tag, save our current position on org mark ring." + (save-excursion + (if (and (org-mode-p) org-ctags-enabled-p) + (org-mark-ring-push)))) + + + +(defun org-ctags-find-tag-at-point () + "Determine default tag to search for, based on text at point. +If there is no plausible default, return nil." + (let (from to bound) + (when (or (ignore-errors + ;; Look for hyperlink around `point'. + (save-excursion + (search-backward "[[") (setq from (+ 2 (point)))) + (save-excursion + (goto-char from) + (search-forward "]") (setq to (- (point) 1))) + (and (> to from) (>= (point) from) (<= (point) to))) + (progn + ;; Look at text around `point'. + (save-excursion + (skip-syntax-backward "w_") (setq from (point))) + (save-excursion + (skip-syntax-forward "w_") (setq to (point))) + (> to from)) + ;; Look between `line-beginning-position' and `point'. + (save-excursion + (and (setq bound (line-beginning-position)) + (skip-syntax-backward "^w_" bound) + (> (setq to (point)) bound) + (skip-syntax-backward "w_") + (setq from (point)))) + ;; Look between `point' and `line-end-position'. + (save-excursion + (and (setq bound (line-end-position)) + (skip-syntax-forward "^w_" bound) + (< (setq from (point)) bound) + (skip-syntax-forward "w_") + (setq to (point))))) + (buffer-substring-no-properties from to)))) + + +;;; Functions for use with 'org-open-link-functions' hook ================= + + +(defun org-ctags-find-tag (name) + "This function is intended to be used in ORG-OPEN-LINK-FUNCTIONS. +Look for a tag called `NAME' in the current TAGS table. If it is found, +visit the file and location where the tag is found." + (interactive "sTag: ") + (let ((old-buf (current-buffer)) + (old-pnt (point-marker)) + (old-mark (copy-marker (mark-marker)))) + (condition-case nil + (progn (find-tag name) + t) + (error + ;; only restore old location if find-tag raises error + (set-buffer old-buf) + (goto-char old-pnt) + (set-marker (mark-marker) old-mark) + nil)))) + + +(defun org-ctags-visit-buffer-or-file (name &optional create) + "This function is intended to be used in ORG-OPEN-LINK-FUNCTIONS. +Visit buffer named `NAME.org'. If there is no such buffer, visit the file +with the same name if it exists. If the file does not exist, then behaviour +depends on the value of CREATE. + +If CREATE is nil (default), then return nil. Do not create a new file. +If CREATE is t, create the new file and visit it. +If CREATE is the symbol `ask', then ask the user if they wish to create +the new file." + (interactive) + (let ((filename (concat (substitute-in-file-name + (expand-file-name name)) + ".org"))) + (cond + ((get-buffer (concat name ".org")) + ;; Buffer is already open + (switch-to-buffer (get-buffer (concat name ".org")))) + ((file-exists-p filename) + ;; File exists but is not open --> open it + (message "Opening existing org file `%S'..." + filename) + (org-open-file filename t)) + ((or (eql create t) + (and (eql create 'ask) + (y-or-n-p (format "File `%s.org' not found; create?" name)))) + (org-ctags-open-file filename name)) + (t ;; File does not exist, and we don't want to create it. + nil)))) + + +(defun org-ctags-ask-visit-buffer-or-file (name) + "This function is intended to be used in ORG-OPEN-LINK-FUNCTIONS. +Wrapper for org-ctags-visit-buffer-or-file, which ensures the user is +asked before creating a new file." + (org-ctags-visit-buffer-or-file name 'ask)) + + +(defun org-ctags-append-topic (name &optional narrowp) + "This function is intended to be used in ORG-OPEN-LINK-FUNCTIONS. +Append a new toplevel heading to the end of the current buffer. The +heading contains NAME surrounded by <>, thus making +the heading a destination for the tag `NAME'." + (interactive "sTopic: ") + (widen) + (goto-char (point-max)) + (newline 2) + (message "Adding topic in buffer %s" (buffer-name)) + (insert (org-ctags-string-search-and-replace + "%t" (capitalize name) org-ctags-new-topic-template)) + (backward-char 4) + (org-update-radio-target-regexp) + (end-of-line) + (forward-line 2) + (when narrowp + ;;(org-tree-to-indirect-buffer 1) ;; opens new frame + (org-narrow-to-subtree)) + t) + + +(defun org-ctags-ask-append-topic (name &optional narrowp) + "This function is intended to be used in ORG-OPEN-LINK-FUNCTIONS. +Wrapper for org-ctags-append-topic, which first asks the user if they want +to append a new topic." + (if (y-or-n-p (format "Topic `%s' not found; append to end of buffer?" + name)) + (org-ctags-append-topic name narrowp) + nil)) + + +(defun org-ctags-rebuild-tags-file-then-find-tag (name) + "This function is intended to be used in ORG-OPEN-LINK-FUNCTIONS. +Like ORG-CTAGS-FIND-TAG, but calls the external ctags program first, +to rebuild (update) the TAGS file." + (unless tags-file-name + (call-interactively (visit-tags-table))) + (when (buffer-file-name) + (org-ctags-create-tags)) + (org-ctags-find-tag name)) + + +(defun org-ctags-ask-rebuild-tags-file-then-find-tag (name) + "This function is intended to be used in ORG-OPEN-LINK-FUNCTIONS. +Wrapper for org-ctags-rebuild-tags-file-then-find-tag." + (if (and (buffer-file-name) + (y-or-n-p + (format + "Tag `%s' not found. Rebuild table `%s/TAGS' and look again?" + name + (file-name-directory (buffer-file-name))))) + (org-ctags-rebuild-tags-file-then-find-tag name) + nil)) + + +(defun org-ctags-fail-silently (name) + "This function is intended to be used in ORG-OPEN-LINK-FUNCTIONS. +Put as the last function in the list if you want to prevent org's default +behaviour of free text search." + t) + + +;;; User-visible functions =================================================== + + +(defun org-ctags-create-tags (&optional directory-name) + "(Re)create tags file in the directory of the active buffer, +containing tag definitions for all the files in the directory and its +subdirectories which are recognised by ctags. This will include +files ending in `.org' as well as most other source files (.C, +.H, .EL, .LISP, etc). All the resulting tags end up in one file, +called TAGS, located in the directory. This function +may take several seconds to finish if the directory or its +subdirectories contain large numbers of taggable files." + (interactive) + (assert (buffer-file-name)) + (let ((dir-name (or directory-name + (file-name-directory (buffer-file-name)))) + (exitcode nil)) + (save-excursion + (setq exitcode + (shell-command + (format (concat "%s --langdef=orgmode --langmap=orgmode:.org " + "--regex-orgmode=\"%s\" -f \"%s\" -e -R \"%s\"") + org-ctags-path-to-ctags + org-ctags-tag-regexp + (expand-file-name (concat dir-name "/TAGS")) + (expand-file-name (concat dir-name "/"))))) + (cond + ((eql 0 exitcode) + (set (make-local-variable 'org-ctags-tag-list) + (org-ctags-all-tags-in-current-tags-table))) + (t + ;; This seems to behave differently on Linux, so just ignore + ;; error codes for now + ;;(error "Calling ctags executable resulted in error code: %s" + ;; exitcode) + nil))))) + + +(defvar org-ctags-find-tag-history nil + "History of tags visited by org-ctags-find-tag-interactive.") + +(defun org-ctags-find-tag-interactive () + "Prompt for the name of a tag, with autocompletion, then visit +the named tag. Uses ido-mode if available. +If the user enters a string that does not match an existing tag, create +a new topic." + (interactive) + (let* ((completing-read-fn (if (fboundp 'ido-completing-read) + 'ido-completing-read + 'completing-read)) + (tag (funcall completing-read-fn "Topic: " org-ctags-tag-list + nil 'confirm nil 'org-ctags-find-tag-history))) + (when tag + (cond + ((member tag org-ctags-tag-list) + ;; Existing tag + (push tag org-ctags-find-tag-history) + (find-tag tag)) + (t + ;; New tag + (run-hook-with-args-until-success + 'org-open-link-functions tag)))))) + + +(org-ctags-enable) + +(provide 'org-ctags) + +;;; arch-tag: 4b1ddd5a-8529-4b17-bcde-96a922d26343 +;;; org-ctags.el ends here diff --git a/lisp/org.el b/lisp/org.el index 2fe62c23e..888366ac6 100644 --- a/lisp/org.el +++ b/lisp/org.el @@ -189,6 +189,7 @@ to add the symbol `xyz', and the package must have a call to (const :tag " bbdb: Links to BBDB entries" org-bbdb) (const :tag " bibtex: Links to BibTeX entries" org-bibtex) (const :tag " crypt: Encryption of subtrees" org-crypt) + (const :tag " ctags: Access to Emacs tags with links" org-ctags) (const :tag " docview: Links to doc-view buffers" org-docview) (const :tag " gnus: Links to GNUS folders/messages" org-gnus) (const :tag " id: Global IDs for identifying entries" org-id)