SeqLisp

A Lisp interpreter written in Seq, a stack-based concatenative programming language.

Requirements

• seqc - The Seq compiler (install from patch-seq)
• just - Command runner (optional, but recommended)

Installation

# Clone and build
git clone https://github.com/navicore/seq-lisp
cd seq-lisp
just build

# Install to ~/.local/bin (includes LSP server)
just install

# Or install to custom prefix
PREFIX=/usr/local just install

This installs:

• seqlisp - The interpreter/REPL
• seqlisp-lsp - Language server for editor integration
• Library files to $PREFIX/share/seqlisp/

Learning SeqLisp

New to Lisp? Try Lisplings — interactive exercises that teach Lisp concepts through hands-on practice with instant feedback.

cargo install lisplings
lisplings init my-lisplings
cd my-lisplings
lisplings

Quick Start

# Run the REPL
just repl

# Or after installing:
seqlisp

Project Structure

seq-lisp/
├── src/              # Seq source code (the interpreter)
│   ├── tokenizer.seq # Lexical analysis
│   ├── parser.seq    # S-expression parser
│   ├── sexpr.seq     # S-expression data types
│   ├── eval.seq      # Evaluator with environments
│   └── repl.seq      # Interactive REPL
├── tests/
│   ├── seq/          # Seq unit tests (test_*.seq)
│   ├── lisp/         # Lisp test suites
│   │   ├── core/           # Arithmetic, types, strings, floats, JSON
│   │   ├── functions/      # Closures, higher-order, recursion
│   │   ├── special_forms/  # if, let, begin, quote, cond
│   │   ├── macros/         # defmacro, quasiquote, gensym
│   │   └── edge_cases/     # Parser edge cases, error suggestions
│   └── lsp/          # LSP integration tests
├── lib/
│   └── test.slisp     # Lisp test framework
├── examples/         # Lisp programs
├── justfile          # Build commands
└── README.md

Commands

just build        # Build the REPL
just install      # Install seqlisp and seqlisp-lsp to ~/.local
just uninstall    # Remove installed files
just repl         # Run the REPL
just test         # Run Seq unit tests
just lisp-test    # Run Lisp test suite
just lsp-test     # Run LSP integration tests
just examples     # Run all Lisp examples
just clean        # Remove build artifacts
just ci           # Run all tests and build

Lisp Features

SeqLisp supports:

• Arithmetic: +, -, *, /, abs, min, max, modulo
• Comparisons: <, >, <=, >=, =
• Booleans: #t, #f
• Definitions: define, lambda (with variadic support and TCO), let
• Conditionals: if, cond
• Lists: cons, car, cdr, list, quote ('), append, reverse, length, nth, last, take, drop
• Higher-order: map, filter, fold, apply
• Predicates: null?, number?, symbol?, list?, boolean?, equal?
• Macros: defmacro, quasiquote (`), unquote (,), splice (,@), gensym
• Sequencing: begin
• Error Handling: try (returns (ok value) or (error message)), symbol suggestions for typos
• I/O: print, exit

Example

;; Define factorial
(define factorial
  (lambda (n)
    (if (<= n 1)
        1
        (* n (factorial (- n 1))))))

(print (factorial 5))  ;; 120

List Utilities

;; Length of a list
(length '(1 2 3 4 5))    ;; => 5

;; Get nth element (0-indexed)
(nth 2 '(a b c d e))     ;; => c

;; Get last element
(last '(1 2 3 4 5))      ;; => 5

;; Take first n elements
(take 3 '(a b c d e))    ;; => (a b c)

;; Drop first n elements
(drop 2 '(a b c d e))    ;; => (c d e)

Higher-Order Functions

;; Map: transform each element
(map (lambda (x) (* x x)) '(1 2 3 4 5))
;; => (1 4 9 16 25)

;; Filter: keep elements matching predicate
(filter (lambda (x) (> x 2)) '(1 2 3 4 5))
;; => (3 4 5)

;; Fold: reduce list to single value
(fold (lambda (acc x) (+ acc x)) 0 '(1 2 3 4 5))
;; => 15

Macros

;; Define a simple macro
(defmacro (when cond body)
  `(if ,cond ,body '()))

(when #t 'yes)           ;; => yes
(when #f 'yes)           ;; => ()

;; Unless macro (opposite of when)
(defmacro (unless cond body)
  `(if ,cond '() ,body))

(unless #f 42)           ;; => 42

;; Short-circuit and/or
(defmacro (and2 a b) `(if ,a ,b #f))
(defmacro (or2 a b) `(if ,a #t ,b))

;; Use gensym for hygiene (unique symbols)
(gensym 0)               ;; => g0
(gensym 'temp 1)         ;; => temp1

Editor Integration

Neovim

Install seq-lisp.nvim for syntax highlighting and LSP diagnostics:

-- lazy.nvim
{
  "navicore/seq-lisp.nvim",
  ft = "seqlisp",
  opts = {},
}

The plugin expects seqlisp-lsp to be in your PATH (installed via just install).

Documentation

• Architecture - How the interpreter works
• Roadmap - Future plans and vision

License

MIT