Home

Awesome

Common Lisp language support for VS Code

This VS Code extension supports Syntax Highlighting, Snippets, Completion, Hover, Definition, References, Document Symbol, Call Hierarchy, and Semantic Tokens for Common Lisp.

Features

Syntax Highlighting

<img src="https://raw.githubusercontent.com/qingpeng9802/vscode-common-lisp/master/images/syntax_dark_plus.png"> <img src="https://raw.githubusercontent.com/qingpeng9802/vscode-common-lisp/master/images/syntax_light_plus.png">

Snippets

<img src="https://raw.githubusercontent.com/qingpeng9802/vscode-common-lisp/master/images/snippets.gif">

Usage and Recommendation

Beginner's Guide: Overview.

Quick Guide

File Types: lisp, lsp, l, cl, asd, asdf, and you can add more by yourself: adding-a-file-extension-to-a-language.

Kind of SymbolsColor (Dark+)Color (Light+)
Macro, DeclarationBlueDark Blue
Special OperatorPurplePurple
Accessor, Functions, Standard Generic FunctionYellowKhaki
Class, System Class, Type, Condition TypeGreenDark Green
Keyword Package Symbol, Local VariableSky BlueNavy Blue
Constant VariableLight BlueBlue
Special VariableRedBrown

Snippets support: defun, if, cond, let, let*, lambda, etc.

For huge files, in some rare cases, semantic highlighting might lose synchronization when switching files or some large change happens quickly. You only need to type any character in the file to recover.

Preference

The language identifier (id) is commonlisp .

If you need to customize your setting only for Common Lisp files, in settings.json, please add something like

"[commonlisp]": {
  "editor.bracketPairColorization.enabled": false
}

Bracket pair colorization:

Hover tooltip:

Quick suggestions:

Semantic highlighting:

Also, there are some built-in settings of this extension that can customize more advanced preferences, for example, which language feature provider should be used, which token range should be excluded, and how to deal with the backquote part. See wiki.

Please note that the static analysis currently implemented is experimental and may be incomplete and contain errors, so the result is not compiler-level.
If you need to disable all Programmatic Language Features, that is, only use TextMate-based syntax highlighting, you can set "commonLisp.StaticAnalysis.enabled": false in this extension's built-in settings (under Common Lisp tab).

Design

Syntax Highlighting

Because of the functional features of Common Lisp, we use the intuition of Common Lisp to design syntax highlighting instead of the intuition of non-functional language to design syntax highlighting. That is, we strictly follow the CL-ANSI 1.4.4.14 to classify the 978 external symbols in COMMON-LISP package.

We processed Common Lisp HyperSpec to get the kind of each symbol. The result is in ./assets/COMMON-LISP-symbols.csv, and please feel free to reuse the result :)

We assign different colors to different kinds of symbols, and the assignment rule can be found in the start comment of ./syntaxes/commonlisp.yaml. This file includes comments (related info in CL-ANSI) for all rules.

Please use VS Code 1.72.0 or later for the best performance and profile consistency.

Static Analysis

Currently, we use a very simple hand-written parser and combine it with regex to parse the code. Thus, the accuracy, precision, and performance are not good enough. However, we have no plans to complicate the parser further since it is like rebuilding a new wheel (new parser) using TypeScript.

Since this extension is designed as a Web Extension, we are considering using node-tree-sitter as the parser in the future. However, we have no plan to update the parser recently since we are still evaluating its impact on the architecture of VS Code language service (see Anycode).

Learn More

See Developer Guide.

Acknowledgment

CL-ANSI Standard Draft, Common Lisp HyperSpec, vscode-scheme, Scheme.tmLanguage, Lisp.tmLanguage, regex101, OSS license from structure101

Image Credits

The icon.png is from Common-Lisp.net and resized.
The commonlisp_file_icon.svg is extracted from the common lisp icon and colored with the purple in Conrad Barski's Logo.
icon.png and commonlisp_file_icon.svg are used under Attribution 4.0 International (CC BY 4.0).
The code segment in Syntax Highlighting is from SBCL Repository.