MIT/GNU Scheme User's Manual: Edwin

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# 7. Edwin

This chapter describes how to start Edwin, the MIT/GNU Scheme text editor. Edwin is very similar to GNU Emacs--you should refer to the GNU Emacs manual for information about Edwin's commands and key bindings--except that Edwin's extension language is MIT/GNU Scheme, while GNU Emacs extensions are written in Emacs Lisp. This manual does not discuss customization of Edwin.

> 7.1 Starting Edwin |  |
> 7.2 Leaving Edwin |  |
> 7.3 Scheme Mode |  |
> 7.4 Evaluation |  |
> 7.5 REPL Mode |  |
> 7.6 The Edwin Debugger |  |
> 7.7 Last Resorts |  |

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 7.1 Starting Edwin

To use Edwin, start Scheme with the following command-line options:

    scheme --edwin --edit

Alternatively, you can load Edwin by giving the ``--edwin`' command-line option and then calling the procedure `edit`:

procedure+: edit
procedure+: edwin
  Enter the Edwin text editor. If entering for the first time, the editor is initialized (by calling `create-editor` with no arguments). Otherwise, the previously-initialized editor is reentered.

  The procedure `edwin` is an alias for `edit`.

variable+: inhibit-editor-init-file?
  When Edwin is first initialized, it loads your init file (called ``~/.edwin`' under unix, ``edwin.ini`' on PCs) if you have one. If the Scheme variable `inhibit-editor-init-file?` is true, however, your init file will not be loaded even if it exists. By default, this variable is false.

  Note that you can set this variable in your Scheme init file (see section 2.2 Customizing Scheme).

procedure+: create-editor arg ...
  Initializes Edwin, or reinitializes it if already initialized. `create-editor` is normally invoked automatically by `edit`.

  If no args are given, the value of `create-editor-args` is used instead. In other words, the following are equivalent:

      (create-editor)
      (apply create-editor create-editor-args)

  On the other hand, if args are given, they are used to update `create-editor-args`, making the following equivalent:

      (apply create-editor args)
      (begin (set! create-editor-args args) (create-editor))

variable+: create-editor-args
  This variable controls the initialization of Edwin. The following values are defined:

  `(#f)`
    This is the default. Creates a window of some default size, and uses that window as Edwin's main window. Under unix, if X11 is not available or if the `DISPLAY` environment variable is undefined, Edwin will run on Scheme's console.

  `(x)`
    Unix only. Creates an X window and uses it as Edwin's main window. This requires the `DISPLAY` environment variable to have been set to the appropriate value before Scheme was started.

  `(x geometry)`
    Unix only. Like ``(x)`' except that geometry specifies the window's geometry in the usual way. Geometry must be a character string whose contents is an X geometry specification.

  `(console)`
    Unix only. Causes Edwin to run on Scheme's console, or in unix terminology, the standard input and output. If the console is not a terminal device, or is not powerful enough to run Edwin, an error will be signalled at initialization time.

  `(pm)`
    OS/2 only. Creates a Presentation Manager window and uses it as Edwin's main window.

  `(win32)`
    Windows only. Creates a window and uses it as Edwin's main window.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 7.2 Leaving Edwin

Once Edwin has been entered, it can be exited in the following ways:

`C-x z`
  Stop Edwin and return to Scheme (`suspend-edwin`). The call to the procedure `edit` that entered Edwin returns normally. A subsequent call to `edit` will resume Edwin where it was stopped.

`C-x c`
  Offer to save any modified buffers, then kill Edwin, returning to Scheme (`save-buffers-kill-edwin`). This is like the `suspend-edwin` command, except that a subsequent call to `edit` will reinitialize the editor.

`C-x C-z`
  Stop Edwin and suspend Scheme, returning control to the operating system's command interpreter (`suspend-scheme`). When Scheme is resumed (using the command interpreter's job-control commands), Edwin is automatically restarted where it was stopped. This command is identical to the `C-x C-z` command of GNU Emacs.

`C-x C-c`
  Offer to save any modified buffers, then kill both Edwin and Scheme (`save-buffers-kill-scheme`). Control is returned to the operating system's command interpreter, and the Scheme process is terminated. This command is identical to the `C-x C-c` command of GNU Emacs.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 7.3 Scheme Mode

As you might expect, Edwin has special support for editing and evaluating Scheme code. This section describes Scheme Mode, the appropriate mode for editing MIT/GNU Scheme programs.

Scheme mode is normally entered automatically by visiting a file whose file name ends in ``.scm`'. You can also mark a file as Scheme code by placing the string ``-*-Scheme-*-`' on the first line of the file. Finally, you can put any buffer in Scheme mode by executing the command `M-x scheme-mode`.

