elps

command module
v1.68.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 25, 2026 License: BSD-3-Clause Imports: 1 Imported by: 0

README

ELPS — An embedded Lisp interpreter for Go programs

Go Reference CI Tests Discord

ELPS (Ellipse) is a Lisp-1 dialect designed to be embedded within Go applications. It provides a standalone CLI for running, linting, formatting, debugging, and exploring ELPS Lisp code.

Why ELPS

  • Built for embedding. A small Go API creates environments, loads code, and exposes Go functions and packages to Lisp (Embedding Guide).
  • Bounded execution. Context cancellation, step limits, stack-height, nesting and tail-iteration limits, and allocation size caps let a host stop runaway programs (Execution Limits).
  • Fast per-request VMs. Load a program once, publish an immutable template, and instantiate independent VMs from it (VM Templates).
  • Condition-based errors. Typed errors carry stack traces and can be handled in Lisp (handler-bind, ignore-errors, with-cleanup) or returned to Go.
  • Standard library. Packages for JSON, regular expressions, time, math, strings, base64, schema validation, testing and more.
  • Tooling included. REPL, language server, DAP debugger, linter, formatter, minifier and MCP server in one binary.

Install

go install github.com/luthersystems/elps@latest

Or build from source:

git clone https://github.com/luthersystems/elps.git
cd elps && make

Quick Start

Launch an interactive REPL:

$ elps repl
> (+ 3 1)
4
> (defun greet (name) (format-string "Hello, {}!" name))
> (greet "World")
"Hello, World!"
> ^D

Run a program:

$ elps run prog.lisp

Embed in a Go program:

env := lisp.NewEnv(nil)
env.Runtime.Reader = parser.NewReader()
env.Runtime.Library = &lisp.RelativeFileSystemLibrary{}
if err := lisp.GoError(lisp.InitializeUserEnv(env)); err != nil {
	log.Fatal(err)
}
if err := lisp.GoError(lisplib.LoadLibrary(env)); err != nil {
	log.Fatal(err)
}
res := env.LoadString("main.lisp", `(concat 'string "hello, " "world")`)
if err := lisp.GoError(res); err != nil {
	log.Fatal(err)
}
fmt.Println(res) // "hello, world"

Editor Support

CLI

Command Description
elps run file.lisp Run a Lisp source file
elps repl Start an interactive REPL
elps lsp Start the Language Server Protocol server
elps debug file.lisp Start the debug adapter (DAP)
elps lint file.lisp Run static analysis
elps fmt file.lisp Format source code
elps minify file.lisp --map symbols.json Minify source and record symbol assignments (details)
elps analyze file.lisp Run performance analysis on source files
elps doc <query> Show function/package documentation
elps mcp Start the MCP server for AI tooling

Documentation

Examples

Community

ELPS is released under the BSD 3-Clause License. See CONTRIBUTING.md to get involved.

Documentation

Overview

Command elps is a frontend for an embedded list processing system.

Source Files

View all Source files

Directories

Path Synopsis
_examples
wasm/app command
wasm/server command
A basic HTTP server.
 A basic HTTP server.
Package analysis provides scope-aware semantic analysis for ELPS lisp source.
 Package analysis provides scope-aware semantic analysis for ELPS lisp source.
perf
Package perf provides call-graph-based performance analysis for ELPS source files.
 Package perf provides call-graph-based performance analysis for ELPS source files.
Package astutil provides shared AST walking utilities for ELPS lisp values.
 Package astutil provides shared AST walking utilities for ELPS lisp values.
cmd
benchgate command
Command benchgate decides whether a benchmark comparison contains a statistically significant performance REGRESSION.
 Command benchgate decides whether a benchmark comparison contains a statistically significant performance REGRESSION.
