Knave

[!WARNING] Knave is experimental. Expect breaking changes to the syntax, the prelude and the command line in any commit. The source extension is still .rslisp. It becomes .knv soon.

(def knave
  "A small Lisp for humans and agents
  that infers types and ownership
  and compiles to readable Rust.")

(def values
  (vec "Few rules, no exceptions."
       "Small compiler, big prelude."
       "No clones or allocations you did not write."
       "Interpret while you iterate, compile when you ship."
       "Errors worth reading."))

docs/language.md describes the language.

Install

Install the compiler with Cargo:

cargo install --locked --profile dist knave

The compiler runs the rustc and rustfmt on your PATH, and needs Rust 1.88 or later.

If you use Nix, install the compiler with the rustc and rustfmt that CI tests against:

nix profile install github:knave-lang/knave

To download a prebuilt binary instead of building it, run cachix use rslisp first.

Use

A program starts at main, as examples/hello.rslisp shows:

(defn main ()
  (println (str "hello" " " "world")))

Run knave alone to start the prompt, as knave repl does. Run knave --help to list the commands. Each command except doc and repl takes a source file, and fmt and test also take a directory:

knave run examples/hello.rslisp
knave emit examples/geometry/main.rslisp
knave fmt src/
knave test tests/

A project is a directory with a project.rslisp file. Inside one, build, run, check, types, expand and emit take the project's entry file when given no file.

Develop

The repository uses a Nix flake.

1. Enter the development shell:

   nix develop
   

   If you use direnv, run direnv allow once instead. The shell then loads when you enter the directory.

2. Run the tests with the coverage, CRAP and emitted-Rust lint checks:

   cargo xtask coverage
   

   cargo test --workspace runs the tests alone.

3. Build the compiler:

   nix build
   

   The binary is result/bin/knave. To install a checkout without Nix, run cargo install --locked --profile dist --path ..

Run nix fmt to format the Nix files, and nix flake check to build the package and run the checks that cargo xtask coverage leaves out.

Contribute

Read AGENTS.md before you change the code. It holds the rules for this repository and lists the commands a change must pass. Follow docs/diagnostics.md when you add or change a compiler error.