From 9579e41a83cad5a719d0dce9f18ef6aa70554850 Mon Sep 17 00:00:00 2001 From: archseer Date: Sun, 7 Nov 2021 01:31:26 +0000 Subject: [PATCH] deploy: acced82be66c9a3920b8147bdd8fa6785388e8c8 --- 404.html | 2 +- configuration.html | 2 +- from-vim.html | 2 +- guides/adding_languages.html | 224 +++++++++++++++++++++++++++++++++++ guides/index.html | 10 +- guides/textobject.html | 6 +- hooks.html | 6 +- index.html | 2 +- install.html | 2 +- keymap.html | 2 +- languages.html | 188 +++++++++++++++++++++++++++++ print.html | 56 ++++++++- remapping.html | 2 +- searchindex.js | 2 +- searchindex.json | 2 +- themes.html | 2 +- usage.html | 2 +- 17 files changed, 489 insertions(+), 23 deletions(-) create mode 100644 guides/adding_languages.html create mode 100644 languages.html diff --git a/404.html b/404.html index 50c829d76..0d296bdd0 100644 --- a/404.html +++ b/404.html @@ -78,7 +78,7 @@ diff --git a/configuration.html b/configuration.html index 09a1be487..fd6f715e3 100644 --- a/configuration.html +++ b/configuration.html @@ -77,7 +77,7 @@ diff --git a/from-vim.html b/from-vim.html index fc4fb0687..3a55be926 100644 --- a/from-vim.html +++ b/from-vim.html @@ -77,7 +77,7 @@ diff --git a/guides/adding_languages.html b/guides/adding_languages.html new file mode 100644 index 000000000..e1ba110be --- /dev/null +++ b/guides/adding_languages.html @@ -0,0 +1,224 @@ + + + + + + Adding Languages + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + +
+
+

Adding languages

+

Submodules

+

To add a new langauge, you should first add a tree-sitter submodule. To do this, you can run the command

+
$ git submodule add -f <repository> helix-syntax/languages/tree-sitter-<name>
+
+

For example, to add tree-sitter-ocaml you would run

+
$ git submodule add -f https://github.com/tree-sitter/tree-sitter-ocaml helix-syntax/languages/tree-sitter-ocaml
+
+

Make sure the submodule is shallow by doing

+
git config -f .gitmodules submodule.helix-syntax/languages/tree-sitter-<name>.shallow true
+
+

or you can manually add shallow = true to .gitmodules.

+

languages.toml

+

Next, you need to add the language to the languages.toml found in the root of the repository; this languages.toml file is included at compilation time, and is distinct from the language.toml file in the user's configuration directory.

+

These are the available keys and descriptions for the file.

+ + + + + + + + + + +
KeyDescription
nameThe name of the language
scopeA string like source.js that identifies the language. Currently, we strive to match the scope names used by popular TextMate grammars and by the Linguist library. Usually source.<name> or text.<name> in case of markup languages
injection-regexregex pattern that will be tested against a language name in order to determine whether this language should be used for a potential language injection site. link
file-typesThe filetypes of the language, for example ["yml", "yaml"]
rootsA set of marker files to look for when trying to find the workspace root. For example Cargo.lock, yarn.lock
auto-formatWhether to autoformat this language when saving
comment-tokenThe token to use as a comment-token
indentThe indent to use. Has sub keys tab-width and unit
configLanguage server configuration
+

Queries

+

For a language to have syntax-highlighting and indentation among other things, you have to add queries. Add a directory for your language with the path runtime/queries/<name>/. The tree-sitter website gives more info on how to write queries.

+

Common Issues

+
    +
  • If you get errors when building after switching branches, you may have to remove or update tree-sitter submodules. You can update submodules by running
    • +
+
$ git submodule update --init
+
+
    +
  • +

    Make sure to not use the --remote flag. To remove submodules look inside the .gitmodules and remove directories that are not present inside of it.

    +
    • +
  • +

    If a parser is segfaulting or you want to remove the parser, make sure to remove the submodule and the compiled parser in runtime/grammar/<name>.so

    +
    • +
  • +

    The indents query is indents.toml, not indents.scm. See this issue for more information.

    +
    • +
+ +
+ + +
+
+ + + +
+ + + + + + + + + + + + diff --git a/guides/index.html b/guides/index.html index ede678f6b..fe71834d7 100644 --- a/guides/index.html +++ b/guides/index.html @@ -77,7 +77,7 @@ @@ -145,10 +145,10 @@ tree-sitter grammers, textobject queries, etc.