[Orgmode] First extension: cycling through links

[Adam Solove]

Hi all,

First, I wanted to say thanks to Carsten and the community here for
org-mode. I'm a graduate student in Chinese literature and after trying
out many outliners and information management systems I've settled very
happily on org-mode and found it to be amazingly useful and especially
well-documented. 

I wanted to post a snippet of code I've been using because I haven't
read through the entire org-mode source, haven't ever written emacs
extensions before,  and would love to know if there is an easier or 
more idiomatic way of doing the following.

I usually create a glossary with radio targets at the end of a project,
allowing me to quickly see autolinks from any other text I might be
working on. Sometimes I want to do the opposite: from a radio target or
link, cycle through all the places in the text that are autolinked to
the same target. The code below does a sparse tree and then, since I
often have lots of occurences spread over more than a page, lets you
cycle forward and back through the actual occurences.

I would love if someone could let me know any defects or infelicities
with my method.

Thanks,

Adam

;; keys:
(org-defkey org-mode-map "\C-]" 'org-backlinks-cycle-forward)
(org-defkey org-mode-map "\C-[" 'org-backlinks-cycle-backward)

;; org-backlinks.el:
(defvar org-backlinks-regexp nil
  "Regexp to find most recent target called with org-backlinks-...")

(make-variable-buffer-local 'org-backlinks-regexp)

(defun org-backlinks-cycle-forward ()
  "Cycle forward through links to the link at point"
  (interactive)
  (org-backlinks-cycle 're-search-forward (+ (point-min) 1)))

(defun org-backlinks-cycle-backward ()
  "Cycle backwards through links to the link at point"
  (interactive)
  (org-backlinks-cycle 're-search-backward (- (point-max) 1)))

(defun org-backlinks-cycle (re-search backup)
  "Find links pointing to the radio target near point, or else the last
radio target at which the command was called. Can be called repeatedly."
  (let ((new-regexp (org-make-target-link-regexp 
                       (ensure-list (org-find-link-path-at-point)))))
        (when (and new-regexp (not (string= new-regexp org-backlinks-regexp)))
          (setq org-backlinks-regexp new-regexp)
          (org-occur org-backlinks-regexp))
        (when org-backlinks-regexp
          (unless (funcall re-search org-backlinks-regexp nil t)
                (goto-char backup) ; ugly, but so that we can -1 later
                (org-backlinks-cycle re-search backup)))))

(defun org-find-link-path-at-point ()
  "Returns string text of link at point, or nil"
  (text-at (org-find-link-at-point)))

(defun org-find-link-at-point ()
  "Returns positions bounding the beginning and end of link at point, else nil"
  (let ((pos (- (point) 1))) ; since search will leave us off just after the 
link
        (when (get-text-property pos 'org-linked-text)
          (cons (previous-single-property-change pos 'org-linked-text)
                        (next-single-property-change pos 'org-linked-text)))))
        
(defun org-find-target-name-near-point ()
  "Returns the text name of the nearbye target, or nil if none"
  (text-at (org-find-target-near-point)))

(defun org-find-target-near-point ()
  "Returns markers bounding the beginning and 
end of nearby target, else nil"
  (or (org-in-regexp org-radio-target-regexp)
          (org-in-regexp org-target-regexp))
  (cons (match-beginning 1) (match-end 1)))

;; Utility functions I had defined elsewhere...
(defun apply-cons (fn cons)
  "Apply a function to the two items in a cons cell"
  (apply fn (list (car cons) (cdr cons))))

(defun text-at (cons)
  "Returns the text between the two markers/positions 
in the provided cons, else nil"
  (and cons
           (apply-cons 'buffer-substring-no-properties cons)))

(defun ensure-list (item)
  (if (listp item)
          item
        (list item)))