search

clojure-emacs / inf-clojure

Basic interaction with a Clojure subprocess
251 stars 45 forks source link
clojure clojure-repl clojurescript emacs repl socket-repl

readme

Circle CI MELPA MELPA Stable NonGNU ELPA Discord License GPL 3

inf-clojure

This package provides basic interaction with a Clojure subprocess (REPL). It's based on ideas from the popular inferior-lisp package.

inf-clojure has two components - a nice REPL buffer (inf-clojure-mode) and a REPL interaction minor mode (inf-clojure-minor-mode), which extends clojure-mode with commands to evaluate forms directly in the REPL.

This documentation tracks the master branch of inf-clojure. Some of the features and settings discussed here might not be available in older releases (including the current stable release). Please, consult the relevant git tag (e.g. 2.2.0) if you need documentation for a specific inf-clojure release.

Overview

inf-clojure aims to expose the extensive self-documenting features of Clojure REPLs via an Emacs package. inf-clojure is extremely simple and does not require special tooling. It supports the following REPLs:

inf-clojure provides a set of essential features for interactive Clojure/ClojureScript/ClojureCLR development:

For a more powerful/full-featured solution see CIDER.

Rationale

inf-clojure's goal is to provide the simplest possible way to interact with a Clojure REPL. In Emacs terminology "inferior" process is a subprocess started by Emacs (it being the "superior" process, of course).

inf-clojure doesn't require much of setup, as at its core it simply runs a terminal REPL process, pipes input to it, and processes its output. As the Clojure socket REPL works in exactly the same manner inf-clojure can also interact with it.

Functionality like code completion and eldoc is powered by evaluation of predefined code snippets that provide the necessary results. As different Clojure REPLs have different capabilities, inf-clojure tracks the type of a REPL and invokes the right code for each REPL type.

inf-clojure is built on top of Emacs's comint. Unfortunately comint is pretty light on official documentation, but there is a good overview/tutorial here.

Installation

Note: inf-clojure requires Emacs 25 or newer.

inf-clojure is available on the official NonGNU ELPA package.el repo and on the community-maintained MELPA Stable and MELPA repos.

NonGNU ELPA and MELPA Stable are recommended as they have the latest stable version. MELPA has a development snapshot for users who don't mind breakage but don't want to run inf-clojure from a git checkout.

You can install inf-clojure using the following command:

M-x package-install [RET] inf-clojure [RET]

or if you'd rather keep it in your Emacs config:

(unless (package-installed-p 'inf-clojure)
  (package-refresh-contents)
  (package-install 'inf-clojure))

If the installation doesn't work try refreshing the package list:

M-x package-refresh-contents

inf-clojure-minor-mode will be auto-enabled for Clojure source buffers after you do M-x inf-clojure. You can disable this behavior by setting inf-clojure-auto-mode to nil.

You can also add the following to your Emacs config to enable inf-clojure-minor-mode for Clojure source buffers, regardless of whether there's an inf-clojure REPL running:

(add-hook 'clojure-mode-hook #'inf-clojure-minor-mode)

Warning: Don't enable inf-clojure-minor-mode and cider-mode at the same time. They have overlapping functionality and keybindings and the result will be nothing short of havoc.

Basic Usage

Just invoke M-x inf-clojure or press C-c C-z within a Clojure source file. You should get a prompt with the supported REPL types and common startup forms. You can select one of these or type in your own custom startup. This will start a REPL process for the current project and you can start interacting with it.

If you want to use a socket REPL server, use M-x inf-clojure-socket-repl which will start a socket server and connect to it for you.

If you've already started a socket REPL server, use M-x inf-clojure-connect and enter its host and port numbers.

Inf-clojure aims to be very simple and offer tooling that the REPL itself exposes. A few commands are:

For a list of all available commands in inf-clojure-mode (a.k.a. the REPL) and inf-clojure-minor-mode you can either invoke C-h f RET inf-clojure-mode and C-h f RET inf-clojure-minor-mode or simply browse their menus.

Many inf-clojure-minor-mode commands by default act on the symbol at point. You can, however, change this behaviour by invoking such commands with a prefix argument. For instance: C-u C-c C-v will ask for the symbol you want to show the docstring for.

Configuration

Note: The configuration options were changed massively in inf-clojure 3.0.

In the time-honoured Emacs tradition inf-clojure's behaviour is extremely configurable.

You can set custom values to inf-clojure variables on a per-project basis using directory variables or by setting them in in your init file.

You can see all the configuration options available using the command M-x customize-group RET inf-clojure.

Startup

While inf-clojure is capable of starting many common REPLs out of the box, it's fairly likely you will want to set some custom REPL startup command (e.g. because you need to include some tools.deps profile) and the REPL type that goes with it. This is most easily achieved with the following .dir-locals.el:

((nil
  (inf-clojure-custom-startup . "clojure -A:compliment")
  (inf-clojure-custom-repl-type . clojure)))

Note: This file has to be in the directory in which you're invoking inf-clojure or a parent directory.

There are two important configuration variables here:

  1. inf-clojure-custom-startup: Which startup command to use so inf-clojure can run the inferior Clojure process (REPL).
  2. inf-clojure-custom-repl-type: The type of the REPL started by the above command (e.g. lumo).

If these are set and you wish to prevent inf-clojure from using them, use a prefix arg when invoking inf-clojure (C-u M-x inf-clojure).

REPL Features

The supported REPL-features are in an alist called inf-clojure-repl-features and it has the following shape:

'((cljs . ((doc . "(cljs.repl/doc %s)")
           (source . "(cljs.repl/source %s)")
           (arglists . "(try (->> '%s cljs.core/resolve cljs.core/meta :arglists) (catch :default _ nil))")
           (apropos . "(cljs.repl/apropos \"%s\")")
           (ns-vars . "(cljs.repl/dir %s)")
           (set-ns . "(in-ns '%s)")
           (macroexpand . "(cljs.core/macroexpand '%s)")
           (macroexpand-1 . "(cljs.core/macroexpand-1 '%s)"))))

