Antescofo for VS Code

Antescofo tooling for Visual Studio Code offering syntax awareness, navigation helpers, and authoring conveniences for .asco, .antescofo, and .asco.txt scores.

Feature Highlights

Rich Syntax Highlighting
- Comprehensive TextMate grammar aligned with the Antescofo parser (Bison/Flex sources).
- Detects directives (@fun_def, @proc_def, @pattern_def, @map_history, …), score keywords (NOTE, BPM, GROUP, VALUE, …), booleans/undef literals, and namespace calls (antescofo::, leading ::).
- Supports comments (;, //, /* … */), preprocessors (#IF, #ELSE, #ENDIF, #insert), and @INSERT includes.
Symbol Navigation
- Cmd/Ctrl+Click, F12, and Alt+F12 jump to definitions of directives, macros, processes, DSP blocks, and other annotated constructs across the workspace.
- Variable assignments ($foo := …, @global $foo := …, $$dsp := …) are indexed; usages resolve back to their definitions even when defined in inserted libraries.
- @INSERT "path" literals become clickable links that open the referenced file when it exists.
Document Outline & Workspace Awareness
- Outline view (Cmd/Ctrl+Shift+O) lists directives and variables with descriptive symbol kinds for quick navigation.
- Indexing scans unsaved buffers, so new definitions are available immediately for navigation and peeking.
OSC Integration
- Send selections/lines directly to Antescofo via /antescofo/cmd playstring.
- Start/Stop the score, load the current file, or restart from the label under the cursor.
- Optional notification of AscoGraph when loading a score.
Snippets & Language Configuration
- Starter snippets for common patterns (Groups, whenever, forward scheduling templates).
- Comment toggling, bracket/quote pairing, folding markers, and other Antescofo-friendly editor defaults.

Keyboard Shortcuts

All keybindings are scoped to Antescofo documents (Alt on Mac is option!):

Keybinding	Command	OSC Payload
`Alt+p`	Antescofo: Play Selection via OSC	`/antescofo/cmd ["playstring", text]`
`Alt+s`	Antescofo: Start	`/antescofo/cmd ["start"]`
`Alt+c`	Antescofo: Stop	`/antescofo/cmd ["stop"]`
`Alt+l`	Antescofo: Load Current Score	`/antescofo/cmd [\"score\", path]` + `/antescofo/loadscore [path]` (AscoGraph)
`Alt+Shift+s`	Antescofo: Start From Label	`/antescofo/cmd [\"startfromlabel\", label]`
`Alt+Shift+l`	Antescofo: Jump to Label	— (navigates within VS Code)

The commands are also available through the Command Palette (Antescofo: …).

Installation

Option 1 – Install from the VS Code Marketplace

Open VS Code, press Ctrl/Cmd+Shift+X, and search for “Antescofo”.
Click Install and reload when prompted. The extension activates automatically for Antescofo files.

Option 2 – Install from GitHub Releases

Grab the latest .vsix from the Releases page.
In VS Code, open Extensions → ⋮ → Install from VSIX… and select the downloaded file.
Alternatively, install via CLI: code --install-extension antescofo-<version>.vsix.

Option 3 – Run from Source (recommended while developing)

Clone or download this repository.
Install dependencies:
```
npm install
```
Open the folder in VS Code and press F5 to launch an Extension Development Host.
In the dev host window, open an .asco file (see Example/ for sample scores) to try the features.

Usage Tips

Jump to definitions with F12, Cmd/Ctrl+Click, or peek with Alt+F12.
Use the Outline (Cmd/Ctrl+Shift+O) for fast navigation between directives, macros, and variables.
Quickly jump to labels with Antescofo: Jump to Label (Alt+Shift+l).
Hover/click on @INSERT "relative/path.asco.txt" to open referenced libraries.
Saving a file reindexes definitions, but unsaved buffers are also scanned so new symbols are usable immediately.

Configuration

Settings live under the antescofo namespace (Settings UI or settings.json):

Setting	Default	Description
`antescofo.osc.host`	`localhost`	Hostname/IP of the Antescofo OSC server.
`antescofo.osc.port`	`5678`	UDP port for Antescofo OSC commands.
`antescofo.ascograph.host`	`localhost`	Hostname/IP for AscoGraph notifications (leave empty to disable).
`antescofo.ascograph.port`	`6789`	UDP port for AscoGraph notifications.
`antescofo.osc.appendNewline`	`true`	Append `\n` when sending selections via `playstring`.

Configuration is read at execution time, so changes take effect immediately.

Contributing

Development Workflow

Install dependencies: npm install.
Start the Extension Development Host with F5 and keep it running while editing.
Modify extension.js, syntaxes/Antescofo.tmLanguage, snippets, or configuration; changes hot-reload in the dev host.
Optional syntax check: node --check extension.js.
Package with npx vsce package to produce a distributable VSIX.

Updating the Grammar

Edit syntaxes/Antescofo.tmLanguage (XML plist).
Keep regex patterns ASCII-friendly and validate with xmllint --noout syntaxes/Antescofo.tmLanguage.
Whenever new directives appear in the core Antescofo sources, mirror them in the grammar and in the regex lists inside extension.js.

Extend the directive or variable regexes in extension.js to index additional constructs.
Rebuild the symbol index by saving files or running the “Antescofo: Rebuild Symbol Index” command (if added).

Submitting Changes

Use descriptive commits (e.g., feat: support go-to-definition for dsp variables).
Document notable behaviour changes in CHANGELOG.md.
Verify navigation and highlighting in the Extension Development Host before opening a pull request.

License

MIT

Antescofo