tree-sitter-gap

tree-sitter grammar for GAP system files.

Example

The above is a parse tree generated using the tree-sitter-gap grammar for the following code snippet:

G := Group((1, 2, 3), (1, 2)(3, 4));
IsNormal(SymmetricGroup(4), G);

Want to help improve this?

• Install tree-sitter (version >= 0.22.2), official instructions;
• Read "how to create a parser";
• Resolve the TODOs in source and test files;
• Add more missing language features;
• Validate by running on the whole GAP library and on packages, see Tests section below.

Files to edit are

• grammar.js, the main file defining the grammar, documentation;
• src/scanner.c, an external scanner used for scanning tokens that are not easily recognized by the built in rules, documentation;
• tests/corpus/*.txt, test files containing annotated syntax trees used to validate the grammar, ideally a test case should be added here prior to changing the grammar.js or scanner.c files, documentation;
• queries/*.scm, queries used for syntax highlighting etc, documentation;
• tests/highlight/*, tests for syntax highlighting, documentation;
• examples/*, assortment of various example gap files, also used to store GAP library and package corpus for tests, see Tests below.

Almost everything else was generated automatically by tree-sitter generate.

Bits of the GAP syntax are documented in Chapter 4 of the GAP manual. A more in-depth look at the GAP grammar can be obtained by studying the GAP-system source files, especially

• read.c for parsing keywords and high level language constructs;
• scanner.c for matters relating to scanning literals and identifiers;
• io.c for handling whitespace and line continuation characters.

Tests

To run syntax tree and highlighting tests run

make test_quick

note that highlighting tests will only be run once all syntax tree tests pass.

To run tests against the GAP library and GAP package corpus do

make corpus && make test_all

the first command will checkout a copy of GAP and download a package archive, then recursively copy GAP files into the appropriate examples/ subdirectory. The second command will then parse each of these files using the tree-sitter grammar. The output of make test_all is a list of GAP files that the grammar fails to parse, along with some statistics on failing and succeeding parses.

Troubleshooting

Issues finding grammar in external tools

Try specifying the grammar name as lowercase gap, instead of uppercase GAP.

Highlighting tests fail

Make sure you are using tree-sitter 0.22.2 or above. A breaking change in highlight group priority was introduces with version 0.22.2, which means that older versions of the tree-sitter tool will incorrectly highlight the existing test files.

Acknowledgements

Writing this tree-sitter grammar and associated query files was made significantly easier by studying the existing parsers, especially tree-sitter-python, tree-sitter-ruby and tree-sitter-c, from which certain code snippets have been taken verbatim. We would like to thank the authors and maintainers of these packages.