hy-nrepl 1.0.4

nREPL implementation for Hy (Hylang)

hy-nrepl

hy-nrepl is an implementation of the nREPL protocol for Hy.

hy-nrepl is a fork from HyREPL and has been adjusted to work with the current Hy.

Implemented Operations

from nREPL Built-in Ops

• add-middleware
• clone
• close
• completions
• describe
• eval
• interrupt
• load-file
• lookup
• ls-middleware
• ls-sessions
• stdin
• swap-middleware

Usage

hy-nrepl requires Python >= 3.11 and Hy >= 0.29.0.

To install:

pip install hy-nrepl

To run the server (default port is 7888):

hy-nrepl

# Output debug log and specify port
hy-nrepl --debug 7888

Testing

Install test dependencies, then run pytest:

pip install -e .[test]

pytest tests

Known Issues

Code evaluation is performed in a thread that is not Python's main thread. Therefore, some libraries that expect to be run on the main thread will not work as expected.

• GUI Libraries: Libraries like Tkinter will not function correctly.
• Plotting Libraries: Matplotlib is known to have issues. As an alternative, you can use libraries like Plotly, which work without relying on the main thread.

Confirmed working nREPL clients

Emacs

The following combinations are currently confirmed to work stably.

• hy-mode + Rail
  • REPL (Eval and Interruption)
  • Symbol completion
  • Eldoc (Function arg documentations)
  • Jump to source

Emacs Configuration Example

Here is an example configuration for a plain Emacs setup using use-package.

1. Install Rail

This setup uses a forked version of Rail that has been modified to work well with hy-nrepl.

Clone the forked Rail repository from GitHub. This example clones it to the home directory (~/Rail).

git clone [https://github.com/masatoi/Rail.git](https://github.com/masatoi/Rail.git) ~/Rail

2. Configure Emacs

Add the following settings to your Emacs initialization file (e.g., ~/.emacs.d/init.el). This setup assumes you are using package.el and use-package.

;;; Assumes use-package is already installed.
;;; If not, add bootstrap code for package.el and use-package.
(require 'package)
(add-to-list 'package-archives '("melpa" . "[https://melpa.org/packages/](https://melpa.org/packages/)") t)
(package-initialize)

;;; hy-mode (will be installed from MELPA)
;;; jedhy is disabled as Rail provides completion.
(use-package hy-mode
  :mode "\\.hy\\'"
  :custom (hy-jedhy--enable? nil))

;;; Rail (loaded from the local path)
(use-package rail
  :ensure nil
  :load-path "~/Rail" ; Must match the path where you cloned Rail
  :commands (rail rail-interaction-mode)
  :hook ((hy-mode . rail-interaction-mode)
         (hy-mode . rail-setup-eldoc)
         (rail-mode . rail-setup-eldoc)))

3. How to Connect

1. Start the nREPL server in your terminal. It will listen on localhost:7888 by default.

   hy-nrepl
   

2. Connect to the nREPL server from Emacs. Run M-x rail, and you will be prompted for the host and port. Enter the default value, localhost:7888, and press Enter. This will complete the connection and open a REPL buffer.

3. Developing with .hy files. Once connected, opening a .hy file will automatically enable the minor mode rail-interaction-mode. This provides features like:

   • Evaluating Hy S-expressions within the buffer
   • Symbol completion
   • Displaying function argument information via Eldoc

4. Interrupting Execution. While an evaluation is running in the REPL buffer, you can interrupt it by pressing C-c C-c.