Misc/pyimenu.el

;;; PYIMENU.EL --- 

;; Copyright (C) 1995 Perry A. Stoll

;; Author: Perry A. Stoll <stoll@atr-sw.atr.co.jp>
;; Created: 12 May 1995
;; Version: 1.0
;; Keywords: tools python imenu

;; This program 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 program 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.

;; A copy of the GNU General Public License can be obtained from the
;; Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
;; USA.

;;;; COMMENTS

;; I use the imenu package a lot for looking at Lisp and C/C++
;; code. When I started using Python, I was dismayed that I couldn't
;; use it to look at Python source. So here's a rough go at it.

;;;; USAGE

;; This program is used in conjunction with the imenu package. When
;; you call imenu in python-mode in a python buffer, a list of
;; functions and classes is built. The top level menu has a list of
;; all functions and classes defined at the top indentation
;; level. Classes which have methods defined in them have a submenu
;; which contains all definitions contained in them. Selecting any
;; item will bring you to that point in the file.

;;;; INSTALLATION

;; You know the routine:
;; 1) Save this file as pyimenu.el,
;; 2) Place that file somewhere in your emacs load path (maybe ~/emacs
;;    or ~/emacs/lisp),
;; 3) Byte compile it (M-x byte-compile-file),
;; 4) Add the following (between "cut here" and "end here") to your
;;    ~/.emacs file,
;; 5) Reboot. (joke: DON'T do that, although you'll probably have to
;;    either reload your ~/.emacs file or start a new emacs)

;;--------------cut here-------------------------------------------
;;;; Load the pyimenu index function
;;(autoload 'imenu "imenu" nil t)
;;(autoload 'imenu-example--create-python-index "pyimenu")
;;;; Add the index creation function to the python-mode-hook 
;;(add-hook 'python-mode-hook
;;	  (function
;;	   (lambda ()
;;	     (setq imenu-create-index-function
;;		   (function imenu-example--create-python-index)))))
;;----------------end here--------------------------------------------
;;
;; That is all you need. Of course, the following provides a more
;; useful interface. i.e. this is how I have it set up ;-)
;;
;;----------------optionally cut here----------------------------------
;;(autoload 'imenu-add-to-menubar "imenu" nil t)
;;(defun my-imenu-install-hook ()
;;  (imenu-add-to-menubar (format "%s-%s" "IM" mode-name)))
;;(add-hook 'python-mode-hook (function my-imenu-install-hook))
;;;; Bind imenu to some convenient (?) mouse key. This really lets you
;;;; fly around the buffer. Here it is set to Meta-Shift-Mouse3Click.
;;(global-set-key [M-S-down-mouse-3] (function imenu))
;;-----------------optionaly end here-----------------------------------

;;;; CAVEATS/NOTES

;; 0) I'm not a professional elisp programmer and it shows in the code
;;    below. If anyone there has suggestions/changes, I'd love to
;;    hear them. I've tried the code out on a bunch of python files
;;    from the python-1.1.1 Demo distribution and it worked with
;;    them - your mileage may very.
;;
;; 1) You must have the imenu package to use this file. This file
;;    works with imenu version 1.11 (the version included with emacs
;;    19.28) and imenu version 1.14; if you have a later version, this
;;    may not work with it.
;;
;; 2) This setup assumes you also have python-mode.el, so that it can
;;    use the python-mode-hook. It comes with the python distribution.
;;
;; 3) I don't have the Python 1.2 distribution yet, so again, this may
;;    not work with that.
;;

