cgit.sxemacs.org Git - packages/blob - xemacs-packages/python-modes/pydoc.el.upstream

   1 ;; LCD-ENTRY:    pydoc.el|Bob Weiner|bob@deepware.com|Interface to pydoc Python documentation viewer|Date|04/23/2001|01.02|www.deepware.com/pub/python
   2 ;;
   3 ;; FILE:         pydoc.el
   4 ;; SUMMARY:      Interface to pydoc Python documentation viewer
   5 ;; USAGE:        Autoloaded XEmacs Lisp Library, use {C-c M-h} to invoke
   6 ;; KEYWORDS:     help, languages, oop, tools
   7 ;;
   8 ;; AUTHOR:       Bob Weiner
   9 ;; ORG:          Deepware
  10 ;; E-MAIL:       bob@deepware.com
  11 ;;
  12 ;; ORIG-DATE:    18-Apr-01 at 19:11:27
  13 ;; LAST-MOD:     23-Apr-01 at 23:59:46 by Bob Weiner
  14 ;;
  15 ;; Copyright (C) 2001  Bob Weiner
  16 ;; Licensed under the Python license version 2.0 or higher.
  17 ;;
  18 ;; This file is part of InfoDock, available from:
  19 ;;   www.sourceforge.net/projects/infodock
  20 ;;
  21 ;; DESCRIPTION:
  22 ;;
  23 ;;   Globally adds key binding {C-c M-h} (pydoc-commands) which
  24 ;;   displays a menu of commands for interacting with the pydoc Python
  25 ;;   documentation viewer library.  See the documentation of
  26 ;;   `pydoc-menu-help' for details on each available command.
  27 ;;
  28 ;;   NOTE: You *must* install the following for pydoc.el to work:
  29 ;;
  30 ;;     python-mode.el 4.1.1 or higher as your Python editing mode (included
  31 ;;     in the pydoc.el distribution)
  32 ;;
  33 ;;     pydoc_lisp.py in your Python site-packages directory (unless
  34 ;;       these functions are already integrated into pydoc.py)
  35 ;;
  36 ;;     set the environment variable PYTHONDOCS to the root directory
  37 ;;       of your Python html documentation tree, for example:
  38 ;;       export PYTHONDOCS=$HOME/Python-2.1/Doc/html/
  39 ;;     and then startup your editor (otherwise, the environment variable
  40 ;;     setting won't be inherited by the editor and some commands will not
  41 ;;     work).
  42 ;;
  43 ;;   Install and byte-compile pydoc.el in one of your load-path directories
  44 ;;   and then either set it to autoload or do a (require 'pydoc) in your
  45 ;;   editor initialization file.  Then invoke it via the menu key binding.
  46 ;;
  47 ;; DESCRIP-END.
  48
  49 ;;; ************************************************************************
  50 ;;; Other required Elisp libraries
  51 ;;; ************************************************************************
  52
  53 (require 'python-mode)
  54
  55 ;; Ensure that the user has a python-mode version which supports pydoc.el.
  56 (if (string-lessp py-version "$Revision: 1.1 $")
  57     (error "(pydoc): you must upgrade from python-mode.el %s to 4.1.1 (or higher)"
  58            (if (string-match "[0-9.]+" py-version)
  59                (match-string 0 py-version) py-version)))
  60
  61 (provide 'pydoc)
  62
  63 ;;; ************************************************************************
  64 ;;; Public variables
  65 ;;; ************************************************************************
  66
  67 (defvar pydoc-version "01.01"
  68   "Release version of the Emacs Lisp interface to pydoc.")
  69
  70 ;; Provide easy access to (pydoc-commands) everywhere since the user may want
  71 ;; to reference Python doc when in a Python help buffer, a documentation file,
  72 ;; etc.  Use {C-c M-h} instead of {C-c C-h} for this next binding since
  73 ;; {C-c C-h} is an important key in InfoDock's outline-minor-mode which is
  74 ;; often used under python-mode, so this avoids conflicts.
  75
  76 ;;;###autoload
  77 (global-set-key "\C-c\M-h" 'pydoc-commands)
  78
  79 (defvar pydoc-buffer-prefix "Py: "
  80   "Prefix string attached to all pydoc display buffers.")
  81
  82 (defvar pydoc-xrefs-prefix "^Related help topics:"
  83   "Prefix regexp output before comma separated pydoc help section names.")
  84
  85 ;;; ************************************************************************
  86 ;;; Private variables
  87 ;;; ************************************************************************
  88
  89 (defvar pydoc-cmd-alist
  90   '(("A)propos"         . pydoc-apropos)
  91     ("H)elp"            . pydoc-help)
  92     ("K)eyword"         . pydoc-keywords)
  93     ("M)odule"          . pydoc-modules)
  94     ("P)ackage"         . pydoc-packages)
  95     ("T)opic"           . pydoc-topics)
  96     ("X)ref"            . pydoc-xrefs))
  97   "Association list of (HELP-CMD-PROMPT . CMD) elements for pydoc commands.")
  98
  99 (defvar pydoc-alist nil
 100   "Association list of (list-name . alist) elements used to build prompt completion tables.")
 101
 102 (defvar pydoc-menu-mode-map nil
 103   "Keymap containing pydoc-menu commands.")
 104
 105 (defvar pydoc-menu-special-keys '(?\C-g ?? ?\C-i ?\C-j ?\C-m ?\ ))
 106
 107 (if pydoc-menu-mode-map
 108     nil
 109   (setq pydoc-menu-mode-map (make-keymap))
 110   (suppress-keymap pydoc-menu-mode-map)
 111   (define-key pydoc-menu-mode-map
 112     (car (where-is-internal 'keyboard-quit)) 'pydoc-menu-enter)
 113   (mapcar #'(lambda (key)
 114               (define-key pydoc-menu-mode-map (char-to-string key) 'pydoc-menu-enter))
 115           pydoc-menu-special-keys)
 116   (let ((i 33))
 117     (while (<= i 127)
 118       (define-key pydoc-menu-mode-map (char-to-string i) 'pydoc-menu-enter)
 119       (setq i (1+ i)))))
 120
 121 ;;; ************************************************************************
 122 ;;; Commands
 123 ;;; ************************************************************************
 124
 125 ;;;###autoload
 126 (defun pydoc-commands (&optional init-flag)
 127   "Display a menu of commands for interacting with the pydoc Python documentation viewer library.
 128 With optional prefix arg INIT-FLAG, reinitializes the pydoc completion
 129 tables which includes the list of available Python modules.
 130 See the documentation for `pydoc-menu-help' for a description of the
 131 available commands."
 132   (interactive "P")
 133   (if (or init-flag (null pydoc-alist))
 134       (pydoc-initialize))
 135   (call-interactively (pydoc-select-command)))
 136
 137 ;;;###autoload
 138 (defun pydoc-apropos (&optional argument)
 139   "Call the Python module apropos function with optional ARGUMENT and display the output.
 140 ARGUMENT defaults to an identifier near point.
 141 The apropos function finds matches for ARGUMENT within the first line of
 142 module or package doc strings."
 143   (interactive)
 144   (if (not argument)
 145       (setq argument (pydoc-read-argument "Python module/package apropos: ")))
 146   (pydoc-call "apropos" (format "'%s'" argument) (concat "apropos " argument)))
 147
 148 ;;;###autoload
 149 (defun pydoc-help (&optional argument)
 150   "Call the Python help function with optional ARGUMENT and display the output.
 151 ARGUMENT defaults to an identifier near point.
 152 ARGUMENT is resolved as a name in any present Python namespace; use
 153 single 'quotes' to send ARGUMENT as a Python literal string."
 154   (interactive)
 155   (if (not argument)
 156       (setq argument (pydoc-read-argument "Python help (name or 'string'): ")))
 157   (pydoc-call "help" argument argument))
 158
 159 ;;;###autoload
 160 (defun pydoc-keywords (argument)
 161   "Prompt with completion for a Python keyword ARGUMENT and display its documentation."
 162   (interactive
 163    (list
 164     (let ((completion-ignore-case t))
 165       (completing-read "Python keyword help (RET for all): "
 166                        (cdr (assoc "keywords" pydoc-alist))
 167                        nil t))))
 168   (if (member argument '(nil ""))
 169       (setq argument "keywords"))
 170   (pydoc-call "help" (format "'%s'" argument) argument))
 171
 172 ;;;###autoload
 173 (defun pydoc-modules (argument)
 174   "Prompt with completion for a Python module/package ARGUMENT and display its documentation."
 175   (interactive
 176    (list
 177     (let ((completion-ignore-case t))
 178       (completing-read "Python module/package help (RET for all): "
 179                        (cdr (assoc "modules" pydoc-alist))
 180                        nil t))))
 181   (if (member argument '(nil ""))
 182       (setq argument "modules"))
 183   (if (string-match "\\`Pkg-" argument)
 184       (setq argument (substring argument (match-end 0))))
 185   (pydoc-call "help" (format "'%s'" argument) argument))
 186
 187 ;;;###autoload
 188 (defun pydoc-packages (argument)
 189   "Prompt with completion for a Python package ARGUMENT and display its documentation."
 190   (interactive
 191    (list
 192     (let ((completion-ignore-case t))
 193       (completing-read "Python package help (RET for all): "
 194                        (delq nil
 195                              (mapcar
 196                               #'(lambda (entry)
 197                                   (if (string-match "\\`Pkg-" entry)
 198                                       (list (substring entry (match-end 0)))))
 199                               (mapcar 'car (cdr (assoc "modules" pydoc-alist)))))
 200                        nil t))))
 201   (if (member argument '(nil ""))
 202       (setq argument "modules"))
 203   (if (string-match "\\`Pkg-" argument)
 204       (setq argument (substring argument (match-end 0))))
 205   (pydoc-call "help" (format "'%s'" argument) argument))
 206
 207 ;;;###autoload
 208 (defun pydoc-topics (argument)
 209   "Prompt with completion for a Python topic ARGUMENT and display its documentation."
 210   (interactive
 211    (list
 212     (let ((completion-ignore-case t))
 213       (completing-read "Python topic help (RET for all): "
 214                        (cdr (assoc "topics" pydoc-alist))
 215                        nil t))))
 216   (if (member argument '(nil ""))
 217       (setq argument "topics")
 218     (setq argument (upcase argument)))
 219   (pydoc-call "help" (format "'%s'" argument) argument))
 220
 221 ;;;###autoload
 222 (defun pydoc-xrefs ()
 223   "Display xref at point or prompt user with completion and display chosen xref.
 224 Xrefs are terms which follow the `pydoc-xrefs-prefix' regular expression."
 225   (interactive)
 226   (cond ((save-excursion
 227            (beginning-of-line)
 228            (looking-at pydoc-xrefs-prefix))
 229          ;; On an xref line
 230          (if (>= (point) (match-end 0))
 231              ;; After prefix, within an xref
 232              (pydoc-display-xref)
 233            ;; Prompt for with completion and display xref
 234            (pydoc-display-xref
 235             (save-excursion
 236               (goto-char (match-end 0))
 237               (pydoc-choose-xref "Display xref: ")))))
 238
 239         ;; Move to last xref line if any in buffer
 240         ((pydoc-xrefs-p)
 241          ;; Prompt for with completion and display xref
 242          (pydoc-display-xref
 243           (save-excursion
 244             (goto-char (match-end 0))
 245             (pydoc-choose-xref "Display xref: "))))
 246
 247         (t (error "(pydoc): No cross-references in this buffer"))))
 248
 249 ;;; ************************************************************************
 250 ;;; Public functions
 251 ;;; ************************************************************************
 252
 253 (defun pydoc-call (func-name argument buf-name-suffix)
 254   "Call the pydoc function FUNC-NAME with ARGUMENT (a string) and display in Py: BUF-NAME-SUFFIX."
 255   (let ((wind-config (current-window-configuration))
 256         (output-buf-name
 257          (py-execute-string
 258           (format
 259            "if not vars().has_key('%s'):\n    from pydoc import %s\n\n%s(%s)\n"
 260            func-name func-name func-name argument)))
 261         (async-process (pydoc-async-output-p))
 262         input-buf-name)
 263     (setq input-buf-name (if async-process
 264                              (buffer-name (process-buffer async-process))
 265                            " *Python Command*"))
 266     (if (buffer-live-p (get-buffer input-buf-name))
 267         (bury-buffer input-buf-name))
 268     (if (or (null output-buf-name)
 269             ;; In earlier versions of python-mode.el, py-execute-string does
 270             ;; not return a buffer name.
 271             (not (stringp output-buf-name))
 272             (not (buffer-live-p (get-buffer output-buf-name)))
 273             (and async-process (not (pydoc-wait-for-output input-buf-name 10.0))))
 274         (message "(\"%s(%s)\" finished with no output)" func-name argument)
 275       (set-window-configuration wind-config)
 276       (bury-buffer output-buf-name)
 277       (set-buffer output-buf-name)
 278       (goto-char (point-max)) ;; User may have moved point elsewhere.
 279       (let ((output-end
 280              ;; Skip any trailing Python prompt
 281              (save-excursion (beginning-of-line) (point)))
 282             (output-start (pydoc-output-start))
 283             (display-buf))
 284         (if (save-excursion
 285               (goto-char (point-max))
 286               (forward-line -1)
 287               (looking-at "^NameError:"))
 288             (progn (switch-to-buffer (car (buffer-list)))
 289                    (error "(pydoc): %s(%s) failed to find any matching term"
 290                           func-name argument))
 291           (setq display-buf (get-buffer-create
 292                              (concat pydoc-buffer-prefix buf-name-suffix)))
 293           (set-buffer display-buf)
 294           (toggle-read-only 0)
 295           (erase-buffer)
 296           (insert-buffer-substring output-buf-name output-start output-end)
 297           (goto-char (point-min))
 298           (set-buffer-modified-p nil)
 299           (message "")
 300           (help-mode)
 301           (pydoc-kill-async-output output-buf-name async-process)
 302           (pop-to-buffer display-buf))))))
 303
 304 (defun pydoc-display-apropos-entry ()
 305   "Detect module/package names in pydoc apropos buffer entries and display their code.
 306 Each module/package name must be at the beginning of the line
 307 and must be followed by a space, dash and then another space."
 308   (interactive)
 309   (if (string-match (concat "\\`" (regexp-quote pydoc-buffer-prefix)
 310                             "apropos ")
 311                     (buffer-name))
 312       (save-excursion
 313         (beginning-of-line)
 314         (if (looking-at "\\([^][-(){}<>'`\"/*+&^%$#@!=|?,~ \t\n\r]+\\) - ")
 315             (let* ((entry (buffer-substring
 316                            (match-beginning 1) (match-end 1)))
 317                    (path (pydoc-pathname entry)))
 318               (if (and path (file-exists-p path))
 319                   (find-file-other-window path)))))))
 320
 321 (defun pydoc-pathname (module-identifier)
 322   "Return the filename or package directory where MODULE-IDENTIFIER is defined, else nil."
 323   (setq module-identifier
 324         (replace-in-string module-identifier "\\."
 325                            (char-to-string directory-sep-char) t))
 326   (or (locate-file module-identifier (pydoc-paths-list) ".py:.pyc:.pyo:.pyd")
 327       ;; May be a package directory
 328       (locate-data-directory module-identifier (pydoc-paths-list))))
 329
 330 ;;; ************************************************************************
 331 ;;; Private functions
 332 ;;; ************************************************************************
 333
 334 (defun pydoc-commands-dialog-box (dialog-box)
 335   "Prompt user with DIALOG-BOX and return selected value.
 336 Assumes caller has checked that `dialog-box' function exists."
 337   (let ((echo-keystrokes 0)
 338         event-obj
 339         event)
 340     ;; Add cmd-help and cancel buttons to dialog box.
 341     (setq dialog-box (append dialog-box
 342                              (list nil '["Cmd-Help" (pydoc-menu-help) t]
 343                                    '["Cancel" 'keyboard-quit t])))
 344     (popup-dialog-box dialog-box)
 345     (catch 'pydoc-done
 346       (while t
 347         (setq event (next-command-event event)
 348               event-obj (event-object event))
 349         (cond ((and (menu-event-p event)
 350                     (memq event-obj '(abort menu-no-selection-hook)))
 351                (signal 'quit nil))
 352               ((button-release-event-p event) ;; don't beep twice
 353                nil)
 354               ((menu-event-p event)
 355                (throw 'pydoc-done (eval event-obj)))
 356               (t
 357                (beep)
 358                (message "Please answer the dialog box.")))))))
 359
 360 (defun pydoc-default-argument ()
 361   "Return a default identifier argument near point."
 362   (require 'etags)
 363   ;; Include periods as symbol constituents but remove any trailing period.
 364   (let* ((period-syntax (char-to-string (char-syntax ?\.)))
 365          (default (unwind-protect
 366                       (progn
 367                         (modify-syntax-entry ?\. "_")
 368                         (find-tag-default))
 369                     (modify-syntax-entry ?\. period-syntax))))
 370     (if (and (stringp default) (string-match "\\.+\\'" default))
 371         (setq default (substring default 0 (match-beginning 0))))
 372     default))
 373
 374 (defun pydoc-initialize()
 375   (message "Please wait a moment while the Python help system is initialized...")
 376   (let (output-buf)
 377     (save-window-excursion
 378       ;; Start a Python interpreter if not already running.
 379       (py-shell)
 380       (pydoc-wait-for-output (current-buffer) 3.0)
 381       (setq output-buf
 382             (py-execute-string
 383              "if not vars().has_key('pydoc_lisp'):
 384     import pydoc_lisp
 385
 386 pydoc_lisp.pydoc_output_lisp()
 387 "))
 388       (setq pydoc-alist (pydoc-lisp-read-result output-buf)))
 389     (if (member pydoc-alist '(nil None Traceback))
 390         (progn
 391           (setq pydoc-alist nil)
 392           (pop-to-buffer output-buf)
 393           (error "(pydoc): Initialization failed, Python did not output Lisp lists"))
 394       (pydoc-kill-async-output output-buf (pydoc-async-output-p))
 395       ;; Normalize Python search paths and make a regular list, not an alist
 396       (let ((paths (assoc "paths" pydoc-alist)))
 397         (setcdr paths (mapcar 'file-name-as-directory
 398                               (mapcar 'car (cdr paths)))))
 399       (message ""))))
 400
 401 (defun pydoc-lisp-read-result (result-buf)
 402   "Read and return the most recent python output in RESULT-BUF as a Lisp expression.
 403 If a timeout occurs before the expression is read, then return nil."
 404   (save-excursion
 405     (if (pydoc-wait-for-output result-buf 5.0)
 406         (progn (goto-char (pydoc-output-start))
 407                (read (current-buffer)))
 408       nil)))
 409
 410 (defun pydoc-output-start ()
 411   "Return the character position start of the most recent Python output."
 412   (save-excursion
 413     ;; Skip any trailing Python prompt
 414     (forward-line 0) ;; to bol
 415     (if (re-search-backward "^>>> " nil t)
 416         (if (not (zerop (forward-line 1)))
 417             (goto-char (point-max)))
 418       (goto-char (point-min)))
 419     (point)))
 420
 421 (defun pydoc-read-argument (prompt)
 422   "Read and return a string argument using PROMPT."
 423   (let* ((default (pydoc-default-argument))
 424          (argument
 425           (read-string
 426            (if default
 427                (format "%s(default %s) " prompt default)
 428              prompt))))
 429     (if (member argument '(nil ""))
 430         default
 431       argument)))
 432
 433 (defun pydoc-select-command ()
 434   "Interactively select and return a pydoc command to run."
 435   (let ((cmd-prompt)
 436         (cmd)
 437         ;; Use dialog box if last user event involved the mouse.
 438         (use-dialog-box (and (fboundp 'popup-dialog-box)
 439                              (fboundp 'button-press-event-p)
 440                              (or (button-press-event-p last-command-event)
 441                                  (button-release-event-p last-command-event)
 442                                  (menu-event-p last-command-event)))))
 443     ;; Create a prompt numbering each command available.
 444     (setq cmd-prompt
 445           (if use-dialog-box
 446               (mapcar
 447                #'(lambda (name-and-cmd)
 448                    (vector (car name-and-cmd)
 449                            (list 'quote (cdr name-and-cmd))
 450                            't))
 451                pydoc-cmd-alist)
 452             (concat
 453              "Pydoc>  "
 454              (mapconcat 'identity (mapcar 'car pydoc-cmd-alist) "  ")
 455              ": ")))
 456     ;; Prompt user.
 457     (if use-dialog-box
 458         (setq cmd (pydoc-commands-dialog-box
 459                    (cons "Choose pydoc command (or choose Cmd-Help for help on commands): " cmd-prompt)))
 460       ;; Otherwise, prompt in the minibuffer.
 461       (let ((item-keys (mapcar #'(lambda (item) (aref item 0))
 462                                (mapcar 'car pydoc-cmd-alist)))
 463             key)
 464         (while (and (not (memq (setq key (upcase
 465                                           (string-to-char
 466                                            (read-from-minibuffer
 467                                             "" cmd-prompt pydoc-menu-mode-map))))
 468                                item-keys))
 469                     (not (memq key pydoc-menu-special-keys)))
 470           (beep)
 471           (discard-input))
 472         (if (eq key ?\C-g)
 473             ;; abort
 474             (keyboard-quit))
 475         (if (memq key pydoc-menu-special-keys)
 476             (setq cmd (pydoc-menu-help))
 477           (setq cmd (cdr (nth (- (length pydoc-cmd-alist)
 478                                  (length (memq key item-keys)))
 479                               pydoc-cmd-alist))))))
 480     cmd))
 481
 482 ;;; Asynchronous handling
 483 (defun pydoc-async-output-p ()
 484   "Return the running asynchronous process for Python code evaluation or nil if none."
 485   (let ((proc (and (stringp py-which-bufname)
 486                    (get-process py-which-bufname))))
 487     (and proc (eq (process-status proc) 'run) proc)))
 488
 489 (defun pydoc-kill-async-output (output-buf async-process)
 490   (if async-process
 491       (progn
 492         (set-buffer output-buf)
 493         ;; Remove output so it doesn't clog up the interpreter buffer.
 494         (comint-kill-output))))
 495
 496 (defun pydoc-wait-for-output (buffer timeout)
 497   "Move to BUFFER and wait a maximum of TIMEOUT seconds or until Python command execution ends.
 498 Python command execution ends when Python returns a top-level prompt.
 499 Return t if waited less than TIMEOUT time (and thus received full output)."
 500   (set-buffer buffer)
 501   (goto-char (point-max)) ;; User may have moved point elsewhere.
 502   (let ((time-waited 0.0)
 503         (wait-time 0.1))
 504     (while (and (< time-waited timeout)
 505                 (not (save-excursion
 506                        (forward-line 0) ;; to bol
 507                        (looking-at ">>> \\'"))))
 508       (sleep-for wait-time)
 509       (setq time-waited (+ time-waited wait-time)))
 510     (< time-waited timeout)))
 511
 512
 513 ;;; Cmd menu handling
 514 (defun pydoc-menu-enter (&optional char-str)
 515   "Uses CHAR-STR or last input character as minibuffer argument."
 516   (interactive)
 517   (let ((input (or char-str (aref (recent-keys) (1- (length (recent-keys))))))
 518         (case-fold-search t))
 519     (cond
 520      ;; GNU Emacs 19 or above
 521      ((and (not (string-match "XEmacs" emacs-version))
 522            ;; Version 19 and above.
 523            (string-lessp "19" emacs-version))
 524       (and (not (integerp input))
 525            (eventp input)
 526            (setq input (event-basic-type input))))
 527      ((string-match "XEmacs" emacs-version)
 528       (if (eventp input)
 529           (setq input (event-to-character input)))))
 530     (erase-buffer)
 531     (insert input))
 532   (exit-minibuffer))
 533
 534 (defun pydoc-menu-help ()
 535   "Type one of the following characters:
 536
 537 a   - A)propos <term>    - list modules/packages with <term> in their first line doc strings
 538 h   - H)elp <term>       - display doc for name <term> or string literal '<term>'
 539 k   - K)eyword <keyword> - with completion, display doc for a Python <keyword>
 540 m   - M)odule <name>     - with completion, display doc for a Python module <name>
 541 p   - P)ackage <name>    - with completion, display doc for a Python package <name>
 542 t   - T)opic <topic>     - with completion, display Python reference doc for <topic>
 543 x   - X)ref <term>       - with completion, display doc for a pydoc cross-reference
 544
 545 ?   - show this help
 546 C-g - abort from menu"
 547   (interactive)
 548   (save-window-excursion
 549     (switch-to-buffer "*Help*")
 550     (setq buffer-read-only nil)
 551     (erase-buffer)
 552     (insert (documentation 'pydoc-menu-help))
 553     (goto-char (point-min))
 554     (pydoc-select-command)))
 555
 556 ;;; Pathname handling
 557 (defun pydoc-paths-list ()
 558   (cdr (assoc "paths" pydoc-alist)))
 559
 560
 561 ;;; Xref handling
 562 (defun pydoc-choose-xref (prompt &optional xrefs-alist)
 563   (or xrefs-alist (setq xrefs-alist (pydoc-xrefs-alist)))
 564   (if (null xrefs-alist)
 565       (error "(pydoc): No cross-references in this buffer")
 566     (let ((completion-ignore-case t)
 567           (default (pydoc-default-argument))
 568           (result))
 569       (if (not (assoc default xrefs-alist))
 570           (setq default nil))
 571       (while (not result)
 572         (setq result (completing-read
 573                       (if default
 574                           (format "%s(default %s) " prompt default)
 575                         prompt)
 576                       xrefs-alist nil t))
 577         (if (string-equal result "")
 578             (if default
 579                 (setq result default)
 580               (beep)
 581               (setq result nil))))
 582       result)))
 583
 584 (defun pydoc-delete-space (string)
 585   "Delete any leading and trailing space from STRING and return the STRING."
 586   (if (string-match "\\`[ \t\n\r\f]+" string)
 587       (setq string (substring string (match-end 0))))
 588   (if (string-match "[ \t\n\r\f]+\\'" string)
 589       (setq string (substring string 0 (match-beginning 0))))
 590   string)
 591
 592 (defun pydoc-display-xref (&optional xref)
 593   "Displays optional XREF (or prompts for and then displays it).
 594 Signals an error when there are no xrefs within the current buffer."
 595   (interactive)
 596   (if (member xref '(nil ""))
 597       ;; Triggers an error if there are no xrefs.
 598       (setq xref (pydoc-choose-xref "Display xref: ")))
 599   (let ((case-fold-search nil))
 600     (if (string-match "\\`[0-9A-Z_]+\\'" xref)
 601         ;; all uppercase, so is a topic
 602         (pydoc-topics xref)
 603       ;; assume is a module
 604       (pydoc-modules xref))))
 605
 606 (defun pydoc-xrefs-alist ()
 607   ;; Assumes all xrefs are on a single line following point.
 608   (mapcar #'(lambda (str) (list (pydoc-delete-space str)))
 609           (split-string (buffer-substring
 610                          (point) (save-excursion (end-of-line) (point)))
 611                         ",")))
 612
 613 (defun pydoc-xrefs-p ()
 614   "Return t if current buffer contains xrefs or nil otherwise.
 615 A call to \(match-end 0) returns the end of the xrefs-prefix."
 616   (save-excursion
 617     (goto-char (point-max))
 618     (re-search-backward pydoc-xrefs-prefix nil t)))
 619
 620