Tooling

Zolo comes with a comprehensive set of development tools.

CLI (zolo)

The zolo command is the primary interface for working with Zolo code.

Running Code #

bash
zolo run hello.zolo       # compile and execute
zolo hello.zolo           # shorthand for 'run'

Compiling #

bash
zolo compile hello.zolo   # show generated Lua code

This is useful for debugging — you can see exactly what Lua code your Zolo program produces.

Type Checking #

bash
zolo check hello.zolo     # parse and type check without executing

Testing #

bash
zolo test tests.zolo                 # run all @test functions
zolo test tests.zolo --filter fib    # only tests matching "fib"
zolo test tests.zolo --list          # list test names

Test output shows pass/fail for each test function:

[PASS] test_addition
[PASS] test_fibonacci
[FAIL] test_broken - assertion failed: expected 5, got 4
Results: 2 passed, 1 failed, 3 total

Formatting #

bash
zolo fmt hello.zolo          # format file in place
zolo fmt --check hello.zolo  # check formatting without modifying

REPL #

bash
zolo repl     # start interactive session

Version and Help #

bash
zolo version   # or zolo -v
zolo help      # or zolo -h

Language Server Protocol (LSP) #

The Zolo LSP server (zolo-lsp) provides IDE features. It's implemented in Rust using tower-lsp and communicates over stdin/stdout.

Supported Features #

Feature Description
Diagnostics Parse errors with source locations
Hover Function signatures, struct/enum/trait info
Autocomplete Keywords, types, document symbols, snippets
Go to Definition Functions, structs, enums, traits, variables
Document Symbols Hierarchical outline of the file
Semantic Tokens Rich syntax highlighting (functions, methods, types, parameters, fields, decorators)
Signature Help Parameter info while typing function calls
Inlay Hints Parameter names in calls, inferred types for let bindings

Semantic Token Types #

The LSP provides semantic tokens for:

  • function — function names (with declaration modifier)
  • method — method names
  • parameter — function parameters
  • variable — local variables
  • property — struct fields
  • type — type names (structs, enums)
  • interface — trait names
  • enumMember — enum variants
  • decorator — @ annotations
  • keyword — language keywords
  • string — string literals
  • number — numeric literals
  • comment — comments

Inlay Hints #

Two types of inlay hints:

  1. Parameter name hints — shown before arguments in function calls:

    add(/*a:*/ 1, /*b:*/ 2)

  2. Type hints — shown after let bindings with inferred types:

    let x /*: int*/ = 42

Debug Adapter Protocol (DAP) #

The zolo-dap crate implements the Debug Adapter Protocol for debugging Zolo programs in VS Code.

Supported Features #

Feature Description
Launch Start debugging a .zolo file
Breakpoints Set line breakpoints
Step Over Execute next line
Step Into Step into function calls
Step Out Step out of current function
Continue Run until next breakpoint
Stack Trace View call stack with source locations
Source Maps Maps Lua output lines back to Zolo source

How It Works #

  1. The DAP compiles Zolo to Lua using compile_to_lua_with_source_map()
  2. Source map entries track (lua_line, zolo_line) mappings
  3. Breakpoints are translated from Zolo lines to Lua lines
  4. The debug session manages stepping, stack frames, and variable scopes

VS Code Launch Configuration #

Add to .vscode/launch.json:

json
{
    "type": "zolo",
    "request": "launch",
    "name": "Debug Zolo",
    "program": "${file}"
}

Formatter (zolo fmt)

The Zolo formatter is AST-based — it parses the source, then reprints it with consistent style.

Features #

  • 4-space indentation
  • Consistent brace placement
  • Comment preservation
  • Expression formatting
  • Declaration alignment

Usage #

bash
zolo fmt myfile.zolo         # format in place
zolo fmt --check myfile.zolo # check without modifying (exit code 1 if changes needed)

VS Code Extension #

The Zolo VS Code extension provides a complete development environment.

Features #

Category Features
Syntax TextMate grammar for full syntax highlighting
Language Config Comments, brackets, indentation, folding
Snippets 28+ snippets for common constructs
LSP Full LSP client with auto-discovery of zolo-lsp binary
Semantic Highlighting Rich token coloring via LSP semantic tokens
Signature Help Parameter info in function calls
Inlay Hints Type and parameter name hints
Explorer Sidebar tree view showing document symbols
AST Viewer Webview panel showing the AST
Debugger DAP integration for debugging
Commands Run, restart LSP, show AST, show output
Run Run current file with Ctrl+Shift+R

Commands #

Command Keybinding Description
Zolo: Run Current File Ctrl+Shift+R Compile and execute the active file
Zolo: Restart Language Server — Restart the LSP server
Zolo: Show AST — Open AST viewer panel
Zolo: Show Output Channel — Show LSP output logs

Configuration #

Setting Default Description
zolo.lsp.enabled true Enable/disable the LSP client
zolo.lsp.serverPath auto Path to the zolo-lsp binary
zolo.trace.server off LSP trace level (off, messages, verbose)

Status Bar #

Shows the LSP connection status:

  • Connected / Disconnected / Error
  • Click to open the output channel with LSP logs

Zolo Explorer #

A sidebar panel (activity bar) showing the document outline:

  • Functions, structs, enums, traits, variables
  • Click any symbol to navigate to its location
  • Auto-refreshes on file changes

AST Viewer #

A webview panel showing the parsed AST as an interactive tree:

  • Updates live as you edit
  • Shows all AST nodes with their types and spans

Debugging #

Press F5 to start debugging with the Zolo debug adapter:

  • Set breakpoints by clicking the gutter
  • Step through code line by line
  • View the call stack
  • Continue/pause execution

Context Menus #

Right-click a .zolo file in the explorer → "Run with Zolo"

Edit on GitHub
enespt-br