Racket Mode

Copying

SPDX-License-Identifier: GPL-3.0-or-later

Introduction

The Racket Mode package consists of a variety of Emacs major and minor modes, including:

racket-mode: A major mode to edit .rkt files. Generally assumes #lang racket.
{{{ref(racket-hash-lang-mode)}}}: An alternative to racket-mode using behavior specified by a #lang for colors, indent, expression navigation, etc. Experimental.
{{{ref(racket-xp-mode)}}}: A minor mode to enhance either edit mode. Explain and explore code, similar to background check-syntax in Dr Racket.
racket-repl-mode: A major mode to run programs and use a REPL.
Various other modes to support specific features:
- {{{ref(racket-logger-mode)}}}
- {{{ref(racket-profile-mode)}}}
- {{{ref(racket-debug-mode)}}}

For code, issues, and pull requests, see the Git repo.

To sponsor this work, see GitHub Sponsors or PayPal.

Install, Update, and Uninstall

The most common way to use Racket Mode is to install from a package archive like MELPA or NonGNU ELPA.

Some people also use a system like straight.el.

Note that Racket Mode is only available on MELPA (not “MELPA Stable”), and is available as a “rolling release” from NonGNU ELPA.

Use Emacs 28.1 or newer with NonGNU ELPA

Emacs 28.1 or newer comes configured to use NonGNU ELPA, in which case you can skip ahead to Install.

With older versions of Emacs, you can use MELPA.

Configure Emacs to use MELPA