elpsvet command
Slice-alias tracking for the elpsfreshness analyzer (issue #371).
 Slice-alias tracking for the elpsfreshness analyzer (issue #371).
Package diagnostic provides Rust-style annotated error rendering for ELPS CLI output.
 Package diagnostic provides Rust-style annotated error rendering for ELPS CLI output.
Package docs embeds the ELPS language reference for use by the CLI.
 Package docs embeds the ELPS language reference for use by the CLI.
Package formatter provides source code formatting for ELPS lisp files.
 Package formatter provides source code formatting for ELPS lisp files.
internal
astraw
Package astraw grants in-repo tooling zero-copy access to the expressions sealed inside a lisp.Program.
 Package astraw grants in-repo tooling zero-copy access to the expressions sealed inside a lisp.Program.
astraw/hook
Package hook is the untyped injection slot behind internal/astraw.
 Package hook is the untyped injection slot behind internal/astraw.
diagnosticsource
Package diagnosticsource supplies evaluated inline text and library-confined file contents to the CLI and REPL diagnostic renderers.
 Package diagnosticsource supplies evaluated inline text and library-confined file contents to the CLI and REPL diagnostic renderers.
fmtmeta
Package fmtmeta holds the formatting metadata attached to lisp values by the format-preserving parser (comments, blank lines, bracket style, original literal text) and consumed by the formatter and comment-directive tooling.
 Package fmtmeta holds the formatting metadata attached to lisp values by the format-preserving parser (comments, blank lines, bracket style, original literal text) and consumed by the formatter and comment-directive tooling.
fmtraw
Package fmtraw grants in-repo tooling access to the formatting metadata stored in lisp values' unexported meta field (see internal/fmtmeta for the metadata itself and the history of why the field is unexported — issue #382).
 Package fmtraw grants in-repo tooling access to the formatting metadata stored in lisp values' unexported meta field (see internal/fmtmeta for the metadata itself and the history of why the field is unexported — issue #382).
fmtraw/hook
Package hook is the untyped injection slot behind internal/fmtraw.
 Package hook is the untyped injection slot behind internal/fmtraw.
formsync
Package formsync holds no code.
 Package formsync holds no code.
funraw
Package funraw grants ELPS libraries explicit builtin construction and in-repo tooling read-only access to a function's captured environment.
 Package funraw grants ELPS libraries explicit builtin construction and in-repo tooling read-only access to a function's captured environment.
funraw/hook
Package hook is the untyped injection slot behind internal/funraw.
 Package hook is the untyped injection slot behind internal/funraw.
fuzzfp
Package fuzzfp watches the arguments a fuzz target hands to a builtin and reports the mutation that no builtin may ever perform: reaching inside an LNative to change the Go value a host handed in.
 Package fuzzfp watches the arguments a fuzz target hands to a builtin and reports the mutation that no builtin may ever perform: reaching inside an LNative to change the Go value a host handed in.
fuzzgen
Package fuzzgen turns a fuzzer-supplied byte script into syntactically valid ELPS source.
 Package fuzzgen turns a fuzzer-supplied byte script into syntactically valid ELPS source.
fuzzseed
Package fuzzseed supplies the shared seed corpus for the repository's native go fuzz targets (parser, lexer, formatter, minifier, json).
 Package fuzzseed supplies the shared seed corpus for the repository's native go fuzz targets (parser, lexer, formatter, minifier, json).
fuzzval
Package fuzzval turns a fuzzer-supplied byte string into typed lisp.LVal arguments for the repository's builtin/stdlib fuzz targets.
 Package fuzzval turns a fuzzer-supplied byte string into typed lisp.LVal arguments for the repository's builtin/stdlib fuzz targets.
fuzzwatch
Package fuzzwatch bounds a fuzz target's watchdog by SCHEDULED time rather than by wall-clock time.
 Package fuzzwatch bounds a fuzz target's watchdog by SCHEDULED time rather than by wall-clock time.
jsonraw
Package jsonraw lets the JSON decoder wrap its map storage in an interpreter-owned map without exporting the backing implementation.
 Package jsonraw lets the JSON decoder wrap its map storage in an interpreter-owned map without exporting the backing implementation.
jsonraw/hook
Package hook breaks the import cycle between lisp and internal/jsonraw.
 Package hook breaks the import cycle between lisp and internal/jsonraw.
lambdalist
Package lambdalist shares lambda-list validation between runtime and lint.
 Package lambdalist shares lambda-list validation between runtime and lint.
macroexp
Package macroexp grants in-repo tests a construction path for the macro-expansion debug metadata sealed inside package lisp.
 Package macroexp grants in-repo tests a construction path for the macro-expansion debug metadata sealed inside package lisp.
macroexp/hook
Package hook is the untyped injection slot behind internal/macroexp.
 Package hook is the untyped injection slot behind internal/macroexp.
packagetable
Package packagetable owns frozen package storage.
 Package packagetable owns frozen package storage.
rootlibrary
Package rootlibrary provides the confined source loader shared by the CLI execution commands and the REPL.
 Package rootlibrary provides the confined source loader shared by the CLI execution commands and the REPL.
stdlib
Package stdlib assembles ELPS's standard packages for public library loading and template-based embedders.
 Package stdlib assembles ELPS's standard packages for public library loading and template-based embedders.
symtext
Package symtext is the single definition of what an ELPS symbol looks like as TEXT: which bytes make up one, where the one under a cursor starts and ends, and how to reach a line of a document without taking the document apart.
 Package symtext is the single definition of what an ELPS symbol looks like as TEXT: which bytes make up one, where the one under a cursor starts and ends, and how to reach a line of a document without taking the document apart.
templatepolicy
Package templatepolicy contains contracts shared only by ELPS's runtime, standard library, and isolation-test tooling.
 Package templatepolicy contains contracts shared only by ELPS's runtime, standard library, and isolation-test tooling.
testdeadline
Package testdeadline scales the wall-clock budget of a test that asserts termination.
 Package testdeadline scales the wall-clock budget of a test that asserts termination.
Package lint provides static analysis for ELPS lisp source files.
 Package lint provides static analysis for ELPS lisp source files.
Package lisp implements ELPS values, environments, evaluation, and reusable templates for constructing independent VMs.
 Package lisp implements ELPS values, environments, evaluation, and reusable templates for constructing independent VMs.
lisplib
Package lisplib is used to conveniently load the standard library for the elps environment
 Package lisplib is used to conveniently load the standard library for the elps environment
lisplib/internal/libutil
lisplib/libbase64
lisplib/libelpspath
elpspath — positional-arg path operations
 elpspath — positional-arg path operations
lisplib/libgolang
lisplib/libhelp
lisplib/libjson
lisplib/libmath
lisplib/libregexp
Package libregexp provides regular expression compilation and matching.
 Package libregexp provides regular expression compilation and matching.
lisplib/libschema
lisplib/libstring
lisplib/libtesting
lisplib/libtime
Package libtime provides immutable wall-clock timestamps and duration operations.
 Package libtime provides immutable wall-clock timestamps and duration operations.
x/debugger
Package debugger implements the ELPS debugger engine (Layer 1).
 Package debugger implements the ELPS debugger engine (Layer 1).
x/debugger/dapserver
Package dapserver implements a DAP (Debug Adapter Protocol) server for the ELPS debugger engine.
 Package dapserver implements a DAP (Debug Adapter Protocol) server for the ELPS debugger engine.
x/debugger/debugrepl
Package debugrepl provides an interactive CLI debug REPL built on top of the extensible repl.RunEnv function and the debugger engine.
 Package debugrepl provides an interactive CLI debug REPL built on top of the extensible repl.RunEnv function and the debugger engine.
x/profiler
Package lsp implements a Language Server Protocol server for ELPS.
 Package lsp implements a Language Server Protocol server for ELPS.
Package minifier provides deterministic, scope-aware identifier minification for ELPS source files and parsed programs.
 Package minifier provides deterministic, scope-aware identifier minification for ELPS source files and parsed programs.
lexer
rdparser
token

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.