cgit.sxemacs.org Git - packages/blob - xemacs-packages/oo-browser/br-python.el

   1 ;;!emacs
   2 ;;
   3 ;; FILE:         br-python.el
   4 ;; SUMMARY:      Support routines for Python inheritance browsing.
   5 ;; USAGE:        GNU Emacs Lisp Library
   6 ;; KEYWORDS:     oop, tools, python
   7 ;;
   8 ;; AUTHOR:       Harri Pasanen / Bob Weiner
   9 ;;               based on Smalltalk and C++ OO-Browsers
  10 ;; ORG:          BeOpen.com
  11 ;;
  12 ;; ORIG-DATE:    5-Apr-96
  13 ;; LAST-MOD:     10-May-01 at 17:39:56 by Bob Weiner
  14 ;;
  15 ;; Copyright (C) 1996, 1997, 1998  BeOpen.com
  16 ;; See the file BR-COPY for license information.
  17 ;;
  18 ;; This file is part of the OO-Browser.
  19 ;;
  20 ;; DESCRIPTION:
  21 ;;
  22 ;;   See 'python-class-def-regexp' for regular expression that matches class
  23 ;;   definitions.
  24 ;;
  25 ;; DESCRIP-END.
  26
  27 ;;; ************************************************************************
  28 ;;; Other required Elisp libraries
  29 ;;; ************************************************************************
  30
  31 (mapcar 'require '(br-lib hypb br-c-ft))
  32
  33 ;;; ************************************************************************
  34 ;;; User visible variables
  35 ;;; ************************************************************************
  36
  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
  40 group of classes.")
  41
  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.")
  46
  47 (defconst python-narrow-view-to-class nil
  48  "*Non-nil means narrow buffer to just the matching class definition when displayed.")
  49
  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.")
  53
  54 ;;; ************************************************************************
  55 ;;; Internal functions
  56 ;;; ************************************************************************
  57
  58 (defun python-get-classes-from-source (filename &optional skip-tags
  59                                                 skip-tags-cleanup)
  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))
  64         (case-fold-search)
  65         (signatures)
  66         classes class has-parents parents parent-cons)
  67     (if no-kill
  68         (set-buffer no-kill)
  69       (funcall br-view-file-function filename))
  70     (save-restriction
  71       (save-excursion
  72         (widen)
  73         (goto-char (point-min))
  74         (or skip-tags
  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))
  81                 parent-cons
  82                 (cons
  83                  ;; Return parents as a list, or nil if no parents
  84                  (if has-parents (python-scan-parents))
  85                  class))
  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))
  92             (or skip-tags
  93                 ;; Scan members defined within class
  94                 (setq signatures
  95                       (append
  96                        signatures
  97                        (python-scan-features-in-class class (point)
  98                                                       (python-locate-class-end))
  99                        ))))))
 100       (if skip-tags
 101           nil
 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)))))
 106
 107
 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)
 113         parent)
 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)
 117                                         (match-end 3))
 118             parent-list (cons parent parent-list)))
 119     (nreverse parent-list)))
 120
 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."
 124   (save-excursion
 125     (let ((result-point (point-max)))
 126       (if (re-search-forward
 127            (concat "^[" python-identifier-chars "]") nil t)
 128           (progn
 129             (setq result-point (- (match-beginning 0) 1))
 130             (if (python-within-string-p)
 131                 (python-locate-class-end)
 132               result-point))
 133         result-point))))
 134
 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)
 139         (car (car (br-rassoc
 140                    class-name
 141                    (cdr (python-get-classes-from-source filename)))))))
 142
 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
 146 with the class."
 147   (cdr paths-htable-elt))
 148
 149 (defun python-set-case (type)
 150   "Return string TYPE identifier for use as a class name."
 151   type)
 152
 153 (defun python-set-case-type (class-name)
 154   "Return string CLASS-NAME for use as a type identifier."
 155   class-name)
 156
 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)
 160       (let ((opoint))
 161         (while (progn (setq opoint (point))
 162                       ;; To previous line
 163                       (if (zerop (forward-line -1))
 164                           (cond ((looking-at "[ \t]*\\(#\\|$\\)"))
 165                                 (t nil)))))
 166         (goto-char opoint)
 167         ;; Skip past whitespace
 168         (skip-chars-forward " \t\n\r\f")
 169         (beginning-of-line))
 170     ;; Assume this is a buffer of C/C++/Java code.
 171     (br-c-to-comments-begin)))
 172
 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
 177 regular expression."
 178   (concat python-class-name-before
 179           (if regexp-flag class (regexp-quote class))
 180           "[ \t\n\r]*[:\(]"))
 181
 182 ;;; Package and module support
 183
 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))))
 188
 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))
 195
 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))))
 203
 204 (defun python-search-directory (dir files)
 205   (mapcar
 206    (function
 207     (lambda (f)
 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)
 220                          br-paths-alist
 221                          (if classes
 222                              (cons (cons classes f) br-paths-alist)
 223                            br-paths-alist)
 224                          br-parents-alist (if parents
 225                                               (append br-parents-alist
 226                                                       parents)
 227                                             br-parents-alist)))
 228           ;; else
 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)))
 233           (sit-for 1)))))
 234    ;; List of files potentially containing classes.
 235    (delq nil
 236          (mapcar
 237           (function
 238            (lambda (f)
 239              (and (string-match br-src-file-regexp f)
 240                   (not (file-directory-p f))
 241                   f)))
 242           files))))
 243
 244 ;;; ************************************************************************
 245 ;;; Internal variables
 246 ;;; ************************************************************************
 247
 248 (defconst python-identifier-chars "a-zA-Z0-9_"
 249   "String of chars and char ranges that may be used within a Python identifier.")
 250
 251 (defconst python-identifier (concat "\\([a-zA-Z_][" python-identifier-chars "]*\\)")
 252   "Regular expression matching a Python identifier.")
 253
 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.")
 258
 259 (defconst python-parent-class-name
 260   (concat "[ \t]*"
 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.")
 265
 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.")
 269
 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.")
 273
 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
 278 expression 2.")
 279
 280
 281 (defconst python-lang-prefix "python-"
 282  "Prefix string that starts \"br-python.el\" symbol names.")
 283
 284 (defconst python-src-file-regexp ".\\.py$"
 285   "Regular expression matching a unique part of Python source file name and no others.")
 286
 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
 290 this list.")
 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
 294 this list.")
 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.")
 299
 300
 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.")
 308
 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
 316 list.")
 317
 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.")
 322
 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.")
 326
 327 (provide 'br-python)