Common Lisp TmLanguage

This repository contains TmLanguage files for Common Lisp, which describes TextMate Grammars, can be used by VSCode, TextMate, Sublime Text, and Atom.

The TmLanguage files can tell the editors how to highlight code.

Development

Setup

Run npm install

TmLanguage Files

We have two syntax files in ./syntaxes, and we use ./syntaxes/scripts/build_grammar.mjs (npm run bg) to convert them into json format:

• commonlisp.yaml is the main syntax of Common Lisp.
• cl_codeblock.yaml is the injection grammar for Markdown.

If you need to modify the syntax, here are some helpful materials:
Syntax Highlight Guide, TextMate grammars, making_language_grammar, textmatebundle, regex101, Common Lisp HyperSpec.

Editing Grammar Workflow

Mastering the TextMate grammars is very difficult. If you are a beginner, you can try to start with a small work sample and then work on it incrementally.
The recommended workflow is:

1. git add
2. construct a regex and verify the regex in regex101
3. add the regex to the syntax
4. convert the syntax into json and test the syntax in real world

If you would like to test the highlighting in a VS Code extension, replace the file commonlisp.tmLanguage.json in the extension with the one you rebuilt.

Maintain Grammar Health

npm run bg # After you modified the grammar, you need to rebuild the grammar. 
npm run testg # Then, test the grammar with the fixtures in `syntaxes/fixtures/baselines`.
npm run diff # Check if it is the test result you expected. Find the differences between the baselines and generated.
npm run accept # If the changes are what you expect, accept the new baselines.

You may need to run npx tsc -p syntaxes/scripts/tsconfig.json to generate gen_record.mjs before npm run testg.

Linting

Run npm run lint for linting.
Most errors and warnings can be fixed automatically by running npm run lint -- --fix.

Run npx unimported to check if there are any dangling files.

Distribution

• GitHub Linguist

Note that althought this grammar is based on vscode-common-lisp. This grammar has no version/source control relationship with vscode-common-lisp, and this grammar is intentionally separated.

Highlighting Sample

Acknowledgment

CL-ANSI Standard Draft, Common Lisp HyperSpec, vscode-scheme, Scheme.tmLanguage, Lisp.tmLanguage, regex101

Image Credits

The code segment in Syntax Highlighting is from SBCL Repository.