elispvm

README

vibeEmacsLispVm

Tiny embeddable Emacs Lisp subset VM for Go.

中文文档

This is not a full Emacs Lisp implementation. It is a minimal S-expression parser/evaluator intended to be embedded by host applications that register their own Go functions.

Packages and Layout

• Root package elispvm: public API facade for embedding. It exposes stable types, constructors, parsing, formatting, and evaluator methods.
• internal/vm: parser, evaluator, runtime values, core forms, and builtin functions. This is the implementation package and is intentionally not importable by downstream modules.
• internal/repl: command-line read-eval-print loop separated from the VM library so interactive I/O does not become part of the embedding API.
• cmd/elispvm: standalone CLI entrypoint for the REPL and one-shot evaluation.

Scope

Supported syntax:

• Lists: (foo bar)
• Symbols: foo, :keyword
• Strings with basic escapes: "hello\nworld"
• Numbers: 1, 3.14
• Quote shorthand: '("read" "grep")
• Backquote/comma: `(a ,b ,@c)
• Line comments: ; comment

Supported special forms:

• quote
• progn
• let
• let*
• setq
• if
• when
• unless
• and
• or
• while
• cond
• catch
• throw
• lambda
• defun
• backquote
• comma
• comma-splice
• defmacro
• with-current-buffer
• save-current-buffer

Supported builtins:

• concat
• format (%s only)
• list
• length
• cons, car, cdr, nth, append, reverse, member, assoc
• funcall, apply
• macroexpand-1, macroexpand
• +, -, *, /
• =, /=, <, <=, >, >=
• eq, equal
• string=, string-equal, string-lessp, string<, string-greaterp, string>
• not
• null, symbolp, stringp, numberp, listp, consp, atom
• bufferp, buffer-name, current-buffer, set-buffer, get-buffer, get-buffer-create, generate-new-buffer, kill-buffer
• point, point-min, point-max, goto-char, insert, delete-region, buffer-substring, buffer-string, erase-buffer
• markerp, make-marker, point-marker, copy-marker, marker-position, marker-buffer, set-marker

Function support currently accepts fixed argument lists only; &optional, &rest, and other full Emacs Lisp lambda-list features are not implemented.

Not supported:

• Full Emacs Lisp runtime
• Full Emacs Lisp lambda-list features
• Reader macros beyond quote/backquote/comma
• Vectors
• Filesystem-backed buffers, windows, frames, processes, files, shell, network, packages

Embedding

package main

import (
	"context"
	"fmt"

	elispvm "github.com/startvibecoding/vibeEmacsLispVm"
)

func main() {
	e := elispvm.New()
	e.RegisterFunc("join", func(ctx *elispvm.EvalContext, args []elispvm.Value) (elispvm.Value, error) {
		a := string(args[0].(elispvm.String))
		b := string(args[1].(elispvm.String))
		return elispvm.String(a + "/" + b), nil
	})

	v, err := e.EvalString(context.Background(), `(concat "hello" " " "world")`)
	if err != nil {
		panic(err)
	}
	fmt.Println(elispvm.Stringify(v))
}

Use RegisterFunc for normal functions with evaluated arguments. Use RegisterSpecial only when a host function must control evaluation of its arguments.

Tooling can inspect registered names with FuncNames, SpecialNames, and GlobalNames. These return sorted copies and do not expose mutable evaluator state.

More examples are available in examples/.

CLI REPL

Build the command:

make build

Start the REPL:

./bin/elispvm

Evaluate source without starting the REPL:

./bin/elispvm -eval '(concat "hello" " " "world")'
./bin/elispvm -file ./script.el

The REPL accepts one expression at a time and supports multi-line lists. Use :help for REPL commands and :quit to exit. In an interactive Linux terminal, press Tab to complete registered functions, special forms, globals, nil, and t; when multiple names match, Tab prints the candidates.

Run the sample script:

./bin/elispvm -file ./examples/scripts/basic.el

Examples

• examples/embedding/main.go: embed the VM in a Go program and register a host function.
• examples/scripts/basic.el: evaluate a small Lisp script with the CLI.

Make Targets

make fmt      # gofmt all Go files
make test     # run go test ./...
make vet      # run go vet ./...
make build    # build ./bin/elispvm
make repl     # build and run the REPL
make package  # create a dist/*.tar.gz bundle with binary, README, and LICENSE
make clean    # remove build artifacts

Tests

go test ./...

License

MIT License. See LICENSE.

Documentation

Overview

Package elispvm implements a tiny embeddable Emacs Lisp subset evaluator.

It intentionally does not implement full Emacs Lisp. The package provides S-expression parsing, a small evaluator, core special forms, and a Go-side function registration API for host applications.

Index

• Variables
• func IsNil(v Value) bool
• func Stringify(v Value) string
• func Truthy(v Value) bool
• type BuiltinFunc
• type Env
  • func NewEnv(parent *Env) *Env
• type Error
• type EvalContext
• type Evaluator
  • func New() *Evaluator
• type Expr
  • func Parse(src string) ([]Expr, error)
• type List
• type NilType
• type Number
• type Position
• type SpecialForm
• type String
• type Symbol
• type Value

Variables

var Nil = vm.Nil

Nil is the Lisp nil value.

Functions

func IsNil

func IsNil(v Value) bool

IsNil reports whether v is Lisp nil.

func Stringify

func Stringify(v Value) string

Stringify returns a readable Lisp representation of v.

func Truthy

func Truthy(v Value) bool

Truthy implements Lisp truthiness: only nil is false.

Types

type BuiltinFunc

type BuiltinFunc = vm.BuiltinFunc

BuiltinFunc is a Go function registered as a Lisp function. Arguments have already been evaluated.

type Env

type Env = vm.Env

Env is a lexical environment.

func NewEnv

func NewEnv(parent *Env) *Env

NewEnv creates an empty environment with an optional parent.

type Error

type Error = vm.Error

Error is a parse or evaluation error with optional source position.

type EvalContext

type EvalContext = vm.EvalContext

EvalContext carries execution context and lexical environment.

type Evaluator

type Evaluator = vm.Evaluator

Evaluator evaluates parsed expressions.

func New

func New() *Evaluator

New creates an evaluator with core forms and builtins registered.

type Expr

type Expr = vm.Expr

Expr is a parsed expression. Parsed expressions and runtime values share the same concrete types for this small Lisp.

func Parse

func Parse(src string) ([]Expr, error)

Parse parses all top-level expressions from src.

type List

type List = vm.List

List is a Lisp list.

type NilType

type NilType = vm.NilType

NilType is the singleton nil value type.

type Number

type Number = vm.Number

Number is a Lisp numeric value.

type Position

type Position = vm.Position

Position identifies a location in source text.

type SpecialForm

type SpecialForm = vm.SpecialForm

SpecialForm is a Go function registered as a Lisp special form. Arguments are passed unevaluated so the form can control evaluation.

type String

type String = vm.String

String is a Lisp string value.

type Symbol

type Symbol = vm.Symbol

Symbol is an interned symbol name.

type Value

type Value = vm.Value

Value is a runtime value.