Merge pull request #40 from vigoux/contributing

Add CONTRIBUTING.md

5 files changed, 163 insertions, 30 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 00000000..b42950b6
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,99 @@
+# Contributing to `nvim-treesitter`
+
+First of all, thank you very much for contributing to `nvim-treesitter`.
+
+If you haven't already, you should really come and reach out to us on our [gitter](https://gitter.im/nvim-treesitter/community?utm_source=share-link&utm_medium=link&utm_campaign=share-link)
+room, so we can help you with any question you might have!
+
+As you know, `nvim-treesitter` is roughly splitted in two parts :
+  - Parser configurations : for various things like `locals`, `highlights`
+  - What we like to call *modules* : tiny lua modules that provide a given feature, based on parser configurations
+
+Depending on which part of the plugin you want to contribute to, please read the appropriate section.
+
+## Parser configurations
+
+Contributing to parser configurations is basically modifying one of the `queries/*/*.scm`.
+Each of these `scheme` files contains a *tree-sitter query* for a given purpose.
+Before going any further, we highly suggest that you [read more about tree-sitter queries](https://tree-sitter.github.io/tree-sitter/using-parsers#pattern-matching-with-queries).
+
+Each query has an appropriate name, which is then used by modules to extract data from the syntax tree.
+For now two types of queries are used by `nvim-treesitter`:
+  - `highlights.scm` : used for syntax highlighting, using the `highlight` module.
+  - `locals.scm` : used to extract keyword definitions, scopes, references,... using the `locals` module.
+
+For both of these types there is a *norm* you will have to follow so that features work fine.
+Here are some global advices :
+  - If your language is listed [here](https://tree-sitter.github.io/tree-sitter/using-parsers#pattern-matching-with-queries),
+    you can debug and experiment with your queries there.
+  - If not, you should consider installing the [tree-sitter cli](https://github.com/tree-sitter/tree-sitter/tree/master/cli),
+    you should then be able to open a local playground using `tree-sitter build-wasm && tree-sitter web-ui` within the
+    parsers repo.
+
+### Highlights
+
+As languages differ quite a lot, here is a set of captures available to you when building a `highlights.scm` query.
+One important thing to note is that many of these capture groups are not supported by `neovim` for now, and will not have any
+effect on highlighting. We will work on improving highlighting in the near future though.
+
+#### Misc
+`@comment`
+`@error` for error `(ERROR)` nodes.
+`@punctuation.delimiter` for `;` `.` `,`
+`@punctuation.bracket` for `()` or `{}`
+
+Some captures are related to language injection (like markdown code blocks). As this is not supported by neovim yet, these
+are optionnal and will not have any effect for now.
+`@embedded`
+`@injection`
+  `language`
+  `content`
+
+#### Constants
+`@constant`
+  `builtin`
+  `macro`
+`@string`
+  `regex`
+  `escape`
+`@character`
+`@number`
+`@boolean`
+`@float`
+
+#### Functions
+`@function`
+  `builtin`
+  `macro`
+`@parameter`
+
+`@method`
+`@field` or `@property`
+
+`@constructor`
+
+#### Keywords
+`@conditional`
+`@repeat`
+`@label` for C/Lua-like labels
+`@operator`
+`@keyword`
+`@exception`
+
+`@type`
+        `builtin`
+`@structure`
+
+### Locals
+
+`@definition` for various definitions
+  `function`
+  `method`
+  `var`
+  `macro`
+  `type`
+
+`@scope`
+
+`@reference`
+
diff --git a/lua/nvim-treesitter/highlight.lua b/lua/nvim-treesitter/highlight.lua
index 65ab48dc..9cf25963 100644
--- a/lua/nvim-treesitter/highlight.lua
+++ b/lua/nvim-treesitter/highlight.lua
@@ -6,6 +6,47 @@ local M = {
   highlighters = {}
 }
 
+local hlmap = vim.treesitter.TSHighlighter.hl_map
+
+-- Misc
+hlmap.error = "Error"
+hlmap["punctuation.delimiter"] = "Delimiter"
+hlmap["punctuation.bracket"] = "Delimiter"
+
+-- Constants
+hlmap["constant"] = "Constant"
+hlmap["constant.builtin"] = "Special"
+hlmap["constant.macro"] = "Define"
+hlmap["string"] = "String"
+hlmap["string.regex"] = "String"
+hlmap["string.escape"] = "SpecialChar"
+hlmap["character"] = "Character"
+hlmap["number"] = "Number"
+hlmap["boolean"] = "Boolean"
+hlmap["float"] = "Float"
+
+-- Functions
+hlmap["function"] = "Function"
+hlmap["function.builtin"] = "Special"
+hlmap["function.macro"] = "Macro"
+hlmap["parameter"] = "Identifier"
+hlmap["method"] = "Function"
+hlmap["field"] = "Identifier"
+hlmap["property"] = "Identifier"
+hlmap["constructor"] = "Special"
+
+-- Keywords
+hlmap["conditional"] = "Conditional"
+hlmap["repeat"] = "Repeat"
+hlmap["label"] = "Label"
+hlmap["operator"] = "Operator"
+hlmap["keyword"] = "Keyword"
+hlmap["exception"] = "Exception"
+
+hlmap["type"] = "Type"
+hlmap["type.builtin"] = "Type"
+hlmap["structure"] = "Structure"
+
 function M.attach(bufnr, ft)
   local buf = bufnr or api.nvim_get_current_buf()
   local ft = ft or api.nvim_buf_get_option(buf, 'ft')
diff --git a/lua/nvim-treesitter/locals.lua b/lua/nvim-treesitter/locals.lua
index 3e517454..b16408ac 100644
--- a/lua/nvim-treesitter/locals.lua
+++ b/lua/nvim-treesitter/locals.lua
@@ -52,8 +52,8 @@ function M.get_definitions(bufnr)
   local defs = {}
 
   for _, loc in ipairs(locals) do
-    if loc.definition and loc.definition.node then
-      table.insert(defs, {node=loc.definition.node, kind=loc.kind})
+    if loc.definition then
+      table.insert(defs, loc.definition)
     end
   end
 
diff --git a/queries/lua/highlights.scm b/queries/lua/highlights.scm
index 3077be10..a674638e 100644
--- a/queries/lua/highlights.scm
+++ b/queries/lua/highlights.scm
@@ -3,16 +3,16 @@
 ;;; Builtins
 ;; Keywords
 "local" @keyword
-"if" @keyword
-"then" @keyword
-"else" @keyword
-"elseif" @keyword
+"if" @conditional
+"then" @conditional
+"else" @conditional
+"elseif" @conditional
 "end" @keyword
 "return" @keyword
-"do" @keyword
-"while" @keyword
-"repeat" @keyword
-"for" @keyword
+"do" @repeat
+"while" @repeat
+"repeat" @repeat
+"for" @repeat
 (break_statement) @keyword
 "goto" @keyword
 
@@ -43,15 +43,16 @@
 "#" @operator
 
 ;; Constants
-(false) @constant
-(true) @constant
-(nil) @constant
+(false) @boolean
+(true) @boolean
+(nil) @constant.builtin
 (spread) @constant ;; "..."
 
 ;; Nodes
 (function "function" @function "end" @function)
+(function_definition "function" @function "end" @function)
 (local_function "function" @function "end" @function)
-(table "{" @operator "}" @operator)
+(table "{" @constructor "}" @constructor)
 (comment) @comment
 (string) @string
 (number) @number
diff --git a/queries/lua/locals.scm b/queries/lua/locals.scm
index 5f21e0aa..ee292732 100644
--- a/queries/lua/locals.scm
+++ b/queries/lua/locals.scm
@@ -2,25 +2,20 @@
 
 ;; Variable and field declarations
 ((variable_declarator
-   (identifier) @definition)
-  (set! definition.kind "v"))
+   (identifier) @definition.var))
 
 ((variable_declarator
-   (field_expression object:(*) @definition.associated (property_identifier) @definition))
-  (set! difinition.kind "v"))
+   (field_expression object:(*) @definition.associated (property_identifier) @definition.var)))
 
 ;; Parameters
 ((local_function
-   (parameters (identifier) @definition))
-  (set! definition.kind "v"))
+   (parameters (identifier) @definition.var)))
 ((function
-   (parameters (identifier) @definition))
-  (set! definition.kind "v"))
+   (parameters (identifier) @definition.var)))
 
 ;; Loops
 ((loop_expression
-   (identifier) @definition)
-  (set! definition.kind "v"))
+   (identifier) @definition.var))
 
 ;; Function definitions
 ;; Functions definitions creates both a definition and a new scope
@@ -28,16 +23,13 @@
    (function_name
      (function_name_field
        (identifier) @definition.associated
-       (property_identifier) @definition))) @scope
- (set! definition.kind "m"))
+       (property_identifier) @definition.method))) @scope)
 
 ((function
-   (function_name (identifier) @definition)) @scope
-  (set! definition.kind "f"))
+   (function_name (identifier) @definition.function)) @scope)
 
 ((local_function
-   (identifier) @definition) @scope
-  (set! definition.kind "f"))
+   (identifier) @definition.function) @scope)
 
 ((if_statement) @scope)
 ((for_in_statement) @scope)