Scheme mode is similar to the Emacs modes that edit Lisp code. So, for example, `C-i` indents the current line, and `C-M-q` indents the expression to the right of point. The close parenthesis will temporarily flash the matching open parenthesis. Most Scheme constructs requiring special indentation are recognized by Scheme mode, for example, `begin`, `do`, and `let`.

Scheme mode also provides support that is specific to Scheme programs, much as Emacs-Lisp mode does in Emacs. Completion of global variable names is provided: type the first few characters of a variable, then type `C-M-i`, and Edwin will attempt to complete the variable name using the current set of bound variables. If `C-M-i` is given a prefix argument, it will complete the name using the current set of interned symbols (which includes the bound variables as a subset).

The `M-A` command (note the uppercase `A`) will show the parameters of a procedure when point is inside a procedure call. For example, type the string ``(quotient`', then press `M-A`, and the command will echo ``(n d)`' in the echo area. With a prefix argument, `M-A` will insert the parameter names in the buffer at point, so in this example, the buffer would contain ``(quotient n d`' after running `C-u M-A`.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 7.4 Evaluation

Scheme mode also provides commands for evaluating Scheme expressions. The simplest evaluation command is `C-x C-e`, which evaluates the expression to the left of point. (This key is bound in all buffers, even if they don't contain Scheme code.) The command `M-z` evaluates the definition that point is in (a definition is an expression starting with a left parenthesis in the leftmost column). The command `M-:` prompts for an expression in the minibuffer, evaluates it, and prints the value in the echo area.

Other commands that evaluate larger amounts of code are `C-M-z`, which evaluates all of the expressions in the region, and `M-o`, which evaluates the entire buffer. Both of these commands are potentially dangerous in that they will evaluate anything that appears to be an expression, even if it isn't intended to be.

Normally, these commands evaluate expressions by sending them to a REPL buffer, which performs the evaluations in a separate thread. This has two advantages: it allows you to continue editing while the evaluation is happening, and it keeps a record of each evaluation and its printed output. If you wish to stop a running evaluation and to erase any pending expressions, use the `C-c C-c` command from any Scheme buffer. (Note that by default, Edwin starts up with one REPL buffer, called ``*scheme*`'.)

If you would prefer to have Scheme mode evaluation commands evaluate directly, rather than sending expressions to the REPL buffer, set the Edwin variable `evaluate-in-inferior-repl` to `#f`. In this case, you will not be able to use Edwin while evaluation is occurring; any output from the evaluation will be shown in a pop-up buffer when the evaluation finishes; and you abort the evaluation using `C-g`.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 7.5 REPL Mode

Edwin provides a special mechanism for interacting with Scheme read-eval-print loops: REPL buffers. A REPL buffer is associated with a Scheme REPL running in a separate thread of execution; because of this, expressions may be evaluated in this buffer while you simultaneously do other things with the editor. A REPL buffer captures all printed output from an evaluated expression, as well as supporting interactive programs such as `debug`. For these and other reasons, REPL buffers are the preferred means for interacting with the Scheme interpreter.

When Edwin starts, it has one buffer: a REPL buffer called ``*scheme*`'. The command `M-x repl` selects this buffer, if it exists; otherwise it creates a new REPL buffer. If you want two REPL buffers, just rename the ``*scheme*`' buffer to something else and run `M-x repl` again.

REPL buffers support all the same evaluation commands that Scheme mode does; in fact, REPL buffers use a special mode called REPL mode that inherits from Scheme mode. Thus, any key bindings defined in Scheme mode are also defined in REPL mode. One exception to this is the `M-o` command, which is deliberately undefined in REPL mode; otherwise it would be too easy to re-evaluate all the previously evaluated expressions in the REPL buffer.

In addition to evaluation commands, REPL mode provides a handful of special commands for controlling the REPL itself. The commands `C-c C-x` and `C-c C-u` abort the current evaluation, returning to the current or previous REPL levels, respectively. The command `C-c C-b` interrupts the current evaluation, entering a breakpoint.

Each REPL buffer maintains a history of the expressions that were typed into it. Several commands allow you to access the contents of this history. The command `M-p` moves backwards through the history, inserting previously evaluated expressions at point. Likewise, `M-n` moves forward through the history. The commands `C-c C-r` and `C-c C-s` search backward and forward through the history for a particular string. The command `C-c C-o` deletes any output from the previous evaluation; use this command with care since it cannot be undone. The command `C-c C-l` finds the most recent expression in the buffer and moves point there.

When an expression that you evaluate signals an error, the REPL buffer notices this and offers to run the debugger for you. Answer this question with a ``y`' or ``n`' response. You can start the debugger whenever the REPL buffer is listening by executing the `C-c C-d` command. In either case, this starts the Edwin debugger, which pops up a new window containing the debugger. Your REPL buffer remains in the error state, allowing you to examine it further if you wish.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 7.6 The Edwin Debugger

The Edwin debugger is similar to the command-line debugger, except that it takes advantage of multiple windows and Edwin's command structure to provide a more intuitive interface. The debugger operates as a browser, much like Dired, presenting you with an overview of the subproblem structure, and allowing you to examine parts of that structure in more detail by selecting the parts. When started, the debugger creates a buffer ``*debug*`' showing the subproblem structure, and selects the first line.

Each line beginning with ``S`' represents either a subproblem or stack frame. A subproblem line may be followed by one or more indented lines (beginning with the letter ``R`') which represent reductions associated with that subproblem. The subproblems are indexed with the natural numbers. To obtain a more complete description of a subproblem or reduction, click the mouse on the desired line or move the cursor to the line using the arrow keys (or `C-n` and `C-p`). The description buffer will display the additional information.

The description buffer contains three major regions. The first region contains a pretty-printed version of the current expression. The current subproblem within the expression is highlighted. The second region contains a representation of the frames of the environment of the current expression. The bindings of each frame are listed below the frame header. If there are no bindings in the frame, none will be listed. The frame of the current expression is preceded with ``==>`'.

The bottom of the description buffer contains a third region for evaluating expressions in the environment of the selected subproblem or reduction. This is the only portion of the buffer where editing is possible. This region can be used to find the values of variables in different environments, or even to modify variable values or data structures (note that variables in compiled code cannot usually be modified).

Typing `e` creates a new buffer in which you may browse through the current environment. In this new buffer, you can use the mouse, the arrows, or `C-n` and `C-p` to select lines and view different environments. The environments listed are the same as those in the description buffer. If the selected environment structure is too large to display (i.e. if the number of bindings in the environment exceeds the value of the editor variable `environment-package-limit`) a message to that effect is displayed. To display the environment in this case, use `M-x set-variable` to set `environment-package-limit` to `#f`. At the bottom of the new buffer is a region for evaluating expressions, similar to that of the description buffer.

The appearance of environment displays is controlled by the editor variables `debugger-show-inner-frame-topmost?` and `debugger-compact-display?` which affect the ordering of environment frames and the line spacing respectively.

Type `q` to quit the debugger, killing its primary buffer, any others that it has created, and the window that was popped up to show the debugger.

Note: The description buffers created by the debugger are given names beginning with spaces so that they do not appear in the buffer list; these buffers are automatically deleted when you quit the debugger. If you wish to keep one of these buffers, simply rename it using `M-x rename-buffer`: once it has been renamed, it will not be automatically deleted.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 7.7 Last Resorts

When Scheme exits abnormally it tries to save any unsaved Edwin buffers. The buffers are saved in an auto-save file in case the original is more valuable than the unsaved version. You can use the editor command `M-x recover-file` to recover the auto-saved version. The name used to specify an auto-save file is operating-system dependent: under unix, and on PC file systems with long file names, ``foo.scm`' will be saved as ``#foo.scm#`'; on PC file systems with short file names, it will be saved as ``foo.sav`'.

The following Scheme procedures are useful for recovering from bugs in Edwin's implementation. All of them are designed for use when Edwin is not running--they should not be used when Edwin is running. These procedures are designed to help Edwin's implementors deal with bugs during the implementation of the editor; they are not intended for casual use, but as a means of recovering from bugs that would otherwise require reloading the editor's world image from the disk.

procedure+: save-editor-files
  Examines Edwin, offering to save any unsaved buffers. This is useful if some bug caused Edwin to die while there were unsaved buffers, and you want to save the information without restarting the editor.

procedure+: reset-editor
  Resets Edwin, causing it to be reinitialized the next time that `edit` is called. If you encounter a fatal bug in Edwin, a good way to recover is to first call `save-editor-files`, and then to call `reset-editor`. That should completely reset the editor to its initial state.

procedure+: reset-editor-windows
  Resets Edwin's display structures, without affecting any of the buffers or their contents. This is useful if a bug in the display code causes Edwin's internal display data structures to get into an inconsistent state that prevents Edwin from running.

[ << ] | [ >> ] |  |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

This document was generated by Chris Hanson on September, 19 2003 using texi2html