lisp/ielm.el

   1 ;;; ielm.el --- interaction mode for Emacs Lisp
   2
   3 ;; Copyright (C) 1994 Free Software Foundation, Inc.
   4
   5 ;; Author: David Smith <maa036@lancaster.ac.uk>
   6 ;; Created: 25 Feb 1994
   7 ;; Keywords: lisp
   8
   9 ;; This file is part of GNU Emacs.
  10
  11 ;; GNU Emacs is free software; you can redistribute it and/or modify
  12 ;; it under the terms of the GNU General Public License as published by
  13 ;; the Free Software Foundation; either version 2, or (at your option)
  14 ;; any later version.
  15
  16 ;; GNU Emacs is distributed in the hope that it will be useful,
  17 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  18 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19 ;; GNU General Public License for more details.
  20
  21 ;; You should have received a copy of the GNU General Public License
  22 ;; along with GNU Emacs; see the file COPYING.  If not, write to the
  23 ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  24 ;; Boston, MA 02111-1307, USA.
  25
  26 ;;; Commentary:
  27
  28 ;; Provides a nice interface to evaluating Emacs Lisp expressions.
  29 ;; Input is handled by the comint package, and output is passed
  30 ;; through the pretty-printer.
  31
  32 ;; To install: copy this file to a directory in your load-path, and
  33 ;; add the following line to your .emacs file:
  34 ;;
  35 ;;   (autoload 'ielm "ielm" "Start an inferior Emacs Lisp session" t)
  36 ;;
  37 ;; For completion to work, the comint.el from FSF Emacs 19.23 is
  38 ;; required.  If you do not have it, or if you are running Lemacs,
  39 ;; also add the following code to your .emacs:
  40 ;;
  41 ;;    (setq ielm-mode-hook
  42 ;;          '(lambda nil
  43 ;;               (define-key ielm-map "\t"
  44 ;;                  '(lambda nil (interactive) (or (ielm-tab)
  45 ;;                                                 (lisp-complete-symbol))))))
  46
  47 ;; To start: M-x ielm.  Type C-h m in the *ielm* buffer for more info.
  48
  49 ;; The latest version is available by WWW from
  50 ;;      http://mathssun5.lancs.ac.uk:2080/~maa036/elisp/dir.html
  51 ;; or by anonymous FTP from
  52 ;;      /anonymous@wingra.stat.wisc.edu:pub/src/emacs-lisp/ielm.el.gz
  53 ;; or from the author: David M. Smith <maa036@lancaster.ac.uk>
  54
  55 ;;; Code:
  56
  57 (require 'comint)
  58 (require 'pp)
  59
  60 ;;; User variables
  61
  62 (defvar ielm-noisy t
  63   "*If non-nil, IELM will beep on error.")
  64
  65 (defvar ielm-prompt "ELISP> "
  66   "Prompt used in IELM.")
  67
  68 (defvar ielm-dynamic-return t
  69   "*Controls whether \\<ielm-map>\\[ielm-return] has intelligent behaviour in IELM.
  70 If non-nil, \\[ielm-return] evaluates input for complete sexps, or inserts a newline
  71 and indents for incomplete sexps.  If nil, always inserts newlines.")
  72
  73 (defvar ielm-dynamic-multiline-inputs t
  74   "*Force multiline inputs to start from column zero?
  75 If non-nil, after entering the first line of an incomplete sexp, a newline
  76 will be inserted after the prompt, moving the input to the next line.
  77 This gives more frame width for large indented sexps, and allows functions
  78 such as `edebug-defun' to work with such inputs.")
  79
  80 (defvar ielm-mode-hook nil
  81   "*Hooks to be run when IELM (`inferior-emacs-lisp-mode') is started.")
  82
  83 ;;; System variables
  84
  85 (defvar ielm-working-buffer nil
  86   "Buffer in which IELM sexps will be evaluated.
  87 This variable is buffer-local.")
  88
  89 (defvar ielm-header
  90   (concat
  91    "*** Welcome to IELM version "
  92    (substring "$Revision: 1.6 $" 11 -2)
  93    " ***  Type (describe-mode) for help.\n"
  94    "IELM has ABSOLUTELY NO WARRANTY; type (describe-no-warranty) for details.\n")
  95   "Message to display when IELM is started.")
  96
  97 (defvar ielm-map nil)
  98 (if ielm-map nil
  99   (if (string-match "Lucid" emacs-version)
 100       ;; Lemacs
 101       (progn
 102         (setq ielm-map (make-sparse-keymap))
 103         (set-keymap-parent ielm-map comint-mode-map))
 104     ;; FSF
 105     (setq ielm-map (cons 'keymap comint-mode-map)))
 106   (define-key ielm-map "\t" 'comint-dynamic-complete)
 107   (define-key ielm-map "\C-m" 'ielm-return)
 108   (define-key ielm-map "\C-j" 'ielm-send-input)
 109   (define-key ielm-map "\e\C-x" 'eval-defun)         ; for consistency with
 110   (define-key ielm-map "\e\t" 'lisp-complete-symbol) ; lisp-interaction-mode
 111   ;; These bindings are from shared-lisp-mode-map -- can you inherit
 112   ;; from more than one keymap??
 113   (define-key ielm-map "\e\C-q" 'indent-sexp)
 114   (define-key ielm-map "\eq" 'lisp-fill-paragraph)
 115   (define-key ielm-map "\177" 'backward-delete-char-untabify)
 116   ;; Some convenience bindings for setting the working buffer
 117   (define-key ielm-map "\C-c\C-b" 'ielm-change-working-buffer)
 118   (define-key ielm-map "\C-c\C-f" 'ielm-display-working-buffer)
 119   (define-key ielm-map "\C-c\C-v" 'ielm-print-working-buffer))
 120
 121 (defvar ielm-font-lock-keywords
 122   (list
 123    (cons (concat "^" (regexp-quote ielm-prompt)) 'font-lock-keyword-face)
 124    '("\\(^\\*\\*\\*[^*]+\\*\\*\\*\\)\\(.*$\\)" (1 font-lock-comment-face) (2 font-lock-reference-face)))
 125   "Additional expressions to highlight in ielm buffers.")
 126
 127 ;;; Completion stuff
 128
 129 (defun ielm-tab nil
 130   "Possibly indent the current line as lisp code."
 131   (interactive)
 132   (if (or (eq (preceding-char) ?\n)
 133           (eq (char-syntax (preceding-char)) ? ))
 134       (progn
 135         (ielm-indent-line)
 136         t)))
 137
 138 (defun ielm-complete-symbol nil
 139   "Complete the lisp symbol before point."
 140   ;; A wrapper for lisp-complete symbol that returns non-nil if
 141   ;; completion has occurred
 142   (let* ((btick (buffer-modified-tick))
 143          (cbuffer (get-buffer "*Completions*"))
 144          (ctick (and cbuffer (buffer-modified-tick cbuffer))))
 145     (lisp-complete-symbol)
 146      ;; completion has occurred if:
 147     (or
 148      ;; the buffer has been modified
 149      (not (= btick (buffer-modified-tick)))
 150      ;; a completions buffer has been modified or created
 151      (if cbuffer
 152          (not (= ctick (buffer-modified-tick cbuffer)))
 153        (get-buffer "*Completions*")))))
 154
 155 (defun ielm-complete-filename nil
 156   "Dynamically complete filename before point, if in a string."
 157   (if (nth 3 (parse-partial-sexp comint-last-input-start (point)))
 158       (comint-dynamic-complete-filename)))
 159
 160 (defun ielm-indent-line nil
 161   "Indent the current line as Lisp code if it is not a prompt line."
 162   (if (save-excursion
 163         (beginning-of-line)
 164         (looking-at comint-prompt-regexp)) nil
 165     (lisp-indent-line)))
 166
 167 ;;; Working buffer manipulation
 168
 169 (defun ielm-print-working-buffer nil
 170   "Print the current IELM working buffer's name in the echo area."
 171   (interactive)
 172   (message "The current working buffer is: %s" (buffer-name ielm-working-buffer)))
 173
 174 (defun ielm-display-working-buffer nil
 175   "Display the current IELM working buffer.
 176 Don't forget that selecting that buffer will change its value of `point'
 177 to its value of `window-point'!"
 178   (interactive)
 179   (display-buffer ielm-working-buffer)
 180   (ielm-print-working-buffer))
 181
 182 (defun ielm-change-working-buffer (buf)
 183   "Change the current IELM working buffer to BUF.
 184 This is the buffer in which all sexps entered at the IELM prompt are
 185 evaluated.  You can achieve the same effect with a call to
 186 `set-buffer' at the IELM prompt."
 187   (interactive "bSet working buffer to: ")
 188   (setq ielm-working-buffer (or (get-buffer buf) (error "No such buffer")))
 189   (ielm-print-working-buffer))
 190
 191 ;;; Other bindings
 192
 193 (defun ielm-return nil
 194   "Newline and indent, or evaluate the sexp before the prompt.
 195 Complete sexps are evaluated; for incomplete sexps inserts a newline
 196 and indents.  If however `ielm-dynamic-return' is nil, this always
 197 simply inserts a newline."
 198   (interactive)
 199   (if ielm-dynamic-return
 200       (let ((state
 201              (save-excursion
 202                (end-of-line)
 203                (parse-partial-sexp (ielm-pm)
 204                                    (point)))))
 205         (if (and (< (car state) 1) (not (nth 3 state)))
 206             (ielm-send-input)
 207           (if (and ielm-dynamic-multiline-inputs
 208                    (save-excursion
 209                      (beginning-of-line)
 210                      (looking-at comint-prompt-regexp)))
 211               (save-excursion
 212                 (goto-char (ielm-pm))
 213                 (newline 1)))
 214           (newline-and-indent)))
 215     (newline)))
 216
 217 (defun ielm-input-sender (proc input)
 218   ;; Just sets the variable ielm-input, which is in the scope of
 219   ;; `ielm-send-input's call.
 220   (setq ielm-input input))
 221
 222 (defun ielm-send-input nil
 223   "Evaluate the Emacs Lisp expression after the prompt."
 224   (interactive)
 225   (let ((buf (current-buffer))
 226         ielm-input)                     ; set by ielm-input-sender
 227     (comint-send-input)                 ; update history, markers etc.
 228     (ielm-eval-input ielm-input)))
 229
 230 ;;; Utility functions
 231
 232 (defun ielm-is-whitespace (string)
 233   "Return non-nil if STRING is all whitespace."
 234   (or (string= string "") (string-match "\\`[ \t\n]+\\'" string)))
 235
 236 (defun ielm-format-errors (errlist)
 237   (let ((result ""))
 238     (while errlist
 239       (setq result (concat result (prin1-to-string (car errlist)) ", "))
 240       (setq errlist (cdr errlist)))
 241     (substring result 0 -2)))
 242
 243
 244 (defun ielm-format-error (err)
 245   ;; Return a string form of the error ERR.
 246   (format "%s%s"
 247           (or (get (car err) 'error-message) "Peculiar error")
 248           (if (cdr err)
 249               (format ": %s" (ielm-format-errors (cdr err)))
 250             "")))
 251
 252 ;;; Evaluation
 253
 254 (defun ielm-eval-input (ielm-string)
 255   "Evaluate the Lisp expression IELM-STRING, and pretty-print the result."
 256   ;; This is the function that actually `sends' the input to the
 257   ;; `inferior Lisp process'. All comint-send-input does is works out
 258   ;; what that input is.  What this function does is evaluates that
 259   ;; input and produces `output' which gets inserted into the buffer,
 260   ;; along with a new prompt.  A better way of doing this might have
 261   ;; been to actually send the output to the `cat' process, and write
 262   ;; this as in output filter that converted sexps in the output
 263   ;; stream to their evaluated value.  But that would have involved
 264   ;; more process coordination than I was happy to deal with.
 265   ;;
 266   ;; NOTE: all temporary variables in this function will be in scope
 267   ;; during the eval, and so need to have non-clashing names.
 268   (let (ielm-form                       ; form to evaluate
 269         ielm-pos                        ; End posn of parse in string
 270         ielm-result                     ; Result, or error message
 271         ielm-error-type                 ; string, nil if no error
 272         (ielm-output    "")             ; result to display
 273         (ielm-wbuf ielm-working-buffer) ; current buffer after evaluation
 274         (ielm-pmark (ielm-pm)))
 275     (if (not (ielm-is-whitespace ielm-string))
 276         (progn
 277           (condition-case err
 278               (let (rout)
 279                 (setq rout (read-from-string ielm-string))
 280                 (setq ielm-form (car rout))
 281                 (setq ielm-pos (cdr rout)))
 282             (error (setq ielm-result (ielm-format-error err))
 283                    (setq ielm-error-type "Read error")))
 284           (if ielm-error-type nil
 285             ;; Make sure working buffer has not been killed
 286             (if (not (buffer-name ielm-working-buffer))
 287                 (setq ielm-result "Working buffer has been killed"
 288                       ielm-error-type "IELM Error"
 289                       ielm-wbuf (current-buffer))
 290               (if (ielm-is-whitespace (substring ielm-string ielm-pos))
 291                   ;; need this awful let convolution to work around
 292                   ;; an Emacs bug involving local vbls and let binding
 293                   (let ((:save :)
 294                         (::save ::)
 295                         (:::save :::))
 296                     (save-excursion
 297                       (set-buffer ielm-working-buffer)
 298                       (condition-case err
 299                           (let ((: :save)
 300                                 (:: ::save)
 301                                 (::: :::save)
 302                                 (ielm-obuf (current-buffer)))
 303                             (setq ielm-result (eval ielm-form))
 304                             (setq ielm-wbuf (current-buffer))
 305                             ;; The eval may have changed current-buffer;
 306                             ;; need to set it back here to avoid a bug
 307                             ;; in let.  Don't want to use save-excursion
 308                             ;; because we want to allow changes in point.
 309                             (set-buffer ielm-obuf))
 310                         (error (setq ielm-result (ielm-format-error err))
 311                                (setq ielm-error-type "Eval error"))
 312                         (quit (setq ielm-result "Quit during evaluation")
 313                               (setq ielm-error-type "Eval error")))))
 314                 (setq ielm-error-type "IELM error")
 315                 (setq ielm-result "More than one sexp in input"))))
 316
 317           ;; If the eval changed the current buffer, mention it here
 318           (if (eq ielm-wbuf ielm-working-buffer) nil
 319             (message "current buffer is now: %s" ielm-wbuf)
 320             (setq ielm-working-buffer ielm-wbuf))
 321
 322           (goto-char ielm-pmark)
 323           (if (not ielm-error-type)
 324               (condition-case err
 325                   ;; Self-referential objects cause loops in the printer, so
 326                   ;; trap quits here. May as well do errors, too
 327                   (setq ielm-output (concat ielm-output (pp-to-string ielm-result)))
 328                 (error (setq ielm-error-type "IELM Error")
 329                        (setq ielm-result  "Error during pretty-printing (bug in pp)"))
 330                 (quit  (setq ielm-error-type "IELM Error")
 331                        (setq ielm-result "Quit during pretty-printing"))))
 332           (if ielm-error-type
 333               (progn
 334                 (if ielm-noisy (ding))
 335                 (setq ielm-output (concat ielm-output "*** " ielm-error-type " ***  "))
 336                 (setq ielm-output (concat ielm-output ielm-result)))
 337             ;; There was no error, so shift the ::: values
 338             (setq ::: ::)
 339             (setq :: :)
 340             (setq : ielm-result))
 341           (setq ielm-output (concat ielm-output "\n"))))
 342     (setq ielm-output (concat ielm-output ielm-prompt))
 343     (comint-output-filter (ielm-process) ielm-output)))
 344
 345 ;;; Process and marker utilities
 346
 347 (defun ielm-process nil
 348   ;; Return the current buffer's process.
 349   (get-buffer-process (current-buffer)))
 350
 351 (defun ielm-pm nil
 352   ;; Return the process mark of the current buffer.
 353   (process-mark (get-buffer-process (current-buffer))))
 354
 355 (defun ielm-set-pm (pos)
 356   ;; Set the process mark in the current buffer to POS.
 357   (set-marker (process-mark (get-buffer-process (current-buffer))) pos))
 358
 359 ;;; Major mode
 360
 361 (defun inferior-emacs-lisp-mode nil
 362   "Major mode for interactively evaluating Emacs Lisp expressions.
 363 Uses the interface provided by `comint-mode' (which see).
 364
 365 * \\<ielm-map>\\[ielm-send-input] evaluates the sexp following the prompt. There must be at most
 366   one top-level sexp per prompt.
 367
 368 * \\[ielm-return] inserts a newline and indents, or evaluates a
 369   complete expression (but see variable `ielm-dynamic-return').
 370   Inputs longer than one line are moved to the line following the
 371   prompt (but see variable `ielm-dynamic-multiline-inputs').
 372
 373 * \\[comint-dynamic-complete] completes Lisp symbols (or filenames, within strings),
 374   or indents the line if there is nothing to complete.
 375
 376 During evaluations, the values of the variables `:', `::', and `:::'
 377 are the results of the previous, second previous and third previous
 378 evaluations respectively.
 379
 380 The current working buffer may be changed (with a call to
 381 `set-buffer', or with \\[ielm-change-working-buffer]), and its value
 382 is preserved between successive evaluations.  In this way, expressions
 383 may be evaluated in a different buffer than the *ielm* buffer.
 384 Display the name of the working buffer with \\[ielm-print-working-buffer],
 385 or the buffer itself with \\[ielm-display-working-buffer].
 386
 387 Expressions evaluated by IELM are not subject to `debug-on-quit' or
 388 `debug-on-error'.
 389
 390 The behaviour of IELM may be customised with the following variables:
 391 * To stop beeping on error, set `ielm-noisy' to nil
 392 * If you don't like the prompt, you can change it by setting `ielm-prompt'.
 393 * Set `ielm-dynamic-return' to nil for bindings like `lisp-interaction-mode'
 394 * Entry to this mode runs `comint-mode-hook' and `ielm-mode-hook'
 395  (in that order).
 396
 397 Customised bindings may be defined in `ielm-map', which currently contains:
 398 \\{ielm-map}"
 399   (interactive)
 400   (comint-mode)
 401   (setq comint-prompt-regexp (concat "^" (regexp-quote ielm-prompt)))
 402   (make-local-variable 'paragraph-start)
 403   (setq paragraph-start comint-prompt-regexp)
 404   (setq comint-input-sender 'ielm-input-sender)
 405   (setq comint-process-echoes nil)
 406   (setq comint-dynamic-complete-functions
 407         '(ielm-tab comint-replace-by-expanded-history ielm-complete-filename ielm-complete-symbol))
 408   (setq comint-get-old-input 'ielm-get-old-input)
 409
 410   (setq major-mode 'inferior-emacs-lisp-mode)
 411   (setq mode-name "IELM")
 412   (use-local-map ielm-map)
 413   (set-syntax-table emacs-lisp-mode-syntax-table)
 414
 415   (make-local-variable 'indent-line-function)
 416   (make-local-variable 'ielm-working-buffer)
 417   (setq ielm-working-buffer (current-buffer))
 418   (setq indent-line-function 'ielm-indent-line)
 419
 420   ;; Value holders
 421   (setq : nil)
 422   (make-local-variable ':)
 423   (setq :: nil)
 424   (make-local-variable '::)
 425   (setq ::: nil)
 426   (make-local-variable ':::)
 427
 428   ;; font-lock support
 429   (make-local-variable 'font-lock-defaults)
 430   (setq font-lock-defaults
 431         '(ielm-font-lock-keywords nil nil ((?: . "w") (?- . "w") (?* . "w"))))
 432
 433   ;; A dummy process to keep comint happy. It will never get any input
 434   (if (comint-check-proc (current-buffer)) nil
 435     (start-process "ielm" (current-buffer) "cat")
 436     (process-kill-without-query (ielm-process))
 437     (goto-char (point-max))
 438     ;; Add a silly header
 439     (insert ielm-header)
 440     (ielm-set-pm (point-max))
 441     (comint-output-filter (ielm-process) ielm-prompt)
 442     (set-marker comint-last-input-start (ielm-pm))
 443     (set-process-filter (get-buffer-process (current-buffer)) 'comint-output-filter))
 444   (run-hooks 'ielm-mode-hook))
 445
 446 (defun ielm-get-old-input nil
 447   ;; Return the previous input surrounding point
 448   (save-excursion
 449     (beginning-of-line)
 450     (if (looking-at comint-prompt-regexp) nil
 451       (re-search-backward comint-prompt-regexp))
 452     (comint-skip-prompt)
 453     (buffer-substring (point) (progn (forward-sexp 1) (point)))))
 454
 455 ;;; User command
 456
 457 ;;;###autoload (add-hook 'same-window-buffer-names "*ielm*")
 458
 459 ;;;###autoload
 460 (defun ielm nil
 461   "Interactively evaluate Emacs Lisp expressions.
 462 Switches to the buffer `*ielm*', or creates it if it does not exist."
 463   (interactive)
 464   (if (comint-check-proc "*ielm*")
 465       nil
 466     (save-excursion
 467       (set-buffer (get-buffer-create "*ielm*"))
 468       (inferior-emacs-lisp-mode)))
 469   (pop-to-buffer "*ielm*"))
 470
 471 ;;; ielm.el ends here