4 ;; SUMMARY: Support routines for Python inheritance browsing.
5 ;; USAGE: GNU Emacs Lisp Library
6 ;; KEYWORDS: oop, tools, python
8 ;; AUTHOR: Harri Pasanen / Bob Weiner
9 ;; based on Smalltalk and C++ OO-Browsers
12 ;; ORIG-DATE: 5-Apr-96
13 ;; LAST-MOD: 10-May-01 at 17:39:56 by Bob Weiner
15 ;; Copyright (C) 1996, 1997, 1998 BeOpen.com
16 ;; See the file BR-COPY for license information.
18 ;; This file is part of the OO-Browser.
22 ;; See 'python-class-def-regexp' for regular expression that matches class
27 ;;; ************************************************************************
28 ;;; Other required Elisp libraries
29 ;;; ************************************************************************
31 (mapcar 'require '(br-lib hypb br-c-ft))
33 ;;; ************************************************************************
34 ;;; User visible variables
35 ;;; ************************************************************************
37 (defvar python-lib-search-dirs nil
38 "List of directories below which Python Library source files are found.
39 Subdirectories of Library source are also searched. A Library is a stable
42 (defvar python-sys-search-dirs nil
43 "List of directories below which Python System source files are found.
44 Subdirectories of System source are also searched. A System class is one
45 that is not yet reusable and is likely to change before release.")
47 (defconst python-narrow-view-to-class nil
48 "*Non-nil means narrow buffer to just the matching class definition when displayed.")
50 ;;; following is reserved for future, currently does not work
51 (defconst python-duplicate-classnames-across-modules nil
52 "*Non-nil means that the module name is prepended to class names.")
54 ;;; ************************************************************************
55 ;;; Internal functions
56 ;;; ************************************************************************
58 (defun python-get-classes-from-source (filename &optional skip-tags
60 "Scans FILENAME and returns cons of class list with parents-class alist.
61 Handles multiple inheritance. Assumes file existence and readability have
62 already been checked."
63 (let ((no-kill (get-file-buffer filename))
66 classes class has-parents parents parent-cons)
69 (funcall br-view-file-function filename))
73 (goto-char (point-min))
75 (progn (setq signatures (cons (python-module-tag filename)
76 (python-scan-features)))
77 (goto-char (point-min))))
78 (while (re-search-forward python-class-def-regexp nil t)
79 (setq has-parents (eq ?\( (following-char))
80 class (br-buffer-substring (match-beginning 1) (match-end 1))
83 ;; Return parents as a list, or nil if no parents
84 (if has-parents (python-scan-parents))
86 (if (python-within-string-p)
87 ;; ignore any class found and skip to the end of the string
88 (progn (re-search-forward python-multi-line-string-delimiter nil t)
89 (setq class nil parents nil))
90 (setq classes (cons class classes)
91 parents (cons parent-cons parents))
93 ;; Scan members defined within class
97 (python-scan-features-in-class class (point)
98 (python-locate-class-end))
102 (python-output-feature-tags filename signatures)
103 (or skip-tags-cleanup (br-feature-build-htables)))
104 (or no-kill (kill-buffer (current-buffer)))
105 (cons classes (delq nil parents)))))
108 (defun python-scan-parents ()
109 "Return list of parents names from a Python class definition.
110 Point must be after the '(' that begins the parent list and before the
111 first parent entry when this function is called."
112 (let ((parent-list) (again t)
114 (while (and again (re-search-forward python-parent-class-name nil t))
115 (setq again (eq ?, (following-char))
116 parent (br-buffer-substring (match-beginning 3)
118 parent-list (cons parent parent-list)))
119 (nreverse parent-list)))
121 (defun python-locate-class-end ()
122 "Look up the end of class. Point is assumed to be in the class definition.
123 Do this by looking up the first line that begins with python-identifier-chars."
125 (let ((result-point (point-max)))
126 (if (re-search-forward
127 (concat "^[" python-identifier-chars "]") nil t)
129 (setq result-point (- (match-beginning 0) 1))
130 (if (python-within-string-p)
131 (python-locate-class-end)
135 (defun python-get-parents-from-source (filename class-name)
136 "Scan source in FILENAME and return list of parents of CLASS-NAME.
137 Assume file existence has already been checked."
138 (or (null class-name)
141 (cdr (python-get-classes-from-source filename)))))))
143 (defun python-select-path (paths-htable-elt &optional feature-p)
144 "Select proper pathname from PATHS-HTABLE-ELT based upon value of optional FEATURE-P.
145 Selection is between path of class definition and path for features associated
147 (cdr paths-htable-elt))
149 (defun python-set-case (type)
150 "Return string TYPE identifier for use as a class name."
153 (defun python-set-case-type (class-name)
154 "Return string CLASS-NAME for use as a type identifier."
157 (defun python-to-comments-begin ()
158 "Skip back from current point past any preceding Python comments at the beginning of lines."
159 (if (eq major-mode 'python-mode)
161 (while (progn (setq opoint (point))
163 (if (zerop (forward-line -1))
164 (cond ((looking-at "[ \t]*\\(#\\|$\\)"))
167 ;; Skip past whitespace
168 (skip-chars-forward " \t\n\r\f")
170 ;; Assume this is a buffer of C/C++/Java code.
171 (br-c-to-comments-begin)))
173 (defun python-class-definition-regexp (class &optional regexp-flag)
174 "Return regexp to uniquely match the definition of CLASS name.
175 Matches past the signature end colon or the argument list open parenthesis.
176 Optional REGEXP-FLAG non-nil means CLASS has already been quoted for use in a
178 (concat python-class-name-before
179 (if regexp-flag class (regexp-quote class))
182 ;;; Package and module support
184 (defun python-module-name (&optional module-file)
185 "Return a module name derived from MODULE-FILE (a pathname) or from `buffer-file-name'."
186 (file-name-sans-extension (file-name-nondirectory
187 (or module-file buffer-file-name))))
189 (defun python-module-tag (module-file)
190 "Return a module tag string for MODULE-FILE."
191 (format "[module]%s%% %s%s"
192 python-type-tag-separator
193 (python-module-name module-file)
194 python-type-tag-separator))
196 (defun python-add-package (dir)
197 "Add Python package DIR to the feature tags file."
198 (python-output-feature-tags
199 dir (list (format "[package]%s%% %s%s"
200 python-type-tag-separator
201 (file-name-nondirectory (directory-file-name dir))
202 python-type-tag-separator))))
204 (defun python-search-directory (dir files)
208 (if (string-equal (file-name-nondirectory f) "__init__.py")
209 ;; Mark this as a package directory and skip this file.
210 (python-add-package dir)
211 (if (file-readable-p f)
212 (progn (message "Scanning %s in %s ..."
213 (file-name-nondirectory f)
214 (br-abbreviate-file-name
215 (or (file-name-directory f) default-directory)))
216 (setq paths-parents-cons
217 (br-get-classes-from-source f nil t)
218 classes (car paths-parents-cons)
219 parents (cdr paths-parents-cons)
222 (cons (cons classes f) br-paths-alist)
224 br-parents-alist (if parents
225 (append br-parents-alist
229 (message "(OO-Browser): Unreadable file: %s in %s"
230 (file-name-nondirectory f)
231 (br-abbreviate-file-name
232 (or (file-name-directory f) default-directory)))
234 ;; List of files potentially containing classes.
239 (and (string-match br-src-file-regexp f)
240 (not (file-directory-p f))
244 ;;; ************************************************************************
245 ;;; Internal variables
246 ;;; ************************************************************************
248 (defconst python-identifier-chars "a-zA-Z0-9_"
249 "String of chars and char ranges that may be used within a Python identifier.")
251 (defconst python-identifier (concat "\\([a-zA-Z_][" python-identifier-chars "]*\\)")
252 "Regular expression matching a Python identifier.")
254 (defconst python-global-name
255 (concat "[ \t]*" python-identifier "[ \t]*")
256 "Regular expression matching a single identifier within a 'global' statement.
257 Grouped expression 1 is matches the identifier.")
259 (defconst python-parent-class-name
261 "\\(" python-identifier "\\.\\)*" ; possible module name precedes
262 python-identifier "[ \t]*")
263 "Regular expression matching optional a single Python parent class.
264 Grouped expression 3 matches the parent class name.")
266 (defconst python-class-name-before "^[ \t]*class[ \t\n\r]+"
267 "Regexp preceding the class name in a class definition.
268 Note: this does not allow for nested classes.")
270 (defconst python-class-name-after
271 (concat "[ \t]*" python-parent-class-name "[ \t\n\r]*:")
272 "Regexp following the class name in a class definition.")
274 (defconst python-class-def-regexp
275 (concat python-class-name-before python-identifier "[ \t\n\r]*")
276 "Regular expression used to match to class definitions in source text.
277 Class name identifier is grouped expression 1. Parent identifier is grouped
281 (defconst python-lang-prefix "python-"
282 "Prefix string that starts \"br-python.el\" symbol names.")
284 (defconst python-src-file-regexp ".\\.py$"
285 "Regular expression matching a unique part of Python source file name and no others.")
287 (defvar python-children-htable nil
288 "Htable whose elements are of the form: (LIST-OF-CHILD-CLASSES . CLASS-NAME).
289 Used to traverse Python inheritance graph. 'br-build-children-htable' builds
291 (defvar python-parents-htable nil
292 "Htable whose elements are of the form: (LIST-OF-PARENT-CLASSES . CLASS-NAME).
293 Used to traverse Python inheritance graph. 'br-build-parents-htable' builds
295 (defvar python-paths-htable nil
296 "Htable whose elements are of the form: (LIST-OF-CLASS-NAMES . FILE-PATH).
297 FILE-PATH gives the location of classes found in LIST-OF-CLASS-NAMES.
298 'br-build-paths-htable' builds this list.")
301 (defvar python-lib-parents-htable nil
302 "Htable whose elements are of the form: (LIST-OF-PARENT-CLASSES . CLASS-NAME).
303 Only classes from stable software libraries are used to build the list.")
304 (defvar python-lib-paths-htable nil
305 "Htable whose elements are of the form: (LIST-OF-CLASS-NAMES . FILE-PATH).
306 FILE-PATH gives the location of classes found in LIST-OF-CLASS-NAMES.
307 Only classes from stable software libraries are used to build the list.")
309 (defvar python-sys-parents-htable nil
310 "Htable whose elements are of the form: (LIST-OF-PARENT-CLASSES . CLASS-NAME).
311 Only classes from systems that are likely to change are used to build the list.")
312 (defvar python-sys-paths-htable nil
313 "Alist whose elements are of the form: (LIST-OF-CLASS-NAMES . FILE-PATH).
314 FILE-PATH gives the location of classes found in LIST-OF-CLASS-NAMES.
315 Only classes from systems that are likely to change are used to build the
318 (defvar python-lib-prev-search-dirs nil
319 "Used to check if 'python-lib-classes-htable' must be regenerated.")
320 (defvar python-sys-prev-search-dirs nil
321 "Used to check if 'python-sys-classes-htable' must be regenerated.")
323 (defvar python-env-spec nil
324 "Non-nil value means Environment specification has been given but not yet built.
325 Nil means current Environment has been built, though it may still require updating.")