Spar for Visual Studio Code

First-party editing support for Spar, the typed scripting and configuration language used by Sparsh.

Highlights

• A color system with meaning. Hue says what a token is, and the built-in modifier says where it comes from: declaring words (var, const, fn, export) and control flow (if, for, return) differ; built-in types and functions (int, str, List, int()) differ from your own; type parameters and enum members have their own colors.
• Native shell { ... } highlighting. Commands (resolved ones green, unresolved ones red), builtins, flags, arguments, operators, redirects, environment assignments, ${...} interpolation and $(...) substitution. Ordinary Spar statements inside a shell block (var, if, for, calls) stay Spar.
• Embedded Bash inside shell bash { ... } blocks.
• Readable on any theme. Spar colors are scoped to Spar files and keep their meaning when you change theme. The extension picks a bright palette (7:1 contrast or better) for dark themes and a deep one for light themes, and switches automatically when you change theme. Spar Dark and Spar Light are also included. Set spar.colors.mode to off to stop the extension from writing colors, or run Spar: Reset Colors.
• spar-ls integration: diagnostics, formatting (on save by default), hover, go-to-definition, references, workspace symbols, rename, signature help, and completion for locals, parameters, named arguments and their values, and imports.
• Import discovery. Type import pkg { and press Ctrl+Space to see everything the bundled std modules export; accepting one adds the from "std/..." clause for you.
• Snippets for functions, constants, enums, tuple bindings, async functions, tasks and import forms.
• A Run button for .spar files, plus commands to check, emit JSON, restart the language server, show its version and open its logs.

Requirements

Install spar (0.6.4 or newer) and spar-ls (0.6.4 or newer) and make them available on PATH. Cargo installs under ~/.cargo/bin are discovered automatically when VS Code is launched without your interactive shell environment. The extension warns when the language server is too old.

You can also configure explicit paths:

{
  "spar.binaryPath": "/absolute/path/to/spar",
  "spar.serverPath": "/absolute/path/to/spar-ls"
}

Changing a color

The extension writes its palette into your user settings (editor.semanticTokenColorCustomizations and editor.tokenColorCustomizations, rules named spar:*). It never overwrites a color you have edited, and other rules are left alone. Your own colors win: For example, to make shell flags brighter:

"editor.semanticTokenColorCustomizations": {
  "rules": { "shellFlag:spar": "#FFD866" }
}

Selectors follow tokenType.modifier:spar: keyword, declarationKeyword, type, type.defaultLibrary, function, function.defaultLibrary, parameter, shellCommand, shellCommand.unresolved, shellBuiltin, shellFlag, shellArgument, shellOperator, shellRedirect, shellEnvironment, shellInterpolation.

IntelliSense

With the intelligence-core spar-ls, Ctrl+Space can complete exports inside imports and named function arguments. Signature help is provided while entering function calls, and workspace-aware navigation/rename works across imported Spar files.

Example:

import pkg { readText } from "std/fs";

fn show(path: str) -> shell {
    return shell {
        echo "${readText(path: path)}";
    };
};

Native and foreign shell blocks

return shell {
    cargo build --release;
};

Native shell tokens are refined semantically by spar-ls, including resolved/unresolved command state.

For Bash-specific syntax, use a foreign shell block:

return shell bash {
    for file in *.txt; do
        echo "$file"
    done
};

VS Code delegates the contents of that region to its Shell Script grammar.

Commands

Open the Command Palette and search for Spar:.

• Spar: Check File
• Spar: Execute File
• Spar: Emit JSON
• Spar: Restart Language Server
• Spar: Show Language Server Version
• Spar: Show Language Server Output

Troubleshooting

Run Spar: Show Language Server Version to verify the binary VS Code actually launched. Use Spar: Show Language Server Output for protocol/server logs. If VS Code cannot locate the server, set spar.serverPath explicitly.