If you want to add a new REPL type, just do something like:

(add-to-list 'inf-clojure-repl-features
             (cons new-repl-type '((doc . "(myrepl/doc-command %s")
                                   (source . "...")
                                   ...)))

The inf-clojure-repl-features data structure is just an alist of alists, so you can manipulate it in numerous ways.

If you want to update a specific form there is a function inf-clojure-update-repl-feature which can be used like so:

(inf-clojure-update-feature 'clojure 'completion "(incomplete.core/completions \"%s\")")

Caveats

As inf-clojure is built on top of comint it has all the usual comint limitations - namely it can't handle well some fancy terminal features (e.g. ANSI colours). In general the "dumber" your terminal REPL is, the better (e.g. clojure vs clj). Connecting to a socket REPL is one simple way to avoid dealing with this type of problems.

If you decide not to use the socket REPL, it is highly recommended you disable output coloring and/or readline facilities: inf-clojure does not filter out ASCII escape characters at the moment and will not behave correctly.

For Leiningen, there are no command-line switches and you need to add a custom project.clj option:

...
:repl-options {:color false}
...

Clojure Command Line Socket REPL

If you have the new Clojure CLI tools installed you can use the clojure command:

do not use clj because it adds readline support

$ clojure -J-Dclojure.server.repl="{:port 5555 :accept clojure.core.server/repl}"

Then either C-c M-c RET localhost RET 5555 from within Emacs or add the following to your .dir-locals.el:

((nil . ((inf-clojure-custom-startup . ("localhost" . 5555)))))

Leiningen Socket REPL

For Leiningen, add the following option to your ~/.lein/profiles.clj or your project.clj:

:jvm-opts ["-Dclojure.server.repl={:port 5555 :accept clojure.core.server/repl}"]

Then run lein repl from within your project directory to start the REPL. To connect, you can either m-x inf-clojure-connect [RET] localhost [RET] 5555 or you can put in a dir local file the information on how connect:

((nil (inf-clojure-custom-startup "localhost" . 5555)))

The socket server REPL configuration options are described here.

Lumo Socket REPL

Lumo is decoupled from inf-clojure-project-type and therefore the command used depends on what you are using for dependency resolution.

For example if a project.clj is present in the project root folder, inf-clojure-lein-cmd will be used.

After you launch lumo ... -n 5555, as customary, either C-c M-c RET localhost RET 5555 from within Emacs or add the following to your .dir-locals.el:

((nil (inf-clojure-custom-startup "localhost" . 5555)))

Multiple Process Support

To run multiple Clojure processes, you start the first up with inf-clojure. It will be in a buffer named *inf-clojure*. Rename this buffer with rename-buffer. You may now start up a new process with another inf-clojure. It will be in a new buffer, named *inf-clojure*. You can switch between the different process buffers with switch-to-buffer.

Note: If you're starting inf-clojure within a Clojure project directory the name of the project will be incorporated into the name of the REPL buffer

Commands that send text from source buffers to Clojure processes (like inf-clojure-eval-defun or inf-clojure-show-arglists) have to choose a process to send to, when you have more than one Clojure process around. This is determined by the global variable inf-clojure-buffer.

Suppose you have three inferior Clojures running:

Buffer              Process
------              -------
foo                 inf-clojure
bar                 inf-clojure<2>
*inf-clojure*       inf-clojure<3>

If you do a inf-clojure-eval-defun command on some Clojure source code, what process do you send it to?

This process selection is performed by function inf-clojure-proc. Whenever inf-clojure fires up a new process, it resets inf-clojure-buffer to be the new process's buffer. If you only run one process, this does the right thing. If you run multiple processes, you might need to change inf-clojure-buffer to whichever process buffer you want to use.

