95 lines
3.3 KiB
Markdown
95 lines
3.3 KiB
Markdown
# JeeJah
|
|
|
|
An nREPL server for [Fennel](https://fennel-lang.org) and [Lua](https://lua.org).
|
|
|
|
## A what now?
|
|
|
|
The [nREPL protocol](https://nrepl.org/nrepl/index.html#_why_nrepl)
|
|
allows developers to embed a server in their programs to which
|
|
external programs can connect for development, debugging, etc.
|
|
|
|
The original implementation of the protocol was written in Clojure,
|
|
and many clients assume they will connect to a Clojure server; however
|
|
the protocol is quite agnostic about what language is being
|
|
evaluated. It supports evaluating snippets of code or whole files with
|
|
`print` and `io.write` redirected back to the connected client.
|
|
|
|
This library was originally written to add Emacs support to
|
|
[Bussard](https://gitlab.com/technomancy/bussard), a spaceflight
|
|
programming game.
|
|
|
|
Currently mainly tested with
|
|
[monroe](https://github.com/sanel/monroe/) and
|
|
[shevek](https://git.sr.ht/~technomancy/shevek/) as
|
|
clients. [grenchman](https://leiningen.org/grench.html) version 0.3.0+
|
|
works. Other clients exist for Vim, Eclipse, and Atom, as well as
|
|
several independent command-line clients; however these may require
|
|
some adaptation to work with Jeejah. If you try your favorite client
|
|
and find that it makes Clojure-specific assumptions, please report a
|
|
bug with it so that it can gracefully degrade when those assumptions
|
|
don't hold.
|
|
|
|
## Installation
|
|
|
|
The pure-Lua dependencies are included (`bencode`, `serpent`, and
|
|
`fennel`) but you will need to install `luasocket` yourself. If your
|
|
operating system does not provide it, you can install it using LuaRocks:
|
|
|
|
$ luarocks install --local luasocket
|
|
|
|
Note that [LÖVE](https://love2d.org) ships with its own copy of
|
|
luasocket, so there is no need to install it there.
|
|
|
|
You can symlink `bin/jeejah` to your `$PATH` or something.
|
|
|
|
## Usage
|
|
|
|
You can launch a standalone nREPL server:
|
|
|
|
$ bin/jeejah
|
|
|
|
Pass in a `--fennel` flag to start a server for evaluating Fennel code
|
|
instead of Lua. Accepts a `--port` argument and a `--debug` flag.
|
|
|
|
You can use it as a library too, of course:
|
|
|
|
```lua
|
|
local jeejah = require("jeejah")
|
|
local coro = jeejah.start(port, {debug=true, sandbox={x=12}})
|
|
```
|
|
|
|
The function returns a coroutine which you'll need to repeatedly
|
|
resume in order to handle requests. Each accepted connection is stored
|
|
in a coroutine internal to that function; these are each repeatedly
|
|
resumed by the main coroutine. If all you're doing is starting an
|
|
nrepl server, you can pass `foreground=true` in the options table to
|
|
leave the server running in the foreground and skip the step of
|
|
resuming the coroutine.
|
|
|
|
Note that the sandbox feature is not well-tested or audited and should
|
|
not be trusted to provide robust security. It currently only works
|
|
with Lua 5.1 and LuaJIT.
|
|
|
|
You can also pass in a `handlers` table where the keys are custom
|
|
[nREPL ops](https://nrepl.org/nrepl/ops.html)
|
|
you want to handle yourself.
|
|
|
|
## Completion
|
|
|
|
The included `monroe-lua-complete.el` file adds support for completion
|
|
to the Monroe client by querying the connected nREPL server for
|
|
possibilities. Simply invoke `completion-at-point` (bound to `C-M-i`
|
|
by default) when connected.
|
|
|
|
## Caveats
|
|
|
|
PUC Lua 5.1 does not allow yielding coroutines from inside protected
|
|
calls, which means you cannot use `io.read`, though LuaJIT and
|
|
Lua 5.2+ allow it.
|
|
|
|
## License
|
|
|
|
Copyright © 2016-2020 Phil Hagelberg and contributors
|
|
|
|
Distributed under the MIT license; see file LICENSE
|