Language implementor tips

This page is odds-and-ends notes for new folks implementing a new language or migrating an existing language to treesitter.

• Sending small PRs is preferred. Make incremental progress.
• The scope visualizer supports hot reloading.
• Make good use of data/playground. Don't be shy about it. It'll help other folks in the future.
• In a PR description, [x] means "done", [ ] means "not done yet", and [-] means "N/A (not applicable)"
• Include screenshots of visualizations in your PR to help reviewers
• Attending meetups is strongly recommended. It's a great place to get questions about behavior answered.
• In a map/list, "take item comma" takes the items on both sides of the comma. Surprising, but semi-intentional. If your implementation throws a no scope error for "take item comma", that is fine too
• Note that you often don't need to implement "item", as we have a default implementation that works for most cases
• In maps/lists, the curly braces should not be part of the iteration scope for "item".
• Think about comment nodes as you define scopes, but don't go crazy trying to make them perfect. In many languages, a comment node can appear pretty much anywhere in the parse tree
• Read https://github.com/cursorless-dev/cursorless/issues/1742, as it has useful information
• Use not just visualize <scope> but also visualize <scope> iteration and visualize <scope> removal
• The removal range is defined as a series of fallbacks:
  • .removal if it exists (rare), .trailing merged with content range if non-empty,
  • .leading merged with content range if non-empty,
  • then just the content range itself.
• The tree-sitter query language only supports three captures attached to any given matched node. After that it silently ignores any captures you write! For example, the pattern (aaa) @bbb @ccc @ddd @eee will silently ignore the @eee capture. To work around this, you can duplicate the query, eg (aaa) @bbb @ccc @ddd (aaa) @eee
• To have the extension maintain open files across test runs, open a workspace (any workspace!) in it, and then open the files you want within that workspace window. Note that the files you open don't even need to be in the given workspace
• The special scope handler comment syntax for .scm files, which you'll see are prefixed with !'s and !!, is documented here https://github.com/cursorless-dev/cursorless/issues/1524 .