You can use the helpful function inf-clojure-set-repl. If called in an inf-clojure REPL buffer, it will assign that buffer as the current REPL ((setq inf-clojure-buffer (current-buffer)). If you are not in an inf-clojure REPL buffer, it will offer a choice of acceptable buffers to set as the REPL buffer. If called with a prefix, it will always give the list even if you are currently in an acceptable REPL buffer.

Tip: Renaming buffers will greatly improve the functionality of this list; the list "project-1: clojure repl", "project-2: cljs repl" is far more understandable than "inf-clojure", "inf-clojure<2>".

REPL Type

An inf-clojure REPL has an associated type. The available types can be obtained from inf-clojure-repl-features:

(mapcar 'car inf-clojure-repl-features)

;; => (cljs lumo planck joker clojure babashka)

What does it mean that a REPL type is supported? Well, it means that inf-clojure would use the proper Clojure(Script) code internally to power commands like definition lookup and friends. Those differ from REPL to REPL and can't be implemented in a REPL-independent way. The REPL type is inferred on startup when using the inf-clojure command or is specified manually when using inf-clojure-connect.

ElDoc

eldoc-mode is supported in Clojure source buffers and *inferior-clojure* buffers which are running a Clojure REPL.

When ElDoc is enabled and there is an active REPL, it will show the argument list of the function call you are currently editing in the echo area. It accomplishes this by evaluating forms to get the metadata for the vars under your cursor. One side effect of this is that it can mess with repl vars like *1 and *2. You can disable inf-clojure's Eldoc functionality with (setq inf-clojure-enable-eldoc nil).

ElDoc should be enabled by default in Emacs 26.1+. If it is not active by default, you can activate ElDoc with M-x eldoc-mode or by adding the following to you Emacs config:

(add-hook 'clojure-mode-hook #'eldoc-mode)
(add-hook 'inf-clojure-mode-hook #'eldoc-mode)

ElDoc currently doesn't work with ClojureScript buffers and REPL's. You can leave it enabled, it just won't show anything in the echo area.

Code Completion

Code completion is a tricky aspect if you are trying to be as close to a generic REPL as possible. Planck and lumo REPL implementations explicitly provide completion functions in their REPL namespaces. For clojure, you will need to have a library on your classpath. If you are using a recent version of Leiningen, you already have incomplete. You could alternatively use compliment {:mvn/version "0.3.10"}.

;; for incomplete
(inf-clojure-update-feature 'clojure 'completion "(incomplete.core/completions \"%s\")")

;; or
;; for compliment
(inf-clojure-update-feature 'clojure 'completion "(compliment.core/completions \"%s\")")

If you give a form for the completion form, it is your responsibility to ensure that this namespace is on the classpath and required. If using Leiningen, this is done for you with incomplete. If adding compliment, the following sample deps.edn can conveniently add the dep to your program:

{:aliases {:compliment {:extra-deps {compliment {:mvn/version "0.3.10"}}}}}

Use the startup command: clojure -A:compliment. Then require the ns once so that the completion machinery will work: (require 'compliment.core). Now tab completion should work.

For more advanced customization, code completion is particularly open to customization. Not only you can setq the customary inf-clojure-completion-form, inf-clojure-completion-form-lumo, inf-clojure-completion-form-planck and inf-clojure-completion-form-joker - the form to send to the REPL - but you can also use inf-clojure-completions-fn for specifying a function that given the REPL response should return Elisp data compatible with completion-at-point-functions. For more info run M-x describe-variable RET inf-clojure-completions-fn. Another option is to have a look at how cider does it.

Lumo Setup

For an optimal Lumo experience the -d needs to be passed to Lumo when launched from the command line. This disable readline support in order to play nicely with Emacs.

Troubleshooting

Things seem broken

Inf-clojure is intentionally quite simple and just sends commands to a REPL on your behalf to provide features. In order to do this inf-clojure largely needs to know the REPL type so it can format the correct calls. Most end up in (lumo.repl/doc [symbol]) or (cljs.repl/doc ...) so its important that the REPL type is set correctly. This REPL type exists in the process buffer (REPL) and the source buffers as a cache. If you have problems, run m-x inf-clojure-set-repl-type from the source buffer to set the REPL type in both buffers. To see how simple inf-clojure is, look at inf-clojure-repl-features to see largely how things are laid out.

REPL not responsive in Windows OS

In Windows, the REPL is not returning anything. For example, type (+ 1 1) and press ENTER, the cursor just drops to a new line and nothing is shown.

The explanation of this problem and solution can be found here.

The solution is to create a file named .jline.rc in your $HOME directory and add this line to that file:

jline.terminal=unsupported

Log process activity

Standard Emacs debugging turns out to be difficult when an asynchronous process is involved. In this case try to enable logging:

(setq inf-clojure-log-activity t)

This creates .inf-clojure.log in the project directory so that you can tail -f on it.

License

Copyright © 2014-2022 Bozhidar Batsov and contributors.

Distributed under the GNU General Public License; type C-h C-c to view it.