███████╗██╗ ██╗███████╗██████╗ ██████╗ ███████╗
██╔════╝██║ ██║██╔════╝██╔══██╗██╔══██╗██╔════╝
█████╗ ██║ ██║███████╗██████╔╝██████╔╝███████╗
██╔══╝ ██║ ██║╚════██║██╔═══╝ ██╔══██╗╚════██║
███████╗███████╗██║███████║██║ ██║ ██║███████║
╚══════╝╚══════╝╚═╝╚══════╝╚═╝ ╚═╝ ╚═╝╚══════╝
[EMACS LISP // RUN .EL OUTSIDE EMACS // LISP-2 + DYNAMIC SCOPE // RUST CORE]
"The editor's language — without the editor."
elisprs runs Emacs Lisp (.el) as standalone programs from the command line: a Lisp-2 obarray (separate value/function cells) with lexical and dynamic binding and an elisp-correct reader, compiled to — and run on — the fusevm bytecode VM, the same engine behind zshrs, stryke, awkrs, vimlrs, and other language frontends. elisprs is a pure frontend: no bespoke VM or JIT — each form lowers to a fusevm::Chunk, hot arithmetic/comparison lowers to native fusevm ops (JIT/AOT-able), and the elisp object heap rides the VM as Value::Obj handles reached through fusevm's extension handler. It AOT-compiles to standalone native binaries (--aot-exe) and caches lowered bytecode in an rkyv shard at ~/.elisprs.
┌──────────────────────────────────────────────────────────────┐ │ ENGINE: FUSEVM FRONTEND: PURE AOT: STANDALONE BIN CACHE: RKYV │ └──────────────────────────────────────────────────────────────┘
Read the Docs · Engineering Report · Builtin Reference · strykelang · zshrs · fusevm
Table of Contents
- [0x00] System Scan
- [0x01] System Requirements
- [0x02] Installation
- [0x03] Language Coverage
- [0x04] Architecture
- [0x05] Status
- [0x06] Roadmap
- [0x07] Build
- [0x08] Test
- [0x09] Documentation
- [0xFF] License
[0x00] SYSTEM SCAN
Positioning: Emacs Lisp has only ever run inside Emacs. elisprs takes the language out of the editor and runs .el as ordinary programs — with a REPL, no Emacs process required. It is a language hosted on fusevm.
Why it's built this way: Emacs Lisp is a Lisp-2 (every symbol carries a separate value cell and function cell) and supports both lexical and dynamic scoping. Those facts are the whole personality of the language, so elisprs owns the value model and the semantics, and leans on fusevm purely for execution:
| Layer | Where |
|---|---|
| Value model — interned symbols, real cons cells (dotted), vectors, hash tables, closures | ours — an ElispHost object heap; objects ride the VM as Value::Obj(u32) handles |
Reader (1+/1-, #'foo, ?c, :kw, backquote, dotted pairs, #N= labels) |
ours — an elisp-correct S-expression reader |
| Lisp-2 obarray, lexical+dynamic binding, special forms, macros, subrs | ours — src/host.rs + src/compiler.rs |
| Bytecode execution, JIT, AOT | fusevm — elisprs has no VM/JIT of its own |
Status: self-hosting elisp on fusevm. Each top-level form is read, macro-expanded, and lowered to a fusevm::Chunk (src/compiler.rs); fusevm executes it and calls back into the object heap (src/host.rs) through a registered extension handler. Core arithmetic/comparison lower to native fusevm ops so hot loops are JIT/AOT-able; --aot-exe emits standalone native binaries; lowered bytecode + a heap image are cached in an rkyv shard at ~/.elisprs. The post-prelude heap is the same bytes for every script one binary compiles, so the shard stores it once as a shared base (with the per-buffer state the prelude builds outside the arena) and an entry keeps only the objects its own file created; storing it per entry cost ~6.8 MB each. The shard is bounded to 64 MiB (ELISPRS_CACHE_MAX_BYTES; ELISPRS_CACHE=0 disables it) and evicted oldest-first, because put rewrites the whole shard and an unbounded one made every run pay for every script ever cached. (An earlier bootstrap built on the rust_lisp crate; it was replaced by this own value model — rust_lisp is no longer a dependency.)
[0x01] SYSTEM REQUIREMENTS
- Rust 2021 edition (stable). Builds on
rustc1.96+. - Platforms: macOS (aarch64 / x86_64) and Linux (x86_64 / aarch64).
- Dependencies:
fusevm(the bytecode VM elisp executes on, withjit,jit-disk-cache,aotandffi),rkyv+bincode(the~/.elisprsbytecode cache),num-bigint(bignums),fancy-regex(the regexp engine),reedline(the REPL),serde/serde_json, andlsp-server/lsp-types(the--lspserver). Norust_lisp.
[0x02] INSTALLATION // ARM THE PAYLOAD
&&
The build produces the elisp binary:
# ` *load*` buffer, so they read the STANDARD syntax table.
# Plain `elisp FILE.el` is the `emacs -l FILE` column.
[0x03] LANGUAGE COVERAGE
Reader syntax. integers, floats, strings (with escapes), symbols (including 1+ / 1- / <= / :keywords), nil / t, 'quote, #'function, ?c char literals, ; comments, backquote (` / , / ,@), radix literals (#x1f / #o17 / #b101 / #16rFF), #:uninterned and ## (the empty-named symbol), #s(NAME …) records and #s(hash-table …), #&N"…" bool-vectors, #("text" START END PLIST …) propertized strings, #^[…] char-tables, #$ (load-file-name), and #N= / #N# labels for shared and circular structure (gated by read-circle) — so anything the printer emits under print-circle reads back to the same object graph. read from a function stream calls the function for every character lread.c's read0 reads and gives back, in the same order.
Special forms. quote function lambda progn prog1 if when unless cond and or while setq let let* defun defmacro defvar defconst condition-case unwind-protect.
Subrs. (The live count is whatever elisp -e "(let ((n 0)) (mapatoms (lambda (s) (when (and (fboundp s) (subrp (symbol-function s))) (setq n (1+ n))))) n)" reports; it moves every round, so it is not written down here.)
| Group | Functions |
|---|---|
| Arithmetic | + - * / % mod 1+ 1- abs max min = /= < > <= >= |
| Lists | car cdr cons list append nth nthcdr reverse length member memq assoc assq member-ignore-case |
| c*r combinators | every two- to four-letter composition, caar .. cddddr, each a setf place (+ cl-caar cl-cadr cl-cdar cl-cddr, and every three- and four-letter one under its cl- alias) |
| Mutation | setcar setcdr aset fillarray store-substring clear-string (a string is a mutable object: aset/store-substring/clear-string write through every reference to it) |
| Overlays | make-overlay overlayp overlay-start overlay-end overlay-buffer overlay-get overlay-put overlay-properties delete-overlay move-overlay copy-overlay overlays-at overlays-in next-overlay-change previous-overlay-change remove-overlays (both ends move with edits, with FRONT-ADVANCE/REAR-ADVANCE deciding which side of an insertion each lands on) |
| Vectors | vector make-vector aref vectorp |
| Records | record make-record recordp (a distinct type — slot 0 is the type symbol, vectorp is nil; backs cl-defstruct) |
| Bool-vectors | make-bool-vector bool-vector bool-vector-p bool-vector-count-population bool-vector-subsetp bool-vector-not (#&N"…" syntax) |
| Advice (nadvice) | advice-add advice-remove add-function remove-function define-advice advice-member-p (all :around/:before/:after/:override/:filter-*/:*-while/:*-until combinators) |
| Hash tables | make-hash-table gethash puthash remhash clrhash maphash hash-table-count hash-table-size hash-table-test hash-table-weakness hash-table-rehash-size hash-table-rehash-threshold hash-table-keys hash-table-values hash-table-p copy-hash-table define-hash-table-test (Emacs's slot + free-list model, so maphash order and slot reuse match; a define-hash-table-test test's elisp functions are called from outside the host borrow) |
| Predicates | eq eql equal null not numberp integerp floatp stringp symbolp consp listp atom functionp |
| Symbols/cells | set symbol-value symbol-function fset boundp fboundp symbol-name intern make-symbol |
| Strings | concat string= string-equal string< upcase downcase number-to-string string-to-number string-split |
| IO/format | format message princ prin1 prin1-to-string print terpri write-char (PRINTCHARFUN is honoured as in print.c: a buffer inserts at its point, a marker at itself, a function is called per character, nil defers to standard-output; with-output-to-string binds standard-output to a buffer, and terpri's ENSURE tests bolp) |
| Functional | funcall apply mapcar mapc sort identity |
| Regexp | string-match string-match-p match-beginning match-end match-string match-data set-match-data replace-regexp-in-string regexp-quote regexp-opt regexp-opt-charset regexp-opt-depth looking-at looking-back re-search-forward re-search-backward (+ save-match-data; regexp-opt and rx reproduce Emacs's output, not just its language) |
| Markers | make-marker point-marker point-min-marker point-max-marker copy-marker set-marker move-marker marker-position marker-buffer markerp marker-insertion-type set-marker-insertion-type |
| Text properties | propertize put-text-property get-text-property set-text-properties add-text-properties remove-text-properties text-properties-at next-single-property-change next-property-change previous-single-property-change get-char-property |
defun/defmacro/lambda support &optional and &rest; macros expand and re-evaluate; condition-case matches the error umbrella and specific error symbols.
A taste (the examples/ directory has runnable, self-testing ERT versions — elisp examples/demo.el):
(defun fact (n) (if (<= n 1) 1 (* n (fact (1- n)))))
(fact 6) ; => 720
(mapcar (lambda (x) (* x x)) '(1 2 3 4)) ; => (1 4 9 16)
(mapcar #'1+ '(10 20 30)) ; => (11 21 31)
(let ((x 10) (y 20)) (+ x y)) ; => 30
(format "%s = %d (hex %x)" 'count 255 255); => "count = 255 (hex ff)"
(condition-case e (/ 1 0)
(arith-error (format "caught %s" e))) ; => "caught (arith-error)"
Now supported (own cons model — Obj::Cons(Value, Value) heap cells):
- Dotted pairs.
(cons 1 2)/(a . b)read, print ((1 . 2)), and round-trip; alists may use(key . value). - Backquote / unquote.
`,,, and,@read as(\` X),(\, X)and(\,@ X), exactly as Emacs reads them, and the\`macro expands them with a port of backquote.el, so nested backquotes keep their levels,'(a ,b)is data, andmacroexpandshows backquote.el'slist/cons/append/backquote-list*output. The printer abbreviates(, X)as,X` only inside a backquote. setcar/setcdrmutate cons cells in place.pcase. Structural dispatch over_, literals,'x, symbol binders,(pred FN),(guard EXPR),(and …),(or …), and backquote patterns`(,a ,b)/`(,a . ,rest)(incl. nested) and vector patterns`[,a ,b], compiled as pcase.el's\`QPAT pattern.- Regexps.
string-match& friends translate elisp regexp syntax (\(\|\{,\</\>, backreferences\1..\9) to a backing engine, honorcase-fold-search, and record char-indexed match data;replace-regexp-in-stringis the subr.el Lisp definition (function-valued REP,\&/\Ntemplates, FIXEDCASE/LITERAL/SUBEXP/START). The syntax-class escapes\sC,\SC,\wand\Ware resolved against the syntax table in force where the regexp is compiled, sowith-syntax-tableandmodify-syntax-entrychange what they match. The category escapes\cC/\CCare resolved the same way against the current category table (a port of category.c:define-category,modify-category-entry,char-category-set,make-category-table,set-category-table), whose standard contents are characters.el's category definitions and Unicode-range entries. - Vector literals.
[1 2 3]reads as a self-evaluating vector (elements unevaluated);aref/elt/length/append/sortoperate on it. - Generalized
setfover the common places:car,cdr,nth,elt,aref,gethash,symbol-value, plus plain variables and multiple place/value pairs. formatfield specs.%[-][0][width][.prec]withs S d o x X c e f g, e.g.(format "%05d" 42)→00042. Width and precision are measured in display columns, as in Emacs: a TAB is 8, a control character 2, a newline 0 and an East-Asian wide character 2, so(format "%.3s" "\tXY")is""and(format "%4c|" ?中)is" 中|".
Scope. Both lexical (lexical-binding: t) and dynamic binding are honored — lexical closures capture their defining environment, while defvar / special variables bind dynamically. load binds the variable lexical-binding to the file's cookie, as lread.c does.
Buffers & text editing. A global registry of named live buffers, each with its own text, 1-based point, mark, and narrowing bounds. current-buffer / set-buffer / get-buffer-create / generate-new-buffer / kill-buffer / rename-buffer / buffer-list manage the registry; insert / delete-region / delete-char / point motion (forward-char, forward-line, beginning-of-line, …) / narrow-to-region / widen edit the current buffer. The mark is a marker (mark-marker) driven by simple.el's set-mark / push-mark / pop-mark / exchange-point-and-mark / region-active-p / use-region-p, and transpose-regions is editfns.c's. The kill ring (kill-region, kill-line, kill-word, yank, current-kill), the transpose commands, and the thingatpt.el core (thing-at-point, bounds-of-thing-at-point, symbol-at-point, number-at-point) are ports of the Emacs 31.1 Lisp, and a buffer-read-only buffer rejects edits unless inhibit-read-only is bound. The preloaded editing libraries paragraphs.el, fill.el, indent.el and newcomment.el are loaded verbatim (paragraph and sentence motion, fill-region / fill-paragraph with prefixes and justification, indent-rigidly / indent-region / indent-relative / tab stops, comment-region), with simple.el's and lisp.el's line, whitespace, kill and defun commands (goto-line, count-words-region, split-line, delete-all-space, transpose-sexps, beginning-of-defun, mark-defun, check-parens, insert-pair, raise-sexp, …) and text-mode.el's centering commands. The Lisp major modes are loadup.el's own files, loaded verbatim: prog-mode.el, lisp-mode.el and elisp-mode.el with easymenu.el, so prog-mode, lisp-data-mode, emacs-lisp-mode and lisp-interaction-mode set up their syntax tables, keymaps, comment and indentation variables and mode hooks as Emacs does, and the initial *scratch* buffer starts in initial-major-mode exactly as startup.el puts it there. Fields are editfns.c's: field-beginning, field-end, field-string, delete-field, constrain-to-field, and line-beginning-position / line-end-position / beginning-of-line / end-of-line stay in point's field. Every modifying primitive runs insdel.c's change hooks (first-change-hook, before-change-functions, after-change-functions), overlay and text-property modification hooks and read-only text checks and sets deactivate-mark (src/modhooks.rs), and records undo.c's entries in buffer-undo-list; undo-boundary, simple.el's primitive-undo and subr.el's change groups (atomic-change-group) work over them. Each buffer keeps Emacs's modification counters: buffer-modified-p / set-buffer-modified-p / restore-buffer-modified-p / with-silent-modifications, and buffer-modified-tick / buffer-chars-modified-tick advance exactly as modiff_incr does; position-bytes / byte-to-position map to the internal UTF-8 bytes. save-excursion restores point via a marker that tracks intervening edits; save-restriction / with-temp-buffer / with-current-buffer scope the buffer and its restriction. Buffer-local variables key off the current buffer, and buffer-local-variables lists them in buffer.c's order (the per-buffer slots, then the Lisp locals oldest first).
Windows and frames. The objects of a batch Emacs (src/window.rs): the terminal frame F1 and window.c's window tree under it — live and internal windows, sibling chains, pixel and character geometry, normal sizes, split-window-internal, delete-window-internal, delete-other-windows-internal, window-resize-apply, window configurations that restore the whole tree, margins, recenter, window-at and coordinates-in-window-p. window.el is loaded verbatim (src/lisp/window.el), so split-window, delete-window, delete-other-windows, balance-windows, enlarge-window, display-buffer with its actions, pop-to-buffer, quit-window, side windows and window states are Emacs's own; kill-buffer runs kill-buffer-query-functions, kill-buffer-hook and replace-buffer-in-windows. buffer-list is in recency order. Every face batch Emacs defines exists, in its face-id order (src/lisp/faces-31.el). current-bidi-paragraph-direction follows bidi.c's paragraph search over the bidi-class of every character (src/bidi_data.rs, generated from Emacs by scripts/gen/bidi-data.el). replace.el (perform-replace, replace-string, replace-regexp, how-many, keep-lines, flush-lines) runs with isearch.el's search core and timer.el.
Environment. process-environment and initial-environment hold the process environment as NAME=VALUE strings (callproc.c); getenv / setenv / with-environment-variables are env.el's over getenv-internal, a subprocess (call-process, process-lines, shell-command-to-string) starts with process-environment as its environment, runs in default-directory and is found on exec-path, ~ expands against the HOME found there, and set-time-zone-rule sets the process time zone from a ZONE.
File names. expand-file-name, file-name-directory / file-name-nondirectory / file-name-as-directory / directory-file-name / directory-name-p / file-name-concat / file-name-absolute-p / file-name-case-insensitive-p are ports of fileio.c's Unix branch (src/fileio.rs: ~USER via the password database, the /.. superroot, a leading // kept); substitute-in-file-name, files.el's extension / split / quote / abbreviate-file-name functions and env.el's substitute-env-vars are ported Lisp. File name handlers are not dispatched.
Markers & text properties. First-class markers (make-marker / point-marker / copy-marker / set-marker / marker-position / marker-buffer / marker-insertion-type) auto-adjust when text is inserted or deleted, honoring insertion type, and serve as buffer positions. String and buffer text carry property intervals: propertize / put-text-property / get-text-property / set-text-properties / add-text-properties / remove-text-properties / text-properties-at / next-single-property-change / next-property-change / previous-single-property-change / get-char-property; buffer-substring and buffer-string carry properties (the -no-properties variant drops them), and so do the string functions that copy characters: concat, substring, upcase/downcase/capitalize, and a %s argument to format (with format's padding treated as Emacs does — trailing padding is inside the argument's interval, leading padding is outside). This is enough that tabulated-list-print produces byte-identical propertized output to GNU Emacs.
Syntax tables & sexp scanning. Syntax tables are char-tables of (CODE . MATCHING-CHAR) descriptors, built by string-to-syntax / modify-syntax-entry / make-syntax-table / copy-syntax-table and selected per buffer by set-syntax-table / with-syntax-table; standard-syntax-table reproduces init_syntax_once entry for entry. On top of them sits syntax.c's scanner: scan-lists / scan-sexps / parse-partial-sexp / syntax-ppss / forward-comment / backward-prefix-chars / matching-paren / syntax-after, and the motion commands forward-sexp / backward-sexp / forward-list / backward-list / down-list / up-list / backward-up-list. It is the real state machine, not a paren counter: two-character comment delimiters, comment styles a/b/c, nested comments, generic string and comment fences, the $ math class, escape and char-quote runs, parse-sexp-ignore-comments, and the syntax-table text property under parse-sexp-lookup-properties. A parse-partial-sexp state can be handed back in to resume a scan, including one stopped between the two halves of a comment delimiter.
AOP pattern intercepts (an elisprs extension, ported from zshrs; distinct from elisp's native per-symbol nadvice). Where advice-add attaches to one named symbol, an intercept fires on a glob across many function names at once — "forward-*", "_*", or the catch-alls "*" / "all" — with before / after / around advice and a timing/proceed protocol. Advice bodies are ordinary elisp forms evaluated in the running host (no subprocess); a re-entrancy guard keeps advice that calls a matching function from recursing.
(defun greet (x) (concat "hi " x))
(intercept 'before "gr*" '(message "calling %s with %s" intercept-name intercept-args))
(intercept 'around "greet" '(upcase (intercept-proceed))) ; => "HI BOB"
(intercept 'after "greet" '(message "took %s us" intercept-us))
(greet "bob")
(intercept-list) ; => ((1 before "gr*" …) (2 around "greet" …) (3 after "greet" …))
(intercept-remove 1) ; => t
(intercept-clear) ; => 2
Registration returns an integer ID; (intercept-list) returns (ID KIND PATTERN FORM) entries; advice reads the dynamic context vars intercept-name / intercept-args / intercept-cmd, and (in after) intercept-ms / intercept-us. (intercept-proceed) runs the original from inside an around body.
Not in scope — surfaced loudly rather than silently misread: this is a useful elisp core, not the ~1000-subr GNU Emacs surface. Within the editor layer, a real interval tree (properties use a per-character plist vector, observably identical for get/put/next-change but O(n) in storage), and redisplay (windows, header lines, faces) are not modeled.
[0x04] ARCHITECTURE // REUSE-OWN SPLIT
.el source → reader.rs → forms on the ElispHost heap → compiler.rs → fusevm::Chunk → fusevm executes (calls back into host.rs)
elisp cells (cons / symbol / vector / closure / macro / subr) live in the ElispHost object heap and ride the VM as Value::Obj(u32) handles, so elisprs gets full elisp semantics — including dynamic scope and Lisp-2 cells — without forking the fusevm core.
| File | Role |
|---|---|
src/reader.rs |
Elisp-correct S-expression reader → forms on the ElispHost heap |
src/host.rs |
ElispHost: the object heap, Lisp-2 obarray, dynamic binding, and the fusevm extension handler that runs elisp ops |
src/compiler.rs |
Lowers elisp forms to a fusevm::Chunk; lambda bodies become sub-chunks |
src/builtins.rs |
The subr standard library (reached host-side from the CALL extension op) |
src/regexp.rs |
Elisp regexp to regex/fancy-regex dialect translation |
src/backquote.rs |
Port of backquote.el's expander |
src/freevars.rs |
Free-lexical-variable analysis used to prune closure environments |
src/timefns.rs |
Lisp timestamps, ported from timefns.c |
src/json.rs |
Native JSON primitives (json-parse-string, json-serialize, ...) |
src/cache.rs |
rkyv bytecode cache at ~/.elisprs/scripts.rkyv |
src/tiers.rs |
--tiers execution-tier report |
src/rust_ffi.rs |
Inline rust { ... } FFI block desugaring |
src/repl.rs · src/banner.rs |
reedline REPL and its stats banner |
src/intercepts.rs |
AOP pattern-intercept layer (glob advice across many function names) — an elisprs extension ported from zshrs, fired on the call_function join point |
src/prelude.rs |
The [DERIVED] elisp prelude — breadth written in elisp on top of the primitives |
src/prelude_31.rs |
Prelude segments loaded after the core prelude: Emacs 31.1 library files included verbatim (time-date.el, the subr.el definitions the core lacked, indent.el, newcomment.el, paragraphs.el, fill.el, simple.el's undo commands with subr.el's change groups, timer.el, the window.el / subr.el window functions, isearch.el's search core with replace.el, and the simple.el / lisp.el / text-mode.el commands the core lacked), the Lisp major modes (easymenu.el, prog-mode.el, lisp-mode.el, elisp-mode.el, with the files.el / syntax.el / easy-mmode.el definitions they need while loading), ports of the keymap.c / keyboard.c primitives, and the autoload table for the lazily bundled libraries |
src/bundled.rs · src/lisp/ |
Emacs 31.1 libraries bundled as unmodified .el files (parse-time, iso8601, thunk, rx, char-fold with its generated equivalence table). load and require fall back to them after load-path, an autoload object whose symbol is called (or funcalled, or expanded as a macro) loads its file through autoload-do-load |
src/lisp/keymap-c.el |
Ports of the keymap.c / keyboard.c / chartab.c primitives written in Lisp: map-keymap, copy-keymap, accessible-keymaps, where-is-internal, make-keymap, map-char-table, event-convert-list, key-description |
src/lisp/editfns-c.el |
Lisp ports of editfns.c's fields, minibuf.c's minibufferp / minibuffer-prompt-end, charset.c's char-charset / charset-after and the C variables the editing libraries read |
src/lisp/category-c.el |
category.c ported to Lisp, followed by the category forms of characters.el |
src/modhooks.rs |
The Lisp a modifying or field-aware primitive runs (change hooks, constrain-to-field, property inheritance), done around the subr from host::call_function because a subr body cannot call Lisp |
src/window.rs |
The window and frame objects of batch Emacs (window.c, frame.c): one terminal frame, its root and minibuffer windows, window configurations, other-buffer and the buffer-list order |
src/textprop.rs |
Text-property intervals: boundary bookkeeping and the textprop.c / intervals.c split rules behind every property primitive |
src/strftime.rs |
nstrftime: format-time-string's directive engine, ported from gnulib's strftime.c (flags, widths, E/O modifiers, bad-format recovery, signed year fields) |
src/aot.rs |
--aot / --aot-exe driver: lowers a .el file to a fusevm::Chunk, emits a native object via fusevm::aot::compile_object, and links a standalone executable |
src/aot_runtime.rs |
The AOT binary's runtime hook: rebuilds the elisp heap from the image embedded in the object, installs the subrs, extension handlers and numeric contract on the fresh VM, and reports an uncaught elisp error as the interpreter does (an error halts the VM cleanly, so without this the process exited 0 in silence) |
src/lsp.rs / src/dap.rs |
--lsp (completion/hover/diagnostics/signature help) and --dap (breakpoints/stepping/variables) servers |
src/main.rs |
The elisp CLI + REPL |
[0x05] STATUS // COMPONENT GRID
The grid reflects the current state of the tree.
| Component | State |
|---|---|
Elisp-correct reader (1+/#'/?c/:kw, nil/t, 'quote, #N= labels) |
Working |
| Lisp-2 obarray (value + function cells) | Working |
Dynamic binding (let/let*, special vars) |
Working |
Special forms + macros (defmacro) |
Working |
| Subr standard library | Working |
Hash tables (make-hash-table/gethash/puthash/maphash) |
Working |
Dotted pairs, backquote/unquote, setcar/setcdr |
Working |
elisp CLI — file / -e / REPL |
Working |
ERT test surface (ert-deftest/should/should-error) |
Working (prelude) |
--lsp / --dap servers |
Working |
Execution-tier report (--tiers) |
Working |
elisp → fusevm::Chunk lowering + execution (compiler.rs / host.rs) |
Working |
--aot / --aot-exe → native object + standalone executable via fusevm::aot::compile_object |
Working |
lexical-binding (lexical + dynamic) |
Working |
[0x06] ROADMAP
Done — elisp executes on fusevm (the reason elisprs exists), the same frontend pattern as the sibling languages:
- ✅ elisp cells (cons / symbol / vector / closure) live in the
ElispHostheap (src/host.rs) and ride the VM asValue::Objhandles — no invasivefusevmcore change was needed (it never had to learn dynamic scope or Lisp cells). - ✅ An elisp
Op::Extended(id, arg)range dispatches quote / funcall / special-var bind / cons navigation through a handler registered withvm.set_extension_handler(...). - ✅ Every top-level form lowers in
compiler.rs; lambda bodies become sub-chunks. - ✅ The subr library is reachable host-side from the
CALLextension op. - ✅ JIT / AOT tiers.
fusevmis built withjit-disk-cache+aot, so elisp chunks pick up the three-tier Cranelift JIT, and--aot/--aot-exeemit a native object and a standalone executable throughfusevm::aot::compile_object. - ✅ Lexical + dynamic binding. Lexical closures capture their defining environment;
defvar/ special variables bind dynamically. - ✅ Tooling.
--lsp(completion/hover/diagnostics/signature help over the obarray, mirroringawkrs --lsp) and--dap(breakpoints/stepping offeval+ the dynamic specstack) both ship.
Next:
- Coverage. Broaden special-form / macro / backquote lowering toward full milestone-2 elisp.
- Editor plugins.
vscode-elisp/vim-elisp/emacs-elispover the--lspserver.
[0x07] BUILD // COMPILE THE PAYLOAD
elisp --help / -h prints the usage screen; elisp --version prints the version.
Embedding
Evaluates src on a fresh interpreter (its own large-stack thread per call, so
calls from several threads never share state or output) and returns everything
printed to stdout. read-from-minibuffer and read-string behave as in
emacs --batch: the prompt is printed, a line is read from input, and EOF
signals end-of-file. An uncaught signal or kill-emacs with a nonzero status
is Err; (kill-emacs) returns Ok with the output so far. The process never
exits.
let out = run_program?;
assert_eq!;
assert!;
[0x08] TEST // INTEGRITY VERIFICATION
Coverage spans reader.rs unit tests (number-vs-symbol tokenization, #' desugaring, ?c char literals, dotted-pair reading) and the end-to-end evaluation suite in tests/eval.rs — arithmetic, recursion, higher-order functions, special forms, macros, and error handling driven through the public eval_str API.
The examples/*.el scripts are self-testing: each uses the prelude's ERT surface (ert-deftest / should / should-error) and ert-run-tests-batch-and-exit, which exits non-zero on any failure. tests/examples.rs runs every example through the built elisp binary as a cargo test gate, and the CI examples job runs them through the release binary on Linux + macOS.
Differential fuzzing against GNU Emacs
scripts/fuzz_parity.sh generates a corpus of random elisp forms from a seeded grammar (scripts/fuzz/gen.el), evaluates every form under both emacs -Q --batch -l (ground truth) and elisp through one shared driver (scripts/fuzz/drive.el), and reports every form whose value — or whose signalled error — differs. Errors are compared too: Emacs's error symbol and error data are as much of the contract as the return value.
The seed makes a divergence reproduce exactly on any machine, and a crash or hang in one form is isolated rather than losing the rest of the corpus. The parity gaps it has already closed are recorded in BUGS.md.
Beyond single calls, the grammar builds forms whose behaviour depends on how their parts combine: cl-loop clause combinations (parallel and bindings, into, conditional accumulation, destructuring, damaged clauses), cl-seq calls with arbitrary keyword lists, sort argument lists, make-hash-table keyword lists, improper lists, wrong-arity calls whose arguments have side effects, and a void function head with a side-effecting argument. Each family reaches behaviour that a corpus of well-formed single calls does not.
The oracle is a (binary, argv) pair, and the run header prints both. The binary is resolved to an absolute, symlink-free path and gated on the version pinned in BUGS.md, because a different Emacs does not fail loudly — it reports a different divergence set, which reads like a regression. The argv decides answers the version number never mentions: emacs -Q --batch -l FILE evaluates in *scratch* under lisp-interaction-mode while emacs --script FILE evaluates in a fundamental-mode *load* buffer, so (char-syntax ?.) is 95 in the first and 46 in the second — same binary, same version, different answer. The two flag vectors are named once in the script, printed in the header, and checked before the corpus runs: scripts/fuzz/entry.el reports the current buffer and a spread of char-syntax answers through the exact argv each engine will use, and a mismatch stops the run rather than producing a wall of syntax "divergences" that are really a door mismatch.
Hits are delta-debugged. A raw hit is a depth-3 tree with three unrelated distractions bolted onto the one call that actually diverges. -S N shrinks the first N of them: scripts/fuzz/shrink.el proposes strictly-smaller candidates — it is a purely syntactic generator and knows nothing about which head symbols matter, so it cannot shrink towards a bug anyone already believes in — and the differential oracle is the only accept test. A candidate is kept only if Emacs still answers with the same signature (a value, or the same error symbol), so the minimal form still explains the hit it came from rather than wandering off to a different bug. Minimal reproducers land in target/fuzz/shrunk.txt.
A zero divergence count only means something if the corpus actually exercised the engines, so each run also prints how many forms the reference evaluated. Two ways a run can score a false zero are reported rather than hidden:
- Both engines failed the same way. A form that hangs or crashes under both produces
<HANG>on both sides, and<HANG>compares equal to<HANG>. Those forms are counted separately and never counted as agreement. (The per-batch timeout also scales with corpus size, because a fixed one silently turned a slow run into "perfect parity".) - The form was never valid. If a corpus form names something Emacs does not have, both engines signal
void-functionand the failures match. The run reports that count and warns above 5%.
[0x09] DOCUMENTATION // RENDERED HTML + MARKDOWN
docs/ is published to GitHub Pages and is the authoritative source for the rendered reference + engineering report.
| Doc | Source | Live URL |
|---|---|---|
| User reference (architecture, coverage, status, taste) | docs/index.html |
https://menketechnologies.github.io/elisprs/ |
Builtin reference (every function, variable, and special form — generated from src/lsp.rs) |
docs/reference.html |
https://menketechnologies.github.io/elisprs/reference.html |
| Engineering report (reuse/own split, fusevm frontend design, dependency posture) | docs/report.html |
https://menketechnologies.github.io/elisprs/report.html |
The HUD-themed HTML docs share hud-static.css, hud-theme.js, and tutorial.css — open them locally via file:// or browse the GitHub Pages URL above.
[0xFF] LICENSE
┌──────────────────────────────────────────────────────────────┐ │ MIT // FREE / OSS │ └──────────────────────────────────────────────────────────────┘
░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
░░ >>> READ THE FORM. BIND THE SYMBOL. EVAL THE LIST. <<< ░░
░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░