madskjeldgaard / tree-sitter-supercollider

SuperCollider grammar for the tree-sitter code parser

Table of Contents generated with DocToc

• tree-sitter-supercollider
  • Contributing
    • Overview
    • Resources
      • Tree-sitter resources:
      • SuperCollider language resources:
    • Testing
  • Status: Experimental but almost fully implemented
  • Features
  • Showcase:
  • Try it out
  • Trying with nvim-treesitter
    • Install locally in nvim

SuperCollider code (on the right) being parsed live by tree-sitter (on the left) using the nvim-playground plugin. Notice how quickly and incrementally it parses the code and includes the precise location of language features of the code

tree-sitter-supercollider

SuperCollider grammar for tree-sitter.

SuperCollider is a programming language for sound. Tree-sitter is a really smart code parser.

This project defines a grammar (the "rules" of the language) for SuperCollider in a way that allows tree-sitter to do fast and very precise analysis of the code, while it is being typed.

Among other things, this allows for a very high level of precision in syntax highlighting (see below) and analyzing/traversing source code with equal precision.

Status: Experimental but almost fully implemented

Most of sclang is now implemented, except for a few of the more esoteric things (see issues/todolist) and generally works well. Yet, it is still early days and so expect bugs and changes to happen.

Features

• Scoped syntax highlighting (tree-sitter can tell the difference between local variables, environment variables and arguments inside of code blocks / functions)
• Very precise error messages (if a node fails, tree-sitter can tell pretty easily where it failed and why - for example if you are missing a semi colon in the middle of a function)
• Editor agnostic - tree-sitter grammars can be implemented in any editor via tree-sitter's language bindings

Showcase:

Syntax highlighting

Syntax highlighting a supercollider document in the terminal using the command tree-sitter highlight <somedocument>.scd:

Get table of contents for all definitions using nvim-treesitter-refactor and navigate the document using those:

Rename all instances of a variable using nvim-treesitter-refactor:

Using nvim-treesitter's playground to get a live view of the parser tree while writing code:

Try it out

See node tree parsing in action

tree-sitter generate && tree-sitter parse example-file.scd

See highlighting in action

tree-sitter generate && tree-sitter highlight example-file.scd

Trying with nvim-treesitter

Install nvim-treesitter to use this grammar with NeoVim and follow their instructions for installing grammars.

Install locally in nvim

For development purposes it may be helpful to install your supercollider grammar locally:

Add this to your nvim config (change path in url to that of the tree sitter supercollider repo on your system if it you've downloaded it somewhere):

-- tree-sitter-supercollider
local parser_config = require "nvim-treesitter.parsers".get_parser_configs()
parser_config.supercollider = {
	install_info = {
		-- url = "~/code/tree-sitter-supercollider",
		url = "https://github.com/madskjeldgaard/tree-sitter-supercollider",
		files = {"src/parser.c"},
		maintainer = "@madskjeldgaard"
	},
	filetype = "supercollider", -- if filetype does not agrees with parser name
}

Contributing

Help WANTED. This project is too big to be handled by one person, and so any and all help would be appreciated.

If you want to help out, you can either identify and open up issues (example: Find some language feature that has not been defined in the grammar yet or some code that makes tree-sitter fail), resolve existing ones or write tests.

Pull requests are especially appreciated.

Overview

The source code is divided up like this:

• grammar.js - This is where the syntax and grammar is defined.
• test/corpus/ - All unit tests sit here as .txt files
• queries/*.scm - Syntax highlighting, code folding and indentation
• src/scanner.c - A C file defining external scanners for more complex matching tasks

Resources

Here are some helpful resources for developers who want to contribute:

Tree-sitter resources:

• Creating parsers - The official tree-sitter documentation for creating parsers
• The javascript tree-sitter grammar is a good reference
• A nice talk about what tree-sitter is and what it does

SuperCollider language resources:

There is no official spec for he SuperCollider language (hehe), but these links are somewhat helpful:

• Literals in SuperCollider
• Symbolic notation in SuperCollider
• Syntax shortcuts in SuperCollider
• the SCIDE lexer

Testing

Ideally, all rules in the grammar should be accompanied by at least one unit test.

These are found in test/corpus and named <subject>.txt. See this part of the tree-sitter docs on how to create tests.

Run them like this:

tree-sitter generate && tree-sitter test

Before pushing a pull request, make sure that it passes all tests.