Following is a quick guide that may work for you. (For definitive instructions and the latest trouble-shooting tips, please see https://melpa.org/#/getting-started.)

Add the following to your ~/.emacs or ~/.emacs.d/init.el:

(require 'package)
(add-to-list 'package-archives
              '("melpa" . "https://melpa.org/packages/")
              t)
(package-initialize)

Restart Emacs.

NOTE: If you ever get an error message about “contacting a host” or “downloading an archive”, the problem is not unique to Racket Mode. Please see https://melpa.org/#/getting-started.

Install

When Emacs is configured to use NonGNU ELPA or MELPA:

Type {{{kbd(M-x)}}} package-initialize {{{kbd(RET)}}}.
Type {{{kbd(M-x)}}} package-refresh-contents {{{kbd(RET)}}}.
Type {{{kbd(M-x)}}} package-install {{{kbd(RET)}}} racket-mode {{{kbd(RET)}}}.

NOTE: If you get an error message about “contacting a host” or “downloading an archive”, the problem is not unique to Racket Mode. Please see https://melpa.org/#/getting-started.

Minimal Racket

If you have installed the minimal Racket distribution (for example by using the homebrew formula) Racket Mode needs some additional Racket packages. A simple way to get all these packages is to install the drracket Racket package. In a command shell:

raco pkg install --auto drracket

A more-targeted approach is instead to install these specific packages and their dependencies:

raco pkg install --auto data-lib errortrace-lib macro-debugger-text-lib rackunit-lib racket-index scribble-lib drracket-tool-text-lib

If you do not want to use racket-xp-mode, then you can omit drracket-tool-text-lib.

On a headless server, you might want to omit gui-lib. Unfortunately, racket-doc depends on gui-lib. On the one hand, if you uninstall racket-doc and gui-lib, you will no longer be able to access documentation when using a Racket Mode back end running there. On the other hand, if you leave gui-lib installed, you should be careful to run the Racket Mode back end using xvfb-run racket.

Uninstall

To uninstall Racket Mode, simply type {{{kbd(M-x)}}} package-delete {{{kbd(RET)}}} racket-mode {{{kbd(RET)}}}.

You should probably also exit and restart Emacs.

Update

Upgrading all packages

The “easy path” provided by Emacs is to update all packages to their latest versions. Although you might not want to do this — see next section — here is how to do so:

Use {{{kbd(M-x)}}} package-initialize.
Use {{{kbd(M-x)}}} package-refresh-contents.
Use {{{kbd(M-x)}}} list-packages. It should display a message like “42 packages can be upgraded; type ‘U’ to mark them for upgrading.”.
Press {{{kbd(U)}}} as suggested to mark them all.
Press {{{kbd(x)}}} to execute.

After such a mass update, it might be wise to exit and restart Emacs.

NOTE: If you get an error message about “contacting a host” or “downloading an archive”, the problem is not unique to Racket Mode. Please see https://melpa.org/#/getting-started.

Updating just Racket Mode

Updating all packages sometimes is more than you want. For example, maybe you will discover that some packages have changed in ways that require you to take time to learn about, change customizations, and so on.

To update just Racket Mode:

{{{ref(Uninstall)}}}.
Optional but most reliable: Exit and restart Emacs.
{{{ref(Install)}}} again. This will install the latest version.

Configure

Although Racket Mode can be customized with many {{{ref(Variables)}}}, there is only one that you might need to set: {{{ref(racket-program)}}}. This is the name or pathname of the Racket executable. It defaults to Racket.exe on Windows else racket.

On Windows or Linux, this default will probably work for you.

On macOS, downloading Racket doesn’t add its bin directory to your PATH. Even after you add it, GUI Emacs doesn’t automatically use your path (unless you use the handy exec-path-from-shell package). Therefore you might want to set racket-program to a complete pathname.

You can setq this directly in your Emacs init file (~/.emacs or ~/.emacs.d/init.el), or, use {{{kbd(M-x)}}} customize, as you prefer.

Which major mode to use

Racket is a programming language.

Racket is also a “language-oriented programming language”. Most Racket source files contain a `#lang` line. The lang may be an s-expression lang like racket, or an at-expression lang like scribble/manual, or something completely different like datalog or rhombus.

The Racket Mode package offers a choice of two major modes to use in buffers for viewing and editing source code. Each has pros and cons.

Whereas racket-mode is in the tradition of Emacs lisp-mode and scheme-mode and assumes s-expression langs, racket-hash-lang-mode takes the approach of DrRacket to work for all langs.

racket-mode is the original, “classic” mode for #lang racket and related s-expression languages. It is implemented entirely in Emacs and does not need Racket Mode’s back end racket process running. Font-lock (coloring) uses rules for a fixed set of identifiers from racket lang and popular modules like racket/match. Indentation uses rules for a fixed set of forms, and may be customized (see below).
racket-hash-lang-mode uses font-lock (colors) and indentation determined by the lang; to get this information it does need the Racket Mode’s back end racket process running. Although basic editing should feel fast, you might notice some delay when indenting. You might see colors appear after a small delay (but it will not block editing). Speaking of colors, they will be “plainer” than racket-mode – mostly just for different kinds of tokens like numbers, comments, strings, and keywords. This looks similar to DrRacket. However if you also enable the minor mode racket-xp-mode, it will eventually add more colors at definition and use sites, and vary the colors depending on whether the identifier is local, imported, or from the module language. So you may see the “syntax” highlighting appear fairly quickly from racket-hash-lang-mode, and later see more “semantic” highlighting contributed by racket-xp-mode. The end result will be about as rich, although not exactly the same, as racket-mode.

You can use different major modes for different kinds of files:

For editing .rkt files and s-expression langs, which mode to use is personal preference.
For .scrbl and at-expression langs like scribble/manual, racket-hash-lang-mode is probably better than racket-mode. (Note there is also an unrelated scribble-mode package.)
For non-s-expression langs like datalog or rhombus (.rhm), racket-hash-lang-mode is definitely better than racket-mode. (Note there is also an unrelated rhombus-mode package.)

You can use auto-mode-alist to tell Emacs which major mode to use initially for certain file extensions. Also, in a buffer you can use M-x racket-mode and M-x racket-hash-lang-mode to switch between them.

Key bindings

To customize things like key bindings, you can use racket-mode-hook in your Emacs init file to modify racket-mode-map. For example, although {{{kbd(C-c C-c)}}} is bound by default to the racket-run command, let’s say you wanted {{{kbd(F5)}}} to be an additional binding:

(add-hook 'racket-mode-hook
          (lambda ()
            (define-key racket-mode-map (kbd "<f5>") 'racket-run)))

Likewise for racket-repl-mode-hook and racket-repl-mode-map.

Font-lock (syntax highlighting)

Note: The alternative major mode {{{ref(racket-hash-lang-mode)}}} disables all of the following behavior and uses colors determined by the #lang.

Font-lock (as Emacs calls syntax highlighting) can be controlled using the variable font-lock-maximum-decoration, which defaults to t (maximum). You can set it to a number, where 0 is the lowest level. You can even supply an association list to specify different values for different major modes.

Historically you might choose a lower level for speed. These days you might do so because you prefer a simpler appearance.

Racket Mode supports four, increasing levels of font-lock:

0: Just strings, comments, and #lang.
1: #:keyword and self-evaluating literals like numbers, quoted symbols (including symbols with spaces delimited by | characters), and #rx and #px regular expressions.
2: Identifiers in define-like and let-like forms.
3: Identifiers provided by racket, typed/racket, racket/syntax, and syntax/parse. (This level effectively treats Racket as a language, instead of a language for making languages.).

Completion at point

In Emacs, a major mode may supply a “completion-at-point function”. This function is used by manual completion commands like complete-symbol (bound by default to {{{kbd(C-M-i)}}}), as well as by auto-completion packages like company-mode.

racket-mode supplies racket-complete-at-point, which simply supplies the same symbols that it knows how to font-lock. This does not require the Racket Mode back end to be running. But of course the completion candidates do not correspond to your program’s definitions or those it imports. This is a static, “better than nothing” fallback.
racket-xp-mode — an optional minor mode that enhances racket-mode — supplies racket-xp-complete-at-point, which uses a static analysis to find local and imported binding names. Although this requires the Racket Mode back end to be running — and will automatically start it — it does not require the edit buffer to be racket-run. This also supplies meta data usable by the company-capf backend.
racket-repl-mode supplies racket-repl-complete-at-point, which uses the result of namespace-mapped-symbols on the program currently running in the REPL.

These completion functions are set by default. (However, racket-xp-mode is not enabled by default. To do so: {{{ref(racket-xp-mode)}}}.)

If you want {{{kbd(TAB)}}} to do completion as well as indent, add the following to your Emacs init file:

(setq tab-always-indent 'complete)

This changes the behavior of Emacs’ standard indent-for-tab-command, to which {{{kbd(TAB)}}} is bound by default in racket-mode and racket-repl-mode.

Completion in minibuffer

Sometimes Racket Mode asks for input in the minibuffer. To do so it uses the standard Emacs function completing-read, so as to be compatible with all Emacs packages that enhance completing-read, such as helm, ivy, ido-completing-read+, vertico, and so on.

(Earlier versions of Racket Mode sometimes used ido-completing-read. If you have upgraded Racket Mode and miss that, simply install the ido-completing-read+ package.)

Xref (definitions and references)

Several modes support the Emacs commands

{{{kbd(M-.)}}} xref-find-definitions
{{{kbd(M-?)}}} xref-find-references
{{{kbd(M-\,)}}} xref-pop-marker-stack

To do so, each mode adds a local hook for xref-backend-functions:

{{{ref(racket-mode)}}}: #'racket-mode-xref-backend-function
{{{ref(racket-xp-mode)}}}: #'racket-xp-xref-backend-function
{{{ref(racket-repl-mode)}}}: #'racket-repl-xref-backend-function

If you prefer, you can remove the local hook — e.g. for racket-mode: (remove-hook 'xref-backend-functions #'racket-mode-xref-function t).

You can M-x customize-group and enter xref to adjust some other settings. For example, the customization variable xref-prompt-for-identifier controls which commands prompt you and when. You might prefer to set it to nil.

If you use paredit, by default it binds {{{kbd(M-?)}}} to paredit-convolute-sexp. You can change that binding in paredit-mode-map allowing the global binding for {{{kbd(M-?)}}} to be used, or, pick some other key for xref-find-references in the global map.

Finally, what to expect:

Racket does not have a global or project-wide database of definitions and references.
Various modules can export identifiers with the same symbolic value – for example a different “define” is provided by racket/base, typed/racket/base, and other modules.
A module can import something, then rename, contract, and re-export it.

As a result, to find a definition, it is necessary to know exactly which identifier is meant — either by expanding the module (as is done by racket-xp-mode) or by actually running it (racket-repl-mode). Once known, we can usually find the definition site, even through a chain of renaming and/or contract-wrapping exports. In addition, when point is on a module within require form, we can usually find the source file. (In plain racket-mode edit buffers not enhanced by racket-xp-mode, the only thing that xref-find-definitions does is visit relative requires, e.g. foo.rkt in (require "foo.rkt").)

As for finding references, the default xref implementation is used, which greps for strings among a project’s files. Although racket-xp-mode can sometimes do better, using drracket/check-syntax for definitions and references within the current buffer, beyond those it also falls back to the default implementation.

In any case, using the Emacs xref API allows for consistent command names, shortcut keys, and even a special buffer to navigate among references and visit each source location.

Indent

Note: The alternative major mode {{{ref(racket-hash-lang-mode)}}} disables all of the following behavior and uses indentation determined by the #lang.

Indentation can be customized in a way similar to lisp-mode and scheme-mode: {{{ref(racket-indent-line)}}}.

(Indentation preserves your line breaks. If you want to use an auto-reformatter — an expressive pretty printer that chooses line breaks while computing an optimal layout — the Racket package fmt is supported by the Emacs package emacs-format-all-the-code.)

paredit

Note: If you use {{{ref(racket-hash-lang-mode)}}}, you can use racket-hash-lang-mode-hook to enable/disable paredit based on the specific #lang.

If you use paredit, you might want to add keybindings to paredit-mode-map:

Bind the curly brace keys to paredit-open-curly and paredit-close-curly.
Bind whatever keys you prefer for paredit-wrap-square and paredit-wrap-curly.

For example, with ~use-package~:

(use-package paredit
  :ensure t
  :config
  (dolist (m '(emacs-lisp-mode-hook
               racket-mode-hook
               racket-repl-mode-hook))
    (add-hook m #'paredit-mode))
  (bind-keys :map paredit-mode-map
             ("{"   . paredit-open-curly)
             ("}"   . paredit-close-curly))
  (unless terminal-frame
    (bind-keys :map paredit-mode-map
               ("M-[" . paredit-wrap-square)
               ("M-{" . paredit-wrap-curly))))

Starting c. November 2022, paredit binds the {{{kbd(RET)}}} key to its own command. Unfortunately this is not compatible with interactive modes — including but not limited to racket-repl-mode — which expect {{{kbd(RET)}}} to be bound to a command to submit your input to the REPL. In other words, if you type an expression and hit {{{kbd(RET)}}}, nothing will happen and the REPL will seem frozen. You M-x racket-repl-submit to proceed.

If you want to use paredit with interactive modes, their advice is to remove the binding from paredit-mode-map (note that this will also disable it for all buffers, including editing buffers). One way you can do this for all related keys:

(dolist (k '("RET" "C-m" "C-j"))
  (define-key paredit-mode-map (kbd k) nil))

smartparens

If instead of paredit you prefer smartparens, you can use the default configuration it provides for Lisp modes generally and for Racket Mode specifically:

(require 'smartparens-config)

Appearance of parentheses

If you prefer parentheses to appear “dimmed”, see paren-face.

If you prefer the opposite, see rainbow-delimiters.

Edit buffers and REPL buffers

By default, all racket-mode edit buffers share one racket-repl-mode buffer, named *Racket REPL*. For example, if you run foo.rkt, the REPL prompt changes to foo.rkt>, and the REPL is inside the file module namespace. If you then run bar.rkt, the REPL prompt changes to bar.rkt>, and you are in that namespace.

If you prefer, you can use more than one REPL buffer, by customizing the variable {{{ref(racket-repl-buffer-name-function)}}}:

Share a REPL buffer among files belonging to the same project; each REPL buffer is named *Racket REPL <project-name>*.
A unique REPL buffer for each edit buffer, similar to Dr Racket; each REPL buffer is named *Racket REPL <file.rkt>*.
You can also define your own, custom function.

You can customize where the REPL buffer is displayed by adding an item to the Emacs variable display-buffer-alist. A good regular expression to use for this would be \\`\\*Racket REPL. For example, if you wanted to make the REPL buffer appear in a new frame:

(add-to-list 'display-buffer-alist
             '("\\`\\*Racket REPL"
               (display-buffer-reuse-window
                display-buffer-pop-up-frame)
               (reusable-frames . 0)
               (inhibit-same-window . t)))

eldoc

By default Racket Mode sets eldoc-documentation-function to nil — no eldoc-mode support. You may set it to racket-eldoc-function in a racket-mode-hook and racket-repl-mode-hook if you really want to use eldoc-mode with Racket. But it is not a very satisfying experience because Racket is not a very “eldoc-friendly” language. Although Racket Mode attempts to discover argument lists, contracts, or types this doesn’t work in many common cases:

Many Racket primitives are defined in #%kernel or #%runtime. There’s no easy way to determine their argument lists. Most do not provide a contract.
Many of the interesting Racket forms are syntax (macros) not functions. There’s no easy way to determine their “argument lists”.
When a form has documentation, Racket Mode can show the "bluebox" – but often that does not fit in a single line as you would normally expect with eldoc.

A more satisfying experience is to use {{{ref(racket-xp-describe)}}} or {{{ref(racket-xp-documentation)}}}.

Start faster

You can use {{{ref(racket-mode-start-faster)}}} to make the Racket REPL start faster.

Unicode input method

An optional Emacs input method, racket-unicode, lets you easily type various Unicode symbols that might be useful when writing Racket code.

To automatically enable the racket-unicode input method in racket-mode and racket-repl-mode buffers, put the following code in your Emacs init file:

(add-hook 'racket-mode-hook      #'racket-unicode-input-method-enable)
(add-hook 'racket-repl-mode-hook #'racket-unicode-input-method-enable)

{{{see(racket-unicode-input-method-enable)}}}.

{{{see(racket-insert-lambda)}}}.

Ligatures

Prior to Emacs 28.0.50, things like auto-composition-mode or ligature-mode that use composition-function-table to display ligatures can cause Emacs to freeze. This can happen when an Emacs overlay displays a string containing such a ligature. Although the problem is not limited to Racket Mode, it affects the overlays created by racket-show-pseudo-tooltip, as used by racket-xp-mode. The only known work-around is to change the value of racket-show-functions to something “boring” such as (racket-show-echo-area).

Architecture

Racket Mode consists of a single Emacs front end, and one or more processes running a back end written in Racket.[fn:pkg]

A back end is responsible for commands that cannot be implemented in Emacs Lisp, as well as supplying zero or more REPLs.

Although you can start and stop a back end with racket-start-back-end and racket-stop-back-end, a back end is normally started automatically when the front end needs to issue some command. This includes commands that do not involve racket-run or a REPL. For example racket-xp-mode issues commands to check your code and annotate the buffer, even if you do not run it. In other words, a back end supplies zero or more REPLs — a back end is not the same thing as a REPL.

To learn more about how many REPLs are used: {{{see(racket-repl-buffer-name-function)}}}.

In the common case there is only one back end, on the same local host as Emacs, and it is used for .rkt files in any directory.

{{{img(scenario-0, Emacs front end and one local back end)}}}

However you can configure using any number of back ends on any number of local or remote hosts.

As one example, you can have multiple back ends on the local host. One back end is used for a project under a specific subdirectory, and the other back end for all others. (Perhaps one project needs Racket built from source, and everything else uses an installed, older version of Racket. By using different back ends, not only will racket-run use the desired version of Racket for a file, so will commands for documentation or visiting definitions.)

{{{img(scenario-1, Emacs front end and two local back ends — one for a project path)}}}

Furthermore, you could work with a project located on a remote host, whose files you edit using TRAMP. You also want the back end to run there. For a remote host, Racket Mode copies its back end source files to the remote when necessary, and runs the back end using ssh.

{{{img(scenario-2, Emacs front end and a back end on a remote host)}}}

Of course the remote can also use different back ends for different paths.

{{{img(scenario-3, Emacs front end and two back ends on a remote host)}}}

And of course you can have multiple remotes.

{{{img(scenario-4, Emacs front end and two back ends each on two remote hosts)}}}

If you need any of these “fancy” configurations: {{{see(racket-add-back-end)}}}.

However by default a configuration is automatically created for one back end on the local host. For that very common case, you don’t need to configure anything.

[fn:pkg] Racket Mode’s Racket code is delivered as part of the Emacs package — not as a Racket package. Delivering both Emacs and Racket code in one Emacs package simplifies installation and updates. The main drawback is that the Racket code is not automatically compiled, as would normally be done by raco pkg install. To address this: {{{see(racket-mode-start-faster)}}}.

Reference

The following sections are generated from the doc strings for each command, variable, or face. (As a result, some of the formatting might not be quite as nice or correct as in the previous sections.)

You can also view these by using the normal Emacs help mechanism:

{{{kbd(C-h f)}}} and enter the name of a command.
{{{kbd(C-h v)}}} and enter the name of a variable.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

racket-mode.org

racket-mode.org

Racket Mode

Copying

Introduction

Install, Update, and Uninstall

Use Emacs 28.1 or newer with NonGNU ELPA

Configure Emacs to use MELPA

Install

Minimal Racket

Uninstall

Update

Upgrading all packages

Updating just Racket Mode

Configure

Which major mode to use

Key bindings

Font-lock (syntax highlighting)

Completion at point

Completion in minibuffer

Xref (definitions and references)

Indent

paredit

smartparens

Appearance of parentheses

Edit buffers and REPL buffers

eldoc

Start faster

Unicode input method

Ligatures

Architecture

Reference

Files

racket-mode.org

Latest commit

History

racket-mode.org

File metadata and controls

Racket Mode

Copying

Introduction

Install, Update, and Uninstall

Use Emacs 28.1 or newer with NonGNU ELPA

Configure Emacs to use MELPA

Install

Minimal Racket

Uninstall

Update

Upgrading all packages

Updating just Racket Mode

Configure

Which major mode to use

Key bindings

Font-lock (syntax highlighting)

Completion at point

Completion in minibuffer

Xref (definitions and references)

Indent

paredit

smartparens

Appearance of parentheses

Edit buffers and REPL buffers

eldoc

Start faster

Unicode input method

Ligatures

Architecture

Reference