GAP System Support

English | 简体中文

This extension provides intelligent code editing powered by tree-sitter-gap, GAP code running, a help system, and language model tools for GAP in VS Code, so that GAP users can write, read, and run GAP code and look up GAP documentation at any time. The file extensions recognized as GAP are .g, .gi, .gd, and .gap.

GAP is a system for computational discrete algebra, with particular emphasis on Computational Group Theory. GAP provides a programming language, a library of thousands of functions implementing algebraic algorithms written in the GAP language as well as large data libraries of algebraic objects. For more information, see the GAP official website.

Features

• Semantic highlighting and syntax diagnostics: based on tree-sitter-gap.
• Code completion: provides completion for GAP constants, keywords, statement structures, and GAP functions (including functions from other GAP files loaded via Read).
• Hover hints: hovering over a function name shows a help link for GAP functions; for user defined functions it shows the definition line and the ## comments.
• Go to Definition: native VS Code definition navigation for user defined functions.
• Running GAP code: runs the current GAP file in the VS Code integrated terminal, with configurable GAP command line options.
• Help system: built-in GAP help system with two search modes (switchable at any time in the settings or the Quick Pick search box), with results filterable by book.
  • prefix: same behavior as ?topic in GAP
  • substring: same behavior as ??topic in GAP
• Documentation viewer: search results are displayed in a webview panel.
• Language model tools: GAP help lookup and syntax checking tools that agents can automatically invoke in chat.

Getting Started

1. Install GAP and Configure the PATH

First, make sure GAP is installed and added to the system PATH. If it is not on the PATH, you can follow the steps below to configure it.

Windows: If GAP was installed via the .exe installer, run the following in PowerShell:

$userPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', $userPath + ';C:\Program Files\GAP-4.16.1\runtime\opt\gap-4.16.1;C:\Program Files\GAP-4.16.1\runtime\bin', 'User')

After running the commands above, open a new PowerShell terminal and run gap --version. If it prints the GAP version, your environment is configured successfully.

Linux / macOS: Run the following in a terminal (on macOS, replace ~/.bashrc with ~/.zshrc):

echo 'export PATH="/opt/gap-4.16.1:$PATH"' >> ~/.bashrc
source ~/.bashrc

Finally, run gap --version to verify that it is configured correctly.

Note: If your installation path differs from the examples, replace it with your actual installation path.

2. Set the GAP Documentation Paths in the Extension Settings

Set the following settings in the walkthroughs on the Welcome page or in the VS Code extension settings:

• gap.docPath: the absolute path of the doc/ folder, for example:
  • Windows: C:\Program Files\GAP-4.16.1\runtime\opt\gap-4.16.1\doc
  • Linux/macOS: /opt/gap-4.16.1/doc
• gap.pkgPath: the absolute path of the pkg/ folder, for example:
  • Windows: C:\Program Files\GAP-4.16.1\runtime\opt\gap-4.16.1\pkg
  • Linux/macOS: /opt/gap-4.16.1/pkg

Feature Demos

1. Language Model Tools

Tool Usage Examples

2. Completion, Hover, and Go to Definition

3. Help System

Same behavior as ?topic and ??topic in GAP, and the demo shows AllSmallGroups for prefix search.

4. Running GAP and Configuring Command Line Options

Note: vscode.workspace.getWorkspaceFolder(doc.uri) determines the terminal cwd when running a GAP file. For a single-root workspace, cwd is set to the workspace root folder; for a multi-root workspace, cwd is set to the workspace root folder that contains the GAP file (for nested roots, the innermost root folder is returned); if the GAP file is not in any workspace, no cwd is specified and the terminal uses the VS Code default directory. See the VS Code API for more information.

Language Model Tools

Tool	Purpose
search_gap_help	Searches the GAP help index and returns matched entries with their file locations
list_gap_books	Lists all GAP help book short names
gap_resolve_link	Resolves a relative link in a GAP help file to its absolute path and target line
check_gap_syntax	Statically checks a GAP source file for syntax errors using tree-sitter-gap

Settings

Setting	Default	Description
gap.docPath	""	Manually enter the absolute path of the doc/ directory
gap.pkgPath	""	Manually enter the absolute path of the pkg/ directory
gap.docAppearance	system	Documentation appearance: system follows the VS Code theme, dark / light use a dark or light theme
gap.mathJax	true	Whether to render MathJax math in GAP documentation pages
gap.runMode	reuse	When running GAP: reuse keeps the same terminal, new opens a new terminal for each run
gap.terminalRoot	""	Unix root for Windows drive letters. Example: / turns C:\project\file.g into /c/project/file.g; leave empty to use the WSL default /mnt/
gap.searchMode	prefix	Search mode: prefix corresponds to ?topic, substring corresponds to ??topic
gap.diagnostics	true	Show syntax error diagnostics (missing/expected tokens, unexpected syntax) from the GAP parser in the Problems panel

Commands

Press Ctrl+Shift+P or F1 to open the Command Palette and use the following commands:

Command	Description
GAP: Run GAP File	Available when a GAP file is open; run the current GAP file in a terminal
GAP: Configure GAP Command Line Options	Configure GAP command line options through Quick Pick
GAP: Search GAP Help	Search GAP help documentation
GAP: Rebuild Help Index	Rebuild the help index
GAP: Open GAP Reference Manual	Open the GAP Reference Manual
GAP: Generate Completion Data	Regenerate the completion data
GAP: Reset Completion Data	Restore the default completion data

These commands are also available in the editor context menu (right-click menu) of GAP files, where GAP: Search GAP Help and GAP: Run GAP File are at the top level, while the remaining commands are grouped in the More GAP Commands submenu.

Development

First, install the dependencies and compile the TypeScript sources:

npm install
npm run compile

Run the tests:

npm test

Then press F5 to start debugging.

Acknowledgements

• Syntax highlighting is implemented based on the tree-sitter-gap query files.
• The extension icon is from gap-logo.

Third Party Notices

• The query files and grammar rules are from tree-sitter-gap (MIT, Copyright (c) 2019 Max Horn, contributor Reinis Cirpons).
• The GAP logo is © Max Horn (contributor Reinis Cirpons) and a trademark of the GAP project, licensed under CC BY-SA 4.0. Derivatives must be shared under the same license. See gap-logo.
• See THIRDPARTYNOTICES.md for third-party notices.

License

MIT