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