Using the grammar with editors

This page serves as a guide for getting tree-sitter-gap up and running for syntax highlighting in different editors. Contributions welcome!

Neovim

For syntax highlighting to work, we need to set up recognition for gap and gaptst files. One way of doing this using vimscript is to add the following to your .vimrc or init.vim file:

autocmd BufRead,BufNewFile *.g,*.gi,*.gd set filetype=gap comments=s:##\ \ ,m:##\ \ ,e:##\ \ b:#
autocmd BufRead,BufNewFile *.tst set filetype=gaptst comments=s:##\ \ ,m:##\ \ ,e:##\ \ b:#

If you prefer lua configurations, then you can add the following to your init.lua instead:

vim.filetype.add {
  extension = {
    g = "gap",
    gi = "gap",
    gd = "gap",
    tst = "gaptst",
  },
}

vim.api.nvim_create_autocmd("FileType", {
  pattern = "gap",
  callback = function() vim.o.commentstring = "#%s" end,
})

Any equivalent configuration will work so as long as all .g, .gi, .gd files have filetype gap and all .tst files have filetype gaptst.

There are now 2 routes to installing the grammar itself: via nvim-treesitter or manually, described below:

Neovim route 1: nvim-treesitter

The simplest way of getting tree-sitter-gap running for syntax highlighting is to use the nvim-treesitter plugin:

1. Install nvim-treesitter, see the install guide on the nvim-treesitter wiki.
2. Ensure that the highlight = {enable = true} config option is set for nvim-treesitter, otherwise no syntax highlighting will appear.
3. In a nvim session run the command :TSInstall gap gaptst. This will install the grammar.

Neovim route 2: manual install

We highly recommend using the nvim-treesitter route for ease of install. The following options are intended for advanced neovim users. Manual install instructions for any treesitter parser can be found in the neovim docs. Paraphrasing from the docs the manual install steps are:

1. Locally clone the tree-sitter-gap repository:

git clone https://github.com/gap-system/tree-sitter-gap.git

2. Change into the directory and build the grammar .so file:

cd tree-sitter-gap && tree-sitter build`

3. Executing the previous step should yield a gap.so file, copy this file to ~/.config/nvim/parser/gap.so (note that other directories may be more appropriate, check the neovim docs for more information):

mkdir -p ~/.config/nvim/parser/ && cp gap.so ~/.config/nvim/parser/gap.so

4. Copy the grammar queries to ~/.config/nvim/queries/gap:

mkdir -p ~/.config/nvim/queries/gap && cp ./queries/* ~/.config/nvim/queries/gap/

5. Register the parser for the gap filetype in your by adding the following lua code to your nvim configuration file:

vim.treesitter.language.register('gap', { 'gap' })

Repeat steps 1.-5. with tree-sitter-gaptst for gap test file support.

Neovim troubleshooting

If no syntax highlighting for gap files materializes after attempting an install, going through the following steps can be useful to determine where an issue has occurred:

1. Open a gap file and run :set ft?. It should return filetype=gap, otherwise there has been an issue with the filetype association.
2. Open a gap file and run :TSInstallInfo. The entry for gap should say Installed, otherwise there has been an issue with the language installation during the TSInstall gap step above.
3. Open a gap file and run :InspectTree. It should open a new buffer with a syntax tree of the current file. If the syntax tree is empty, then this could indicate an issue with the installation of the grammar.
4. Open a gap file and run :TSModuleInfo. The row for gap should have a tick in the highlights column. If not, this could indicate an issue when copying the highlight queries.
5. Open a gap file and run :TSConfigInfo. The highlight array should contain and entry enable=true. If it does not, this could indicate that there was an issue when configuring nvim-treesitter where highlighting was not enabled.

If the above troubleshooting steps do not narrow down the issue, please open a Github issue and we can try to work it through.

Emacs

TODO: write this section

VSCode

TODO: write this section