ELPS Lisp

ELPS — Syntax highlighting, language server, and debugger for VS Code

Full-featured VS Code extension for ELPS, an embedded Lisp interpreter implemented in Go. Provides syntax highlighting, language server integration, and debugging.

The extension includes the elps binary for supported platforms (macOS, Linux, Windows on x64 and arm64). No separate installation required — just install the extension and it works.

To use a custom build instead, set elps.path in VS Code settings to point to your binary:

{
  "elps.path": "/path/to/your/elps"
}

Features

Syntax Highlighting

TextMate grammar for .lisp files with support for:

Comments, strings, raw strings ("""...""")
Numbers (integer, float, hex #xFF, octal #o77)
Keywords (:keyword), booleans (true, false), nil (())
Definition forms (defun, defmacro, deftype, defconst, lambda, let)
Special operators (if, cond, set, handler-bind, thread-first, etc.)
Built-in functions (car, map, concat, sorted-map, etc.)
Qualified symbols (pkg:name)
Quote/function-quote/expr-shorthand prefixes (', #', #^)
Parameter lists with &optional, &rest, &key

Language Server (LSP)

Automatically starts the ELPS language server and provides:

Diagnostics — real-time parse errors and lint warnings
Hover — documentation and type information
Completion — symbol completion (triggers on ( and :)
Signature Help — function parameter hints
Go to Definition — jump to symbol definitions
Find References — find all usages across workspace
Rename — rename symbols across files
Document Symbols — outline view of functions, macros, variables
Workspace Symbols — search symbols across all .lisp files
Semantic Tokens — precise syntax highlighting from the language server
Call Hierarchy — incoming and outgoing call chains
Inlay Hints — parameter name hints for function calls
Code Actions — quick fixes for diagnostics (including ; nolint: suppression)
Folding Ranges — fold s-expressions and comment blocks
Selection Range — expand/contract selection by AST node
Document Highlighting — highlight symbol occurrences
Formatting — format documents (Shift+Alt+F)

Debugger (DAP)

Launch or attach to the ELPS debug adapter:

Line breakpoints
Conditional breakpoints (Lisp expressions)
Hit count breakpoints (>N, >=N, ==N, %N)
Log points (message templates with {expr} interpolation)
Function breakpoints
Exception breakpoints
Step into / over / out
Variable inspection (local and package scopes)
Watch expressions
Debug console evaluation
Pause / continue

Settings

Setting	Type	Default	Description
`elps.path`	string	`"elps"`	Path to the `elps` binary
`elps.lsp.enable`	boolean	`true`	Enable the ELPS language server
`elps.lsp.trace.server`	string	`"off"`	Trace LSP communication (`off`, `messages`, `verbose`)

Debug Configuration

Create a .vscode/launch.json (or use the auto-generated snippet from Cmd+Shift+P > "Debug: Add Configuration"):

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "elps",
      "request": "launch",
      "name": "Debug ELPS",
      "program": "${file}",
      "stopOnEntry": true
    },
    {
      "type": "elps",
      "request": "attach",
      "name": "Attach to ELPS",
      "host": "localhost",
      "port": 4711
    }
  ]
}

Debug Launch Attributes

Attribute	Type	Default	Description
`program`	string	`${file}`	Path to the `.lisp` file to debug
`stopOnEntry`	boolean	`true`	Pause before the first expression
`rootDir`	string	`${workspaceFolder}`	Source root for file resolution
`elpsPath`	string	`""`	Override `elps.path` setting for this session

Debug Attach Attributes

Attribute	Type	Default	Description
`host`	string	`"localhost"`	Host of the running DAP server
`port`	number	`4711`	Port of the running DAP server

Troubleshooting

Extension doesn't activate / "ELPS" not in language list: VS Code must trust the workspace. If the workspace is in "Restricted Mode", click "Trust" in the banner or run Workspaces: Manage Workspace Trust from the command palette.

Language server fails to start: The extension auto-discovers elps in common Go install locations. If it's installed elsewhere, set the full path:

{
  "elps.path": "/path/to/elps"
}

Check the "ELPS Language Server" output channel (View > Output > ELPS Language Server) for details.

Syntax highlighting looks wrong: If another extension claims .lisp files, set "files.associations": { "*.lisp": "elps" } in your workspace settings.

Debug adapter fails: Verify elps debug --help works from your terminal.

Development

To build and install from source:

git clone https://github.com/luthersystems/elps.git
cd elps/editors/vscode
npm install
npm run package
code --install-extension elps-*.vsix

Run grammar tests:

npm test

About Luther Systems

Our mission is to accelerate the advent of the automated enterprise. Founded by a team who spent years automating complex processes for some of the world's largest financial institutions, Luther Systems builds platforms that bring enterprise-grade infrastructure and operations to teams of every size.

Luther Systems