places.el --- remember list of places within files

[spamfilteraccount]

Here's a little package I used when I had to understand how a big
legacy software package works. I used it to remember positions within
the source code belonging to particular use cases.

I post it here if anyone's interested (and I also will find it here in
case I need it again later). There is no error handling, so be sure no
to make mistakes. :)


;;; places.el --- remember list of places within files

;; Copyright (C) 2005  Free Software Foundation, Inc.

;; This file is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation; either version 2, or (at your option)
;; any later version.

;; This file is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;; GNU General Public License for more details.

;; You should have received a copy of the GNU General Public License
;; along with GNU Emacs; see the file COPYING.  If not, write to
;; the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
;; Boston, MA 02111-1307, USA.

;;; Commentary:

;; Places is a tool to maintain a list of bookmarked places belonging
;; to different "chains".
;;
;; For example, it can be used to record notable positions of a call
;; chain in a complex software package and visit these positions later.
;;
;; New chains/places can be defined with `places-add'. Existing chains
;; can be visited with `places-visit'. `places-save' and `places-load'
;; saves and loads stored chain data.
;;
;; See `places-mode-map' for the keys you can use in the Places buffer.
;;

;;; Code:

(defvar places-current-chain nil
  "Name of the last used chain.")

(defvar places-chains nil
  "Data of known chains.")

(defvar places-file "~/.places"
  "Name of the file were places are stored.")


(defvar places-mode-map nil
  "Keymap for Places mode.")

(if places-mode-map
    ()
  (setq places-mode-map (make-sparse-keymap))
  (define-key places-mode-map "\C-m" 'places-visit-place)
  (define-key places-mode-map "q" 'places-quit-buffer)
  (define-key places-mode-map "n" 'places-next)
  (define-key places-mode-map "p" 'places-previous)
  (define-key places-mode-map "r" 'places-rename)
  (define-key places-mode-map "d" 'places-delete))


(defun places-mode ()
  "Major mode for places buffers."
  (interactive)
  (kill-all-local-variables)
  (use-local-map places-mode-map)
  (setq mode-name "Places")
  (setq major-mode 'places-mode))


(defun places-add ()
  "Add a place to a chain."
  (interactive)
  (setq places-current-chain (read-from-minibuffer "Add to chain: "

places-current-chain))

  (let ((chain (assoc places-current-chain places-chains)))
    (unless chain
      (setq chain (list places-current-chain))
      (push chain places-chains))

    (let ((place-name (read-from-minibuffer "Name (can be empty): ")))
      (if (equal "" place-name)
          (setq place-name (int-to-string (length (cdr chain)))))
      (bookmark-set (places-get-real-name place-name))
      (setcdr chain (append (cdr chain) (list place-name))))))


(defun places-visit ()
  "Visit places of a selected chain."
  (interactive)
  (setq places-current-chain
        (completing-read "Chain: " places-chains nil t
places-current-chain))

  (pop-to-buffer (concat "*Chain: " places-current-chain "*"))
  (erase-buffer)

  (let ((chain (assoc places-current-chain places-chains)))
    (dolist (place (cdr chain))
      (insert place "\n")))

  ;; delete last newline
  (delete-backward-char 1)

  (goto-char (point-min))
  (places-mode))


(defun places-visit-place ()
  "Visit currentl selected place."
  (interactive)
  (let ((name (places-get-real-name (places-get-current)))
        (current-window (selected-window)))

    (other-window 1)
    (bookmark-jump name)
    (select-window current-window)))


(defun places-quit-buffer ()
  "Quit the *Places* buffer."
  (interactive)
  (delete-window))


(defun places-next ()
  "Visit next place in the chain."
  (interactive)
  (if (= 0 (forward-line))
      (places-visit-place)))


(defun places-previous ()
  "Visit previous place in the chain."
  (interactive)
  (if (= 0 (forward-line -1))
      (places-visit-place)))


(defun places-rename ()
  "Rename selected place."
  (interactive)
  (let* ((old-name (places-get-current))
         (new-name (read-from-minibuffer "New name: " old-name)))
    (bookmark-rename (places-get-real-name old-name)
                     (places-get-real-name new-name))
    (delete-region (line-beginning-position)
                   (line-end-position))
    (insert new-name)

    (let ((chain (assoc places-current-chain places-chains)))
      (setcdr chain (mapcar (lambda (name)
                              (if (equal name old-name)
                                  new-name
                                name))
                            (cdr chain))))))

(defun places-delete ()
  "Delete selected place."
  (interactive)
  (if (y-or-n-p "Are you sure? ")
      (let ((place (places-get-current)))
        (let ((begin (line-beginning-position)))
          (forward-line)
          (delete-region begin (point)))
        (bookmark-delete (places-get-real-name place))
        (let ((chain (assoc places-current-chain places-chains)))
          (setcdr chain (delete place (cdr chain)))))))


(defun places-save ()
  "Save data of all chains."
  (interactive)
  (save-excursion
      (set-buffer (find-file-noselect places-file))
      (erase-buffer)
      (pp places-chains (current-buffer))
      (save-buffer)
      (kill-buffer (current-buffer))))


(defun places-load ()
  "Load chain data from disk."
  (interactive)
  (save-excursion
      (set-buffer (find-file-noselect places-file))
      (setq places-chains (read (current-buffer)))
      (kill-buffer (current-buffer))))


(defun places-get-real-name (name)
  "Return the real bookmark name of a place."
  (concat places-current-chain "_" name))


(defun places-get-current ()
  "Return the current place from the Places buffer."
  (buffer-substring-no-properties (line-beginning-position)
                                  (line-end-position)))

 
(provide 'places)
;;; places.el ends here