VS Code Integration

Nostos provides a rich VS Code extension with syntax highlighting, error checking, autocomplete, an integrated REPL, and visual file status indicators.

Installation

Install the Nostos extension from the VS Code marketplace or build from source: 

# Install from marketplace
code --install-extension pegesund.nostos

# Or build from source
cd editors/vscode
npm install
npm run compile
npm run package
code --install-extension nostos-*.vsix

The extension requires the nostos-lsp binary. Install it: 

# Build and install the LSP server
cargo build --release -p nostos-lsp
cp target/release/nostos-lsp ~/.local/bin/

File Status Indicators

The extension shows visual badges on files in the explorer to indicate their compile status:

Badge Color Meaning
✓ Green Compiled successfully - no errors
✗ Red Compile error - check Problems panel
◌ Blue Stale - depends on a file that changed
● Yellow Dirty - modified but not compiled yet

Note: Files become "dirty" when you edit them. Use Ctrl+Alt+C to commit changes to the live system and clear the dirty status.

Keyboard Shortcuts

The extension provides several keyboard shortcuts for common operations:

Shortcut Action
Ctrl+Alt+C Commit current file to the live system
Ctrl+Alt+R Open the integrated REPL

Integrated REPL

Open the REPL with Ctrl+Alt+R or run the command Nostos: Open REPL from the command palette.

The REPL provides an interactive environment connected to your project:

  • All your project's modules are automatically loaded
  • Autocomplete with documentation for functions, types, and modules
  • Type expressions and see results immediately
  • Import modules with use module.*
  • Define variables that persist across evaluations
# In the REPL:
> use mymodule.*
imported: helper, calculate, Person

> p = Person(name: "Alice", age: 30)
Person(name: "Alice", age: 30)

> p.name
"Alice"

> calculate(10, 20)
30

> [1, 2, 3].map(x => x * 2)
[2, 4, 6]

Autocomplete

The REPL provides intelligent autocomplete:

  • Functions: Shows parameter placeholders like func(,) for arity
  • Types: Shows field names like Person(name: , age: )
  • Modules: Type module name to see all exports
  • Methods: Type value. to see available methods

Non-imported functions show their full module path (e.g., mymodule.helper) until you import them with use mymodule.*.

Tip: Documentation appears above the completion list, showing function signatures and descriptions.

Live Development Workflow

Nostos supports a live development workflow where you can modify code and immediately test it:

  1. Edit your .nos files - they'll show as dirty (yellow badge)
  2. Errors are shown in real-time in the Problems panel
  3. When ready, press Ctrl+Alt+C to commit to the live system
  4. Successfully compiled files turn green
  5. Test your changes immediately in the REPL
# Example workflow in REPL:

# 1. Load your module
> use mymath.*
imported: add, multiply

# 2. Test initial implementation
> add(2, 3)
5

# 3. Edit add() in your file, then Ctrl+Alt+C to commit

# 4. Test the updated version
> add(2, 3)
6  # Now returns different result based on your changes

Available Commands

Access these commands from the Command Palette (Ctrl+Shift+P):

Command Description
Nostos: Open REPL Open the integrated REPL panel
Nostos: Commit Current File Compile and commit the active file
Nostos: Commit All Open Files Compile and commit all open .nos files
Nostos: Restart Language Server Restart the LSP server
Nostos: Build Module Cache Build cache for faster startup
Nostos: Clear Module Cache Clear the module cache

Troubleshooting

LSP not starting

Check that nostos-lsp is in your PATH or configure it in settings: 

{
    "nostos.serverPath": "/path/to/nostos-lsp"
}

Extension not updating

After rebuilding the extension, copy it to the extensions folder: 

# Copy updated extension
cp out/extension.js ~/.vscode/extensions/pegesund.nostos-*/out/

# Restart VS Code or run "Developer: Reload Window"

File decorations not showing

Restart VS Code after installing the extension. File decorations require a full restart to register properly.

Previous: TCP Sockets End of Tutorial