(require 'imenu)

;;;
;;; VARIABLES: customizable in your .emacs file.
;;;

(defvar imenu-example--python-show-method-args-p nil 
  "*When using imenu package with python-mode, whether the arguments of
the function/methods should be printed in the imenu buffer in addition
to the function/method name. If non-nil, args are printed.")

;;;
;;; VARIABLES: internal use.
;;;
(defvar imenu-example--python-class-regexp
  (concat                              ; <<classes>>
   "\\("                               ;
   "^[ \t]*"                           ; newline and maybe whitespace
   "\\(class[ \t]+[a-zA-Z0-9_]+\\)"    ; class name
                                       ; possibly multiple superclasses
   "\\([ \t]*\\((\\([a-zA-Z0-9_, \t\n]\\)*)\\)?\\)"
   "[ \t]*:"                           ; and the final :
   "\\)"                               ; >>classes<<
   )
  "Regexp for Python classes for use with the imenu package."
)

(defvar imenu-example--python-method-regexp
  (concat                               ; <<methods and functions>>
   "\\("                                ; 
   "^[ \t]*"                            ; new line and maybe whitespace
   "\\(def[ \t]+"                       ; function definitions start with def
   "\\([a-zA-Z0-9_]+\\)"                ;   name is here
					;   function arguments...
   "[ \t]*(\\([a-zA-Z0-9_=,\* \t\n]*\\))"
   "\\)"                                ; end of def
   "[ \t]*:"                            ; and then the :
   "\\)"                                ; >>methods and functions<<
   )
  "Regexp for Python methods/functions for use with the imenu package."
  )

(defvar imenu-example--python-method-no-arg-parens '(2 8)
  "Indicies into the parenthesis list of the regular expression for
python for use with imenu. Using these values will result in smaller
imenu lists, as arguments to functions are not listed.

See the variable imenu-example--python-show-method-args-p to for
information")

(defvar imenu-example--python-method-arg-parens '(2 7)
  "Indicies into the parenthesis list of the regular expression for
python for use with imenu. Using these values will result in large
imenu lists, as arguments to functions are listed.

See the variable imenu-example--python-show-method-args-p to for
information")

;; Note that in this format, this variable can still be used with the
;; imenu--generic-function. Otherwise, there is no real reason to have
;; it.
(defvar imenu-example--generic-python-expression
  (cons
   (concat 
    imenu-example--python-class-regexp
    "\\|"  ; or...
    imenu-example--python-method-regexp
    )
   imenu-example--python-method-no-arg-parens)
  "Generic Python expression which may be used directly with imenu by
setting the variable imenu-generic-expression to this value. Also, see
the function \\[imenu-example--create-python-index] for an alternate
way of finding the index.")

;; These next two variables are used when searching for the python
;; class/definitions. Just saving some time in accessing the
;; generic-python-expression, really.
(defvar imenu-example--python-generic-regexp)
(defvar imenu-example--python-generic-parens)

;;;
;;; CODE:
;;;

;; Note:
;; At first, I tried using some of the functions supplied by
;; python-mode to navigate through functions and classes, but after a
;; while, I decided dump it. This file is relatively self contained
;; and I liked it that.

;;;###autoload
(defun imenu-example--create-python-index ()
  "Interface function for imenu package to find all python classes and
functions/methods. Calls function
\\[imenu-example--create-python-index-engine]. See that function for
the details of how this works."
  (setq imenu-example--python-generic-regexp
	(car imenu-example--generic-python-expression))
  (setq imenu-example--python-generic-parens
	(if imenu-example--python-show-method-args-p
	    imenu-example--python-method-arg-parens
	  imenu-example--python-method-no-arg-parens))
  (goto-char (point-min))
  (imenu-example--create-python-index-engine nil))

(defun imenu-example--create-python-index-engine (&optional start-indent)
"Function for finding all definitions (classes, methods, or functions)
in a python file for the imenu package. 

Retuns a possibly nested alist of the form \(INDEX-NAME
 INDEX-POSITION). The second element of the alist may be an alist,
producing a nested list as in \(INDEX-NAME . INDEX-ALIST).

This function should not be called directly, as it calls itself
recursively and requires some setup. Rather this is the engine for the
function \\[imenu-example--create-python-index].

It works recursively by looking for all definitions at the current
indention level. When it finds one, it adds it to the alist. If it
finds a definition at a greater indentation level, it removes the
previous definition from the alist. In it's place it adds all
definitions found at the next indentation level. When it finds a
definition that is less indented then the current level, it retuns the
alist it has created thus far.

 The optional argument START-INDENT indicates the starting indentation
at which to continue looking for python classes, methods, or
functions. If this is not supplied, the function uses the indentation
of the first definition found. "
  (let ((index-alist '())
	(sub-method-alist '())
	looking-p
	def-name prev-name
	cur-indent def-pos
	(class-paren (first  imenu-example--python-generic-parens)) 
	(def-paren   (second imenu-example--python-generic-parens)))
    (setq looking-p
	  (re-search-forward imenu-example--python-generic-regexp
			     (point-max) t))
    (while looking-p
      (save-excursion
	;; used to set def-name to this value but generic-extract-name is
	;; new to imenu-1.14. this way it still works with imenu-1.11
	;;(imenu--generic-extract-name imenu-example--python-generic-parens))
	(let ((cur-paren (if (match-beginning class-paren)
			     class-paren def-paren)))
	  (setq def-name
		(buffer-substring (match-beginning cur-paren)
				  (match-end  cur-paren))))
	(beginning-of-line)
	(setq cur-indent (current-indentation)))

      ;; HACK: want to go to the correct definition location. Assuming
      ;; here that there are only two..which is true for python.
      (setq def-pos
	    (or  (match-beginning class-paren)
		 (match-beginning def-paren)))

      ; if we don't have a starting indent level, take this one
      (or start-indent
	  (setq start-indent cur-indent))

      ; if we don't have class name yet, take this one
      (or prev-name
	  (setq prev-name def-name))

      ;; what level is the next definition on? 
      ;; must be same, deeper or shallower indentation
      (cond

       ;; at the same indent level, add it to the list...
       ((= start-indent cur-indent)
	(push (cons def-name def-pos) index-alist))

       ;; deeper indented expression, recur...
       ((< start-indent cur-indent)

	;; the point is currently on the expression we're supposed to
	;; start on, so go back to the last expression. The recursive
	;; call will find this place again and add it to the correct
	;; list
	(re-search-backward imenu-example--python-generic-regexp
			    (point-min) 'move)
	(setq sub-method-alist (imenu-example--create-python-index-engine
				cur-indent))

	(if sub-method-alist
	    ;; we put the last element on the index-alist on the start
	    ;; of the submethod alist so the user can still get to it.
	    (let ((save-elmt (pop index-alist)))
	      (push (cons (imenu-create-submenu-name prev-name)
			  (cons save-elmt sub-method-alist))
		    index-alist))))

       ;; found less indented expression, we're done.
       (t 
	(setq looking-p nil)
	(re-search-backward imenu-example--python-generic-regexp 
			    (point-min) t)))
      (setq prev-name def-name)
      (and looking-p
	   (setq looking-p
		 (re-search-forward imenu-example--python-generic-regexp
				    (point-max) 'move))))
    (nreverse index-alist)))

(provide 'pyimenu)

;;; PyImenu.EL ends here