tower-lsp-boilerplate

This boilerplate implements a full suite of LSP features for l-lang:

• Semantic Tokens: Role-based syntax highlighting.
• Inlay Hints: Type annotations for variables.
• Diagnostics: Real-time syntactic and semantic error reporting.
• Code Completion: Context-aware symbol suggestions.
• Go to Definition: Navigation to symbol declarations.
• Find References: Locating all usages of a symbol.
• Rename: Refactoring symbols across the codebase.
• Format: Code formatting support.

L-lang is a simple, statically-typed programming language used in this boilerplate. It supports:

• Struct definitions: Defining types with specific field types.
• Functions: Typed parameters and return types.
• Variable bindings: Using let with type inference.
• Arithmetic: +, -, *, /.
• Field access: Accessing struct members.
• Struct literals: Instantiating structs.
• Basic types: int, bool, string.

struct Point {
    x: int,
    y: int,
}

fn add_points(a: Point, b: Point) -> Point {
    return Point { x: a.x + b.x, y: a.y + b.y };
}

fn main() {
    let p1 = Point { x: 10, y: 20 };
    let result = add_points(p1, p2);
    return result;
}

To develop and debug the language server within VSCode, follow these steps:

1. Install dependencies: pnpm i
2. Build the Rust server: cargo build
3. Open the project in VSCode: code .
4. Launch the debugger: Press <kbd>F5</kbd> or go to the Debug panel and click Launch Client.
5. Test the implementation: In the new VSCode instance that opens, open examples/test.l to verify syntax highlighting and LSP features.

Troubleshooting: If you encounter the error Cannot find module '/xxx/xxx/dist/extension.js', run tsc -b manually to build the TypeScript project.

To package the extension and install it as a local VSCode extension:

1. Ensure all dependencies are installed and l-language-server is in your PATH.
2. Package the extension: pnpm run package.
3. Install the generated .vsix file: code --install-extension l-language-server-${version}.vsix (replace ${version} with the actual version found in your file system).
4. Restart VSCode and create a minimal .l file to test the effects.

The server provides semantic tokens via semantic_tokens_full and semantic_tokens_range. It maps l-lang symbols to LSP semantic token types using a delta-encoding scheme. The supported token types are:

Tokens are calculated by iterating over symbol spans and reference spans in the CompileResult and converting byte offsets to line/character positions using the document's Rope.

The language server provides semantic tokens for syntax highlighting of functions, variables, parameters, structs, and fields. To use this, ensure semantic highlighting is enabled in your VSCode settings.json:

{
  "editor.semanticHighlighting.enabled": true
}

The language server is initialized using LspService::build with a Backend implementation. The server communicates via stdin and stdout. The main function sets up the LspService, creates a Backend instance with empty DashMaps for document and semantic data, and starts the server loop using Server::new(...).serve(service).await.

#[tokio::main]
async fn main() {
    env_logger::init();

    let stdin = tokio::io::stdin();
    let stdout = tokio::io::stdout();

    let (service, socket) = LspService::build(|client| Backend {
        client,
        semanticast_map: DashMap::new(),
        document_map: DashMap::new(),
    })
    .finish();

    Server::new(stdin, stdout, socket).serve(service).await;
}

The extension determines which executable to run for the language server using the SERVER_PATH environment variable. If SERVER_PATH is not set, it defaults to running the command l-language-server.

To use a custom server binary, set the SERVER_PATH environment variable in your shell or development environment before launching VS Code.

# Example: setting a custom path to the server binary
export SERVER_PATH=/path/to/your/custom-l-language-server
code .

The hover method provides Markdown-formatted information about the symbol at the current position. It uses the semanticast_map to identify the symbol kind and type information.

• Functions/Structs: Returns a code block like ` ```l fn name

``` `.

• Variables/Parameters/Fields: Returns a code block containing the name and the formatted type, e.g., ` ```l let name: type_str

``` `.