Sage X3 .src support for Visual Studio Code, focused on snippets, keyword-aware function suggestions, hover help, outline symbols, and navigation.
Features
- Registers
.src files as the x3 language.
- Provides standard Sage X3 / AIMSYS snippets.
- Provides keyword-aware completions from configured Sage X3 source directories.
- Shows hover documentation for recognized function calls.
- Adds Outline View / Document Symbols for
$ labels, Subprog, and Funprog.
- Supports Go to Definition / Peek Definition for
Call, Gosub, and func references.
- Can optionally render clickable document links for references.
- Can optionally watch configured source directories and refresh the function index after
.src files change.
- Indexes configured source roots asynchronously with visible progress and a persistent cache.
Setup
The extension does not ship proprietary source files such as AIMGENLIB.src or AIMGENCHECK.src. Configure local directories that contain your own .src files.
Run these commands from the Command Palette:
Sage X3: Configure Source Directories
Source directories are scanned recursively for custom function suggestions, hover/signature help, Go to Definition, and Peek Definition.
Supported References
Navigation and hover support these patterns:
Call FOO(ARG1, ARG2) From BAR
Call FOO From BAR
Gosub FOO From BAR
Gosub FOO
func BAR.FOO(ARG1, ARG2)
Call FOO(ARG1, ARG2)
func FOO(ARG1, ARG2)
Navigation resolves by reference type. Call FOO From BAR resolves only to Subprog FOO in BAR.src; func BAR.FOO() resolves only to Funprog FOO in BAR.src; Gosub FOO From BAR resolves only to $FOO in BAR.src. When no module is present, the extension resolves in the current .src module when possible.
Function Documentation
Custom function suggestions are built from documented Subprog and Funprog declarations:
# Short description
# @keywords keyword1 keyword2 keyword3
# @param VALUE: description
# @return: description
Funprog MYFUNC(VALUE)
The description, keywords, parameters, and return details are shown in completion details and hover text.
Future Keyword Catalog
Currently, custom completions use information that already exists in the .src files: function names, module names, parameters, descriptions, @keywords, and return comments. Functions without useful comments or keywords are still suggested by name, but they may not appear for intent-based searches such as import file or validate site.
A future enhancement may add an optional external keyword catalog, so users can maintain extra descriptions, aliases, and search terms for standard or proprietary functions without editing the original .src files.
Settings
{
"sageX3.sourceDirectories": [
"C:/path/to/sagex3/sources"
],
"sageX3.watchSourceFiles": false,
"sageX3.indexOnStartup": false,
"sageX3.enableDocumentLinks": false,
"sageX3.maxCompletionItems": 200
}
For large repositories, configure the narrowest folders that contain the .src files you need. Full-root indexing is supported, but the first refresh may take several minutes for very large trees.
By default, the extension does not index on startup and does not watch source folders. Run this command when you want to build or refresh the function index:
Sage X3: Refresh Function Index
Refresh runs asynchronously, shows progress, supports cancellation, and caches parsed results. Later refreshes only reparse files whose size or modified time changed.
The cached custom function index is not loaded automatically when startup indexing is disabled. This keeps standard snippets available immediately when a .src file opens. After you run Sage X3: Refresh Function Index, custom completions, hover, signature help, and navigation use the in-memory index. Edits to an open .src file update only that file's functions after a short debounce instead of rebuilding the whole index while you type.
Document links are disabled by default because they require scanning visible documents for links and can be expensive with very large files or very large indexes. Go to Definition, hover, and completion still work when document links are disabled.
Development
Install dependencies:
npm install
Compile:
npm run compile
Package locally:
npx vsce package --no-dependencies --allow-missing-repository
Package into the local release folder:
npm run package:release
Use GitHub Releases for published VSIX artifacts instead of committing generated .vsix files. Keep source files in git, and attach the packaged VSIX to a release tag such as v1.1.5.
License
See LICENSE.txt.
