austinhaas / scrim

An Emacs package for Clojure REPL interaction

Scrim - Simple Clojure REPL Interaction Mode

An Emacs package for Clojure REPL interaction.

A major mode for a Clojure REPL process in a buffer.

A minor mode for buffers containing Clojure(Script) code.

Status

Alpha

Goals

• The basic features necessary to use Emacs as a Clojure REPL interface.
• Compatibility with the REPLs that are included with Clojure.
• Compatibility with Clojure and Clojurescript.
• Strictly minimal, by default.
• Customizable, where appropriate.
• Extensible.
• No magic; never guess what the user wants.

Non-Goals

• Support for other REPLs.

• Support for multiple REPLs.

  This may be added later, but only if there is a simple, magic-free way to do it, that doesn't complicate the more common case of a single REPL. The main challenge seems to be keeping track of which buffer maps to which REPL.

• Anything that isn't essential to basic REPL interaction, but could be added separately (e.g., eldoc).

  Additional features may be included in a separate, optional, non-essential file. Support (e.g., hooks) may be included in the core file if it can be done simply.

Dependencies

• clojure-mode

Installation

Clone the repository

cd ~/.emacs.d/site-lisp  # or wherever you keep locally installed Emacs packages
git clone [email protected]:austinhaas/scrim.git

Update your .emacs

I've included a couple init files that you can use as reference. This is what I use to initialize scrim. Take what you want and modify as necessary.

• A minimal configuration
• Extra (experimental)

Usage

The keybindings can be displayed by either using C-h m in a Scrim-enabled buffer and then selecting Scrim under the enabled minor modes, or C-h f scrim-minor-mode RET.

Guides

This repository includes a couple simple sample projects with instructions that walk through the steps required to get to a working interactive development environment.

• Clojure
• ClojureScript

Bugs, feedback, etc.

Please create an issue here: https://github.com/austinhaas/scrim/issues

Debugging

See README files in sample projects.

Credit

Similar projects I've used and referenced:

• SLIME
• Geiser
• inf-clojure
• CIDER

License

Copyright (c) 2021 Austin Haas.

Licensed under the GNU General Public License, version 3.

scrim's Issues

Consider hiding REPL buffer with C-c C-z.

For when you want to glance at the REPL, then return to whatever buffer it may have replaced.

Eldoc: ClojureScript doesn't know the current namespace, so symbols may be looked up in the wrong namespace.

In Clojure, eldoc won't look up a symbol unless the current namespace matches the current buffer. In ClojureScript, `ns always returns nil. To make eldoc work in ClojureScript at all, that check doesn't happen. This causes a few issues:

• The symbol is looked up in the wrong namespace. Usually, that means it can't be found, but it could possibly return unexpected results: if the same symbol exists in more than one namespace.
• The most recent symbol's documentation is cached locally, so if eldoc tries to look up a symbol and fails because you are in the wrong namespace, and then you change to the namespace that matches the current buffer, then you'll need to move point away from that symbol to another symbol to clear the cache. This could possibly be fixed just by not caching missed values.

Evaluate "almost toplevel" expressions inside `comment` expression without evaluating the comment expression.

echo-output doesn't work correctly without echo-input

The problem is that scrim--echo-output uses comint-last-input-end to determine where the output starts, but that isn't set if scrim-echo-input-p is nil. The result is that it just keeps displaying the complete history.

A fallback could be to search for the end of the last prompt.

I think we should make echo input the only option and do this instead: #19.

`scrim-send-pp` doesn't work in clojurescript

Needs cljs.pprint ns, not clojure.pprint ns.

Not sure if there is a simple solution.

Output doesn't always display in the echo area.

"Background" evaluations shouldn't change the REPL state.

This applies to functions that use scrim--redirect-result-from-process, and it affects the repl vars like e* and 1*.

Truncate long input

Allow user to specify the threshold.

The user should be able to interactively show/hide the full input.

Consider using hideshow or something based on emacs' set-selective-display.

Some commands should be smarter when searching for the target symbol.

E.g., if a command applies to a function, then search up for the nearest containing function symbol.

Improve handling of output.

