add contributing instructions

CONTRIBUTING.md

@@ -0,0 +1,107 @@
+# contributing
+
+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
+
+- [`nushell`][001]
+- [`tree-sitter cli`][002]
+
+## organization
+the most important sections of this repo and the ones which you will
+interact with the most are:
+
+- [grammar.js][101] -> this is the file where the parser rules are
+written. to learn how to write rules, consider visiting the official
+[tree-sitter docs][003] or check out the [tree-sitter github org][004]
+for some implementations
+
+- [queries/][102] -> this directory contains [queries][005] which, among
+other things, help with syntax highlighting. to learn how to write queries,
+consider [this][005]
+
+- [corpus/][103] -> this directory contains tests for the parser. the tests
+roughly organized in directories with their nodes. add a file with a descriprive
+name that should generally cover a node to the right folder and write the
+tests using the [special test syntax][006]
+
+## hacking
+the [`ts.nu`][104] module wraps the [`tree-sitter cli`][002] and makes 
+the commands shorter. to use the module, run
+
+
+```nu
+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
+
+```nu
+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(s)
+and print out their ASTs. 
+ - pass `--debug(-d)` to print the AST along with debug info
+ - pass `--stat(-s)` to only print a success or failure message
+
+```nu
+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.
+```nu
+# generate the config file
+> ts config
+
+# open the generated file in your favorite editor
+> vim <path> 
+```
+
+a [`sample config file`][105] is provided to get you started.
+
+> **Note**
+> You only have to do this once
+
+```
+ts hl ts.nu
+```
+
+## getting help
+
+if you need any help or have a question, ping me `(@1Kinoti)` on the
+[official editor support channel on discord][007] and i will try and answer it
+
+## further reading
+
+- https://tree-sitter.github.io/tree-sitter/
+- https://github.com/tree-sitter/tree-sitter/issues/418
+- https://siraben.dev/2022/03/22/tree-sitter-linter.html
+- https://derek.stride.host/posts/comprehensive-introduction-to-tree-sitter
+- https://rfdonnelly.github.io/posts/using-tree-sitter-parsers-in-rust/
+- https://deepsource.io/blog/lightweight-linting/
+- https://github.com/DerekStride/tree-sitter-math
+
+<!--External Links-->
+[001]: https://github.com/nushell/nushell "nushell"
+[002]: https://tree-sitter.github.io/tree-sitter/creating-parsers#installation "installation"
+[003]: https://tree-sitter.github.io/tree-sitter/creating-parsers#writing-the-grammar "writing grammar"
+[004]: https://github.com/tree-sitter "tree-sitter organization"
+[005]: https://tree-sitter.github.io/tree-sitter/using-parsers#pattern-matching-with-queries "writing queries"
+[006]: https://tree-sitter.github.io/tree-sitter/creating-parsers#command-test "writing tests"
+[007]: https://discord.com/channels/601130461678272522/1066353495638278194 "editor support channel"
+
+<!--Internal Links-->
+[101]: ./grammar.js
+[102]: ./queries/
+[103]: ./corpus/
+[104]: ./ts.nu
+[105]: ./resources/sample-config.json

README.md

@@ -2,70 +2,17 @@
 
 [**WIP**] [nushell](https://github.com/nushell/nushell) grammar for [tree-sitter](https://tree-sitter.github.io/tree-sitter/)
 
-# issues
-1. unquoted strings
-
-![treesitter-nu.readme.1.png](resources/treesitter-nu.readme.1.png)
-
-2. blocks vs records
-since we cannot backtrack, it is difficult to tell apart blocks and
-records. so currently, blocks are not parsed as values
-
-![treesitter-nu.readme.2.png](resources/treesitter-nu.readme.2.png)
-
-3. command arguments are parsed as strings
-
-![treesitter-nu.readme.3.png](resources/treesitter-nu.readme.3.png)
-
-here `2`, `-f`, `arg` will all be parsed as strings
-
-## installation guide
-- for *neovim* users, please have a look at [`installation/neovim.md`](installation/neovim.md)
-
-# tree-sitter-nu
-
-This is an experiment to see if we can create a good parser for nu-lang.
-
-## Goals (brainstorming)
+## goals (brainstorming)
 
 - Ability to serve as a parser for a repl
 - Ability to work in editors that support tree-sitter (`hx`, `nvim`, others)
 - Ability to work in rust
 - Fast
 - Ability to be utilized for syntax highlighting
-- ?
+- ...
 
-## How-To - taken from [here](https://tree-sitter.github.io/tree-sitter/creating-parsers)
-
-1. `cargo install tree-sitter-cli`
-2. make sure nodejs and npm is installed (you may have to do npm install - see docs above)
-3. `tree-sitter generate`
-4. `tree-sitter parse example-file.nu`
-
-## Examples with rust
-
-1. main.rs
-2. `cargo run --example main`
-
-## Testing
-
-1. Add a file to test/corpus/descriptive_test_name.txt
-2. Use the `custom_command_1.txt` as a guide
-3. run `tree-sitter test -f 'custom command 1'` and evaluate the results
-4. More information can be found [here](https://tree-sitter.github.io/tree-sitter/creating-parsers#command-test)
-
-## 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](https://tree-sitter.github.io/tree-sitter/creating-parsers#the-grammar-dsl)
-
-## Further reading
-
-- https://siraben.dev/2022/03/22/tree-sitter-linter.html
-- https://derek.stride.host/posts/comprehensive-introduction-to-tree-sitter
+## installation guide
+- for *neovim* users, please have a look at [`installation/neovim.md`](installation/neovim.md)
 
-- https://tree-sitter.github.io/tree-sitter/
-- https://rfdonnelly.github.io/posts/using-tree-sitter-parsers-in-rust/
-- https://deepsource.io/blog/lightweight-linting/
-- https://github.com/tree-sitter/tree-sitter/issues/418
-- https://github.com/DerekStride/tree-sitter-math
+## contributing
+see [instructions](./CONTRIBUTING.md)

grammar.js

@@ -20,7 +20,7 @@ module.exports = grammar({
  ))
  ),
 
- shebang: $ => seq('#!', /.*/),
+ shebang: $ => seq('#!', /.*\n/),
 
  /// Identifiers
  // NOTE:

resources/sample-config.json

@@ -0,0 +1,36 @@
+{
+ "parser-directories": [
+ "<the path to the parent directory of your parser>"
+ ],
+ // You can change these colors to whatever you want
+ "theme": {
+ "comment": "#a89984",
+
+ "type.builtin": "#d79921",
+ "type.enum": "#b57614",
+
+ "constant": "#d3869b",
+ "string": "#98971a",
+
+ "variable": "#fbf1c7",
+ "variable.builtin": "#b16286",
+ "variable.parameter": "#458588",
+
+ "punctuation": "#fe8019",
+ "punctuation.delimiter": "#fe8019",
+ "punctuation.bracket": "#fe8019",
+ "punctuation.special": "#fe8019",
+
+ "keyword": "#cc241d",
+ "keyword.control.import": "#689d6a",
+ "keyword.storage.modifier": "#af3a03",
+
+ "operator": "#d65d0e",
+
+ "function": "#fabd2f",
+ "function.method": "#458588",
+ "namespace": "#fbf1c7",
+
+ "special": "#fb4934"
+ }
+}

ts.nu

@@ -41,3 +41,8 @@ export def "ts parse" [ # -> string
  tree-sitter parse $file
  }
 }
+
+# Generates a default config file and prints out its path
+export def "ts config" [] {
+ tree-sitter init-config
+}