cl-parser-kit

cl-parser-kit is a small, dependency-free parser toolkit for Common Lisp, targeting SBCL. It covers the pieces that recur in real text-language parsers — tokenization, source spans, parser combinators, Pratt expression parsing, structured diagnostics with fix-its, and AST/CST helpers — and deliberately stops there. It is not a compiler framework, an editor integration layer, or a language workbench. Since v1.0.0 the 290 exported symbols are a frozen contract, enforced by a test rather than by convention.

Full documentation is published at https://nerima-lisp.github.io/cl-parser-kit/. The source for that site lives in docs/src/.

Quick Start

(asdf:load-system :cl-parser-kit)

(let ((tokenizer (cl-parser-kit:make-tokenizer
                  :rules (list (cl-parser-kit:make-whitespace-rule :skip-p t)
                               (cl-parser-kit:make-literal-rule :plus "+")
                               (cl-parser-kit:make-number-rule)
                               (cl-parser-kit:make-identifier-rule)))))
  (cl-parser-kit:tokenize-string "sum + 42" tokenizer))
;; => a vector of three tokens -- :IDENTIFIER "sum", :PLUS "+", :NUMBER 42 --
;;    each carrying the source span it came from.

Combinators, Pratt parsing, diagnostics and CST output are covered step by step in Recipes.

Install

# flake.nix
inputs.cl-parser-kit = {
  url = "github:nerima-lisp/cl-parser-kit/v1.0.0";
  inputs.nixpkgs.follows = "nixpkgs";
};

Note the pinned tag. Consumers inside this org pin a release tag rather than following the default branch.

ASDF, Quicklisp, Ultralisp and manual-registry paths are described in Getting Started.

Documentation

• Getting started — every install path, and how to verify a checkout.
• Core concepts — tokens, spans, tokenizers, the parser and Pratt layers, diagnostics.
• API reference — the exported surface grouped by concern.
• Compatibility — what v1.0.0 froze, and what it deliberately did not.

Development

nix develop          # SBCL and Perl, with the test dependency roots exported
nix run .#test       # run the test suite
nix flake check      # tests, compile check, coverage, lint, formatting, docs
nix fmt              # format Nix sources (treefmt)

Tests live in t/ and run under cl-weave, the org's test framework; parser-table invariants are additionally checked as executable cl-prolog-kit queries. The suite also runs from a raw checkout without Nix:

sbcl --script run-tests.lisp

See Development for the coverage floor, the other entry points, and the release process.

Contributing

See the org-wide CONTRIBUTING guide and the package standard.

Support

See SUPPORT. Report vulnerabilities through private GitHub security advisories, not a public issue.

License

MIT. See LICENSE.