contributing

December 19, 2023 ยท View on GitHub

Thank you for wanting to make tree-sitter-nu better. This document will take you through how to setup and contribute to tree-sitter-nu

requirements

organization

the most important sections of this repo and the ones which you will interact with the most are:

  • grammar.js -> this is the file where the parser rules are written. to learn how to write rules, consider visiting the official tree-sitter docs or check out the tree-sitter github org for some implementations

  • queries/ -> this directory contains queries which, among other things, help with syntax highlighting. to learn how to write queries, consider the official docs

  • corpus/ -> this directory contains tests for the parser. the tests roughly organized in directories with their nodes. add a file with a descriptive name that should generally cover a node to the right folder and write the tests using the special test syntax

hacking

the ts.nu module wraps the tree-sitter cli. to use the module, run

> use ts.nu *

  • ts gen -> wraps tree-sitter generate, use this after making changes to the grammar to generate a new parser.

  • ts test -> wraps tree-sitter test, use this to run all the tests. you can optionally supply a string to only run the tests that contain it

> ts test     # run all the tests
> ts test let # run all tests that contain 'let'
  • ts parse -> wraps tree-sitter parse, use this to parse a specific file and print out its AST.
    • pass --debug or -d to print the AST along with debug info
    • pass --stat or -s to only print a success or failure message
> ts parse ts.nu
  • ts hl -> wraps tree-sitter highlight, use this to syntax highlight a file and print the results. this requires some setup in order to tell tree-sitter what colors to apply to what node.

Note You only have to do this once

# generate the config file
> ts config

# open the generated file in your favorite editor
> vim <path>

a sample config file is provided to get you started.

> ts hl ts.nu

using the parser from rust

  1. the code is located at examples/main.rs
  2. run it with cargo run --example main

tips

  • A line in the grammar.js that begins with $._blah means that blah is anonymous and won't show up in the final syntax tree.
  • Most of the grammar how-to is found here

getting help

if you need any help or have a question, ping me (@1Kinoti) on the official editor support channel on discord and i will try and answer it

further reading