This may only pertain to displaying output in the echo area.

The output filter function that gets called when new output arrives may be called multiple times for each output. We already filter out prompts, trailing newlines, and empty strings, but desired output might also be split into multiple calls, and only the last will be displayed in the echo area. That will look incorrect.

Determine if there is any way to modify comint's behavior. If not, then we may need to buffer the output.

Proposal: Each time output is received, use comint's fns to find the output between the last input and the current prompt.

Improve documentation.

• Mention config options.
• Improve guides.

Make scrim-find-definition work for ClojureScript.

eldoc: Consider including the namespace from the current buffer when looking up a symbol.

Currently, eldoc just looks up the symbol in whatever namespace is currently loaded. This may lead to unexpected results.

Add a tutorial.

scrim-eval-innermost-sexp-at-point can't find expression when run in a group of closing parens

Don't recommend paredit hook for REPL buffer.

It's too easy to hit the "unbalanced parens" issue.

"Background" evaluations should catch errors.

Provide an example for a custom REPL command.

eldoc displays a bunch of clojure warnings when you start typing `(:`.

Proposal: don't send ":" to the repl.

Jump to definition

• Jump back.
• https://github.com/clojure/clojure/blob/817abb3d0ca3b7ee80cfe17b5cfe3ea8306f0720/src/clj/clojure/repl.clj#L148
  • Can get the file and line number from (meta (resolve 'clojure.core/+)).
    • Need to use that code above to figure out how to convert that file path to one that can be
      opened in Emacs.
  • Don't know how to communicate out of band with process.
    • Do we want anything to show in the REPL?
    • How do we capture the output?
      • Can we just get the last output?

eldoc mangles function signatures that contain maps

scrim--get-arglists uses elisp's read function, which doesn't understand clojure syntax.

Automatically switch to current namespace before evaluating expression.

Not sure we want this. May be more trouble than it is worth.

Input must be <4096 characters, if process was launched from Emacs

This may be an issue with comint, or something below it.

Cider does not appear to suffer from this issue.

Sometimes evaluating sends an extra newline.

Add keybinding to show stacktrace

Make find-definition work on code eval'd via the repl.

When code is originally loaded, via require, symbols will have metadata associated with them that indicates the file and line from where it was loaded. If you eval the code after that, :file will be changed to "NO_SOURCE_PATH".

I really don't know the best way to handle this. That metadata really only tells you where the code originally came from; if you edit any of the source files, that info may become stale.

It would be good to know how Clojure sets those values in the first place. This might be a good place to start: clojure/clojure@6bbfd94

Error when evaluating forms with a %.

(defn foo% [] 1)

error in process filter: if: Format string ends in middle of format specifier
error in process filter: Format string ends in middle of format specifier

Support eldoc.

This causes the current function symbol (based on point) to display in the minibuffer with its argument lists.

Intial support: 94f7da1

Barely tested in clj, not cljs. Seems to work, but needs improvement.

Known issues:

• Doesn't know how to handle special forms. Prints if: <unknown symbol>. One possible solution might be to get the documentation for the symbol and parse it; seems like what we want is on the 3rd line after a couple spaces.

Log all REPL history

I.e., to a file.

I clear the REPL often, for simplicity and sometimes for performance reasons. It would be nice to have the entire history sometimes.

Use prepl

Not sure how easy this is to implement, because we might have to parse EDN in elisp.

Might make it easy to colorize the output by type.

eldoc: clear cache after loading a namespace

I notice this frequently when:

1. I'm not in the namespace for the current buffer, which I notice because eldoc isn't working.
2. So I switch to the current namespace.
3. But I still have to move point to a new symbol to clear the cache before eldoc will work.

This may depend on #28

The scrim function should take a program and arguments

The arguments need to be passed to make-comint-in-buffer as SWITCHES.

Input is truncated when \. is inside a string.

Steps to reproduce:

1. Connect to REPL.
2. Enter "\." at the REPL prompt.

Actual behavior:
The REPL responds with a message: "Unsupported escape character: \.", and no prompt is returned.

Expected behavior:
Same error message, but a prompt is returned.