duncanmak / geiser

emacs and scheme talk to each other

-*- mode: org -*-

Overview

Geiser is a generic Emacs/Scheme interaction mode, featuring an enhanced REPL and a set of minor modes improving Emacs’ basic scheme major mode. The main functionalities provided are:

• Evaluation of forms in the namespace of the current module.
• Macro expansion.
• File/module loading.
• Namespace-aware identifier completion (including local bindings, names visible in the current module, and module names).
• Autodoc: the echo area shows information about the signature of the procedure/macro around point automatically.
• Jump to definition of identifier at point.
• Access to documentation (including docstrings when the implementation provides it).
• Listings of identifiers exported by a given module.
• Listings of callers/callees of procedures.
• Rudimentary support for debugging (list of evaluation/compilation error in an Emacs’ compilation-mode buffer).
• Support for inline images in schemes, such as Racket, that treat them as first order values.

NOTE: if you’re not in a hurry, Geiser’s website (http://www.nongnu.org/geiser/) contains a nicer manual, also included in Geiser tarballs as a texinfo file (doc/geiser.info).

Requirements

Geiser needs Emacs 23.2 or better, and at least one of the supported scheme implementations:

• Guile 2.0 or better.
• PLT Racket 6.0 or better.
• Chicken 4.8.0 or better.
• MIT/GNU Scheme 9.1.1 or better.
• Chibi 0.7.3 or better.
• Chez 9.4 or better.

Installation

The easiest way is to use MELPA, and just type `M-x install-package RET geiser` inside emacs.

Geiser can be used either directly from its uninstalled source tree or byte-compiled and installed after performing the standard configure/make/make install dance. See the INSTALL file for more details.

Chicken Addendum

These steps are necessary to fully support Chicken Scheme, but are not required for any other scheme.

• Install the necessary support eggs: $ chicken-install -s apropos chicken-doc
• Update the Chicken documentation database: $ cd `csi -p ‘(chicken-home)’` $ curl http://3e8.org/pub/chicken-doc/chicken-doc-repo.tgz | sudo tar zx

Basic configuration

The loading invocations above install all supported Scheme implementations. You can list explicitly the ones that you want by setting the variable `geiser-active-implementations’ before loading geiser.el. For instance:

(setq geiser-active-implementations ‘(chicken guile))

On opening a scheme file, Geiser will try to guess its Scheme, defaulting to the first in the list. Use `C-c C-s’ to select the implementation by hand (on a per file basis).

Check the geiser customization group for some options with:

M-x customize-group RET geiser RET

In particular, customize `geiser-<impl>-binary’, which should point to an executable in your path.

To start a REPL, M-x geiser.

Completion with company-mode

Geiser offers identifier and module name completion, bound to M-TAB and M-` respectively. Only names visible in the current module are offered.

While that is cool and all, things are even better: if you have company-mode (http://company-mode.github.io/) installed, Geiser’s completion will use it. Just require company-mode and, from then on, any new scheme buffer or REPL will use it.

Quick key reference

In Scheme buffers:

C-c C-z	Switch to REPL
C-c C-a	Switch to REPL and current module
C-c C-s	Specify Scheme implementation for buffer
M-.	Go to definition of identifier at point
M-,	Go back to where M-. was last invoked
C-c C-e m	Ask for a module and open its file
C-c C-e C-l	Add a given directory to Scheme’s load path
C-c C-e [	Toggle between () and [] for current form
C-M-x	Eval definition around point
C-c C-c	Eval definition around point
C-c M-e	Eval definition around point and switch to REPL
C-x C-e	Eval sexp before point
C-c C-r	Eval region
C-c M-r	Eval region and switch to REPL
C-c C-b	Eval buffer
C-c M-b	Eval buffer and switch to REPL
C-c C-m x	Macro-expand definition around point
C-c C-m e	Macro-expand sexp before point
C-c C-m r	Macro-expand region
C-c C-k	Compile and load current file
C-c C-l	Load scheme file
C-c C-d d	See documentation for identifier at point
C-c C-d s	See short documentation for identifier at point
C-c C-d i	Look up manual for identifier at point
C-c C-d m	See a list of a module’s exported identifiers
C-c C-d a	Toggle autodoc mode
C-c <	Show callers of procedure at point
C-c >	Show callees of procedure at point
M-TAB	Complete identifier at point
M-`, C-.	Complete module name at point
TAB	Complete identifier at point or indent
	(If `geiser-mode-smart-tab-p’ is t)

In the REPL

C-c C-z	Start Scheme REPL, or jump to previous buffer
C-c M-o	Clear scheme output
C-c C-q	Kill Scheme process
C-c C-l	Load scheme file
C-c C-k	Nuke REPL: use it if the REPL becomes unresponsive
M-.	Edit identifier at point
TAB, M-TAB	Complete identifier at point
M-`, C-.	Complete module name at point
M-p, M-n	Prompt history, matching current prefix
C-c C-m	Set current module
C-c C-i	Import module into current namespace
C-c C-r	Add a given directory to scheme’s load path
C-c C-d C-d	See documentation for symbol at point
C-c C-d C-m	See documentation for module
C-c C-d C-a	Toggle autodoc mode

In the documentation browser:

f	Next page
b	Previous page
TAB, n	Next link
S-TAB, p	Previous link
N	Next section
P	Previous section
k	Kill current page and go to previous or next
g, r	Refresh page
c	Clear browsing history
., M-.	Edit identifier at point
z	Switch to REPL
q	Bury buffer

In backtrace (evaluation/compile result) buffers:

• M-g n, M-g p, C-x ` for error navigation.
• q to bury buffer.