lisp/ielm.el

   1 ;;; ielm.el --- interaction mode for Emacs Lisp
   2
   3 ;; Copyright (C) 1994, 2002, 2003 Free Software Foundation, Inc.
   4
   5 ;; Author: David Smith <maa036@lancaster.ac.uk>
   6 ;; Maintainer: FSF
   7 ;; Created: 25 Feb 1994
   8 ;; Keywords: lisp
   9
  10 ;; This file is part of GNU Emacs.
  11
  12 ;; GNU Emacs is free software; you can redistribute it and/or modify
  13 ;; it under the terms of the GNU General Public License as published by
  14 ;; the Free Software Foundation; either version 2, or (at your option)
  15 ;; any later version.
  16
  17 ;; GNU Emacs is distributed in the hope that it will be useful,
  18 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  19 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20 ;; GNU General Public License for more details.
  21
  22 ;; You should have received a copy of the GNU General Public License
  23 ;; along with GNU Emacs; see the file COPYING.  If not, write to the
  24 ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  25 ;; Boston, MA 02111-1307, USA.
  26
  27 ;;; Commentary:
  28
  29 ;; Provides a nice interface to evaluating Emacs Lisp expressions.
  30 ;; Input is handled by the comint package, and output is passed
  31 ;; through the pretty-printer.
  32
  33 ;; To start: M-x ielm.  Type C-h m in the *ielm* buffer for more info.
  34
  35 ;;; Code:
  36
  37 (require 'comint)
  38 (require 'pp)
  39
  40 ;;; User variables
  41
  42 (defgroup ielm nil
  43   "Interaction mode for Emacs Lisp."
  44   :group 'lisp)
  45
  46
  47 (defcustom ielm-noisy t
  48   "*If non-nil, IELM will beep on error."
  49   :type 'boolean
  50   :group 'ielm)
  51
  52 (defcustom ielm-prompt "ELISP> "
  53   "Prompt used in IELM."
  54   :type 'string
  55   :group 'ielm
  56   :get #'(lambda (symbol) (substring-no-properties (symbol-value symbol)))
  57   :set #'(lambda (symbol value) (set symbol (propertize value 'read-only t 'rear-nonsticky t))))
  58
  59 (defcustom ielm-dynamic-return t
  60   "*Controls whether \\<ielm-map>\\[ielm-return] has intelligent behaviour in IELM.
  61 If non-nil, \\[ielm-return] evaluates input for complete sexps, or inserts a newline
  62 and indents for incomplete sexps.  If nil, always inserts newlines."
  63   :type 'boolean
  64   :group 'ielm)
  65
  66 (defcustom ielm-dynamic-multiline-inputs t
  67   "*Force multiline inputs to start from column zero?
  68 If non-nil, after entering the first line of an incomplete sexp, a newline
  69 will be inserted after the prompt, moving the input to the next line.
  70 This gives more frame width for large indented sexps, and allows functions
  71 such as `edebug-defun' to work with such inputs."
  72   :type 'boolean
  73   :group 'ielm)
  74
  75 (defcustom ielm-mode-hook nil
  76   "*Hooks to be run when IELM (`inferior-emacs-lisp-mode') is started."
  77   :options '(turn-on-eldoc-mode)
  78   :type 'hook
  79   :group 'ielm)
  80
  81 (defvar * nil
  82   "Most recent value evaluated in IELM.")
  83
  84 (defvar ** nil
  85   "Second-most-recent value evaluated in IELM.")
  86
  87 (defvar *** nil
  88   "Third-most-recent value evaluated in IELM.")
  89
  90 (defvar ielm-match-data nil
  91   "Match data saved at the end of last command.")
  92
  93 (defvar *1 nil
  94   "During IELM evaluation, most recent value evaluated in IELM.
  95 Normally identical to `*'.  However, if the working buffer is an IELM
  96 buffer, distinct from the process buffer, then `*' gives the value in
  97 the working buffer, `*1' the value in the process buffer.
  98 The intended value is only accessible during IELM evaluation.")
  99
 100 (defvar *2 nil
 101   "During IELM evaluation, second-most-recent value evaluated in IELM.
 102 Normally identical to `**'.  However, if the working buffer is an IELM
 103 buffer, distinct from the process buffer, then `**' gives the value in
 104 the working buffer, `*2' the value in the process buffer.
 105 The intended value is only accessible during IELM evaluation.")
 106
 107 (defvar *3 nil
 108   "During IELM evaluation, third-most-recent value evaluated in IELM.
 109 Normally identical to `***'.  However, if the working buffer is an IELM
 110 buffer, distinct from the process buffer, then `***' gives the value in
 111 the working buffer, `*3' the value in the process buffer.
 112 The intended value is only accessible during IELM evaluation.")
 113
 114 ;;; System variables
 115
 116 (defvar ielm-working-buffer nil
 117   "Buffer in which IELM sexps will be evaluated.
 118 This variable is buffer-local.")
 119
 120 (defvar ielm-header
 121   "*** Welcome to IELM ***  Type (describe-mode) for help.\n"
 122   "Message to display when IELM is started.")
 123
 124 (defvar ielm-map nil)
 125 (if ielm-map nil
 126   (if (string-match "Lucid" emacs-version)
 127       ;; Lemacs
 128       (progn
 129         (setq ielm-map (make-sparse-keymap))
 130         (set-keymap-parent ielm-map comint-mode-map))
 131     ;; FSF
 132     (setq ielm-map (cons 'keymap comint-mode-map)))
 133   (define-key ielm-map "\t" 'comint-dynamic-complete)
 134   (define-key ielm-map "\C-m" 'ielm-return)
 135   (define-key ielm-map "\C-j" 'ielm-send-input)
 136   (define-key ielm-map "\e\C-x" 'eval-defun)         ; for consistency with
 137   (define-key ielm-map "\e\t" 'lisp-complete-symbol) ; lisp-interaction-mode
 138   ;; These bindings are from `lisp-mode-shared-map' -- can you inherit
 139   ;; from more than one keymap??
 140   (define-key ielm-map "\e\C-q" 'indent-sexp)
 141   (define-key ielm-map "\177" 'backward-delete-char-untabify)
 142   ;; Some convenience bindings for setting the working buffer
 143   (define-key ielm-map "\C-c\C-b" 'ielm-change-working-buffer)
 144   (define-key ielm-map "\C-c\C-f" 'ielm-display-working-buffer)
 145   (define-key ielm-map "\C-c\C-v" 'ielm-print-working-buffer))
 146
 147 (defvar ielm-font-lock-keywords
 148   (list
 149    (cons (concat "^" (regexp-quote ielm-prompt)) 'font-lock-keyword-face)
 150    '("\\(^\\*\\*\\*[^*]+\\*\\*\\*\\)\\(.*$\\)"
 151      (1 font-lock-comment-face)
 152      (2 font-lock-constant-face)))
 153   "Additional expressions to highlight in ielm buffers.")
 154
 155 ;;; Completion stuff
 156
 157 (defun ielm-tab nil
 158   "Possibly indent the current line as lisp code."
 159   (interactive)
 160   (if (or (eq (preceding-char) ?\n)
 161           (eq (char-syntax (preceding-char)) ? ))
 162       (progn
 163         (ielm-indent-line)
 164         t)))
 165
 166 (defun ielm-complete-symbol nil
 167   "Complete the lisp symbol before point."
 168   ;; A wrapper for lisp-complete symbol that returns non-nil if
 169   ;; completion has occurred
 170   (let* ((btick (buffer-modified-tick))
 171          (cbuffer (get-buffer "*Completions*"))
 172          (ctick (and cbuffer (buffer-modified-tick cbuffer))))
 173     (lisp-complete-symbol)
 174      ;; completion has occurred if:
 175     (or
 176      ;; the buffer has been modified
 177      (not (= btick (buffer-modified-tick)))
 178      ;; a completions buffer has been modified or created
 179      (if cbuffer
 180          (not (= ctick (buffer-modified-tick cbuffer)))
 181        (get-buffer "*Completions*")))))
 182
 183 (defun ielm-complete-filename nil
 184   "Dynamically complete filename before point, if in a string."
 185   (if (nth 3 (parse-partial-sexp comint-last-input-start (point)))
 186       (comint-dynamic-complete-filename)))
 187
 188 (defun ielm-indent-line nil
 189   "Indent the current line as Lisp code if it is not a prompt line."
 190   (when (save-excursion (comint-bol) (bolp))
 191     (lisp-indent-line)))
 192
 193 ;;; Working buffer manipulation
 194
 195 (defun ielm-print-working-buffer nil
 196   "Print the current IELM working buffer's name in the echo area."
 197   (interactive)
 198   (message "The current working buffer is: %s" (buffer-name ielm-working-buffer)))
 199
 200 (defun ielm-display-working-buffer nil
 201   "Display the current IELM working buffer.
 202 Don't forget that selecting that buffer will change its value of `point'
 203 to its value of `window-point'!"
 204   (interactive)
 205   (display-buffer ielm-working-buffer)
 206   (ielm-print-working-buffer))
 207
 208 (defun ielm-change-working-buffer (buf)
 209   "Change the current IELM working buffer to BUF.
 210 This is the buffer in which all sexps entered at the IELM prompt are
 211 evaluated.  You can achieve the same effect with a call to
 212 `set-buffer' at the IELM prompt."
 213   (interactive "bSet working buffer to: ")
 214   (setq ielm-working-buffer (or (get-buffer buf) (error "No such buffer")))
 215   (ielm-print-working-buffer))
 216
 217 ;;; Other bindings
 218
 219 (defun ielm-return nil
 220   "Newline and indent, or evaluate the sexp before the prompt.
 221 Complete sexps are evaluated; for incomplete sexps inserts a newline
 222 and indents.  If however `ielm-dynamic-return' is nil, this always
 223 simply inserts a newline."
 224   (interactive)
 225   (if ielm-dynamic-return
 226       (let ((state
 227              (save-excursion
 228                (end-of-line)
 229                (parse-partial-sexp (ielm-pm)
 230                                    (point)))))
 231         (if (and (< (car state) 1) (not (nth 3 state)))
 232             (ielm-send-input)
 233           (if (and ielm-dynamic-multiline-inputs
 234                    (save-excursion
 235                      (beginning-of-line)
 236                      (looking-at comint-prompt-regexp)))
 237               (save-excursion
 238                 (goto-char (ielm-pm))
 239                 (newline 1)))
 240           (newline-and-indent)))
 241     (newline)))
 242
 243 (defvar ielm-input)
 244
 245 (defun ielm-input-sender (proc input)
 246   ;; Just sets the variable ielm-input, which is in the scope of
 247   ;; `ielm-send-input's call.
 248   (setq ielm-input input))
 249
 250 (defun ielm-send-input nil
 251   "Evaluate the Emacs Lisp expression after the prompt."
 252   (interactive)
 253   (let ((buf (current-buffer))
 254         ielm-input)                     ; set by ielm-input-sender
 255     (comint-send-input)                 ; update history, markers etc.
 256     (ielm-eval-input ielm-input)))
 257
 258 ;;; Utility functions
 259
 260 (defun ielm-is-whitespace (string)
 261   "Return non-nil if STRING is all whitespace."
 262   (or (string= string "") (string-match "\\`[ \t\n]+\\'" string)))
 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 (error-message-string 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                   ;; To correctly handle the ielm-local variables *,
 304                   ;; ** and ***, we need a temporary buffer to be
 305                   ;; current at entry to the inner of the next two let
 306                   ;; forms.  We need another temporary buffer to exit
 307                   ;; that same let.  To avoid problems, neither of
 308                   ;; these buffers should be alive during the
 309                   ;; evaluation of ielm-form.
 310                   (let ((*1 *)
 311                         (*2 **)
 312                         (*3 ***)
 313                         ielm-temp-buffer)
 314                     (set-match-data ielm-match-data)
 315                     (save-excursion
 316                       (with-temp-buffer
 317                         (condition-case err
 318                             (unwind-protect
 319                                 ;; The next let form creates default
 320                                 ;; bindings for *, ** and ***.  But
 321                                 ;; these default bindings are
 322                                 ;; identical to the ielm-local
 323                                 ;; bindings.  Hence, during the
 324                                 ;; evaluation of ielm-form, the
 325                                 ;; ielm-local values are going to be
 326                                 ;; used in all buffers except for
 327                                 ;; other ielm buffers, which override
 328                                 ;; them.  Normally, the variables *1,
 329                                 ;; *2 and *3 also have default
 330                                 ;; bindings, which are not overridden.
 331                                 (let ((* *1)
 332                                       (** *2)
 333                                       (*** *3))
 334                                   (kill-buffer (current-buffer))
 335                                   (set-buffer ielm-wbuf)
 336                                   (setq ielm-result (eval ielm-form))
 337                                   (setq ielm-wbuf (current-buffer))
 338                                   (setq
 339                                    ielm-temp-buffer
 340                                    (generate-new-buffer " *ielm-temp*"))
 341                                   (set-buffer ielm-temp-buffer))
 342                               (when ielm-temp-buffer
 343                                 (kill-buffer ielm-temp-buffer)))
 344                           (error (setq ielm-result (error-message-string err))
 345                                  (setq ielm-error-type "Eval error"))
 346                           (quit (setq ielm-result "Quit during evaluation")
 347                                 (setq ielm-error-type "Eval error")))))
 348                     (setq ielm-match-data (match-data)))
 349                 (setq ielm-error-type "IELM error")
 350                 (setq ielm-result "More than one sexp in input"))))
 351
 352           ;; If the eval changed the current buffer, mention it here
 353           (if (eq ielm-wbuf ielm-working-buffer) nil
 354             (message "current buffer is now: %s" ielm-wbuf)
 355             (setq ielm-working-buffer ielm-wbuf))
 356
 357           (goto-char ielm-pmark)
 358           (if (not ielm-error-type)
 359               (condition-case err
 360                   ;; Self-referential objects cause loops in the printer, so
 361                   ;; trap quits here. May as well do errors, too
 362                   (setq ielm-output (concat ielm-output (pp-to-string ielm-result)))
 363                 (error (setq ielm-error-type "IELM Error")
 364                        (setq ielm-result  "Error during pretty-printing (bug in pp)"))
 365                 (quit  (setq ielm-error-type "IELM Error")
 366                        (setq ielm-result "Quit during pretty-printing"))))
 367           (if ielm-error-type
 368               (progn
 369                 (if ielm-noisy (ding))
 370                 (setq ielm-output (concat ielm-output "*** " ielm-error-type " ***  "))
 371                 (setq ielm-output (concat ielm-output ielm-result)))
 372             ;; There was no error, so shift the *** values
 373             (setq *** **)
 374             (setq ** *)
 375             (setq * ielm-result))
 376           (setq ielm-output (concat ielm-output "\n"))))
 377     (setq ielm-output (concat ielm-output ielm-prompt))
 378     (comint-output-filter (ielm-process) ielm-output)))
 379
 380 ;;; Process and marker utilities
 381
 382 (defun ielm-process nil
 383   ;; Return the current buffer's process.
 384   (get-buffer-process (current-buffer)))
 385
 386 (defun ielm-pm nil
 387   ;; Return the process mark of the current buffer.
 388   (process-mark (get-buffer-process (current-buffer))))
 389
 390 (defun ielm-set-pm (pos)
 391   ;; Set the process mark in the current buffer to POS.
 392   (set-marker (process-mark (get-buffer-process (current-buffer))) pos))
 393
 394 ;;; Major mode
 395
 396 (put 'inferior-emacs-lisp-mode 'mode-class 'special)
 397
 398 (defun inferior-emacs-lisp-mode nil
 399   "Major mode for interactively evaluating Emacs Lisp expressions.
 400 Uses the interface provided by `comint-mode' (which see).
 401
 402 * \\<ielm-map>\\[ielm-send-input] evaluates the sexp following the prompt.  There must be at most
 403   one top level sexp per prompt.
 404
 405 * \\[ielm-return] inserts a newline and indents, or evaluates a
 406   complete expression (but see variable `ielm-dynamic-return').
 407   Inputs longer than one line are moved to the line following the
 408   prompt (but see variable `ielm-dynamic-multiline-inputs').
 409
 410 * \\[comint-dynamic-complete] completes Lisp symbols (or filenames, within strings),
 411   or indents the line if there is nothing to complete.
 412
 413 The current working buffer may be changed (with a call to
 414 `set-buffer', or with \\[ielm-change-working-buffer]), and its value
 415 is preserved between successive evaluations.  In this way, expressions
 416 may be evaluated in a different buffer than the *ielm* buffer.
 417 Display the name of the working buffer with \\[ielm-print-working-buffer],
 418 or the buffer itself with \\[ielm-display-working-buffer].
 419
 420 During evaluations, the values of the variables `*', `**', and `***'
 421 are the results of the previous, second previous and third previous
 422 evaluations respectively.  If the working buffer is another IELM
 423 buffer, then the values in the working buffer are used.  The variables
 424 `*1', `*2' and `*3', yield the process buffer values.
 425
 426 Expressions evaluated by IELM are not subject to `debug-on-quit' or
 427 `debug-on-error'.
 428
 429 The behaviour of IELM may be customised with the following variables:
 430 * To stop beeping on error, set `ielm-noisy' to nil
 431 * If you don't like the prompt, you can change it by setting `ielm-prompt'.
 432 * Set `ielm-dynamic-return' to nil for bindings like `lisp-interaction-mode'
 433 * Entry to this mode runs `comint-mode-hook' and `ielm-mode-hook'
 434  (in that order).
 435
 436 Customised bindings may be defined in `ielm-map', which currently contains:
 437 \\{ielm-map}"
 438   (interactive)
 439   (comint-mode)
 440   (setq comint-prompt-regexp (concat "^" (regexp-quote ielm-prompt)))
 441   (make-local-variable 'paragraph-start)
 442   (setq paragraph-start comint-prompt-regexp)
 443   (setq comint-input-sender 'ielm-input-sender)
 444   (setq comint-process-echoes nil)
 445   (make-local-variable 'comint-dynamic-complete-functions)
 446   (setq comint-dynamic-complete-functions
 447         '(ielm-tab comint-replace-by-expanded-history ielm-complete-filename ielm-complete-symbol))
 448   (setq comint-get-old-input 'ielm-get-old-input)
 449   (make-local-variable 'comint-completion-addsuffix)
 450   (setq comint-completion-addsuffix
 451         (cons (char-to-string directory-sep-char) ""))
 452
 453   (setq major-mode 'inferior-emacs-lisp-mode)
 454   (setq mode-name "IELM")
 455   (use-local-map ielm-map)
 456   (set-syntax-table emacs-lisp-mode-syntax-table)
 457
 458   (make-local-variable 'indent-line-function)
 459   (make-local-variable 'ielm-working-buffer)
 460   (setq ielm-working-buffer (current-buffer))
 461   (setq indent-line-function 'ielm-indent-line)
 462   (make-local-variable 'fill-paragraph-function)
 463   (setq fill-paragraph-function 'lisp-fill-paragraph)
 464
 465   ;; Value holders
 466   (make-local-variable '*)
 467   (setq * nil)
 468   (make-local-variable '**)
 469   (setq ** nil)
 470   (make-local-variable '***)
 471   (setq *** nil)
 472   (set (make-local-variable 'ielm-match-data) nil)
 473
 474   ;; font-lock support
 475   (make-local-variable 'font-lock-defaults)
 476   (setq font-lock-defaults
 477         '(ielm-font-lock-keywords nil nil ((?: . "w") (?- . "w") (?* . "w"))))
 478
 479   ;; A dummy process to keep comint happy. It will never get any input
 480   (unless (comint-check-proc (current-buffer))
 481     ;; Was cat, but on non-Unix platforms that might not exist, so
 482     ;; use hexl instead, which is part of the Emacs distribution.
 483     (condition-case nil
 484         (start-process "ielm" (current-buffer) "hexl")
 485       (file-error (start-process "ielm" (current-buffer) "cat")))
 486     (process-kill-without-query (ielm-process))
 487     (goto-char (point-max))
 488
 489     ;; Lisp output can include raw characters that confuse comint's
 490     ;; carriage control code.
 491     (set (make-local-variable 'comint-inhibit-carriage-motion) t)
 492
 493     ;; Add a silly header
 494     (insert ielm-header)
 495     (ielm-set-pm (point-max))
 496     (unless comint-use-prompt-regexp-instead-of-fields
 497       (add-text-properties
 498        (point-min) (point-max)
 499        '(rear-nonsticky t field output inhibit-line-move-field-capture t)))
 500     (comint-output-filter (ielm-process) ielm-prompt)
 501     (set-marker comint-last-input-start (ielm-pm))
 502     (set-process-filter (get-buffer-process (current-buffer)) 'comint-output-filter))
 503
 504   (run-hooks 'ielm-mode-hook))
 505
 506 (defun ielm-get-old-input nil
 507   ;; Return the previous input surrounding point
 508   (save-excursion
 509     (beginning-of-line)
 510     (if (looking-at comint-prompt-regexp) nil
 511       (re-search-backward comint-prompt-regexp))
 512     (comint-skip-prompt)
 513     (buffer-substring (point) (progn (forward-sexp 1) (point)))))
 514
 515 ;;; User command
 516
 517 ;;;###autoload (add-hook 'same-window-buffer-names "*ielm*")
 518
 519 ;;;###autoload
 520 (defun ielm nil
 521   "Interactively evaluate Emacs Lisp expressions.
 522 Switches to the buffer `*ielm*', or creates it if it does not exist."
 523   (interactive)
 524   (if (comint-check-proc "*ielm*")
 525       nil
 526     (save-excursion
 527       (set-buffer (get-buffer-create "*ielm*"))
 528       (inferior-emacs-lisp-mode)))
 529   (pop-to-buffer "*ielm*"))
 530
 531 (provide 'ielm)
 532
 533 ;;; arch-tag: ef60e4c0-9c4f-4bdb-8402-271313329790
 534 ;;; ielm.el ends here