subrepo: subdir: "vendor/jeejah" merged: "3ed9eb1" upstream: origin: "https://gitlab.com/technomancy/jeejah.git" branch: "master" commit: "3ed9eb1" git-subrepo: version: "0.4.2" origin: "https://github.com/ingydotnet/git-subrepo" commit: "65fde50"
3.3 KiB
JeeJah
An nREPL server for Fennel and Lua.
A what now?
The nREPL protocol 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, a spaceflight programming game.
Currently mainly tested with monroe and shevek as clients. grenchman 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 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:
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
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